agent-mesh

Acknowledge a message, removing it from the agent's inbox. Writes an 'ack' receipt (per-recipient — a broadcast is acked independently by each recipient).

Open a bounded, two-agent Discussion: sends the root question and (optionally) explicitly reserves one peer attempt, then waits until the conversation deadline for a settled answer. Message arrival never starts an agent by itself — wake_peer:true is the explicit, budgeted authority to run the peer once.

Attach an agent to a running fleet. It banks complete only when result_contract is ok; refused, blocked, artifact_missing, invalid, or absent banks failed.

Cast a vote on an open ratification. approve=true records approval, approve=false rejection. Re-casting CHANGES your effective vote (each change appends a new sequenced receipt — history is never rewritten); repeating your current vote is a no-op.

Get fleet outputs and loss tally. Only result_contract ok can bank complete; refused, blocked, artifact_missing, invalid, or absent banks failed. Declared outcome, not quality. Check lost first.

Offline projection of caller-supplied route-candidate snapshots. Does not persist, rank, execute, authorize, wake, or contact providers.

Check fleet and agent status.

Full BuildIdentityReport for the running install: package name/version, source_commit, entrypoint_count, per-entrypoint SHA-256 map, entrypoints_match_runtime bit. Diagnostic access to the install's identity.

Read-only: derive and return a Discussion's full state — transcript, attempts, budget, and fail-closed status (invalid > closed > deadman > expired > exhausted > active > open) — from durable messages and receipts. Remains useful after every inbox entry has been acknowledged.

Fleet health + liveness. Pass verbosity="summary" for a smaller routine probe (entrypoints map omitted); default "full" is the full BuildIdentityReport. Use `get_build_identity` for diagnostics.

Get messages in an agent's inbox, optionally since a timestamp.

Get the full receipt trail for a message: who acked, who annotated, when. Answers 'who saw this and who acted on it'.

Read back a work receipt by composite key. Returns the exact stored bytes plus the server's `recorded_at`. `not_found` means no row exists for that key; a schema-shaped error means the key itself is malformed.

List all available premade agents from .opencode/agents/ directories.

List all saved fleet templates, sorted by name.

List all fleets with summaries (agent count, status, completion).

Open a quorum vote ('council') over the fleet. Broadcasts a proposal; peers vote with cast_vote. Ratifies when approvals reach the quorum and every required signoff approves. Returns the proposal message_id.

Minimal liveness check. Returns { status: 'ok', timestamp }.

Pure, caller-approved speculative backlog projection. Does not persist, execute, authorize, wake agents, contact providers, poll, allocate capacity, schedule, spend, send, or publish.

Write a non-consuming receipt on a message — the audit primitive. Use actions like 'seen', 'r-ack' (approve), 'retracted'. Unlike ack_message, the message stays in the inbox. One receipt per (message, agent, action); repeat calls are idempotent.

Advisory-only ranking over caller-supplied sanitized task traits and candidate snapshots. Does not persist, execute, authorize, wake agents, or contact providers.

Record whether a routed task succeeded or failed. Future route_work calls for the same agent weight their score by accumulated outcomes (Wilson-style). NOTE: outcomes are currently accumulated PER AGENT, not per capability — capability_key is recorded for forward compatibility but does not yet scope the penalty, so a failure at one capability lowers the agent's score for all of them. Feedback is in-process and resets when the server restarts.

Record a first-class external work receipt (Hermes Kanban result contract). Stores the canonicalized payload in the `work_receipts` collection with an immutable idempotency key of (source, task_id, run_id). Byte-equivalent replays return the existing row; conflicting replays (same key, different bytes) refuse history and return an error. Does not attest, fetch, or verify the evidence — see Kanban receipt dogfood design §4.

Register an agent's capabilities (role, skills, model) for routing.

Submit the one reply an active wake attempt is authorized to produce. Never launches an agent. Rejects a second reply for the same attempt, a stale head, or a reply past the conversation/attempt deadline. close:true makes the conversation terminal; exhausting the last turn without close returns exhausted.

