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 (the daemon)
Section titled “mast (the daemon)”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.
| Flag | Default | Meaning |
|---|---|---|
--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. |
--model | echo | echo (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 | :7777 | HTTP 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-driver | sqlite | sqlite 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. |
--timeout | 5m | One-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-resume | true | On 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-window | 1h | Only 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-digest | true | Route 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-level | info | debug, 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.
Chat egress for monitoring cycles
Section titled “Chat egress for monitoring cycles”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:
MAST_INJECT_TOKEN=… MAST_NOTIFY_TOKEN=… mast --workload=cluster-watch \ --notify-url=http://switchboard:8080 --listen=:7777 --session-db=/var/lib/mast/sessions.dbThe 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.
Announcing a park
Section titled “Announcing a park”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:
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.dbOne 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 arethrottled; a failed send iserrorand an ERROR log line. Neither ever fails the turn: the park stays recorded and stays answerable whatever the chat ingress does.
mast sessions (operator surface)
Section titled “mast sessions (operator surface)”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/showread the session DB directly (SQLite path) — they work with or without a running daemon.listprints one row per session with state (paused/aborted/interrupted/idle) and pending interrupt IDs;showprints 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,showalso lists the set’s other calls, the freshness re-read each one is subject to, and the--responsethat approves them all at once; if the call is being asked about a second time because an earlier approval stopped covering it, aStale:line says why.export-decisionsreads the session DB directly too, and writes one JSON Lines record per operator adjudication — approve, reject, edit — with a_metaprovenance 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;--outwrites0600, and without it the rows go to stdout for piping. See exporting decisions.resume/abortgo through a running daemon (--addr, defaulthttp://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 sendMAST_INJECT_TOKENas a bearer when set.
Pause and resume tokens (v0.2)
Section titled “Pause and resume tokens (v0.2)”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.
Who a resume names
Section titled “Who a resume names”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 arrived | consumed_by |
|---|---|
Over HTTP with MAST_INJECT_TOKEN set | shared-bearer-token |
Over HTTP with a token from MAST_INJECT_USERS_FILE | that row’s identity, e.g. alice@example.com |
A relay in MAST_INJECT_PROXY_IDENTITIES sending X-Asserted-Caller | alice@example.com (asserted by sa:switchboard) |
| The daemon’s timed-pause scheduler | timer |
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.
Naming people on the daemon
Section titled “Naming people on the daemon”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 bygid 2000, which this process (gid 65532) is not a member of; use 0600, orset the Kubernetes fsGroup to a group the container runs asMAST_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 (terminal since v0.2)
Section titled “Abort (terminal since v0.2)”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.
Boot-time auto-resume
Section titled “Boot-time auto-resume”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 (planned stop)
Section titled “mast stop (planned stop)”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.
A2A server
Section titled “A2A server”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):
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 aresulttext artifact; the in-process task registry then reportscompleted(which a transcript read cannot prove). A message with ataskIdcontinues 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 acontextIdwhen 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 returnsinput-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 provecompleted/failed), falling back to the session’s log-proven state projected onto the A2A lifecycle (working,input-requiredwhen a HITL interrupt is pending,canceledwhen aborted). A transcript-only read never reportscompleted— 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 operatorabortuses. Cancel is authoritative: a task canceled as its turn finishes still reportscanceled, never a leaked answer.message/stream— run a turn likemessage/send, but stream its progress as Server-Sent Events (text/event-stream), one JSON-RPC response perdata:frame: an initialTasksnapshot, then astatus-updateper model response carrying its text as progress, then the closingartifact-update(the agent’s answer) and a finalstatus-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 advertisescapabilities.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):
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.
AG-UI server
Section titled “AG-UI server”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):
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 }}| Field | Meaning |
|---|---|
state_delta | Whether 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_keys | The 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. |
reasoning | Whether 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):
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.
Scopes and the shared token
Section titled “Scopes and the shared token”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.scopesin/agui/agents.jsonstates 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.