agent-bus (0.7.0)

Claim a name on the bus, optionally declaring capability tags. Idempotent when replace: true is set. Without replace, fails with NAME_TAKEN if the name was last seen within 60 seconds. MCP sessions default project from the repo cwd; CLI relay registrations default to null.

Returns every row in the agents table sorted by last_seen descending.

Insert a msg row addressed to one agent. Returns immediately. A new thread_id is auto-generated unless one is provided.

Returns messages addressed to the caller with status='pending'.

• Without wait_s: returns immediately (may be empty).
• With wait_s: blocks up to that many seconds (max 110) for the first message to arrive.
• Without claim_s: returned messages flip to delivered (at-most-once).
• With claim_s: returned messages stay pending with a claim_deadline set to now + claim_s*1000. They become invisible to other inbox calls until either you ack them or the claim expires and they become visible again.

Flip a claimed pending message to delivered and clear its claim. Use after successfully processing a message returned by inbox(claim_s=...).

Inserts an ask message and polls for a reply row pointing back at it. Blocks up to timeout_s seconds (max 110, default 60). Refuses cycles: if the recipient has a pending ask back to the caller, fails with ASK_CYCLE.

Picks the most-recently-active agent that has the given capability tag in the selected project/area, then performs ask. Pass project: "*" or area: "*" to search more broadly. Refuses matches where the candidate hasn't been seen in 5 minutes.

Close an ask with an answer. Creates a reply row pointing at the ask via reply_to, inheriting the ask's thread_id, and flips the original ask's status to answered.

Idempotent — re-subscribing refreshes subscribed_at.

No-op if the agent isn't subscribed.

Fans out: inserts one msg row per subscriber (sender excluded). Each row carries channel = <name> and a shared thread_id.

Returns every message that shares the given thread_id, in chronological order. Does not mutate status.

Useful for catching up on the bus. Does not mutate status. Project and area filters return matching messages plus legacy/global null scope messages. Pass "*" for global on a dimension.

Creates a first-class unit of work in open state. Tasks are queryable work items; messages and threads carry the discussion around that work. A thread_id is generated unless provided. Project defaults to the requester agent's project.

Moves an open task to claimed and sets claimed_by. The update is atomic and only succeeds when the task is still open and unclaimed.

Updates a task while enforcing the state machine: open -> claimed|canceled, claimed -> working|open|canceled|failed, working -> blocked|completed|failed|canceled, and blocked -> working|completed|failed|canceled. Terminal states cannot transition. Only the requester or current holder can update.

Clears claimed_by and moves a non-terminal task back to open so another agent can claim it. The requester or current holder can release.

Returns tasks sorted by priority descending, then creation order. Terminal tasks are excluded by default unless include_terminal is true or a terminal state filter is provided. Active tasks may include stale: true when their holder has not heartbeated within AGENT_BUS_TASK_STALE_MS. Concrete project and area filters hide null-scope legacy tasks; project: "*" and area: "*" broaden the view.