Route a work description to the best-matching registered agents by keyword + role/skill overlap scoring (with synonym expansion), weighted by routing feedback (success/fail history). top_n controls how many matches to return (default 1, max = fleet size).

Save a named fleet template (set of agent specs) for reuse. Names: lowercase letters, numbers, dashes, underscores.

Send a P2P message from one agent to another within the same fleet. Set to_agent_id to "*" to broadcast to every other agent in the fleet (each recipient acks independently; see get_receipts).

Send a batch of P2P messages in ONE ledger transaction — use instead of repeated send_message calls for bulk fan-out (much faster: the recipient inbox is updated once per batch, not once per message). Atomic: one invalid message rejects the whole batch. Max 1000 messages per call.

Set a per-fleet timeout override (in milliseconds). Agents exceeding this are auto-failed.

Spawn parallel agents. Returns fleet_id. An agent banks complete only when result_contract is ok; refused, blocked, artifact_missing, invalid, or absent banks failed.

Return a fleet spec from a saved template, ready to pass to spawn_fleet.

Subscribe to the unified fleet-wide event stream via Server-Sent Events (SSE). Returns a stream URL that emits every ledger event (messages, receipts, ratifications, spawns, completions, discussions) as it is appended. Keep-alive :hb comment frames are sent every 30s. Optional fleet_id filter narrows to events carrying that fleet_id. If the operator set MESHFLEET_AUTH_TOKEN, requests to the stream must carry it (Authorization: Bearer, or ?token=).

Subscribe to an agent's inbox via Server-Sent Events (SSE). Returns a stream URL that the agent opens to receive real-time push of incoming P2P messages. Falls back to polling get_inbox if SSE is unreachable. If the operator set MESHFLEET_AUTH_TOKEN, requests to the stream must carry it (Authorization: Bearer, or ?token=).

Evaluate every open ratification now and persist any that reached a terminal state (deadline expiry, silent-approval, unreachable quorum). The server also sweeps automatically every AGENT_MESH_RATIFY_SWEEP_MS (default 60s).

Read the live vote tally and current status (open / ratified / rejected / expired) of a ratification, and persist the status if it has reached a terminal state.

Audit the ledger's internal consistency: every receipt points at a real message and honors the idempotency key, acknowledged flags are supported by ack receipts, inboxes hold no consumed or dangling messages, and ratification tallies (quorum, signoffs, vote polarity, terminal status) recompute from the receipts. Read-only. Returns ok, error/warning counts, per-finding detail, and a `scope` object stating the guarantee boundary — errors mean the ledger asserts something its own records do not support. SCOPE: ok=true means CONSISTENT, not AUTHENTIC. There is no hash chain or signature in this verifier, so an edit that rewrites the ledger consistently is indistinguishable from honest history. Do not report a passing verification as proof the ledger was not tampered with.

Versioned verifier output read from a dedicated read-only file snapshot; the handler performs no ledger writes. Normal parent-server startup recovery or migration may initialize or change the configured ledger before tool dispatch. Returns the unchanged internal-consistency report inside meshfleet.verify/v2 with an unsigned-snapshot evidence scope; it does not establish authorship, snapshot integrity, content binding, completeness, external delivery or execution, or external time.

Opt-in verifier output read from a dedicated read-only file snapshot; the handler performs no ledger writes. Returns a detached meshfleet.verify/v3 report with one local consistency band per finding, derived only from its severity. Those labels are not provenance or confidence and do not establish authenticity, completeness, tamper evidence, authorship, snapshot integrity, content binding, external delivery or execution, or external time.

The sole general-purpose Discussion run trigger. Atomically reserves one bounded attempt for a resident participant who is the current recipient of the canonical head, then launches it. Never waits for the reply. Duplicate concurrent calls return the existing active attempt or turn_already_active — they never launch twice.