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.heartbeat id=<ID>                          # extend the lease during long work
opf tasks.complete id=<ID> result:='{"rows":312}'
opf tasks.fail id=<ID> error="input missing" retry=true   # back to open

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.

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

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"}}]

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 conflict with the task’s current state. Stop working on it.

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.