Skip to content

CLI

Flag names, subcommand verbs and exit codes on this page become a frozen contract at v1.0 — see stability and versioning for what that covers and what it deliberately leaves out. mast is pre-1.0 today, so they can still move.

Everything here holds for a binary you build yourself from the cli package as well: it runs this exact command line, with your models and tools added.

mast --workload=... runs the daemon: the HTTP inject endpoint, the runner, and the session store.

There is no serve subcommand — serve mode is the flag-only invocation, and adding a positional prompt switches the same binary into one-shot mode. mast serve --attach-listen=… therefore does not start a daemon; it exits 2 with the misplaced-flag error, because serve was read as the prompt. The only subcommands are sessions and stop.

FlagDefaultMeaning
--workload—Workload to run: a name resolved via .agents/ discovery, or a path to a workload directory. Empty = trivial single-agent coordinator (inject-endpoint smoke only).
--instructions(empty)A project directory whose AGENTS.md (falling back to CLAUDE.md, then GEMINI.md; read from <dir>/.agents/ or <dir>/, with @include and .agents/AGENTS.d/*.md) is placed ahead of the coordinator’s and every specialist’s instruction. For deployment facts the workload can’t know, such as which cluster this agent serves. A named directory with no instruction file is refused at startup. Empty loads nothing; the working directory is never read implicitly, so running mast inside a repo doesn’t pull that repo’s AGENTS.md into the prompts.
--dispatch(unset)Dispatch shape: coordinator (SubAgents pattern), graph (workflow-graph LLM-as-router), fanout (whole roster investigates concurrently, one _synthesis specialist merges), bounded (one SingleTurn specialist, one model call, a report forced to a schema), or auto (read the shape off the roster — it never picks bounded, because a cost ceiling is declared, never inferred). Unset takes the bundle’s own dispatch:, then coordinator; the flag wins only when the operator actually typed it. fanout requires a read-only roster and bounded a single schema-declaring SingleTurn specialist — see the bundle reference.
--modelechoecho (offline fake, no credentials), scripted (JSONL recorded-turn replay; path via MAST_SCRIPT, strict matching via MAST_SCRIPT_STRICT=1), a Gemini model id like gemini-2.5-flash, or a Claude model id like claude-sonnet-4-6.
--provider—Provider alias: echo, scripted, gemini, vertex, anthropic, or anthropic-vertex. Validates --model when both are set; picks the provider’s default model from the --task profile’s tier when --model is unset. The alias also picks the backend within a family, and the two families differ in what happens without one. vertex serves gemini-* against Vertex AI (GOOGLE_CLOUD_PROJECT + ADC; location from GOOGLE_CLOUD_LOCATION / GOOGLE_CLOUD_REGION, default global) — with no alias, only GOOGLE_GENAI_USE_VERTEXAI=true gets you there, and a project alone does not. For claude-*, no alias means ANTHROPIC_API_KEY selects the first-party API, then a Vertex project (ANTHROPIC_VERTEX_PROJECT_ID / GOOGLE_CLOUD_PROJECT) selects Vertex. See credentials.
--listen:7777HTTP bind address for /inject, /resume, /abort, /monitor-ack, /metrics, /healthz (readiness; unauthenticated — see Asking whether it is ready). Non-loopback binds are refused without MAST_INJECT_TOKEN (/resume releases parked mutating calls; /stop stops the daemon) — so the default bind needs either the token or --listen=127.0.0.1:7777. A MAST_INJECT_USERS_FILE table does not satisfy this: it gates two routes, not the listener.
--attach-listen(empty)Operator attach surface (HTTP/SSE for mast-web and other attach clients): a TCP address like 127.0.0.1:8484, or a Unix socket as unix:/path/mast.sock. Empty = disabled. Implies a durable --session-db at ~/.mast/sessions.db when you name none — the live tail pumps from the eventlog overlay, which an in-memory store does not have, so attach used to refuse to start rather than imply one. Naming a path still wins, and --session-db= (explicitly empty) is refused rather than quietly overridden. The implication is sqlite-only: --session-db-driver=postgres still needs a DSN, because one cannot be invented. Non-loopback TCP binds are refused unless auth is configured — set MAST_ATTACH_TOKEN. Serve mode only.
--a2a-listen(empty)A2A server surface: a TCP address like 127.0.0.1:7780. Empty = disabled. Publishes an agent card and a JSON-RPC 2.0 endpoint (POST /a2a) for workloads that opt in via the bundle’s a2a.expose section. Card endpoints (/.well-known/agent-card.json, /.well-known/agent-card/<name>.json) are public; /a2a is authenticated when MAST_A2A_TOKEN is set, with per-skill scope enforcement. Non-loopback binds are refused without a token (tasks/cancel is destructive). Serve mode only. See A2A server.
--agui-listen(empty)AG-UI server surface: a TCP address like 127.0.0.1:7781. Empty = disabled. Serves a per-workload HTTP+SSE run endpoint and a /agui/agents.json discovery descriptor for workloads that opt in via the bundle’s agui.expose section. Authenticated when MAST_AGUI_TOKEN is set (per-workload scope enforcement); rate limits via MAST_AGUI_RATE/MAST_AGUI_BURST. Non-loopback binds are refused without a token (a run drives a budgeted turn). Serve mode only. See AG-UI server.
--notify-url(empty)Chat egress for monitoring cycles: switchboard’s message ingress, as an origin (http://switchboard:8080) or the full /v1/messages endpoint. Empty = disabled, and a workload whose bundle declares a monitor.notify block then refuses to start. Requires MAST_NOTIFY_TOKEN. Serve mode only — one-shot runs no monitoring cycle. See chat egress.
--park-notify(empty)The conversation a durable approval park announces itself to, through the ingress --notify-url configures (which is then required, along with MAST_NOTIFY_TOKEN — setting this without them is a startup error). Empty = disabled, and a park is then discoverable only by pulling: GET /parks, the attach stream, mast sessions show. Announced once per park, never repeated, capped at 3 then 1 per 5 minutes. Serve mode only — one-shot builds no write gate, so it raises no parks. See announcing a park.
--session-db(empty)SQLite file path (default driver) or Postgres DSN/URL with --session-db-driver=postgres. Empty = in-memory sessions, no durability — except under --attach-listen, which implies ~/.mast/sessions.db. Also the condition for the durable budget ledger: with a session database, max_cost_usd bounds what a workload spends across restarts rather than per process, and a crash loop can no longer spend the cap once per restart. See spend survives a restart.
--session-db-driversqlitesqlite or postgres. postgres with an empty --session-db is a startup error, never a silent in-memory downgrade — and it stays one under --attach-listen, since the implied default is a sqlite path and a DSN has a host, a database and credentials that cannot be guessed.
--timeout5mOne-shot turn deadline (2m, 90s, …); 0 disables. One-shot only — serve-mode wallclock ceilings come from workload budgets. An unresponsive backend (or a provider SDK silently retrying on quota errors) fails loudly instead of hanging a script.
--auto-resumetrueOn boot, scan for sessions a prior shutdown interrupted and drive a continuation turn for each eligible one (see boot-time auto-resume). --auto-resume=false disables. Serve mode only; needs --session-db (in-memory sessions never survive a restart).
--auto-resume-window1hOnly auto-resume sessions interrupted within this window; older interruptions are left for an operator. 0 disables the freshness gate. Serve mode only.
--watchdog(unset)Behavioral-watchdog posture, a ladder where each rung includes the one before it. warn logs a detected tool loop and lets the turn run. feedback also prepends a [watchdog] block to the session’s next prompt, telling the model what it is doing, and inside a turn tells it on the result of a call repeated with the same arguments and result, ending the turn as loop_stop if it keeps going (a loop inside one turn). enforce also cancels the turn in flight on a Critical alert (repeated-tool-call, alternating-tool-cycle) and refuses the session’s every subsequent turn until POST /sessions/{id}/guardrails/reset. Detection is identical in all three — only the reaction changes. Unset takes the workload’s safety.watchdog, then mast’s default (feedback); the startup line says which won. Applies to serve and one-shot mode, except feedback’s next-turn block, which needs a next turn a one-shot does not have (its in-turn loop guard still applies); a one-shot has no session to refuse either, so an enforce halt just ends the turn. With --attach-listen, an enforce halt is written to the session database and survives a daemon restart (and so does the reset that clears it); without one it lives only in the process, and the daemon warns at startup that it does. See where the posture comes from and a halt outlives the process.
--mcp-digesttrueRoute MCP tool responses through the structural digest before the model reads them. Responses under 8000 bytes are handed back untouched; larger ones are pruned, and the model gets a retrieve_raw tool to pull the original back when the digest dropped something it needs. --mcp-digest=false is the kill switch for the whole daemon; no_digest: true on a server in mcp.json opts out one server. See digesting large tool responses.
--log-levelinfodebug, info, warn, error (JSON logs on stderr).
--version—Print version and exit.

Set MAST_INJECT_TOKEN to require bearer auth on the HTTP endpoints; unset means unauthenticated (dev only, warned at startup). The attach surface has its own token, MAST_ATTACH_TOKEN — attach can read transcripts and inject operator messages, so treat it as a separate trust boundary from the inject webhook. The A2A surface has its own token too, MAST_A2A_TOKEN — a different auth model (per-skill scopes for external agent callers), so treat it as a third trust boundary. The AG-UI surface has its own token as well, MAST_AGUI_TOKEN — per-workload scopes for user-facing clients (CopilotKit apps, chat-platform bots), a fourth trust boundary.

Those four are all inbound: they let a caller drive this daemon. --notify-url is the one that points the other way — the daemon posting into a chat when a monitoring cycle has something to report:

Terminal window
MAST_INJECT_TOKEN=… MAST_NOTIFY_TOKEN=… mast --workload=cluster-watch \
--notify-url=http://switchboard:8080 --listen=:7777 --session-db=/var/lib/mast/sessions.db

The bearer comes from MAST_NOTIFY_TOKEN and there is deliberately no flag for it: a flag puts a credential in every ps on the node and in the container spec’s args. The daemon refuses to start if that token equals any of the four inbound ones — they authorize opposite directions, and sharing one means anything that can read the chat bridge’s configuration can inject turns here. Setting the token with no --notify-url is a startup warning, because it usually means half a rollout.

Which conversation to post into, and how long the workload may stay silent, are the bundle’s (monitor.notify.conversation, monitor.notify.digest_after) — they are properties of the workload, while the ingress and the credential are properties of the deployment.

A park is durable, and everything that discovers one is a pull: GET /parks, the attach stream, mast sessions show. An unattended workload on a fifteen-minute cadence can therefore park at 03:00 and wait until somebody thinks to look. --park-notify is the push:

Terminal window
MAST_INJECT_TOKEN=… MAST_NOTIFY_TOKEN=… mast --workload=cluster-watch \
--notify-url=http://switchboard:8080 --park-notify='#sre-oncall' \
--listen=:7777 --session-db=/var/lib/mast/sessions.db

One message per park, when the park opens, saying which session is waiting and what for, and ending with the mast sessions show line that prints the resume command. It is never repeated: this reports that a decision is pending, not that it is still pending.

The destination is a daemon flag and not a bundle field, which is the one difference from monitor.notify.conversation above and is deliberate. A monitoring cycle’s conversation is a property of the workload — it is the workload talking. A park announcement is mast talking about the workload, so letting the bundle route it would put the destination of “mast is asking permission” inside the thing being asked about.

Three more properties worth knowing before you point this at a channel:

  • It announces every park, not just the unwatched ones. mast does not check whether an operator happens to be attached when the park opens, because a park outlives the process and attachment right then predicts nothing about an hour later. The cost is a redundant message to somebody already watching; the alternative costs the 03:00 park nobody hears about.
  • The message carries the call’s arguments, elided. The park hint renders as Approve mutating call scale_deployment(deployment=api, replicas=10)?, with each value cut at 120 characters. A chat channel’s readership is not the session’s ACL — pick the conversation accordingly. The untruncated arguments never leave the confirmation record.
  • It has a budget of its own, three then one per five minutes, counted in mast_park_notifications_total. A workload that parks in a loop can exhaust its own announcements and nothing else — not the monitoring egress, which shares the client and nothing else. Dropped announcements are throttled; a failed send is error and an ERROR log line. Neither ever fails the turn: the park stays recorded and stays answerable whatever the chat ingress does.
mast sessions list --session-db=... [--user=...] [--state=paused|aborted|interrupted|idle]
mast sessions show <session-id> --session-db=...
mast sessions resume <session-id> --interrupt=<iid> --response='{"approved":true}' [--ack-effects] [--addr=...]
mast sessions resume --token=<mrt_...> [--response='<json>'] [--ack-effects] [--addr=... | --session-db=...]
mast sessions pause <session-id> --reason=<enum> [--message=...] [--resume-at=RFC3339 | --resume-after=15m]
[--cancel-turn] [--ttl=48h] [--addr=...]
mast sessions extend-token <mrt_...> --ttl=<duration> [--addr=...]
mast sessions abort <session-id> [--reason=...] [--addr=...]
mast sessions ack-effects <session-id> [--reason=...] [--addr=... | --session-db=...]
mast sessions export-decisions [<session-id>] --session-db=... [--workload=...]
[--since=RFC3339] [--until=RFC3339] [--include-approver] [--out=file.jsonl]

The split is deliberate:

  • list / show read the session DB directly (SQLite path) — they work with or without a running daemon. list prints one row per session with state (paused / aborted / interrupted / idle) and pending interrupt IDs; show prints session detail including each pending interrupt’s message, response schema, and a copy-pasteable resume command — plus, for a mutating call an operator edited, the arguments that actually ran and who authorized them (see the write gate). When the parked call belongs to a change set, show also lists the set’s other calls, the freshness re-read each one is subject to, and the --response that approves them all at once; if the call is being asked about a second time because an earlier approval stopped covering it, a Stale: line says why.
  • export-decisions reads the session DB directly too, and writes one JSON Lines record per operator adjudication — approve, reject, edit — with a _meta provenance header. Naming a session exports that session; omitting it exports every session in the store. Approver identities are digested unless you pass --include-approver, and the header records which mode produced the file. Tool arguments are exported verbatim, so an export is as sensitive as the arguments your tools take; --out writes 0600, and without it the rows go to stdout for piping. See exporting decisions.
  • resume / abort go through a running daemon (--addr, default http://127.0.0.1:7777) — resume must be executed by the runner that owns the workflow, and routing abort through the daemon keeps a single SQLite writer. Both send MAST_INJECT_TOKEN as a bearer when set.

pause gate-pauses a session: the daemon refuses every subsequent turn on it — inject, attach, resume, timer — until the pause is resumed, and prints a resume token (mrt_...). Token possession is the resume capability: resume --token=... needs nothing else (the daemon resolves the session), works for gate pauses and for the planner’s own pause_session parks alike, and consumes the token — a replay is a no-op. Add --cancel-turn to a pause to also cancel the session’s in-flight turn (hard pause). That flag was spelled --interrupt before v0.10; the old spelling is refused, and the refusal names the new one. It moved because resume --interrupt is an unrelated flag that takes an InterruptID — one name, two types, two meanings, on sibling subcommands — and v1.0 freezes flag names.

--resume-at / --resume-after arm the daemon’s timed-pause scheduler: the session auto-resumes at that time through the same budget-metered paths an operator resume takes. Tokens expire after 7 days by default (--ttl can only shorten that); an expired token refuses to resume but the pause stays — extend-token is the audited recovery, then resume again.

resume --token --session-db=... (no daemon) clears gate pauses only, and only on a DB no daemon is serving; an interrupt-pause resume always needs the daemon that owns the runner.

Every consumed token records who spent it — the consumed_by on the pause record, which is what a replay of the same token reports back (already consumed at 2026-08-19T14:02:11Z by shared-bearer-token) and what the daemon logs. It comes from the credential the resume presented, never from a name in the request body:

How the resume arrivedconsumed_by
Over HTTP with MAST_INJECT_TOKEN setshared-bearer-token
Over HTTP with a token from MAST_INJECT_USERS_FILEthat row’s identity, e.g. alice@example.com
A relay in MAST_INJECT_PROXY_IDENTITIES sending X-Asserted-Calleralice@example.com (asserted by sa:switchboard)
The daemon’s timed-pause schedulertimer
resume --token --session-db=... (no daemon)operator resume --token --session-db

shared-bearer-token is what a shared credential can honestly prove: that someone holding it resumed the session. Per-person attribution needs a per-person credential.

Point MAST_INJECT_USERS_FILE at a users file and /resume starts accepting each row’s token as well as the shared one, recording the person behind it:

{
"version": 1,
"users": [
{"identity": "alice@example.com", "token": "..."},
{"identity": "sa:switchboard", "token": "..."}
]
}

It holds bearer tokens, so it must be mode 0600 or stricter — or 0640 / 0440 when the owning group is one the daemon process belongs to. Any other-bit, and group write or execute in every case, is refused, and the daemon refuses to start rather than warning.

The group-read carve-out exists because Kubernetes leaves no alternative. fsGroup is the standard way to give a non-root pod read access to a Secret volume, and it sets group-read on every file in that volume unconditionally — so a Secret mounted at defaultMode: 0400 arrives as 0440, and mast’s own StatefulSet sets fsGroup: 65532. The membership test is the whole security argument: group-read widens access to members of the owning group and to nobody else, so when the daemon is already one of them the bit grants no read it did not already hold. Supplementary groups count, because fsGroup without runAsGroup lands the gid there rather than on the primary. When the daemon is not a member, the load still fails, and the error names the gid on both sides:

auth: users file "/etc/mast/users.json" has mode 0440 and is group-owned by
gid 2000, which this process (gid 65532) is not a member of; use 0600, or
set the Kubernetes fsGroup to a group the container runs as

MAST_INJECT_PROXY_IDENTITIES is a comma-separated list of identities in that table allowed to answer on someone else’s behalf via X-Asserted-Caller — a chat relay with an approve button is the case it exists for. Both are checked at startup: a proxy list with no table, or one naming an identity the table doesn’t have, refuses to boot rather than issuing 403s later.

The table says who did something a name belongs on; it is not a second way in. Two routes read it — /resume, where the name is who approved, and /monitor-ack, where it is who silenced a finding. /inject, /abort and the rest still take MAST_INJECT_TOKEN and nothing else.

MAST_INJECT_TOKEN keeps working alongside the table, and a resume that presents it is still recorded as shared-bearer-token — configuring a table does not retroactively attribute anything, and an emitter you haven’t migrated keeps working. To require attribution, leave MAST_INJECT_TOKEN unset: /resume then admits only the table’s tokens, and there is no unattributed way to answer a gate. (A request presenting the shared token and X-Asserted-Caller is refused outright rather than silently recorded as the shared credential — a token that can’t name its own holder doesn’t get to vouch for someone else’s.)

There is deliberately no approver field in the resume body. An attribution a caller writes about itself is worth nothing after an incident, so mast takes it from the credential instead — the same rule the write gate applies to its own approver.

/monitor-ack goes one step further and refuses a body carrying ack_by rather than ignoring it: on that route mast’s authentication is the only thing in front of the producer’s suppression, so a client that believed it had named someone is told it did not.

abort writes a durable abort marker with a reason, cancels the session’s in-flight turn, and the daemon refuses every further turn kind on the session — inject and attach included, not just resume (that narrower contract was v0.1’s). Aborting also voids the session’s pause tokens and timers. Markers live in a companion row beside the session, not in its transcript — an in-flight turn is never disturbed by an abort (or by a shutdown marker), and the model never sees marker events.

Resume takes either keying: interrupt ID (--interrupt + --response, printed by show) or a resume token (--token, the v0.2 programmatic-pause surface above).

interrupted marks a session whose turn was cut short by a daemon shutdown: on SIGTERM the daemon stops accepting new work (/inject and /resume answer 503 + Retry-After; new attach turns are refused; requests naming a reserved …:mast-ops ID answer 400 on all three write endpoints), drains in-flight turns for up to the workload’s budget.max_wallclock_seconds (30s without a budget), durably marking their sessions before waiting, and clearing the marker for turns that finish inside the window. The marker survives even a SIGKILL mid-drain. It is state, not preemption — the next turn on the session proceeds normally, and a session that reached a HITL pause reports paused, not interrupted.

On boot (and on by default — --auto-resume), the daemon scans for interrupted sessions and drives a continuation turn for each eligible one through the same chokepoint every other turn kind uses, so unattended work cut short by a restart finishes on its own. It needs a durable --session-db; in-memory sessions never survive a restart, so there is nothing to resume.

The guarantee is the operational form of exactly-once: auto-resume never double-fires a mutation. A session carrying any dangling mutating tool call (an ambiguous prior effect — see below) is skipped and left for an operator ack-effects, not resumed. A dangling read-only call is repaired with a synthetic interrupted before completion response and the turn re-runs; a transcript that already ended on a completed model turn just has its stale marker cleared (no spurious turn). Rails: --auto-resume-window (default 1h) skips work already stale at crash; a per-session restart-loop breaker plus a per-boot cap bound a poison session; and a session advanced by a concurrent inject between the scan and the turn is skipped. Slice-1 drives coordinator dispatch only. Every decision is counted in mast_autoresume_total{workload,outcome}. --pause-sessions on mast stop (below) opts a session out — a gate pause outranks interrupted, so those sessions are handed back to the operator instead of continued.

mast stop [--addr=...] [--reason=...] [--pause-sessions]

Asks a running daemon to drain and exit — exactly the SIGTERM path, with the interruption markers classified operator stop (plus --reason) instead of daemon shutdown, so transcripts distinguish a planned stop from a crash forever. --pause-sessions additionally gate-pauses every session the drain marks, so boot-time auto-resume hands them back to the operator instead of continuing them.

Daemon exit codes encode whether work was cut short, not who initiated: 0 = clean drain (all in-flight turns finished), 3 = drain window expired with interrupted survivors, 1 = error, 2 = usage, 4 = teardown watchdog fired (the post-drain unwind — an OTel flush or a Close — deadlocked past its 15s bound; the daemon dumps goroutine stacks to stderr and force-exits so a wedged shutdown surfaces a diagnostic instead of hanging until SIGKILL). Restart=always remains the default systemd guidance; Restart=on-failure now composes too — exit 3 revives the daemon exactly when boot-time repair has work to do, and a cleanly-drained stop stays down.

An interrupted turn can leave a dangling mutating tool call — a call whose outcome the log cannot prove. The recorded-effect outbox then runs the session’s next turn in ambiguous-effect mode: mutating and sub-run-spawning tool calls are refused with a structured ambiguous_prior_effect error (read-only work proceeds) until an operator acknowledges — asserting they checked whether the dangling calls took effect externally — or aborts the session. The acknowledgement surface is mast sessions ack-effects <id> (through the daemon by default, which serializes it against in-flight turns; --session-db writes directly when no daemon serves that DB, e.g. a one-shot task session — this direct path prints a warning because it cannot serialize against a running daemon, so use it only when none serves the DB), or resume --ack-effects when the session is also paused on an interrupt. Unknown tools — MCP tools included — count as mutating unless the workload’s tool_catalog.tools overrides them (see the workload bundle reference); the acknowledgement is recorded durably beside the session and covers only calls persisted up to that moment. Task delegations, HITL interrupts, and long-running calls never count as dangling effects. Task delegations are excluded by name (a delegation is a FunctionCall named after the sub-agent), so a mutating tool that shared a specialist’s name would slip past that exclusion — therefore mast refuses to start when a composed sub-agent name also names a mutating tool: rename one side (a read-only tool of the same name is harmless and allowed).

Two related contracts: the daemon runs one turn per session at a time — a second inject or resume for the same session queues behind the in-flight turn (bounded by the wallclock budget) rather than corrupting it; and every SQLite session store the tooling opens (serve, one-shot, the sessions CLI) carries the same write hardening, so concurrent access waits instead of failing.

With --a2a-listen, the daemon exposes its workloads to the A2A ecosystem — other agents can discover mast’s skills from an agent card and drive them over a standard JSON-RPC endpoint. It runs on its own listener, separate from the inject webhook and the operator attach surface.

A workload opts in per bundle (exposure has real ops implications — auth setup, an external contract, cross-org discoverability, so it is never automatic):

.agents/workloads/incident-triage.yaml
a2a:
expose: true
skill_name: incident-triage
skill_description: Investigate GKE pod-failure incidents.
auth:
scopes: [incident-triage.invoke]

Discovery is public. An aggregated agent card at /.well-known/agent-card.json lists every exposed workload as a skill; per-workload cards at /.well-known/agent-card/<name>.json serve registries that require a distinct endpoint per agent. Cards advertise JSON-RPC as the preferred transport and the tested-against A2A spec line (A2A-Version header).

Invocation is the single POST /a2a JSON-RPC 2.0 endpoint. It serves:

  • message/send — run a turn (a task id is a mast session id). Execution is synchronous: the call blocks and the reply is a terminal task. The agent’s answer surfaces as a result text artifact; the in-process task registry then reports completed (which a transcript read cannot prove). A message with a taskId continues that task; without one it routes to the single exposed skill and mints a fresh task (an endpoint exposing more than one skill refuses a selector-less fresh send with -32004). The server assigns a contextId when the caller omits one, returned on the task so follow-ups can be grouped. Text-only for now — a message with no text parts is rejected (-32602). If the turn pauses for a HITL interrupt the task returns input-required; if the session is aborted or gate-paused the call is refused at the chokepoint and the task reports its durable state; while draining for shutdown, new sends are refused with the retryable -32000.
  • tasks/get — snapshot a task’s state. The registry is consulted first (it alone can prove completed/failed), falling back to the session’s log-proven state projected onto the A2A lifecycle (working, input-required when a HITL interrupt is pending, canceled when aborted). A transcript-only read never reports completed — the event log cannot prove a turn finished versus is still in flight.
  • tasks/cancel — cancel a task idempotently, routing to the same terminal-abort path the operator abort uses. Cancel is authoritative: a task canceled as its turn finishes still reports canceled, never a leaked answer.
  • message/stream — run a turn like message/send, but stream its progress as Server-Sent Events (text/event-stream), one JSON-RPC response per data: frame: an initial Task snapshot, then a status-update per model response carrying its text as progress, then the closing artifact-update (the agent’s answer) and a final status-update (final: true) with the terminal state. Updates are message-granular (one per model response, not token deltas). Auth, scope, and rate-limit refusals are decided before the stream opens, so a refusal is a normal JSON-RPC error, not a truncated stream. The card advertises capabilities.streaming: true.

These verbs address only tasks this server minted (ids carrying the a2a- prefix); any other session id — an operator incident, an attach or autoresume session — is reported as not found (-32001), so a caller cannot reach another surface’s session through the A2A endpoint.

Distributed tracing. A2A calls propagate W3C trace context: an inbound traceparent/baggage header is adopted so the turn’s spans parent under the caller’s span, and mast’s own outbound A2A client calls inject the current trace context. This is a no-op when tracing is disabled.

Auth. Card endpoints are always public (a card is a descriptor, not a capability). The /a2a endpoint is authenticated when MAST_A2A_TOKEN is set — a request without a valid bearer is refused 401, and a call whose token lacks a skill’s declared auth.scopes is refused 403. One token means one principal: MAST_A2A_TOKEN resolves to a single subject holding the union of every exposed skill’s scopes, so the 403 above is unreachable on a daemon configured this way. Per-skill scopes start discriminating when the embedding host supplies its own serverauth.TokenValidator — see scopes and the shared token below. Unset means unauthenticated (dev only, warned at startup) — and because tasks/cancel is destructive, a non-loopback --a2a-listen bind (anything but 127.0.0.1/localhost/::1) is refused at startup without a token; bind loopback or set MAST_A2A_TOKEN. The token model is deliberately separate from the inject and attach tokens: A2A callers are external agents scoped per skill, not operators.

Rate limiting. External callers can consume the agent’s provider budget through message/send and message/stream, so both turn-driving verbs are rate limited (they share one bucket per caller and workload). Set MAST_A2A_RATE to the allowed requests/second per caller and workload, and optionally MAST_A2A_BURST for the bucket depth (defaults to ceil(rate), minimum 1):

Terminal window
MAST_A2A_RATE=5 MAST_A2A_BURST=10 mast --a2a-listen=127.0.0.1:7780 ...

The caller is the token’s tenant claim if present, else its subject; an unauthenticated endpoint buckets all callers together. A refused send returns the retryable -32000 error with an advisory Retry-After header. MAST_A2A_RATE unset means no rate limiting; a set-but-malformed value fails startup. Control-plane verbs (tasks/get, tasks/cancel) are never rate limited — an operator can always read or cancel a task.

With --agui-listen, the daemon exposes its workloads to the AG-UI ecosystem — the agent↔user protocol CopilotKit React apps and chat-platform bots speak. A client POSTs a RunAgentInput and receives the turn back as a Server-Sent Events (text/event-stream) run stream. It runs on its own listener, separate from the inject webhook, the attach surface, and the A2A endpoint (mast has no single shared HTTP root — each surface owns its listener).

A workload opts in per bundle (like A2A, exposure carries real ops implications — auth setup, a public turn-driving endpoint, user-facing UX — so it is never automatic):

.agents/workloads/incident-triage.yaml
agui:
expose: true
endpoint_path: /agui/incident-triage # defaults to /agui/<name>
description: Investigate GKE pod-failure incidents.
session_model: per_thread # or per_run
state_projection: [plan, phase] # empty (default) publishes no state
emit_reasoning: false # default — no reasoning frame at all
auth:
scopes: [incident-triage.run]

Discovery is public: GET /agui/agents.json lists every exposed workload as {name, endpoint, description, input_schema, protocol_version, auth: {required, scopes}, capabilities: {…}}. AG-UI has no standardized well-known path (unlike A2A’s agent card), so this descriptor is a mast convention for clients that want to discover-then-connect.

capabilities says which of the optional frame families a run on that workload can contain, which the protocol version cannot: these are per-bundle publication decisions, so two workloads on one daemon can differ on every field.

{
"name": "incident-triage",
"endpoint": "/agui/incident-triage",
"protocol_version": "0.1",
"auth": { "required": true, "scopes": ["incident-triage.run"] },
"capabilities": {
"state_delta": true,
"state_keys": ["plan", "phase"],
"reasoning": false
}
}
FieldMeaning
state_deltaWhether a run can emit StateDelta frames beyond the opening StateSnapshot. false (the default) means a client never sees a patch and can skip wiring a reducer. Reflects agui.state_projection.
state_keysThe top-level keys those patches may touch, in the order the bundle declares them, so a client can lay out panels before the first patch. Omitted when state_delta is false. Not a promise every key is written — a key the run never sets produces no patch.
reasoningWhether a run can emit the REASONING_* phase bracket. false means no reasoning frame of any kind, so don’t render a “thinking” affordance at all. Reflects agui.emit_reasoning.

The two booleans are always present, never elided when false: an absent key means a server older than this object, an explicit false is a live promise that the frame family will not appear, and a client needs to tell those apart.

There is no bit for the STEP_* bracket, and that is the same reasoning read the other way: every workload emits it, so there is nothing per-bundle to report. A frame family that is uniform across a daemon belongs to the protocol version, not to this object — and protocol_version does not move for it, because STEP_STARTED / STEP_FINISHED are core AG-UI vocabulary a 0.1 client already has to tolerate.

Adding capabilities did not move the document behind the token. The rule it follows is that this descriptor may state what a client permitted to run would observe in the stream anyway — reasoning from the first ReasoningStart, the key names from the paths in the first StateDelta — and may not state a property of the governance around the stream. That is why there is no HITL bit: an unauthenticated “this workload does not park mutations for a human” describes what fires unattended here, and a caller who never gets a run to park would never observe it.

Invocation is a POST to each workload’s endpoint_path. The body is an AG-UI RunAgentInput; the response is the run streamed as SSE frames: RunStarted, then a StateSnapshot echoing the client’s input state, then the model’s answer as a TextMessage triad (TextMessageStart/Content/End) with ToolCallStart/Args/End and ToolCallResult frames for any tool activity — all of it inside a StepStarted/StepFinished bracket naming the agent that produced it — then exactly one terminal frame — RunFinished on success (outcome: {type: "success"}) or on a HITL pause (outcome: {type: "interrupt", interrupts: […]}), or RunError (aborted when the session was aborted or gate-paused, internal on a runner error). Updates are message-granular (one text message per model response, not token deltas). The session id is always derived by the daemon from the AG-UI threadId/runId and namespaced under agui- — a client never supplies a raw session id, and an id that would collide with a reserved …:mast-ops row is refused before the stream opens. session_model picks the mapping: per_thread (the default — one continuing session per thread, matching chat UX) or per_run (a fresh session per run, for stateless one-shots).

Steps. A run brackets its work with StepStarted / StepFinished frames, and the step name is the agent that authored that stretch of the run. A single-agent workload therefore produces one bracket around the whole run; a coordinator that hands off to a specialist produces one per handoff, so a client can show which agent is working without parsing tool calls. The brackets are flat — a step closes before the next one opens, and the open one closes before the terminal frame, on every disposition including an abort and a HITL pause. Under a parallel fan-out the workers’ events interleave on one stream, so the same name can bracket more than once; that is the arrival order, not a nesting. There is no switch for this — unlike the two keys below, a step publishes nothing a caller permitted to run could not already read off the stream, since a handoff arrives as a transfer_to_agent / invoke_specialist tool call naming the same agent. One thing steps do not cover: a planner dispatch runs its specialist on a private stream, so you see the invoke_specialist tool call and no step inside it.

State. By default the only state frame a client sees is that opening StateSnapshot, which is the client’s own input state echoed back — mast publishes none of the session state the run itself writes. A workload opts in per key with agui.state_projection: [plan, phase]; a write to a named key then arrives as a StateDelta carrying RFC 6902 patches ({"op": "add", "path": "/plan", "value": …}, keys sorted). A key that is not on the list produces no operation at all, so a client cannot tell that it changed. This is an allowlist on purpose: session state carries whatever the run put there, approval grants and captured change sets included. The daemon logs the enabled list at startup, so what a workload publishes can be read off the log rather than off the bundle you believe is mounted; an empty or duplicated entry is refused before the listener binds.

Reasoning. By default a client sees none of the model’s thinking, and agui.emit_reasoning: true publishes it as the spec’s phase bracket around a message triad: ReasoningStart, then ReasoningMessageStart/Content/End carrying one message per model response, then ReasoningEnd — emitted before the answer’s TextMessage triad, because that is the order the provider streamed the parts in. Off emits nothing at all, not an empty bracket: the existence of a thought is itself a disclosure. The opt-in is per workload and the daemon logs a warning at startup rather than the projection’s informational line, because a state allowlist is a list someone curated and this is an unbounded channel from the model’s private working-out. Two things it never publishes under either setting: the provider’s thought signature, which is a replay credential rather than a thought (so AG-UI’s ReasoningEncryptedValue event is deliberately not implemented, and a signature-only block produces no frame), and the answer stream — a thought never becomes TextMessage content or RunFinished.result. Expect an opted-in workload to be quiet for now: under the request mast sends today claude-opus-5 returns a thinking block whose body is empty.

HITL. A turn that parks for human input closes the stream with a terminal RunFinished whose outcome.type is interrupt, listing each pending interrupt as {id, message, responseSchema?, expiresAt?} (projected from the durable session’s pending-interrupt state — not a fabricated success). The client resumes by starting a new run whose RunAgentInput.resume carries one entry per interrupt ({interruptId, status: "resolved" | "cancelled", payload?}); the daemon reconciles each entry against the session’s open interrupt ids and drives the resume turn through the same chokepoint. A resume that references no open interrupt (or an unknown id) is refused 409 rather than silently forking a fresh turn. A resume run may carry an empty input — the resume array alone drives it. Under session_model: per_run (where the session is keyed on runId) the resume must also carry parentRunId naming the run that parked, so the daemon can reach the parked session; under the default per_thread the shared threadId already reaches it.

Per-key state deltas, client-declared tools, and the agui:// federation client are follow-on stages.

Auth. The discovery descriptor is always public. Each run endpoint is authenticated when MAST_AGUI_TOKEN is set — a request without a valid bearer is refused 401, and a token lacking a workload’s declared auth.scopes is refused 403, which on a daemon holding one shared token is unreachable — see scopes and the shared token. Unset means unauthenticated (dev only, warned at startup) — and because a run drives a budgeted turn, a non-loopback --agui-listen bind is refused at startup without a token; bind loopback or set MAST_AGUI_TOKEN.

Rate limiting. A run consumes the agent’s provider budget, so runs are rate limited per caller and workload. Set MAST_AGUI_RATE to the allowed requests/second, and optionally MAST_AGUI_BURST for the bucket depth (defaults to ceil(rate), minimum 1):

Terminal window
MAST_AGUI_RATE=5 MAST_AGUI_BURST=10 mast --agui-listen=127.0.0.1:7781 ...

A refused run returns HTTP 429 with an advisory Retry-After header (AG-UI has no JSON-RPC error envelope, so refusals ride HTTP status). MAST_AGUI_RATE unset means no rate limiting; a set-but-malformed value fails startup.

Concurrent runs. Rate limiting bounds arrivals, not what is already running: one caller can hold N runs open on a thread as long as they arrive slowly enough. A thread runs one turn at a time and queues the rest, bounded by agui.run_queue.depth (default 3 waiting plus the one executing). The run past that is refused 409 with a Retry-After, before the stream opens — a distinct status from the rate limiter’s 429 on purpose, since “this thread is busy” and “you are calling too fast” have different remedies.

Both token-authenticated surfaces check scopes per workload, and under the validator the daemon builds for itself, neither check can fail. This is worth knowing before you design a scope scheme around it.

MAST_A2A_TOKEN and MAST_AGUI_TOKEN are each one token. Each resolves to one principal, carrying the union of every exposed workload’s declared scopes — necessarily so, because that one token has to be able to drive all of them. The scope loop still runs on every call; it has no reachable failing branch. So on a daemon configured this way:

  • You cannot express “this token runs the reporting workload but not the deploying one.” There is one token, and it carries both scopes.
  • auth.scopes in /agui/agents.json states the workload’s requirement, not a property of any token mast hands out. The sentence is true; the natural reading of a published per-workload scope list — that tokens differ per workload — is not.
  • AG-UI thread ownership separates deployments, not users. The caller tag folded into a derived session id hashes the principal’s tenant and subject, and here those are constants. Two browsers sharing the token share the thread.
  • Rate-limit buckets are per workload, not per caller, for the same reason: every request arrives as the same subject.

What changes all four at once is a host-supplied token validator. The serverauth.TokenValidator seam is real and needs no change to either server: an embedding host that validates its own users’ tokens gets discriminating scopes, per-user thread ownership, per-caller rate limiting and a meaningful subject in the audit trail, immediately.

A single shared bearer token remains a defensible default for a single-tenant daemon, which is why it is the default. A daemon-side multi-token form — a token→{subject, scopes} map instead of one environment variable — is tracked as #389 and is not blocked by the v1.0 freeze: these are environment variables, which the promise does not cover.