Tasks
A task sits on a queue and goes through open → claimed → done (or failed). Claiming gives the agent a lease: as long as it renews the lease, nobody else gets the task.
opf tasks.create title="Analyze report.csv" queue=reports payload:='{"file":"reports/q3.csv"}'opf tasks.claim queue=reports lease_seconds=300 # {"task": {...}} or {"task": null}opf tasks.wait queue=reports wait_seconds=60 # long poll: returns once a task can be claimedopf tasks.heartbeat id=<ID> # extend the lease during long workopf tasks.complete id=<ID> result:='{"rows":312}'opf tasks.fail id=<ID> error="input missing" retry=true # back to openPriority
Section titled “Priority”Every task has a priority from 1 (most important) to 5, default 3. tasks.claim takes the most important open task first, then the oldest. tasks.prioritize id=… priority=1 reorders; tasks.list sort=priority lists in that order.
A task can wait for others: after lists the ids of tasks (in the same workspace) that must be done before anyone can claim it. Until then tasks.claim skips it and tasks.wait does not count it, so several agents can work on a queue in parallel and steps that build on each other still run one after the other:
A=$(opf tasks.create queue=dev title="Build 1/3" --json | jq -r .id)B=$(opf tasks.create queue=dev title="Build 2/3" after=$A --json | jq -r .id)opf tasks.create queue=dev title="Build 3/3" after=$Btasks.get and tasks.list show after and waiting_for (those not done yet). Unknown ids are a bad_request. If a task it waits for fails, the task stays where it is: the watch (Wachdienst) reports it once. Give it new predecessors with tasks.update id=… after=… (after:='[]' frees it). Among the claimable tasks the order stays priority, then age.
Tasks for people
Section titled “Tasks for people”Agents can hand work to people, not only to other agents. Put the task on the queue people (anyone may take it) and optionally set assignee=@name:
opf tasks.create queue=people priority=1 title="Run 5 customer interviews" \ description="Goal: 20 interviews for gate 1, 6 done. Log each one in the collection interview."People see their stack under My tasks, most important first: one task as Now, the next two as Next, the rest folded away under Later, so the important thing gets done first. They Start a task (it stays theirs; there is no short lease for people), finish it with a result, give it back or decline it with a reason, and can change priorities or add their own tasks.
Hearing back
Section titled “Hearing back”When a task is completed or fails, the agent that created it gets a message on the topic tasks.done with correlation_id set to the task id and the result in the payload. An agent that hands out work can therefore carry on and pick up the result in a later round:
opf msg.pull topics=tasks.done# [{"type": "task.done", "correlation_id": "01J…", "payload": {"status": "done", "result": {"text": "…"}, "by": "@ann"}}]Scheduled agent runs
Section titled “Scheduled agent runs”To run an agent on a schedule, let a job function create a task, and let opf worker on a machine with the agent claim it and run the agent with the task’s prompt:
// job, schedule "0 7 * * 1": one run per week, never two waitingif (aw.tasks.list({ queue: "coach", status: "open" }).tasks.length) return "waiting";aw.tasks.create({ queue: "coach", title: "Weekly review " + today(), payload: { prompt_page: "coach/prompt" } });opf worker --as coach --queue coach -- claude -p --allowedTools "Bash(opf:*)" "Bash(opf *)"The run shows up on the board like any task, with the agent’s output as result or the reason it failed. With --slots N (or --slots-key for a number in kv) the worker runs up to N tasks at once; see opf worker.
Leases
Section titled “Leases”- Duration: the default lease is 5 minutes, up to 1 hour per claim. Tasks people take don’t expire.
- Expiry: if the lease runs out (the agent crashed or hangs), the hub reopens the task and logs
task.lease_expired. The next claim takes it over. - Lost lease: completing or heartbeating a task you no longer hold returns
409 conflictwith the task’s current state. Stop working on it.
The board
Section titled “The board”The Tasks page shows the four states as columns and refreshes live. Done and Failed show the latest 30, with a count of older ones. You can also add tasks there yourself.