116 lines
2.9 KiB
Markdown
116 lines
2.9 KiB
Markdown
---
|
|
name: work-queue
|
|
description: "Work queue skill for TheLab agents. Submit, dispatch, track, and complete work items via the Work Queue API. Embeds TheLab dispatch opinion: one in_progress per agent, stale detection, automatic blocking of timed-out items."
|
|
---
|
|
|
|
# Work Queue Skill
|
|
|
|
Thin wrapper around the Work Queue API with embedded dispatch opinion.
|
|
|
|
## Setup
|
|
|
|
Set the base URL:
|
|
```bash
|
|
export WORK_QUEUE_API_URL=https://api.example.com # replace with actual API URL
|
|
```
|
|
|
|
The skill reads `WORK_QUEUE_API_URL` from env.
|
|
|
|
## Core Commands
|
|
|
|
### `wq add`
|
|
|
|
Submit a new work item (status=queued).
|
|
|
|
```bash
|
|
wq add <type> <description> [--agent <agent>] [--project-id <id>] [--priority 1-5>] [--payload <json>]
|
|
```
|
|
|
|
Example:
|
|
```bash
|
|
wq add code_review "Review PR #3 in shopping-list-api" --agent steve-w --priority 2 --payload '{"pr":3,"repo":"shopping-list-api"}'
|
|
```
|
|
|
|
### `wq dispatch`
|
|
|
|
Dispatch a queued item to an agent (moves queued→dispatched→in_progress atomically).
|
|
|
|
```bash
|
|
wq dispatch <work_item_id> <agent>
|
|
```
|
|
|
|
Fails if agent already has an in_progress item.
|
|
|
|
### `wq update`
|
|
|
|
Update status, outcome, or notes on a work item.
|
|
|
|
```bash
|
|
wq update <work_item_id> [--status <status>] [--outcome <success|failed|cancelled>] [--notes <text>]
|
|
```
|
|
|
|
Valid status transitions:
|
|
- dispatched → in_progress (agent picked it up)
|
|
- in_progress → blocked (waiting on something)
|
|
- in_progress → completed (done)
|
|
- in_progress → failed (unrecoverable error)
|
|
- queued → cancelled
|
|
- dispatched → cancelled
|
|
|
|
### `wq list`
|
|
|
|
List work items, optionally filtered.
|
|
|
|
```bash
|
|
wq list [--status <status>] [--agent <agent>] [--project-id <id>]
|
|
```
|
|
|
|
### `wq get`
|
|
|
|
Get a single work item by ID.
|
|
|
|
```bash
|
|
wq get <work_item_id>
|
|
```
|
|
|
|
### `wq my-queue`
|
|
|
|
Short-cut: list items assigned to a given agent with status=dispatched (what Steve should poll).
|
|
|
|
```bash
|
|
wq my-queue <agent>
|
|
```
|
|
|
|
---
|
|
|
|
## Dispatch Opinion
|
|
|
|
These rules are enforced automatically by the skill:
|
|
|
|
1. **One in_progress per agent** — dispatch fails if target agent is already in_progress
|
|
2. **Stale detection** — on every heartbeat, `wq stale-check` is called; items in_progress >30min are automatically marked blocked
|
|
3. **Terminal states require outcome** — moving to completed/failed/cancelled requires outcome field
|
|
4. **Cancelled only from queued/dispatched** — cannot cancel something already in_progress
|
|
|
|
---
|
|
|
|
## Stale Check (for heartbeat)
|
|
|
|
```bash
|
|
wq stale-check [--timeout-minutes 30]
|
|
```
|
|
|
|
Finds all in_progress items older than timeout, marks them blocked, prints a summary line per item.
|
|
|
|
---
|
|
|
|
## Integration with Gitea Watcher
|
|
|
|
The Gitea watcher (`gitea_cron/check.sh`) outputs `dispatch:` lines. On heartbeat, parse those lines and for each:
|
|
|
|
```bash
|
|
wq add <type> <description> --agent steve-w --payload '<json>'
|
|
```
|
|
|
|
The watcher itself does NOT call the API — it just emits dispatch lines. Marcus's heartbeat parses them, creates real work items via `wq add`, then dispatches via `wq dispatch`.
|