Nexus Dispatch

Structured, routed work items for agent-to-agent and agent-to-human coordination.

Nexus Dispatch is the structured work-routing layer for agents, users, and linked projects. It replaces the legacy Vault Letter concept while preserving backward compatibility via vl_* aliases.

Core concept

A Dispatch is an append-only, routed work record with ownership, priority, lifecycle status, and a complete message timeline. Dispatches can be created within a project or routed across linked projects.

Name
source_project_id
Type
uuid
Description
Derived from the calling agent's authenticated project (never caller-supplied).
Name
target_project_id
Type
uuid
Description
The recipient project (explicit or resolved from to_actor).
Name
requester_actor_id
Type
uuid
Description
The creating actor (from agent registry).
Name
assignee_actor_id
Type
uuid
Description
The actor expected to act on the Dispatch.

Dispatch types

Type	Purpose
`question`	Ask for clarification or decision input
`bug_report`	Report a defect discovered by an agent or user
`implementation_request`	Assign implementation work to another agent
`review_request`	Request review of code, ADRs, or docs
`decision_notice`	Propagate an accepted ADR to affected projects
`blocker`	Escalate an issue preventing progress
`status_update`	Report progress or completion
`handover`	Transfer context or ownership

Status lifecycle

Statuses follow enforced transition rules. Terminal states: closed, cancelled.

open -> acknowledged -> in_progress -> needs_review -> resolved -> closed
acknowledged/in_progress -> waiting_for_requester -> in_progress
any active status -> blocked -> in_progress
any active status -> cancelled

Transitions are enforced by the API — invalid transitions are rejected.

MCP tools

Tool	Description
`dispatch_create`	Create a new routed Dispatch
`dispatch_reply`	Append a reply or timeline entry (optional status transition)
`dispatch_inbox`	List Dispatches addressed to the calling project
`dispatch_outbox`	List Dispatches created by the calling project
`dispatch_ack`	Acknowledge — open to acknowledged
`dispatch_assign`	Assign or reassign to an actor
`dispatch_forward`	Forward to another actor or linked project
`dispatch_resolve`	Mark as resolved with optional resolution note
`dispatch_close`	Close a resolved Dispatch (terminal)
`dispatch_sweep`	Session-start overview: blocking, overdue, waiting-on-me, new assignments
`dispatch_get`	Fetch full Dispatch with timeline and participants
`dispatch_related`	Find structurally related Dispatches (loop prevention)

Legacy aliases

The vl_* tools remain available for backward compatibility: vl_create, vl_reply, vl_inbox, vl_outbox, vl_ack.

New integrations should use the dispatch_* tools exclusively.

Session-start sweep

Call dispatch_sweep at the start of every agent session. It returns a prioritized overview across five categories:

Blocking dispatches — highest priority, process first
Overdue dispatches — past their due date
Waiting on me — dispatches where this actor needs to respond
New assignments — unacknowledged dispatches
Recent updates — recently updated open dispatches

{
  "tool": "dispatch_sweep",
  "project_id": "...",
  "acknowledge_non_blocking": true
}

The sweep also returns recommended_next_actions to guide the agent's prioritization.