Workload bundle schema
A workload bundle is the declarative operational profile for a mast
deployment: one YAML file naming the specialists, tool catalog, budget,
HITL policy, and edge trigger for one named workload. Bundles live at
.agents/workloads/<name>.yaml (see .agents/ discovery)
or in a workload directory passed to --workload=<path>.
This page documents the v0.1 subset — exactly the fields the shipped
loader parses. The canonical full schema lives in
docs/orchestration-design.md;
fields beyond this subset (planner review knobs, isolation scope, bundle
learning) land with their subsystems.
Example
Section titled “Example”name: gke-triagedescription: Autonomous triage of GKE cluster incidents.mode: single_session
tool_catalog: mcp: - server: gke tools: - name: list_clusters mutating: false
specialists: - triage-classifier - CrashLoopBackOff - ImagePullBackOff - _fallback
budget: max_wallclock_seconds: 300 max_turns: 20 max_cost_usd: 5.00
hitl: require_approval: true
safety: watchdog: enforce
builtin_tools: web_search: true
prompt_cache: ttl: 5m
planner: enabled: false
edge_trigger: http: path: /inject auth: bearer scheduled: interval: 15m jitter: 45s prompt: Sweep every namespace for pods in CrashLoopBackOff and report what you find.
a2a: expose: true skill_name: incident-triage skill_description: Investigate GKE pod-failure incidents. auth: scopes: [incident-triage.invoke]
agui: expose: true endpoint_path: /agui/incident-triage description: Investigate GKE pod-failure incidents. session_model: per_thread state_projection: [plan, phase] emit_reasoning: false run_queue: depth: 3 auth: scopes: [incident-triage.run]Fields
Section titled “Fields”| Field | Type | Notes |
|---|---|---|
schema_version | int | Which bundle schema this file is written for. Currently 1, and omitting it means 1 — every bundle written before the key existed loads unchanged. A version this mast does not speak is a load error naming both numbers. See schema_version: below. |
name | string | Required. Unique per deployment; used as the workload metric label. |
description | string | Human-readable; used in operator UIs and logs. |
mode | string | single_session (default) or multi_session. Multi-session is vocabulary-only in v0.1 — declared intent, honored when the multi-session substrate lands (v0.2). |
tool_catalog.mcp[].server | string | MCP server references, by name from the deployment’s mcp.json (HTTP or local stdio). Intersected against per-specialist tool allowlists at dispatch time. |
tool_catalog.tools[].name | string | Tool name a per-tool policy override applies to. Names must be unique. |
tool_catalog.tools[].mutating | bool | Overrides the tool’s mutation classification for the recorded-effect outbox. This override is read before every other source, including an MCP server’s own readOnlyHint, so it is how you pin a tool your server classifies differently. Below it, an MCP tool is read-only if its server says so and mutating otherwise — including when the server publishes no annotation, which is indistinguishable on the wire from publishing false. Omitted means no override. Every applied override is audit-logged at startup. |
tool_catalog.tools[].precondition | block | Optional. The re-read that decides whether an approval of this tool’s call is still fresh when the call finally fires — see precondition: below. Only consulted for calls covered by a change_set grant; a call the operator is answering right now needs no freshness check. |
tool_catalog.tools[].precondition.read | string | Required in the block. The tool to re-read with. It must be declared mutating: false in the same catalog — a freshness check that changes the cluster is not a check — and since an unlisted tool is mutating by default, an undeclared read fails at startup rather than at the incident. |
tool_catalog.tools[].precondition.args | map | Fixed arguments for the read, e.g. {namespace: prod}. |
tool_catalog.tools[].precondition.args_from | map | Arguments taken from the change itself: {name: deployment} reads the read’s name from this call’s deployment. This is what lets each call in a set be checked against its own object. |
tool_catalog.tools[].precondition.fields | list of strings | Dotted paths into the read’s result that must not have moved. Omitted means the whole result is digested. For an MCP tool every path starts output. — that is how a structured MCP result arrives. |
tool_catalog.tools[].capture | block | Optional. What to record before a call to this tool changes anything, so that “how do I undo this” has an answer in the transcript — see capture: below. Consulted on every path a mutating call can take to the tool, not only the gated ones. |
tool_catalog.tools[].capture.read | string | Required in the block. The read-only tool that records the prior state. Same rule as a precondition read, for a sharper reason: mast refuses to start rather than run a recording that changes what it records. It also may not be the changing tool itself — by the time that has run there is no prior state left to read. |
tool_catalog.tools[].capture.args | map | Fixed arguments for the read. |
tool_catalog.tools[].capture.args_from | map | Arguments taken from the change: {name: deployment} reads the read’s name from this call’s deployment. |
tool_catalog.tools[].capture.fields | list of strings | Dotted paths into the read’s result to record. Omitting them records the whole result — the opposite of a precondition’s default, and deliberately so: a capture that kept too little cannot restore, and the cost of keeping too much is a bigger row. |
tool_catalog.tools[].capture.revert | block | Optional. The call that puts the captured state back. Omitting it is honest rather than incomplete — the record still carries the old value, and mast sessions show says in as many words that this workload declares no way back. |
tool_catalog.tools[].capture.revert.call | string | Required in the block. The tool that performs the undo — often the changing tool itself. It must be classified mutating: a call that changes nothing cannot undo a change, and offering one as a way back during an incident is worse than offering none. |
tool_catalog.tools[].capture.revert.args | map | Fixed arguments for the revert call. |
tool_catalog.tools[].capture.revert.args_from_change | map | Revert arguments taken from the change — how the undo addresses the same object the change addressed. |
tool_catalog.tools[].capture.revert.args_from_capture | map | Revert arguments taken from the recorded state, by dotted path: the old values, going back. A revert that names none of these is refused at load, because it re-applies the change rather than undoing it. |
specialists[] | list of strings | Specialist names; resolve against the config root’s specialists/*.specialist.md. A roster with a SingleTurn classifier plus a _fallback Task specialist enables graph dispatch. |
dispatch | string | The root shape this roster is built for: coordinator, graph, fanout, bounded, or auto. Empty leaves the choice to the caller. auto never picks bounded — a cost ceiling is declared, never inferred. A shape is a property of the roster, not of how the daemon happened to be launched, so the bundle is where it belongs — --dispatch overrides it only when an operator actually typed the flag. |
fanout.max_concurrency | int | Under dispatch: fanout, how many analyst branches run at once. 0 (omitted) means the default, 4; a negative value means unbounded. Ignored under any other dispatch. |
budget | block | See below. |
hitl.require_approval | bool | When true, every specialist result pauses on a durable RequestInput interrupt until an operator resumes with a verdict. |
hitl.on_mutation | string | What happens before a call that would change something: require_approval (the default — the call parks on a durable interrupt, with its arguments, and fires only once an operator approves it), apply (run it, unattended), or dry_run (never run it; report what would have happened). Because this defaults to gating, a bundle that says nothing about mutation does not get to write; unattended writes have to be asked for. The block may also be spelled hitl_policy:; setting both is an error. See the write gate for the verdict an operator sends back. |
hitl.change_set_ttl | duration | How long an approval given with scope: change_set authorizes the set’s remaining calls for. Default 10m — far longer than an approve-then-execute round trip, far shorter than the span over which an operator forgets what they approved. It is the backstop, not the check: what an approval is really bounded by is the precondition: the tool declares. |
safety.watchdog | string | The runaway-loop posture this workload ships with: warn (log only), feedback (mast’s default when nothing declares one — tell the model on its next turn, and end a turn whose model keeps repeating one call after being told), or enforce (also cancel the turn in flight and refuse every later turn until an operator resets). Unset is not warn: it means leave it to the host, which is what keeps --watchdog able to override a bundle in both directions. Precedence is --watchdog > safety.watchdog > the default, and the daemon logs which won at startup. Declare enforce on a workload whose tool loop is bounded by construction; see where the posture comes from. |
builtin_tools.web_search | bool | The provider’s server-side web search, run inside the vendor’s infrastructure. Omitted means off, on every provider. See builtin_tools: below — this is reach the permissions gate cannot see, so mast makes you ask for it. |
builtin_tools.url_context | bool | The provider’s server-side URL fetch-and-ground. Omitted means off. Gemini only; no Anthropic equivalent, and a bundle that asks for it on Claude gets nothing rather than an error. |
builtin_tools.code_execution | bool | Sandboxed code execution on the provider’s servers. Omitted means off. Gemini only. |
prompt_cache.enabled | bool | Claude prompt caching. Omitted means on; false turns it off. Anthropic only; see prompt_cache: below. |
prompt_cache.ttl | string | Breakpoint lifetime: 5m (default) or 1h. Any other value refuses the bundle. A 1-hour write bills at 2x base input against 1.25x, so it pays only when turns are routinely more than five minutes apart. |
planner.enabled | bool | v0.1 scaffold: switches the root agent to the supervisor-body planner with the bundle’s specialists as its invoke_specialist roster (--dispatch is then ignored). The planner’s run_shape_* vocabulary tools return not_implemented until v0.2. |
edge_trigger.http.path, .auth | strings | Informational, and not wired — the inject server declares its routes globally and reads nothing from the bundle; per-workload path prefixes come later. Declaring a path does not create one: POST your envelope to /inject. A bundle that declares one is warned about at startup, and the declared path answers 404 naming the real route. See a declared path is not a route. |
edge_trigger.scheduled.interval | duration | Required in the block. How often the workload wakes itself, with nothing calling in — 15m, 1h, 24h. Minimum 1s. A malformed or missing value is a load error naming the file, because a cadence that fails to parse at runtime is a workload you believe is running and that never wakes up. See scheduled: below. |
edge_trigger.scheduled.jitter | duration | Optional random offset added to each fire, drawn afresh every time. Defaults to a tenth of the interval, capped at 30s; 0s is honored as a declaration. Must be shorter than the interval. It is not decoration: N replicas started by one rollout otherwise wake on the same second. |
edge_trigger.scheduled.prompt | string | What the workload is being woken up to do. Delivered as prose after the wake-up envelope, so it reaches the roster as you wrote it. A schedule with no prompt runs the roster against the envelope alone, which is a workload guessing at its own job. |
monitor.collect[].tool | string | Required in each entry. A wired tool mast runs on its own behalf at the top of each scheduled cycle, before the model is woken; the results arrive in the wake-up envelope under collected. Requires an edge_trigger.scheduled block — a collection with no cadence never runs. No tool named here may be reachable from any specialist’s allowlist, and the daemon refuses to start if one is. See monitor: below. |
monitor.collect[].args | map | Literal arguments for the call, e.g. {transitions: "new,escalated,resolved"}. There is no args_from: a collection call is not about any particular object, so there is nothing to map arguments from. |
monitor.collect[].as | string | The key this call’s result is filed under in the envelope. Defaults to the tool name; needed only when one workload collects from the same tool twice. Two entries filed under one key is a load error. |
monitor.transitions_from | string | Optional. Names the monitor.collect key whose result carries the run-to-run classification — what is new, escalated, resolved since the last cycle. That result is parsed into the envelope’s transitions block instead of being passed through raw. Must name a key some collect entry files a result under, or it is a load error. It names where the classification comes from, never what it may say: mast has no vocabulary of transition classes. See transitions_from: below. |
monitor.notify.conversation | string | Required when a notify: block is present. Where a speaking cycle posts — the conversation id switchboard knows, e.g. #sre-oncall or a platform id. Requires an edge_trigger.scheduled block, for the same reason collect does: a cycle speaks at the end of a cycle, so with no cadence it never speaks. The ingress URL and its bearer token are the daemon’s (--notify-url, MAST_NOTIFY_TOKEN), not the bundle’s — deployment facts, so one bundle moves between staging and production unedited. See notify: below. |
monitor.notify.digest_after | duration | Optional deadman. After this long with nothing sent, the next cycle speaks whether or not anything changed. Omitted or 0s = no deadman, and the workload may stay silent indefinitely. Wall-clock, not a count of quiet cycles: a monitor that has been quiet for a week is otherwise indistinguishable from one that died a week ago. |
monitor.ack.tool | string | Optional. The wired tool an operator’s acknowledgement is forwarded to, which arms POST /monitor-ack on the daemon; without the block that route answers 404. Unlike collect and notify it needs no cadence — an ack arrives from an operator, not from a cycle. Fenced like a collect tool (reachable from no roster), and refused if it is also a collect tool: a cycle that acked what it just classified would suppress findings nobody asked to suppress. See ack: below. |
monitor.ack.args | map | Literal arguments merged under the two mast supplies from the request itself, subject_key and ack_by. Deployment policy goes here — which cluster, how long a suppression lasts. Pinning either reserved name is a load error: a bundle that named the acker would name them for everyone. |
a2a.expose | bool | Opt this workload into the A2A server surface (--a2a-listen). Default false — A2A exposure is an external contract, so it is never automatic. |
a2a.skill_name, a2a.skill_description | strings | The skill id/name and human-readable summary published on the agent card. skill_name defaults to the workload name; skill_description to the workload description. |
a2a.input_schema, a2a.output_schema | maps | A mast-side convention only: mast may validate inbound task inputs against them and fold them into the skill description. Spec AgentSkill has no schema fields, so they do not round-trip through the agent card as machine-readable schema. |
a2a.auth.required, a2a.auth.scopes | bool, list of strings | Per-skill auth policy. scopes are enforced per call when a token validator is configured (MAST_A2A_TOKEN): a caller whose token lacks a scope is refused 403. MAST_A2A_TOKEN is one token carrying every exposed skill’s scopes, so that 403 needs a host-supplied validator to become reachable — see scopes and the shared token. |
agui.expose | bool | Opt this workload into the AG-UI server surface (--agui-listen). Default false — like A2A, AG-UI exposure is a public turn-driving endpoint, so it is never automatic. |
agui.endpoint_path | string | The HTTP path the workload’s run endpoint is served at. Must start with /. Defaults to /agui/<name>. |
agui.description | string | Surfaced in the /agui/agents.json discovery descriptor; defaults to the workload description. |
agui.session_model | string | How a run maps to a mast session: per_thread (default — one continuing session per AG-UI threadId, matching chat UX) or per_run (a fresh session per runId, for stateless one-shots). The daemon always derives and namespaces the session id; a client never supplies a raw one. |
agui.input_schema | map | A mast-side convention only: an optional JSON-Schema-shaped hint surfaced in the discovery descriptor so a client can render an input form. AG-UI’s RunAgentInput has no schema field, so it does not constrain the wire input. |
agui.state_projection | list of strings | Allowlist of runtime state keys published to the client as StateDelta patches. Empty (the default) publishes nothing. A key on the list is emitted as an RFC 6902 {"op": "add", "path": "/<key>", "value": …} whenever the run writes it; a key not on the list produces no operation at all, so a client cannot tell that it changed. Treat this as a publication decision, not a display preference: session state holds whatever the runtime put there, including approval grants and captured change sets, and the AG-UI client is a browser. An empty or duplicated entry is refused at startup; a key the workload never happens to write is accepted. The enabled list is advertised on the public discovery descriptor as capabilities.state_keys, so a client can lay out its panels before the first patch. |
agui.emit_reasoning | bool | Whether this workload streams the model’s thinking to its AG-UI clients, as the spec’s REASONING_START / REASONING_MESSAGE_* / REASONING_END frames. Defaults to false, and false emits nothing at all — not an empty phase bracket, not a redaction marker, so a client cannot learn that the model deliberated. A chain of thought is not a draft of the answer: it is where the model talks itself out of things, and where a prompt injection shows its working. The answer is addressed to the user; the reasoning is addressed to nobody. Turning it on is a decision about a browser-reachable surface, and the daemon logs a warning at startup naming the workload. The provider’s thought signature is never published under either setting — it is a replay credential, not a thought — so a thinking block with a signature and no prose produces no frame. The setting is advertised on the public discovery descriptor as capabilities.reasoning, so a client knows before a run whether to render a “thinking” affordance at all. |
agui.run_queue.depth | int | How many runs may wait on one AG-UI thread while another is executing. Defaults to 3, so a thread admits four at once and the fifth is refused with 409 and a Retry-After before the stream opens — see run_queue: below. 0 is legal and means no concurrency: one run at a time per thread, the rest refused. A negative value is refused at startup. |
agui.auth.required, agui.auth.scopes | bool, list of strings | Per-endpoint auth policy. scopes are enforced per run when a token validator is configured (MAST_AGUI_TOKEN): a caller whose token lacks a scope is refused 403. The list is also published on the discovery descriptor, where it states this workload’s requirement — not a property of any token mast issues. MAST_AGUI_TOKEN is one token holding every exposed workload’s scopes, so on a daemon configured that way the 403 is unreachable: see scopes and the shared token. |
schema_version: — and why an unknown key is refused
Section titled “schema_version: — and why an unknown key is refused”The bundle is edited by operators who never import Go, so it versions on its own clock rather than mast’s (stability). The current schema is 1:
schema_version: 1name: gke-triageOmitting it means 1. Every bundle written before the key existed — including all of the examples on this page — keeps loading exactly as it did, and there is no migration to run. Write it down if you want the file to say out loud what it was written against; leave it out and nothing changes.
A version bump is for a key that changes shape or meaning, not for a
key being added. builtin_tools: arrived in v0.8 and the schema stayed
at 1, because an older mast reading a newer bundle is precisely the case
strictness already catches, by name. What would move the number is
budget: changing units, or hitl: changing what its default does.
A bundle declaring a version this binary does not speak is refused, and the error names both numbers, because the operator holding the file needs to know which of the two to change:
workload: "workload.yaml": bundle declares schema_version 2 and this mastspeaks 1; upgrade mast, or point it at a bundle written for schema 1.Refusing rather than loading the keys it happens to recognise: this filedeclares which tools may run without an operatorAn explicit schema_version: 0 is also refused. Absent and 0 are
different things: absent is a file written before the key existed, and a
literal 0 is someone reaching for a version number and getting it
wrong.
An unrecognised key is a load error, not a warning
Section titled “An unrecognised key is a load error, not a warning”Misspell a key and mast refuses to start, naming the key:
workload: parse "workload.yaml": yaml: unmarshal errors: line 8: field tool_catalogue not found in type workload.Bundle
An unrecognised key is refused rather than ignored, because a dropped keyin this file is a tool that silently stops being gated. Check the spellingagainst the bundle reference; if the key belongs to a newer bundle schema,the bundle should declare schema_version and this mast is too old to read itThis is stricter than most YAML config and it is deliberate. This is the
only file in a mast deployment that can declare a tool safe to run
without an operator, and mast’s own predicate is default-deny-unknown. The
failure being designed against is a misspelled block — tool_catalogue:,
hitl_polciy:, saftey: — that leaves a whole section of policy
unapplied while the daemon logs a clean start and the workload runs all
night. A WARN at boot is not a control; nobody is reading the log at
the moment it scrolls past.
The strictness reaches nested keys too, which is where the sharper
version of the same bug lives: mutatin: true on a catalog entry leaves
the tool catalogued, so nothing looks missing, while the tool quietly
reverts to default-deny-unknown.
The order matters when both go wrong at once. A real bundle from the
future does not arrive carrying only a version bump — it arrives carrying
the keys that motivated the bump. mast reads schema_version first, on
its own, so what you are told is “this bundle is from a newer schema” and
not “field quarantine_policy not found”, which reads as a typo in a key
you copied out of correct documentation.
Specialist frontmatter is strict too, and has no version of its own
Section titled “Specialist frontmatter is strict too, and has no version of its own”The same rule applies to the YAML frontmatter in a specialists/*.specialist.md
file, for a reason specific to that file: tools: is the one key that
fails in the unsafe direction. An absent tools: block means the
specialist inherits every MCP server the workload wires, so a
misspelled toosl: does not narrow the specialist to the servers its
file carefully lists — it hands over the whole surface, and nothing
downstream can tell that apart from an author who meant to inherit.
(capability: is the milder case: absent resolves to read_only, so
misspelling it fails toward the safe value.)
Frontmatter deliberately takes no schema_version of its own, and
writing one is an error. A specialist is only ever reached through a
bundle that names it, so the bundle’s version already governs the
roster; a second independently-versioned artifact would multiply the
compatibility matrix across every specialist file in the tree for a document
that is mostly prose. If the frontmatter ever needs a breaking change,
it rides the bundle’s version bump.
Fan-out rosters
Section titled “Fan-out rosters”dispatch: fanout runs the whole roster against one incident at the same
time and merges what comes back:
dispatch: fanoutfanout: max_concurrency: 2specialists: - dns - rbac - quota - _synthesisThree constraints the loader enforces at startup, rather than letting a run discover them:
_synthesisis a reserved specialist name and is required. It is the one that receives every analyst’s finding and writes the single report an operator approves. A roster without it is refused; every other Task specialist in the roster is an analyst.- Analysts must be read-only. Every branch runs before the one
approval gate, so a mutation in a branch is a mutation no operator was
offered the chance to refuse. A roster whose analysts can reach a
mutating tool is refused with the tool named — either drop it, or, if
it really is read-only, classify it with
tool_catalog.tools[].mutating: false. (request_operator_inputpasses the read-only check but still cannot be in a branch: a branch has no gate to pause on.) - Each analyst must name the tools it needs. A branch with no tool allowlist is refused rather than silently inheriting the catalog.
An analyst that returns nothing is reported to _synthesis as silent, not
dropped. Approving the merged report finishes the run without re-running
any analyst — including after the daemon restarts, since branch events are
in the session log the run state is reconstructed from.
The shipped GKE triage bundle is not a fan-out
roster — it carries a change executor, and a branch check refuses even a
declared one, since a branch has no gate to pause on — so fan-out ships its
own read-only example at examples/workloads/ns-audit.
Bounded rosters
Section titled “Bounded rosters”dispatch: bounded is for the workload whose value is that it cannot get
expensive: one cheap model call, a report forced to a schema, and a step
count an operator can read off the meter rather than infer from how long
the run took.
dispatch: boundedspecialists: - incident-report---description: Classifies one incident and returns the finding report.mode: SingleTurntier: smalloutput_schema: ../schemas/finding.json---The roster is built as a single node with no orchestrator above it, so
there is nothing in the shape that can delegate, retry, or take a second
turn. The specialist’s reply is validated against output_schema: before
the turn ends — a model that answers in prose fails the run instead of
returning an unparseable paragraph that reads like success.
Four things are refused at startup, each naming what it found, because each one silently un-bounds the run:
- A roster that is not exactly one specialist. The error prints the count and the names.
- A specialist not in
SingleTurnmode. A Task specialist runs a tool loop, which is however many calls it takes. A spec with nomode:at all is reported asTask (the default for a spec with no mode:)— the author wrote nothing and the default is what has to be named. - A specialist with no
output_schema:. Without it, one call buys a paragraph nothing downstream can read. planner.enabled: true. The planner is the orchestrator the shape is defined by not having.
dispatch: auto never infers this shape: a one-specialist roster is an
ordinary coordinator, and imposing a cost ceiling the bundle did not ask
for is not a favor. The worked example is
examples/workloads/bounded-triage, on the same finding.json report
contract the GKE triage bundle uses.
The prompt body: sent as written
Section titled “The prompt body: sent as written”Everything after the frontmatter is sent to the model unchanged. There is
no placeholder syntax, no escape sequence and nothing to quote: braces,
${...}, {{...}} and JSON all arrive as typed. The same is true of a
coordinator’s instruction: in this file and of the planner’s prompt.
The optional marker is the one removal. {project?} was the supported
way to ask for session state, and session state is no longer reachable
from a prompt by any spelling. A specialist body that still contains one
is refused at load, naming the file, every offending line and the key
each one asked for — because the alternative is rendering {project?} as
itself and saying nothing:
specialists: "Diagnose.specialist.md": a placeholder in the template body no longerinjects anything — mast sends instructions verbatim line 4: {project?} → asked for session-state key "project"{artifact.report?} is refused on the same grounds, though it never
loaded anything in the first place: mast runs no artifact service.
To get a value in front of a specialist, put it in the request, or have the caller build the instruction with the value already in it.
Per-specialist capability
Section titled “Per-specialist capability”A specialist declares whether it may change anything:
---description: Applies one approved remediation and reports what it did.capability: change_executor---The values are read_only and change_executor. read_only is the
default, so a specialist that says nothing about capability gets the safe
one.
Mast refuses to build a roster in which a read-only specialist can reach a mutating tool, naming the specialist, the tools, and the fix. Three shapes are refused:
- it names a mutating tool in
tools.mcp[].toolsortools.builtin; - it grants itself a whole MCP server (
- server: gkewith notools:), since whatever that server adds later is unreviewed; - it declares no
tools.mcpat all while the bundle ships atool_catalog— inheriting the catalog inherits everything mutating in it.
Fix any of them by enumerating the read-only tools the specialist needs, by
writing mcp: [] if it needs none, or by declaring capability: change_executor if it really is meant to change things. SingleTurn
specialists are exempt; the mode carries no tools.
“Mutating” is the same test the write gate (hitl.on_mutation, above) and
the effect log use — including its default-deny-unknown rule, so a tool your
tool_catalog has not classified counts as mutating and will fail the
roster rather than the incident. Classify the catalog with
tool_catalog.tools[].mutating.
A name that matches nothing
Section titled “A name that matches nothing”An allowlist is applied by dropping what does not match, so a name that matches nothing is not an error — it is a capability that quietly is not there. Both halves of an entry can go wrong that way, and mast answers each at the earliest point it honestly can.
A server the workload does not declare fails the roster at startup,
naming the specialist, the name, and the servers tool_catalog.mcp does
declare:
compose: specialist "stuck-pod" allows MCP server "loggging", which theworkload's tool_catalog.mcp does not declare (it declares "gke", "logging","monitoring"); the allowlist is applied by dropping what does not match, sothis grants the specialist nothing from it and would not have been reportedat run time. Fix the name, or add the server to tool_catalog.mcpA tool the server does not serve cannot be checked that early: knowing
what a server serves means calling tools/list, and mast’s toolsets are lazy
so that a bundle still loads when a server is down. It is reported the first
time that specialist’s toolset lists, once, at WARN:
WARN ALLOWLIST NAMES A TOOL THE SERVER DOES NOT SERVE — the specialist holds fewer tools than its file says specialist=scale-outage mcp_server=gke unmatched=list_datasets,query granted=1Naming fewer tools than a server offers is the whole point of an allowlist,
and is silent. Only naming more is the mistake. A bundle that declares no
tool_catalog.mcp has not said what exists, so the startup half is skipped
for it and only the warning applies.
Every change_executor in a roster is logged at startup, so the answer to
“which specialists here can change my cluster” is one log line rather than
an intersection of three files. The shipped GKE triage bundle logs exactly
one.
This is a stronger guarantee than prompt wording. A diagnoser told “do not mutate anything” is one persuasive incident away from doing it; a diagnoser that holds no mutating tool has nowhere to go.
Per-specialist model: model: and tier:
Section titled “Per-specialist model: model: and tier:”A specialist file may declare its own model in frontmatter, so a roster can run cheap analysts under a frontier synthesizer instead of billing every specialist at one tier:
---description: Inspects pod state and returns a 3-bullet digest.model: claude-haiku-4-5---Specialists that declare no model: inherit the process model
(--model). An override is dispatched by model id, exactly like
--model — the --provider alias only disambiguates the Anthropic
backend — so an override may name a different provider than the
parent. Resolution is memoized per model id, so eight specialists on one
tier share one client.
Two behaviors worth knowing before you tier a roster:
- A declared override that cannot be resolved fails startup. It is never quietly downgraded to the parent’s model, because a bundle that reads as tiered while running everything on one tier is worse than one that refuses to start. Credentials for every provider named in the roster must resolve at construction.
- Offline fakes collapse overrides. Under
--model=echo,scripted, ortoolactor, every override resolves back to that fake, so a tiered bundle still runs credential-free in smoke and acceptance runs.
Naming a concrete model id binds the bundle to that provider. When what you mean is “this step is not worth the frontier model” rather than “this step needs Haiku specifically”, declare a tier instead.
tier: — the portable spelling
Section titled “tier: — the portable spelling”A specialist may declare how much model it is worth and let the running provider answer with a concrete id:
---description: Inspects pod state and returns a 3-bullet digest.tier: small---The values are small, mid, and frontier. Mast resolves the tier
against the provider it is actually running (internal/taskclass.ModelForTier),
so the same bundle reads the same and costs the right thing on either
backend:
| tier | Gemini | Anthropic |
|---|---|---|
small | gemini-3.5-flash-lite | claude-haiku-4-5 |
mid | gemini-3.5-flash | claude-sonnet-5 |
frontier | gemini-3.8-flash | claude-opus-5 |
Which provider a tier resolves against is the one mast dispatches on: the
--provider alias when you passed it, otherwise the root model id’s own
prefix. A root model whose provider cannot be told from either — say a
custom id under no known prefix — fails startup asking for --provider,
rather than guessing a vendor and billing you for the guess.
Everything above holds for tiers too: an unresolvable tier fails startup
instead of falling back to the parent’s model, resolution is memoized per
resolved id (twelve tier: small analysts share one client), and offline
fakes collapse every tier back to the fake so the bundle still runs
credential-free. Each resolution is logged at startup with the tier and
the id it became.
A spec may declare model: or tier:, not both — that is a load
error naming the file, not a precedence rule. The two say different
things, and a bundle that says both has not decided which it means.
The shipped ns-audit bundle is the worked example: four tier: small
namespace analysts under one tier: mid synthesis step.
Per-specialist report contract
Section titled “Per-specialist report contract”A specialist file may declare the shape of what it returns:
---description: Diagnoses OOMKilled container terminations.output_schema: ../schemas/finding.json---The value is a path to a JSON-Schema document (.json, .yaml or
.yml), resolved relative to the specialist file’s own directory — so
../schemas/finding.json means the same thing whether the roster sits in
a workload bundle or a shared config root.
It is a file reference rather than an inline block on purpose. A report
shape is a contract between the specialist that produces it and every
consumer that reads it; inlining it in one specialist’s frontmatter makes
that contract private to that specialist, and a roster of a dozen
diagnosers ends up with a dozen copies that drift. The shipped
gke-triage-routed bundle points all twelve diagnosers at one
schemas/finding.json.
A violation is a refusal, not a warning, and the shape is the same in both agent modes:
Taskmode — the schema becomes the auto-injectedfinish_taskdeclaration. A non-conforming call comes back to the model as a validation error naming the offending key, and the model can correct itself within its turn budget.SingleTurnmode — the reply is validated on the way out. A violation refuses the delegation; the caller sees an error naming the key, with no result attached.
Either way non-conforming output never becomes the specialist’s answer, and the caller — not just a log line — learns that it was refused.
The document is read and checked when the roster loads, not when a
specialist first runs, so a broken contract fails startup with the file
named. Refused at load time: unknown keys (a misspelled propertys:
would otherwise produce a schema that constrains nothing), a node with no
type, an array with no items, an object with no properties, a
required name that is not a declared property, and a top level that is
not an object.
That last one is a mast restriction rather than an ADK one, because ADK’s
two modes disagree about non-object schemas: Task wraps a scalar under
a result key, while SingleTurn unmarshals the reply into an object
before it consults the schema at all, so a scalar contract can never
validate there. Rather than let one document mean two things, mast
requires an object. A report contract is an object anyway.
Mast does not interpret the schema, with exactly one exception. There is no built-in report type; the shape belongs to the workload.
The one property mast reads: proposed_change
Section titled “The one property mast reads: proposed_change”A report can carry the calls it recommends, not just prose describing them.
Declare a proposed_change array and mast will check it:
"proposed_change": { "type": "array", "description": "The executable form of your recommendation …", "items": { "type": "object", "properties": { "tool": {"type": "string"}, "arguments": {"type": "string"} }, "required": ["tool", "arguments"] }}Every entry has to name a tool the workload declares in its tool_catalog
and carry arguments that fit that tool’s own input schema. Both are
checked at the moment the report is returned, before it becomes the
specialist’s answer. A report naming an unknown tool, or arguments the tool
would reject, comes back to the specialist as an error it can correct —
the same refusal shape as a schema violation, not a failed run.
When the roster’s change executors have enumerated their MCP allowlists,
the check narrows further: the entry has to name a tool one of them can
actually run. This is the difference between a call this daemon holds and a
call that will fire if an operator approves it, and the gap between the two
is where an approval ends with nothing happening. An executor that took an
un-enumerated grant has no finite surface to check against, so the narrower
check is skipped; an executor whose declared surface is only
tools.builtin has an empty one and every proposal is refused, which
mast warns about at startup — built-in tools are a declaration, not a grant
(see specialists).
arguments is a JSON object encoded in a string —
"{\"namespace\":\"prod\",\"replicas\":2}", or "{}" for a tool that takes
none. It has to be, because its keys are whichever tool the entry names and
no report schema can declare them in advance; an object property with no
declared properties is refused at load time (above) for exactly the reason
that it would accept anything. Mast parses the string and validates it
against the real tool’s real schema, which is a stronger check than the
report schema could have made.
An empty list is a complete report. A specialist that cannot name an
exact call — the fix needs a human decision, or a tool the workload was not
given — returns [] and says why in its own escalation field. Nothing is
recorded and nothing is refused. A roster that does not declare the property
at all is unaffected.
What the property buys: under graph
dispatch
a finding whose change set the operator approved is handed to the roster’s
change executor verbatim, so the call that fires is the call that was on
screen. See approvals.
precondition: — what makes an approval stale
Section titled “precondition: — what makes an approval stale”An operator answering scope: change_set authorizes calls that have not
fired yet. What should void that authorization is the cluster changing
underneath it — not a clock running out. But mast cannot work that out on
its own: a tool is opaque to it, so it does not know which tool reads the
object a write is about, or which of the write’s arguments names that
object. The bundle knows both, so the bundle declares it:
tool_catalog: tools: - name: get_deployment mutating: false # required: the read must be read-only - name: scale_deployment mutating: true precondition: read: get_deployment args_from: {name: deployment} # the read's "name" <- this call's "deployment" args: {namespace: prod} # …plus anything fixed fields: [output.replicas]The read runs twice: once when the operator answers, to snapshot the world
they answered about, and once immediately before each granted call fires. If
a declared field moved in between, the grant is voided and the call is
re-parked with a question that names the field and both values —
output.replicas was 1 at approval and is 5 now. Every field is reported,
not the first, because an operator re-reading the question needs the whole
delta.
Four things to know before writing one:
- A precondition over the field the set itself rewrites invalidates its
own set. The snapshot is taken once, at approval. So a two-call set that
scales the same object to 2 and then to 3 has call 1 move what call 2 was
checked against, and call 2 goes back to the operator. The fix is
args_from: check each call against its own object, and a set that touches two Deployments works while a set that touches one twice, by design, does not. - The read must be declared
mutating: false. An unlisted tool is mutating by default (default-deny-unknown), so a catalog that simply forgot to list the read fails at startup with the declaration named — not at 3am with a “freshness check” that was writing to the cluster. fields:paths startoutput.for MCP tools. A structured MCP result arrives wrapped in anoutputproperty. A path that misses the wrapper matches nothing, every read digests identically, and the check silently compares nothing to nothing — which looks exactly like “the cluster never moves”.- Omitting
fields:digests the whole result. That is right for a narrow read and wrong for a chatty one, where a timestamp or aresourceVersionin the payload makes every re-read look like drift. Narrow the read rather than filtering a wide one here.
A tool that declares no precondition is bounded by hitl.change_set_ttl
alone, and the parked question says so in those words. If mast cannot
evaluate a declared precondition at all, the set is not grantable: the
question says the calls must be approved one at a time, and scope: change_set is refused rather than granted on a check that is not running.
capture: — what a change overwrote, and how to put it back
Section titled “capture: — what a change overwrote, and how to put it back”mast can park a mutating call, run it, and record that it ran. Until it also records what was there before, an operator who approves a change and watches it make things worse has no way back except reconstructing the old state by hand, under time pressure, at 3am.
So the write gate takes a snapshot before the call fires — and, when the bundle can name one, the call that restores it:
tool_catalog: tools: - name: get_deployment mutating: false # required: a recording must not change what it records - name: scale_deployment mutating: true capture: read: get_deployment args_from: {name: deployment} # the read's "name" <- this call's "deployment" fields: [spec.replicas] # what to keep revert: call: scale_deployment args_from_change: {deployment: deployment} # same object… args_from_capture: {replicas: spec.replicas} # …old valuemast sessions show then prints, beside the transcript:
Prior state captured: Changed by: scale_deployment(deployment=api, replicas=10) Captured: 2026-09-05T09:00:00Z by get_deployment(name=api) spec.replicas = 3 Undo: scale_deployment(deployment=api, replicas=3) (proposal, not a button: it goes through the write gate like any other change) scale_deployment {"deployment":"api","replicas":3}mast does not fire the undo. The recorded revert is a proposal. Running it sends it back through this same gate, with a person answering, because an automatic rollback is a mutating call nobody approved — decided by the component whose entire job is to not let that happen.
Five things to know before writing one:
- It looks like a
precondition:and it is not one. A precondition asks is the world still what it was when this was approved, so it wants the narrowest read that settles the question and keeps only a digest. A capture asks what was here before I overwrote it, so it keeps the values — they are what goes back into the revert. The defaults forfields:are opposite for exactly that reason. - The capture happens before the call, so a failure costs nothing. If the read fails, or the declaration cannot be honored, the call is refused and the cluster is untouched. That is the whole reason the work happens up front: the alternative is acting first and then finding out no record was taken, which leaves an operator believing in an undo that does not exist.
- A revert whose arguments all come from the change is refused at load.
It re-applies the change rather than undoing it, and it is shaped closely
enough like an undo to be believed by whoever reads the record during an
incident. At least one argument has to come from
args_from_capture. - Omitting
revert:is a complete declaration. Plenty of changes have no inverse a workload can name —delete_poddoes not invert, and a patch inverts only over the fields it touched. The record still carries the old value, and the view says the undo is undeclared and names the tool, rather than going quiet in a way that reads as “an undo exists somewhere”. - A capture proves the record exists, not that the revert works. Nothing here executes a revert to check. A workload that wants that assurance has to exercise it.
A deployment that declares captures but has no seam to run reads still starts, and says so at startup — the declaring tools’ calls are then refused one at a time, with the reason. The failure that warning closes is a bundle author seeing a clean start and believing their changes became reversible.
A declared path is not a route
Section titled “A declared path is not a route”edge_trigger.http is accepted, validated as a bundle field, and then read
by nothing. The inject server’s route table is fixed at construction; no
part of it consults the workload. This has been true since the spike, and
the field’s own definition says so — but from outside, a field documented as
informational used to be indistinguishable from one that works:
edge_trigger: http: path: /alert auth: bearer$ curl -X POST http://127.0.0.1:7777/alert405 Method Not Allowed405 reads as a verb mistake, so the time goes into the emitter rather than
the bundle. Two things changed, neither of them a new capability:
-
Startup says it. A bundle declaring a path is warned about next to the write gate and watchdog posture:
WARN edge_trigger.http IS NOT WIRED — the declared path serves nothingdeclared_path=/alert declared_auth=bearer endpoint="POST /inject" -
The unmatched path says it. An unknown path now answers
404and lists the routes this daemon actually serves; a known path with the wrong verb answers405naming the verb it wants (GET /inject→ “takes POST, not GET”). Previously every unmatchedGETwas absorbed by the health route and answered200 ok, which a relay reads as success.
The declaration is warned about rather than refused: it has always been inert, and failing a bundle that runs today over a field that never did anything would be a break with no safety behind it. Per-workload path prefixes remain deferred — the fix is to the honesty of the answer, not to the routing.
scheduled: — a workload that wakes itself
Section titled “scheduled: — a workload that wakes itself”Every other way into a mast daemon needs something outside it: an inbound
POST, an operator, or a cron entry holding your schedule on mast’s behalf.
edge_trigger.scheduled lets the bundle hold it:
edge_trigger: scheduled: interval: 15m jitter: 45s prompt: Sweep every namespace for pods in CrashLoopBackOff and report what you find.Four things to know before declaring one:
- The cadence is anchored, not restarted. Fires land on
anchor + k×interval, and the anchor is written to the session store the first time the trigger comes up. A daemon that is redeployed twice a day resumes the phase it had rather than quietly moving a 02:00 sweep into the afternoon — the failure where a schedule keeps working and stops meaning what it said. (The anchor lives on a bookkeeping row, not a session; it never appears inmast sessions list.) - A tick the daemon was down for is skipped, not caught up. Coming back from an outage that spanned three ticks fires none of them and logs one line naming how many were dropped and over what window. A periodic run samples the current state of the world, so a sample nobody took is owed to nobody — and catching up means a crash-looping daemon buys a fresh backlog of model runs at every restart, about the crash. If you need every occurrence to run, a schedule is the wrong shape: post them.
- Every fire is a fresh session, and it runs as
mast:scheduler. The session is named for its tick and listed like any other, so a scheduled run is as readable after the fact as an injected one. The identity is namespaced, so no human login can produce it and no audit row can be misread as somebody’s. A mutating call inside a scheduled run still parks for a real approver underhitl.on_mutation— unattended is not unsupervised — and the run is bounded by the samebudget:block as everything else. - One replica fires the cadence; the others say they are not. Two
replicas sharing a session store no longer both fire: the first to start
takes a lease and drives the schedule, and every other one logs at
ERRORthat it will not, naming the instance that does. This is a refusal, not leader election — a passive replica stays passive for its whole life and does not take over if the driving one dies; your orchestrator restarting the dead pod is what restores the cadence.jitterstill staggers fires within one instance and was never a deduplication mechanism. See scaling a scheduled workload and #345.
Fires are counted by mast_scheduled_fires_total{workload,outcome} —
ran, skipped (a tick that came due during a drain), error, and
missed (one per tick coalesced away after an outage). A run that fails is
not retried: the next tick is the retry, and it samples a fresher world.
monitor: — the facts a cycle gathers for itself
Section titled “monitor: — the facts a cycle gathers for itself”A scheduled fire on its own wakes the model with a tick and a prompt, and
leaves it to work out what to look at. monitor.collect runs the looking
first, as mast rather than as the model:
edge_trigger: scheduled: interval: 15m
monitor: collect: - tool: k8s_cluster_health as: health - tool: k8s_findings_diff args: {transitions: "new,escalated,resolved"} as: transitions transitions_from: transitionsThe calls run in declaration order, serially, before any model call. Their results reach the roster inside the wake-up envelope:
{ "kind": "scheduled", "workload": "cluster-watch", "tick": "2026-08-21T10:00:00Z", "collected": { "health": { "…": "whatever the tool returned" } }, "transitions": { "scanned": 412, "records": [ { "subject_key": "prod/checkout-7d9f/OOMKilled", "transition": "escalated", "fields": { "severity": "critical", "prev_severity": "warning" } } ] }}Everything named in collect lands under collected as the tool returned
it. The one key named by transitions_from is the exception: it is parsed,
and it moves — it appears under transitions and not under collected,
so the model is never handed two spellings of the same fact.
Why this is not just a tool the model holds
Section titled “Why this is not just a tool the model holds”Because of what the interesting tools are. Knowing what changed since the
last run means asking something that keeps per-run state, and a tool that
advances persisted state as a side effect of answering is a mutating tool —
correctly so. Under the default hitl.on_mutation: require_approval, a
model holding that tool parks the cycle for an operator on every fire.
An unattended monitor that needs someone awake to authorize finding out
whether anything changed is not unattended. (And a tool nothing has
classified is mutating by default, so this is the common case, not a corner
of it.)
So the collection is mast’s. Three things follow, all of them deliberate:
- Nothing gates it, because no model asked for anything. The write gate stays registered and stays in force for everything the model does call.
- It costs zero model calls, by construction rather than by tuning — a leg the model is not part of cannot spend a token. A monitoring cycle on a bounded roster therefore costs exactly one model call, the same as an injected incident.
- mast learns nothing about your domain. It runs the calls you named and passes the results through unchanged. What a transition means is the collected tool’s business.
transitions_from: — the classification comes from the tool
Section titled “transitions_from: — the classification comes from the tool”A monitor’s real question is not “what does the cluster look like” but “what
changed since last time”, and answering that needs per-run state. The tool
that keeps it — k8s-lookout’s
findings diff, or anything shaped like it — already does the classifying.
transitions_from points mast at that result so the transitions ride the
envelope as data rather than as a wall of text the model has to re-read:
monitor: collect: - tool: k8s_findings_diff args: {transitions: "new,escalated,resolved"} as: transitions transitions_from: transitionsmast has no vocabulary of transition classes. There is no enum, no
severity comparison, no fingerprinting, no “is this really new” second
opinion. A record’s transition value is whatever string the classifier
wrote, carried to the model verbatim — if your tool emits quiesced, the
model sees quiesced. transitions_from names where the verdict comes
from; it never constrains what the verdict says. Two implementations of
“what changed” is one more than can be right.
The record stream
Section titled “The record stream”The named tool answers in text: one record per line, then a summary line.
Each record is logfmt or flat JSON (detected per line, so a stream may mix
them), and needs two keys — subject_key and transition. Everything else
becomes fields:
subject_key=prod/checkout-7d9f/OOMKilled transition=escalated severity=critical prev_severity=warning{"subject_key":"prod/api-5c1/CrashLoopBackOff","transition":"new","severity":"warning"}scanned=412 findings=2 elapsed=1.4sThe trailing scanned=<n> findings=<n> elapsed=<d> line is mandatory,
and findings= must equal the records above it. That is the only judgement
mast makes about the stream, and it is about completeness, not correctness:
a truncated answer is a prefix of a healthy one, and the notify half
deliberately says nothing when nothing changed. Without the summary line the
two are indistinguishable, so a stream that lacks it — or whose count
disagrees — is void, and voids the cycle. A record with a transition but
no subject_key is malformed on the same footing: nothing downstream can
acknowledge or de-duplicate a subject it cannot name.
A quiet cycle says so
Section titled “A quiet cycle says so”"records": [] means “we classified, and nothing changed”. A workload with
no transitions_from ships no transitions key at all, which means “we do
not know”. Those are different facts and the notify half acts on only one of
them, so the empty list is never elided.
A malformed stream fails the cycle exactly the way a failed
collection does — before any model call, counted
error, cadence continuing — and the log line names both the
transitions_from key and what was wrong with the bytes.
notify: — speaking only when something changed
Section titled “notify: — speaking only when something changed”transitions_from tells mast whether anything changed. notify is what it
does with that answer:
monitor: collect: - tool: k8s_findings_diff args: {transitions: "new,escalated,resolved"} as: transitions transitions_from: transitions notify: conversation: "#sre-oncall" digest_after: 12hThe daemon supplies the other half — which ingress, and with what credential:
MAST_INJECT_TOKEN=… MAST_NOTIFY_TOKEN=… mast --workload=cluster-watch \ --notify-url=http://switchboard:8080 --listen=:7777 --session-db=…That split is deliberate. Where to speak is a property of the workload;
which switchboard, and as whom is a property of the deployment. A bundle
that named its own ingress could not be promoted from staging to production
without editing the workload. The token is refused at startup if it equals
any of the daemon’s own inbound tokens (MAST_INJECT_TOKEN,
MAST_ATTACH_TOKEN, MAST_A2A_TOKEN, MAST_AGUI_TOKEN): those point the
other way, and sharing one means anything that can read the chat bridge’s
configuration can drive this daemon. It is an env var and never a flag, so
it stays out of ps and out of the container spec’s args.
A bundle with a notify: block and a daemon with no --notify-url is a
startup refusal, not a warning. The workload’s entire output is the
message it was going to send.
A quiet cycle does not wake the model
Section titled “A quiet cycle does not wake the model”Not “wakes it and then declines to post” — the turn never runs. A fifteen-minute cadence that spends a model call on every quiet cycle costs more per month in nothing-happened than the incidents it exists to catch.
The skip is narrow: it applies only when the workload declared both
transitions_from (so “nothing changed” is the classifier’s answer, not
mast’s guess) and notify (so speaking is what the cycle is for). A
workload that names no classification source speaks on every cycle, and the
daemon says so at startup with speaks_every_cycle=true.
One incident is one message
Section titled “One incident is one message”The first speaking cycle posts; the next ones append to that message, so an incident that takes six cycles to resolve reads as one growing story instead of six notifications an operator has to reassemble. The first quiet cycle closes the timeline — what happens after calm is a new incident, and it gets a new message.
Switchboard can answer an append two ways that are not errors, and both are handled rather than surfaced:
- 409, “send the full text” — a restart, another replica, or a message posted from elsewhere means it no longer remembers the body. mast holds what it last sent and re-sends the whole story as an edit.
- 200 with a continuation ref — the message is full, so the platform posted a threaded continuation. Every later cycle targets that one.
If neither works (the platform cannot edit, or the message is gone), the whole story is posted fresh, so the thread that survives is the readable one.
A failed send is not replayed
Section titled “A failed send is not replayed”There is no queue, no retry and no spool. A send that failed is an errored
fire, counted mast_monitor_notifications_total{outcome="error"}, and the
next cycle reports what is new then.
Holding the message and re-sending it next cycle is the tempting fix and it is wrong: the classifier advanced its own state when it answered, so the replay would describe a world that has already moved on. Advancing state before speaking is the ordering that makes this safe.
A broken monitor says so
Section titled “A broken monitor says so”If a cycle cannot complete — collection failed, the classification was truncated, the turn errored — mast posts a notice of its own into the same conversation, and another when the cycle next succeeds. Both are edge-triggered: once on the way down and once on the way back, never on every failing cycle, because a channel that repeats itself every fifteen minutes is a channel an operator mutes, and the mute costs them the incident report too. A health notice that cannot be delivered is logged and never fails the fire.
Silence has a deadline
Section titled “Silence has a deadline”With digest_after, a workload that has said nothing for that long speaks
on its next cycle whether or not it has news, and the deadman resets. The
clock starts at daemon startup, so a daemon booting into a quiet world does
not immediately announce the quiet. Those cycles are counted separately on
mast_monitor_digest_wakes_total, because “did anything change” and “did
the deadman have to fire” are different operator questions.
Every cycle’s outcome is on
mast_monitor_notifications_total{workload,outcome} — posted, appended,
replaced, rolled, quiet, health, error. A healthy monitor is
mostly quiet.
ack: — taking an acknowledgement back
Section titled “ack: — taking an acknowledgement back”Everything above runs outward. ack is the one leg that runs the other way:
an operator reads a finding in the chat, says “I have seen this one”, and the
monitoring stops reporting it.
monitor: ack: tool: k8s_findings_ack args: {window: 4h}That arms POST /monitor-ack on the daemon. A workload with no ack: block
answers 404 there — nowhere to forward one.
curl -s -X POST http://localhost:7777/monitor-ack \ -H 'Authorization: Bearer '"$MAST_INJECT_TOKEN" \ -H 'Content-Type: application/json' \ -d '{"subject":"ns/checkout/oom-restarts","reason":"known, fix rolling out"}'{ "workload": "cluster-watch", "subject": "ns/checkout/oom-restarts", "ack_by": "alice@example.com", "previously_acked_by": "bob@example.com", "previously_acked_at": "2026-08-21T07:02:11Z"}The subject is the producer’s subject key, verbatim from the classification
mast reported — mast does not parse it and has no vocabulary for what a
subject is.
Who owns what
Section titled “Who owns what”The suppression lives with the producer of the transitions. It is the only
place the next cycle’s classification can read it from, so mast forwarding
and then keeping its own copy of “how long this is muted” would be a second,
wrong answer to a question already answered. monitor.ack.args is where the
deployment’s policy goes — which cluster, how long — and there is no
per-request window.
What the producer cannot do is say who asked. Its ack surface takes an identity string from whoever calls it and has no way to check it. mast can, because the ack came through an authenticated ingress, so the split is:
| Store of record for | |
|---|---|
| The producer | the suppression — whether a subject is muted, and until when |
| mast | the attribution — who acked, when, from what credential, with what note |
mast writes its record before forwarding. A forward that then fails leaves an attributed ack the suppression never reached, which is visibly different from nobody having acked at all; the operator is told, and acking again is the recovery.
ack_by comes from the credential, never the body
Section titled “ack_by comes from the credential, never the body”The identity mast forwards and records is the one that authenticated the
request. A body carrying ack_by is refused with a 400 naming the
field — not ignored, because silently dropping a field a client believed in
produces an audit line naming the wrong person with no sign anything went
wrong.
A relay acking on a human’s behalf names them the supported way, with the
X-Asserted-Caller header, which works only for a credential the users file
provisioned to assert. Both are kept: the human is the acker, the relay is
recorded alongside. This is the rule /resume settled for approvals, and it
matters at least as much here — see Who a resume
names.
An ack is not an approval
Section titled “An ack is not an approval”They share an operator, a chat window and a verb, and nothing else. An approval mints a grant that licenses a write to the world and is consumed on use. An ack asserts no diagnosis, authorizes no change, and carries no verdict, no grant, no freshness window and no change-set signature. It does not go through the write gate and does not appear in the decision export — otherwise “who approved this change” would quietly start meaning “who muted an alert”.
The count is on mast_monitor_acks_total{workload,outcome}: forwarded or
error, and nothing between them.
The fence
Section titled “The fence”The exception is narrow because it is enforced, not because it is
documented. A tool mast runs on its own behalf — everything named in
monitor.collect, plus the one named in monitor.ack — must be reachable by
nothing else, and the daemon refuses to start otherwise, before it wires MCP,
so an operator without credentials reads the roster problem rather than a
403 standing in for it. Three ways a roster reaches a tool, all three
refused:
- a specialist names it outright, on an MCP server or among its built-ins;
- a specialist allows an MCP server with no
tools:list, which grants it every tool on that server (refused whether or not a collect tool is on that server today — mast cannot tell without connecting to it); - a specialist declares no
tools.mcpkey at all, which inherits the whole catalog. Writemcp: []if it needs no tools.
SingleTurn specialists are exempt: they are built with no toolsets at all,
so they reach nothing. That is what makes a bounded monitoring roster the
clearest form of the shape — its model holds no tools whatsoever and still
gets the transitions.
The fence matters most for the ack tool. A collect tool a model could also reach would let it gather facts ungated; an ack tool it could reach would let it suppress its own alerts, and the producer’s triage-status write is typically not permission-gated on its side, so the daemon’s ingress authentication is the only thing in front of it. “There is no ack tool the model can call” is a property of the build — an agent that cannot see a tool cannot be talked into calling it.
When collection fails
Section titled “When collection fails”The cycle fails, before any model call. Not “collect what you can and wake
the model with the rest”: a cycle whose diff failed and whose scan succeeded
would hand the model a snapshot with no transitions attached, and the honest
reading of “no transitions” is “nothing changed”. A monitor that reports calm
because its collection broke is worse than one that reports nothing, because
only the second is visibly broken. The fire is counted error on
mast_scheduled_fires_total, the reason is logged against the tick, and the
cadence continues to the next one.
builtin_tools: — the provider’s own server-side tools
Section titled “builtin_tools: — the provider’s own server-side tools”Both providers ship tools that do not run where mast’s tools run. Gemini’s
google_search, url_context and code_execution, and Anthropic’s
web_search, execute inside the vendor’s infrastructure; their results
arrive folded into the model’s response.
That last clause is the whole problem. A server-side built-in never becomes a tool call, so:
- the permissions gate has no name to allow or deny,
- the write gate has no call to park for an operator,
- the effect outbox has nothing to record,
- and the transcript shows a model that simply knew something.
A specialist declared capability: read_only
— a declaration mast verifies at startup and the write gate measures at
runtime — could still read the public internet, and nothing downstream
would say so. builtin_tools: is the only gate there is.
Silence means off
Section titled “Silence means off”builtin_tools: web_search: true # opt in, explicitly url_context: false # explicit off; same as omitting itOmitting the block entirely, or omitting a key inside it, leaves that tool
off — on every provider. mast does not inherit the vendor’s default.
Gemini’s own baseline is search-and-URL-context on and Anthropic’s is search
off, so inheriting them would mean one mast image changing an unattended
agent’s reach with a --provider flag, and “the same bundle runs on Gemini
or Claude” is the point of the bundle. It also means the paths with no
bundle to read — mast run, a library embed that sets only a model name —
are safe because there is nothing to forget.
Writing false explicitly is worth doing anyway: it records that somebody
decided, rather than that nobody wrote a key.
What each provider can actually send
Section titled “What each provider can actually send”| Bundle key | Gemini | Anthropic |
|---|---|---|
web_search | google_search | web_search |
url_context | url_context | — |
code_execution | code_execution | — |
A key with no equivalent lands nowhere. That is fail-safe by construction — a tool a provider cannot be sent is a tool it cannot leave on — but it is also silent, so read the startup line rather than assume:
INFO model constructed name=gemini-3.7-flash builtin_tools=web_search,url_contextINFO model constructed name=claude-sonnet-4-6 builtin_tools=web_searchThe line reports what the constructed model will send, not what the
bundle said. Unknown YAML keys are discarded without complaint, so
builtin_tols: {web_search: true} parses fine and turns nothing on; a line
derived from the same discarded struct would have agreed with the typo.
builtin_tools=none means the provider has these tools and all of them are
off. No line at all means the backend has no such concept — the offline
fakes, scripted replay.
The gate is per bundle, not per specialist
Section titled “The gate is per bundle, not per specialist”There is no per-specialist builtin_tools:. Under a default-off baseline
there is nothing for a specialist to reclaim: only the bundle can turn a
tool on, and a specialist’s model: override
resolves through the same gate the root does — a workload that turned web
search off cannot have it handed back by an analyst that names a different
tier. If a roster ever needs one analyst grounded and the rest not, that is
a change to make then; until it exists, the missing axis fails closed.
prompt_cache: — Claude prompt caching
Section titled “prompt_cache: — Claude prompt caching”Unless a bundle turns it off, mast places a cache breakpoint on a claude-* model’s system prompt
(which caches the tool schemas with it, since they render first) and
rolling breakpoints over the end of the conversation. An incident
re-sends its whole growing transcript on every model call; with the
breakpoints in place, Anthropic re-reads it at the cache rate, a tenth of
fresh input, instead of billing it in full again.
prompt_cache: enabled: true # the default; false turns it off ttl: 5m # the default; or 1hOn by default, and that is a breaking change. Before this block
existed mast sent no cache breakpoints, so a workload that upgrades
starts caching without touching its bundle: Claude bills the cache
writes at 1.25x input and the re-reads at 0.1x. On the judged corpus the
run came out 30% cheaper; a workload of single-call turns could come out
slightly dearer, and enabled: false restores the old behaviour. The
default matches core-agent’s, and it changed before v1.0 on purpose,
while the compatibility policy
still allows a default to move without a deprecation window.
Measured on the judged corpus (claude-sonnet-5 on Vertex’s global
endpoint, ten incidents, --prompt-cache=5m against off), caching left
every score unchanged and cut the run’s cost by 30%, and its input cost
by 45%. Those incidents average about three model calls; a longer
investigation re-reads more and saves more. On the global endpoint
consecutive calls can also miss the cache, since they may be served from
different regions; a regional endpoint such as us-east5 reads it
reliably.
The TTL is a real trade-off. Writing to the cache costs more than
fresh input: 1.25x for a 5-minute breakpoint, 2x for a 1-hour one. A
tight loop refreshes the 5-minute window on every call, so 5m is right
for nearly every workload, and the extra 0.75x of 1h would be pure
loss there. 1h pays when turns are routinely more than five minutes
apart: a turn parked on an operator’s approval, or a scheduler-driven
daemon. Both TTLs are priced at their own
rate, because
Anthropic reports which TTL each write used.
The block is workload-wide: the root and every specialist on a claude-*
model cache the same way, and so does a provider profile on the
Anthropic dialect. It changes nothing on Gemini, whose caching is
implicit (or the Vertex context cache). With no bundle to read — mast run, a library embed that sets only a model name — the default applies:
on, 5 minutes. The eval harness follows the same default and takes
--prompt-cache=off|5m|1h to override it, so the measurement above is
reproducible from the command line.
core-agent has the same setting, as --prompt-cache-ttl / --no-prompt-cache
and model.anthropic.prompt_cache in its config, on by default there too.
Both products get it from the same core-models adapter.
run_queue: — bounding concurrent runs on one thread
Section titled “run_queue: — bounding concurrent runs on one thread”One AG-UI thread runs one turn at a time. That is not an AG-UI decision: a
mast session is a single-writer store, so every turn-driving surface
serializes on the same per-session lock. What run_queue: decides is what
happens to the second run.
agui: expose: true run_queue: depth: 3 # runs that may WAIT. Omit for this default.depth counts runs that may wait, not runs that may exist, so the admitted
total is depth + 1 — one executing plus depth queued. That is why 0 is a
useful setting rather than an absurd one: it means no concurrency on a
thread, one run at a time and the rest refused immediately. Omitting the key
gives you 3.
The run that arrives at a full thread is refused with 409 Conflict and a
Retry-After, decided before the SSE stream opens, so a client gets an HTTP
status it can branch on rather than a stream that opens and immediately
carries an error frame. Retry-After is a fixed backoff floor, not a
prediction: mast does not know how long the turn ahead of you will take.
Three things worth knowing before you tune it:
- 409, not 429. A
429from this endpoint means the rate limiter refused your arrival rate, and the remedy is to slow down everywhere. A409means this one conversation is busy, and the remedy is to retry it or start a different thread. Collapsing them would leave a client unable to tell which it is. - The bound is per thread, so a busy thread never refuses a run addressed
to another one, and under
session_model: per_run— a fresh session per run — it effectively never fires at all. - There is no way to say “unbounded”. Unbounded is what this key exists to
end, so a negative depth is refused at daemon start rather than read as
-1 means no limit.
Refusals are counted as
mast_agui_runs_total{outcome="queue_full"}, kept
separate from the rejected the credential-shaped refusals share: a climbing
queue_full is answered with capacity or with this key, not with a caller’s
token.
Budget fields
Section titled “Budget fields”| Field | Meaning |
|---|---|
budget.max_turns | Cap on model calls per session. One “turn” = one model call — a Task specialist looping through five model calls before finish_task has spent five turns, not one. Absent/0 = unlimited. |
budget.max_model_calls_per_turn | Cap on model calls in one turn, where max_turns caps the session. The backstop for a turn that runs away in a shape the watchdog does not recognize; it needs no price, so it holds for unpriced models. The call over the cap is not made and the turn ends as loop_stop, with nothing latched. Absent/0 = mast’s default of 100; negative = unlimited. Applies under every watchdog posture. See a loop inside one turn. |
budget.max_wallclock_seconds | Bounds each whole turn with a context timeout. |
budget.max_cost_usd | Session-cumulative cost ceiling, derived by the budget meter from streamed usage metadata (flat per-1K-token spike pricing in v0.1). |
budget.final_report | Grants a specialist stopped by a ceiling one model call past it, with every tool but its report tool withdrawn, to file what it already established. Default false. Once per specialist per session, and never to one that has spent nothing. See letting a stopped specialist file what it found. |
Crossing a ceiling cancels the run context mid-turn, aborts in-flight
model/tool work, and increments mast_budget_trips_total. Budgets compose:
workload-level and per-specialist budgets both apply, tightest cap wins.
Per-specialist ceilings
Section titled “Per-specialist ceilings”A specialist file may declare its own budget in frontmatter, alongside the model override and report contract above:
---description: Diagnoses OOMKilled container terminations.budget: max_turns: 6 max_wallclock_seconds: 60 max_cost_usd: 0.25---max_turns and max_cost_usd are ceilings on that specialist’s spend,
checked on every model call it authors; max_wallclock_seconds bounds
each activation of its node under graph dispatch. Composition with the
workload’s ceilings is by construction rather than arithmetic: each call
is measured against the specialist’s ceiling and the workload’s, and
whichever is reached first stops what it holds — the specialist, or the
whole run. When one call crosses both, the
error names the specialist — the more specific fact, and the one an
operator acts on. A specialist that declares a model: override or a
tier: is priced at the rate of the model it actually runs on — a tier is
priced off what it resolved to — so a cheap analyst’s tokens are not billed
at the synthesizer’s.
One limit is worth knowing. A ceiling is checked both before a call and
after it, but the pre-call check refuses only what it can prove — so
max_turns is exact, while a call that starts with dollars or tokens to
spare always finishes and is billed for what it turns out to cost. The cap
bounds total spend within one call’s overshoot; it does not pre-authorize a
call.
A specialist’s own ceiling stops that specialist and not the session: the
coordinator is handed the refusal and routes around it, so a workload with
budget elsewhere finishes with a path missing rather than failing. The loss
is reported on mast_budget_trips_total, in the daemon log, per specialist
under cost_ceiling.scopes[], and in mast.Result.Exhausted
(budgets).
Env-var overrides
Section titled “Env-var overrides”Scalar budget values can be overridden process-wide (applies to every bundle loaded in the invocation, overrides file values unconditionally; set-but-unparseable is a fatal load error):
budget.max_cost_usd → MAST_BUDGET_MAX_COST_USDbudget.max_wallclock_seconds → MAST_BUDGET_MAX_WALLCLOCK_SECONDSChanging a bundle under a running daemon
Section titled “Changing a bundle under a running daemon”mast reads the bundle once, at startup, and never reloads it. Editing
workload.yaml, a specialist template or mcp.json while the daemon is
running changes nothing until the daemon restarts.
That is easy to trip over in Kubernetes, because the deployment mounts
the bundle from a ConfigMap and the kubelet does rewrite the mounted
files under a running pod. The base kustomization also sets
disableNameSuffixHash: true, so kubectl apply does not roll the pod
either. Both are deliberate — see below — and together they mean an
applied edit can look like it took effect when it has not.
So mast says which configuration it is running. At startup:
level=INFO msg="workload config identity" root=/workspace/workload bundle=/workspace/workload/workload.yaml digest=sha256:1f0c2a93b7d4e615 files=17 bytes=41328 newest_mtime=2026-09-06T10:14:22ZThe digest covers every file the loaders actually read — the bundle,
each specialist template, each output_schema: they resolve, and the
MCP catalog — keyed by path relative to the root, so the digest you
compute from a checkout is the digest the pod prints. It does not
include modification times, because a ConfigMap remount rewrites those
whether or not a byte changed.
Once a minute the daemon re-hashes the same files. When they stop matching what it loaded, it says so once:
level=WARN msg="WORKLOAD CONFIG ON DISK NO LONGER MATCHES THE RUNNING CONFIG — the edit has not taken effect" running_digest=sha256:1f0c2a93b7d4e615 on_disk_digest=sha256:9b31c07ae5f2d488 changed=specialists/CrashLoopBackOff.specialist.md remedy="mast does not reload configuration; restart the daemon (kubectl rollout restart) to pick this up"Once per edit, not once per minute; reverting the file logs that the two agree again.
Why not roll the pod on apply, and why not hot reload. A hashed
ConfigMap name would restart the daemon on every kubectl apply, which
is a heavier action here than it looks: an unattended daemon holds
in-flight turns that are spending money, parked approvals waiting on a
human, and an armed cadence. Making the restart something an operator
asks for is the safer default, and kubectl rollout restart statefulset/mast is the whole of it. Hot reload is a larger question
than a file watcher — what a mid-flight turn, a parked approval or a
running monitoring cycle should do when the bundle changes underneath
them — and it is not answered by noticing that a file moved.