Documentation
¶
Overview ¶
Package workload loads workload bundles — the declarative operational profile for a mast deployment. A bundle enumerates the MCP servers, specialists, budget, and edge-trigger configuration for one named workload.
Schema authority: docs/orchestration-design.md defines the canonical bundle schema. This package implements the spike subset needed for the GKE triage anchor use case (see docs/triage-demo-plan.md) plus the v0.1 planner scaffold knob (planner.enabled). Fields beyond that — planner review/shape knobs, isolation scope, bundle learning — are omitted here and will be added when their downstream subsystems land.
Index ¶
- Constants
- type A2A
- type A2AAuth
- type AGUI
- type AGUIAuth
- type Budget
- type BuiltinTools
- type Bundle
- type Capture
- type EdgeTrigger
- type Fanout
- type HITL
- type HTTPTrigger
- type MCPServerRef
- type Mode
- type Monitor
- func (m Monitor) AckArgs() map[string]any
- func (m Monitor) AckTool() string
- func (m Monitor) CollectTools() []string
- func (m Monitor) EffectiveDigestAfter() (time.Duration, error)
- func (m Monitor) Enabled() bool
- func (m Monitor) NotifyTarget() string
- func (m Monitor) SelfRunTools() []string
- func (m Monitor) TransitionsKey() string
- type MonitorAck
- type MonitorCollect
- type MonitorNotify
- type OnMutation
- type Planner
- type Precondition
- type Revert
- type Safety
- type ScheduledTrigger
- type ToolCatalog
- type ToolPolicy
Constants ¶
const ( // WatchdogWarn logs a detected runaway pattern and lets the turn // run. WatchdogWarn = "warn" // WatchdogFeedback warns, and additionally tells the model what it // is doing on its next turn. WatchdogFeedback = "feedback" // WatchdogEnforce feeds back, and additionally halts the session on // a Critical alert until an operator resets it. WatchdogEnforce = "enforce" )
Watchdog postures a bundle may declare, in ladder order. These are string copies of pkg/watchdog's Mode constants, not the constants themselves: this package is stdlib-only by design (it sits in the slim-embed slice, and a YAML schema has no business pulling the ADK runtime in behind it). TestSafetyWatchdogVocabularyMatchesTheWatchdog imports pkg/watchdog from the test binary and fails if the two lists ever disagree, so the copy cannot rot silently.
const ( // DispatchCoordinator is the SubAgents coordinator shape. DispatchCoordinator = "coordinator" // DispatchGraph is the workflow-graph LLM-as-router shape. DispatchGraph = "graph" // DispatchFanout is the concurrent-analysts + synthesis shape. DispatchFanout = "fanout" // DispatchBounded is the one-call shape: a single SingleTurn // specialist with a declared output_schema, no router and no tool // loop, so the cost of a cycle is a constant an operator can read // off the bundle. Never inferred — a roster has to ask for it. DispatchBounded = "bounded" // DispatchAuto picks a shape from the roster. DispatchAuto = "auto" )
Dispatch names the root shape a workload wants assembled. The values mirror internal/compose.Dispatch; the string lives here so a bundle can declare its own shape instead of depending on how it happens to be launched. An empty value leaves the choice to the caller.
Precedence is caller-explicit over bundle: `mast serve --dispatch=X` wins when the operator actually typed it, the bundle's declaration wins otherwise. A shape is a property of the roster (fan-out needs read-only analysts and a synthesis specialist; graph needs a SingleTurn classifier and a `_fallback`), so the bundle is where it belongs — the flag stays for overriding one run.
const ( // AGUISessionPerThread maps one mast session per AG-UI threadId (the // default): a chat thread continues one conversation across runs. AGUISessionPerThread = "per_thread" // AGUISessionPerRun maps a fresh mast session per AG-UI runId: each run // is a stateless one-shot. AGUISessionPerRun = "per_run" )
SessionModel values for AGUI.SessionModel.
const CurrentSchemaVersion = 1
CurrentSchemaVersion is the bundle schema this binary speaks.
Bump it when a change to the bundle format cannot be read correctly by a mast that predates it — a key changing shape or meaning, not a key being added. Adding an optional key does not need a bump: an older mast refuses it as unknown (see Load), which is a refusal naming the key rather than a silent misreading.
Variables ¶
This section is empty.
Functions ¶
This section is empty.
Types ¶
type A2A ¶ added in v0.2.0
type A2A struct {
// Expose gates the whole section; false (the default) means no A2A
// skill is published for this workload.
Expose bool `yaml:"expose,omitempty"`
// SkillName is the A2A skill id published on the agent card and named
// by inbound message/send calls. Defaults to the workload name.
SkillName string `yaml:"skill_name,omitempty"`
// SkillDescription is the human-readable skill summary on the card.
SkillDescription string `yaml:"skill_description,omitempty"`
// InputSchema / OutputSchema are a MAST-SIDE convention only: mast
// validates inbound task inputs against them and may render them into
// the skill description. Spec AgentSkill has no schema fields, so
// these do NOT round-trip through the agent card as machine-readable
// schema (docs/a2a-design.md note).
InputSchema map[string]any `yaml:"input_schema,omitempty"`
OutputSchema map[string]any `yaml:"output_schema,omitempty"`
// Auth is the per-skill auth policy.
Auth A2AAuth `yaml:"auth,omitempty"`
}
A2A is the workload's A2A-server exposure (docs/a2a-design.md, "Which agents get exposed"). Absent or expose:false means the workload is not reachable over A2A — exposure has real ops implications (auth setup, external contract stability), so it is opt-in per workload.
type A2AAuth ¶ added in v0.2.0
type A2AAuth struct {
// Required declares the skill needs authentication. Informational in
// v0.2 when a server-wide token validator is configured (all exposed
// skills sit behind it); Scopes are the enforced grain.
Required bool `yaml:"required,omitempty"`
// Scopes are the token scopes a caller must carry to invoke the
// skill; missing scope → 403 (docs/a2a-design.md "Auth model").
Scopes []string `yaml:"scopes,omitempty"`
}
A2AAuth is the per-skill auth policy within a workload's a2a: section.
type AGUI ¶ added in v0.2.0
type AGUI struct {
// Expose gates the whole section; false (the default) means no AG-UI
// endpoint is served for this workload.
Expose bool `yaml:"expose,omitempty"`
// EndpointPath is the HTTP path the workload is served at. Defaults to
// "/agui/<name>". Must start with "/".
EndpointPath string `yaml:"endpoint_path,omitempty"`
// Description is surfaced in the /agui/agents.json discovery descriptor;
// defaults to the workload description.
Description string `yaml:"description,omitempty"`
// InputSchema is 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 this does
// NOT constrain the wire input.
InputSchema map[string]any `yaml:"input_schema,omitempty"`
// SessionModel selects how a run maps to a mast session: "per_thread"
// (the default — one session per AG-UI threadId, so a chat thread is one
// continuing conversation) or "per_run" (a fresh session per runId, for
// stateless one-shot runs). The daemon always derives + namespaces the
// session id; a client never supplies a raw session id.
SessionModel string `yaml:"session_model,omitempty"`
// Auth is the per-endpoint auth policy.
Auth AGUIAuth `yaml:"auth,omitempty"`
}
AGUI is the workload's AG-UI-server exposure (docs/ag-ui-design.md): the agent→user surface a browser/app UI (CopilotKit et al.) drives over an HTTP POST + SSE run stream. Absent or expose:false means the workload is not reachable over AG-UI — like A2A, exposure carries real ops implications (auth setup, a public turn-driving endpoint), so it is opt-in per workload.
type AGUIAuth ¶ added in v0.2.0
type AGUIAuth struct {
// Required declares the endpoint needs authentication. Informational in
// v0.2 when a server-wide token validator is configured (all exposed
// endpoints sit behind it); Scopes are the enforced grain.
Required bool `yaml:"required,omitempty"`
// Scopes are the token scopes a caller must carry to drive a run; missing
// scope → 403 (docs/ag-ui-design.md "Auth model").
Scopes []string `yaml:"scopes,omitempty"`
}
AGUIAuth is the per-endpoint auth policy within a workload's agui: section.
type Budget ¶
type Budget struct {
// MaxTurns caps the number of model calls per session. 0 means
// unlimited. One "turn" = one model call (the unit pkg/budget's
// meter counts), so a Task specialist's internal tool loop spends
// one turn per model call, not one per dispatch.
MaxTurns int `yaml:"max_turns,omitempty"`
MaxWallclockSeconds int `yaml:"max_wallclock_seconds,omitempty"`
MaxCostUSD float64 `yaml:"max_cost_usd,omitempty"`
// FinalReport lets a specialist that has already spent something buy
// one model call past the ceiling that stopped it, purely to write
// its report: every tool but the report tool is withdrawn for that
// call, and it is granted at most once per specialist.
//
// Off by default, because it is a deliberate overshoot. A workload
// whose cap is a hard spending limit should leave it off and accept
// that a stopped specialist returns nothing. Turn it on where the
// cap is a guardrail against a runaway and an unresolved delegation
// is the more expensive outcome. See pkg/budget/finalreport.go.
FinalReport bool `yaml:"final_report,omitempty"`
}
Budget is the workload-level runtime budget ceiling. Composes over per-specialist budgets — the tightest cap wins.
type BuiltinTools ¶ added in v0.8.0
type BuiltinTools struct {
// WebSearch toggles server-side web search grounding.
WebSearch *bool `yaml:"web_search,omitempty"`
// URLContext toggles fetching and grounding on URLs the model
// decides to visit. Gemini only.
URLContext *bool `yaml:"url_context,omitempty"`
// CodeExecution toggles sandboxed Python execution on the
// provider's servers. Gemini only.
CodeExecution *bool `yaml:"code_execution,omitempty"`
}
BuiltinTools gates the PROVIDER's server-side built-in tools — the ones the model invokes inside the vendor's own infrastructure, whose results come back folded into the response.
This is a different axis from everything else in this file. mast never sees a tool call for these, so nothing in the tool layer can reach them: not tool_catalog, not a specialist's tools allowlist (ToolAllowlist.Builtin is documented in its own field comment as not a grant), not the permissions gate, not the write gate, not the effect outbox. A read_only specialist with web search on can read the public internet and leave no tool call behind to show for it. This block is the only lever, which is why it sits on the bundle: the file that bounds an unattended agent should be where its reach is stated.
mast's baseline is everything off, on every provider — not the vendor's baseline. Gemini ships web search and URL context on and Anthropic ships web search off, so inheriting the vendor default would mean one image changing an unattended agent's internet reachability with a --provider flag, and multi-provider is mast's premise. Turning one on is a bundle's decision, stated here (#324, resolved 2026-09-10).
Every field is a tri-state *bool: absent takes mast's default (off), and an explicit true/false says so in the file. The distinction buys nothing today beyond documenting an operator's intent — it is kept because a default is a thing that can move, and a bundle that wrote `false` should keep meaning off if one ever does.
The names are provider-neutral, not provider-native:
web_search Gemini google_search; Anthropic web_search url_context Gemini url_context; no Anthropic equivalent code_execution Gemini code_execution; no Anthropic equivalent
A field with no equivalent on the resolved provider is ignored rather than refused. That only ever fails safe: "no equivalent" means the provider has no such tool to leave on, so a value that lands nowhere describes a state that already holds. It does mean a `code_execution: true` written against a claude-* model buys nothing — which is why mast logs the effective set at startup, read off the constructed provider rather than off this struct.
func (BuiltinTools) CodeExecutionOn ¶ added in v0.8.0
func (b BuiltinTools) CodeExecutionOn() bool
func (BuiltinTools) URLContextOn ¶ added in v0.8.0
func (b BuiltinTools) URLContextOn() bool
func (BuiltinTools) WebSearchOn ¶ added in v0.8.0
func (b BuiltinTools) WebSearchOn() bool
WebSearchOn, URLContextOn and CodeExecutionOn resolve each tri-state against mast's default-off baseline. Asked through methods rather than dereferenced at each call site so the "absent means off" rule lives in one place — the rule is the security property, and a nil deref at a call site that forgot it is the other failure mode.
type Bundle ¶
type Bundle struct {
// SchemaVersion declares which bundle schema this file is written
// against. Absent means 1 — every bundle written before the field
// existed is a schema-1 bundle, and stays loadable untouched.
//
// Load refuses a version newer than CurrentSchemaVersion, naming
// both numbers. That refusal is the reason the field exists: this
// is the file that declares which tools may run without an
// operator, so a mast that cannot read all of it must say so rather
// than run the part it understands.
SchemaVersion int `yaml:"schema_version,omitempty"`
// Name is the workload identifier — unique per mast deployment.
Name string `yaml:"name"`
// Description is a human-readable summary used in operator UIs and
// logs.
Description string `yaml:"description,omitempty"`
// Mode declares the session mode. Defaults to single_session.
Mode Mode `yaml:"mode,omitempty"`
// ToolCatalog enumerates the tools available to this workload.
ToolCatalog ToolCatalog `yaml:"tool_catalog,omitempty"`
// Specialists lists the specialist names this workload composes.
// Names resolve against the .agents/specialists/ directory (or the
// spike's --specialists-dir).
Specialists []string `yaml:"specialists,omitempty"`
// Dispatch declares the root shape this roster is built for; empty
// leaves the choice to the caller. See the Dispatch* constants.
Dispatch string `yaml:"dispatch,omitempty"`
// Fanout configures the fan-out shape; ignored under any other
// dispatch.
Fanout Fanout `yaml:"fanout,omitempty"`
// Budget bounds this workload's per-invocation runtime.
Budget Budget `yaml:"budget,omitempty"`
// Safety is the workload's runaway-backstop policy; the zero value
// leaves every posture to the host's default.
Safety Safety `yaml:"safety,omitempty"`
// BuiltinTools gates the provider's server-side built-in tools
// (web search, URL context, code execution). The zero value is
// mast's baseline: all of them off, on every provider.
BuiltinTools BuiltinTools `yaml:"builtin_tools,omitempty"`
// HITL is the human-in-the-loop policy for this workload.
HITL HITL `yaml:"hitl,omitempty"`
// HITLPolicy is the spelling docs/orchestration-design.md uses for
// the same block. The two keys are equivalent and Load folds this
// one into HITL; declaring both is an error rather than a
// precedence rule, because a bundle with two conflicting HITL
// blocks has no reading that is obviously right and the wrong
// reading executes a mutation nobody approved.
HITLPolicy HITL `yaml:"hitl_policy,omitempty"`
// Planner configures the supervisor-body planner for this
// workload; zero value means planner off.
Planner Planner `yaml:"planner,omitempty"`
// EdgeTrigger declares how external signals reach this workload.
EdgeTrigger EdgeTrigger `yaml:"edge_trigger,omitempty"`
// Monitor declares the calls a scheduled cycle makes on mast's own
// behalf, before the model is woken; zero value means the model is
// woken with nothing but the tick.
Monitor Monitor `yaml:"monitor,omitempty"`
// A2A declares the workload's A2A-server exposure; zero value (or
// expose:false) means the workload is not reachable over A2A.
A2A A2A `yaml:"a2a,omitempty"`
// AGUI declares the workload's AG-UI-server exposure; zero value (or
// expose:false) means the workload is not reachable over AG-UI.
AGUI AGUI `yaml:"agui,omitempty"`
// Filename is preserved for diagnostics; not part of the on-disk
// schema.
Filename string `yaml:"-"`
}
Bundle is the loaded workload bundle.
func Load ¶
Load reads a workload bundle YAML file, parses it, validates required fields, and returns the populated Bundle.
Decoding is two passes, and the order is the point. The first pass reads nothing but schema_version, leniently; the second decodes the whole file strictly, refusing any key the Bundle does not declare. A bundle from the future fails both — it names a version this binary does not speak *and* it almost certainly carries keys this binary has never heard of — and the version check has to win, because "this bundle declares schema 2, this mast speaks 1" tells an operator what to do and "field foo not found" does not.
type Capture ¶ added in v0.7.0
type Capture struct {
// Read names the read-only tool that records the prior state. It
// must be classified read-only, and mast refuses to start rather
// than run a recording that changes what it records.
Read string `yaml:"read"`
// Args are literal arguments for the read.
Args map[string]any `yaml:"args,omitempty"`
// ArgsFrom maps a read argument name to the argument of the change
// being captured that supplies it.
ArgsFrom map[string]string `yaml:"args_from,omitempty"`
// Fields are dot-separated paths into the read's result to record.
// Empty records the whole result — the opposite default from a
// precondition, and deliberately: a capture that kept too little is
// a capture that cannot restore, and the cost of keeping too much is
// a larger row.
Fields []string `yaml:"fields,omitempty"`
// Revert declares the call that puts the captured state back, or is
// omitted when this workload has no inverse to offer. Omitting it is
// honest and still useful: the record carries the old value even
// when mast cannot name the call that restores it.
Revert *Revert `yaml:"revert,omitempty"`
}
Capture is the bundle spelling of a prior-state capture (approval.Capture, converted by internal/compose for the same reason Precondition is: pkg/approval does not import pkg/workload).
tools:
- name: patch_k8s_resource
mutating: true
capture:
read: get_k8s_resource
args_from: {kind: kind, name: name, namespace: namespace}
fields: [spec.template.spec.containers]
revert:
call: patch_k8s_resource
args_from_change: {kind: kind, name: name, namespace: namespace}
args_from_capture: {patch: spec.template.spec.containers}
It looks like a precondition and 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 call.
type EdgeTrigger ¶
type EdgeTrigger struct {
HTTP *HTTPTrigger `yaml:"http,omitempty"`
Scheduled *ScheduledTrigger `yaml:"scheduled,omitempty"`
}
EdgeTrigger declares how external signals reach this workload: an inbound POST, a cadence of its own, or both. Other transports (a message queue) will join here.
type Fanout ¶ added in v0.3.0
type Fanout struct {
// MaxConcurrency caps how many analyst branches run at once. It is
// passed to ADK's NewParallelWorker, which is the only concurrency
// knob that binds from a workflowagent root (resolved-decision row
// 133 — WithMaxConcurrency is unreachable there). 0 means the
// package default; negative means unbounded, which is ADK's own
// meaning for the argument and is why the field is not clamped.
MaxConcurrency int `yaml:"max_concurrency,omitempty"`
}
Fanout configures the fan-out dispatch shape (docs/v0.3-plan.md W3). Ignored under any other dispatch.
type HITL ¶
type HITL struct {
// RequireApproval pauses the workflow after each specialist result
// via a durable RequestInput interrupt; an operator resume supplies
// the approval verdict.
//
// This is the *result*-level gate (the change-safety-gate stand-in
// from docs/triage-demo-plan.md) and is orthogonal to OnMutation,
// which gates individual tool calls before they fire.
RequireApproval bool `yaml:"require_approval,omitempty"`
// OnMutation is the pre-call write gate's policy. Empty means
// require_approval: a workload that says nothing about mutation
// gets the safe answer, because the failure mode of the other
// default is an unattended agent writing to a production cluster
// that nobody agreed to.
//
// The default binds to the bundle, not to the process. A library
// embed running with no bundle at all has no workload policy and
// no channel to answer a park on, so it gets no write gate unless
// it asks for one; see internal/compose.WriteGate.
OnMutation OnMutation `yaml:"on_mutation,omitempty"`
// ChangeSetTTL bounds how long an operator's approval of a change
// set authorizes that set's remaining calls (v0.4 W7). A Go
// duration string: "10m", "45s". Empty means
// approval.DefaultGrantTTL.
//
// Tune it up rather than down. The TTL is a backstop against an
// approval executing in a world nobody looked at — a daemon that
// comes back tomorrow — and not the freshness check itself; that is
// tool_catalog.tools[].precondition. A TTL short enough to fire
// during normal operation trains operators to re-approve without
// reading, which costs more safety than it buys.
ChangeSetTTL string `yaml:"change_set_ttl,omitempty"`
}
HITL is the workload's human-in-the-loop policy (docs/orchestration-design.md's hitl_policy; the shipped YAML key is `hitl:`, and `hitl_policy:` is accepted as the documented spelling — see Bundle.HITLPolicy).
func (HITL) EffectiveChangeSetTTL ¶ added in v0.4.0
EffectiveChangeSetTTL parses hitl.change_set_ttl. A zero duration means "unset, use the package default" — the caller resolves it, because the default belongs to the write gate rather than to the bundle schema.
The parse error is returned rather than swallowed: a typo'd duration silently becoming the default is how a workload ends up with a freshness window nobody chose. Load refuses the bundle instead.
func (HITL) EffectiveOnMutation ¶ added in v0.3.0
func (h HITL) EffectiveOnMutation() OnMutation
EffectiveOnMutation resolves the empty value to the documented default.
type HTTPTrigger ¶
HTTPTrigger declares that a workload accepts inbound POSTs on the mast inject endpoint. The path + auth mode are informational for the spike (the inject server declares its own routes globally); later steps will wire per-workload path prefixes.
type MCPServerRef ¶
type MCPServerRef struct {
Server string `yaml:"server"`
}
MCPServerRef references an MCP server by its declared name in the deployment's mcp.json.
type Mode ¶
type Mode string
Mode is the session mode a workload runs in.
const ( // ModeSingleSession is the spike default: one long-lived session // per workload. Multi-session substrate is deferred to v0.2. ModeSingleSession Mode = "single_session" // ModeMultiSession will be honored once the multi-session substrate // lands. Kept in the vocabulary so bundles can declare intent // today. ModeMultiSession Mode = "multi_session" )
type Monitor ¶ added in v0.5.0
type Monitor struct {
// Collect is the ordered list of calls one cycle opens with. Order
// is honoured and the calls are serial: a diff that classifies the
// scan has to run after the scan, and there is no useful
// concurrency in two calls when the second depends on the first.
Collect []MonitorCollect `yaml:"collect,omitempty"`
// TransitionsFrom names the collect key whose result carries the
// run-to-run classification — what is new, what got worse, what
// cleared since the previous cycle (v0.5 W4.4).
//
// monitor:
// collect:
// - tool: k8s_findings_diff
// args: {transitions: "new,escalated,resolved"}
// as: transitions
// transitions_from: transitions
//
// Naming it does three things nothing else can do: the envelope
// files the parsed set under `transitions` instead of a wall of
// text; the cycle FAILS on a malformed or truncated answer rather
// than waking the model with a hole where the diff should be; and
// W4.5's notifier gets a set to be empty or not, which is what "only
// notify on change" is decided from.
//
// It is optional, and a workload that collects raw facts and lets
// the model read them is a supported shape — but a workload that
// wants to notify on change needs the classification named, because
// mast will not derive one. See pkg/monitor.
TransitionsFrom string `yaml:"transitions_from,omitempty"`
// Notify is where a cycle speaks, and how long it may stay silent
// (v0.5 W4.5). Absent means a cycle that changes nothing outside
// mast: the assessment lands in the session transcript and nowhere
// else, which is the right default for a workload nobody has told
// where to post.
Notify *MonitorNotify `yaml:"notify,omitempty"`
// Ack is the tool an operator's acknowledgement is forwarded to
// (v0.5 W4.6). Absent means the daemon's ack route answers 404: a
// workload that declares nowhere to forward an ack cannot take one.
Ack *MonitorAck `yaml:"ack,omitempty"`
}
Monitor is the workload's unattended-monitoring block (v0.5 W4.2): the calls a scheduled cycle makes for itself, outside the model's tool surface.
Why this is a block and not a specialist's allowlist ¶
The obvious spelling — give the model the collection tools and let it call them — does not survive contact with the write gate, and the reason is not a mast quirk. A run-to-run finding diff *advances persisted state* as a side effect of answering "what changed?", so it declares itself mutating and is right to; and mast's mutation predicate defaults every MCP tool to mutating regardless, because ADK's mcptoolset drops MCP's annotations and default-deny-unknown is the only safe reading of a tool nobody classified. Under the default hitl.on_mutation: require_approval, a cycle that asks the model to call the diff parks for a human on EVERY fire. An unattended monitor that needs an operator to authorize finding out whether anything changed is not unattended.
So the collection leg is mast's. Nothing gates it because no model asked for anything, and internal/compose refuses to start if a tool named here also appears in any specialist's reach — the exception is narrow by construction rather than by convention.
The corollary is the property scoreboard row 9 is about: a leg the model is not part of cannot spend a token.
What this block does NOT carry ¶
The cadence. That is edge_trigger.scheduled, where v0.4 put it, and duplicating it here would be two places to configure one cycle — the failure mode being that they disagree and the operator reads the one that is not running.
And the transition vocabulary. transitions_from names WHERE the classification comes from; what the classes are, and which findings deserve which one, belongs to the tool that answers — see pkg/monitor for why mast holds no opinion about it.
func (Monitor) AckArgs ¶ added in v0.5.0
AckArgs returns the bundle's literal ack arguments. The caller merges mast's two over the top of these, never under them.
func (Monitor) AckTool ¶ added in v0.5.0
AckTool is the tool an operator acknowledgement is forwarded to, or "" for a workload that takes no acks (v0.5 W4.6).
func (Monitor) CollectTools ¶ added in v0.5.0
CollectTools returns the tool names the collection leg runs, in declaration order and de-duplicated.
func (Monitor) EffectiveDigestAfter ¶ added in v0.5.0
EffectiveDigestAfter parses monitor.notify.digest_after. Zero means no heartbeat: this workload speaks only when something changed.
The parse error is returned rather than swallowed, for the reason EffectiveInterval gives: a deadman that silently failed to parse is an operator believing they will hear from a monitor that has no way left to speak.
func (Monitor) Enabled ¶ added in v0.5.0
Enabled reports whether this workload collects on its own behalf.
func (Monitor) NotifyTarget ¶ added in v0.5.0
NotifyTarget returns the conversation a cycle posts into, or "" when the workload declares no notify block.
func (Monitor) SelfRunTools ¶ added in v0.5.0
SelfRunTools returns every tool mast runs on this workload's behalf outside the model's dispatch path — the collection calls and the ack forward. This is the set internal/compose keeps out of every roster.
One list rather than two because the fence is one rule: a tool mast runs ungated must be reachable by nobody else. Which direction it runs in is why the exception exists, not what bounds it.
func (Monitor) TransitionsKey ¶ added in v0.5.0
TransitionsKey is the collect key the classification is read from, or "" if the workload does not name one.
type MonitorAck ¶ added in v0.5.0
type MonitorAck struct {
// Tool is the wired tool an ack is forwarded to. It resolves
// against the same toolsets everything else does.
Tool string `yaml:"tool"`
// Args are literal arguments merged UNDER the two mast supplies:
// subject_key (what the operator acked) and ack_by (who they are).
// Deployment facts belong here — which cluster, how long a
// suppression lasts. An attempt to pin subject_key or ack_by is
// refused at load, because a bundle that names the acker names it
// for everyone.
Args map[string]any `yaml:"args,omitempty"`
}
MonitorAck is the inbound half of a monitoring cycle (v0.5 W4.6): an operator says "I have seen this one, stop telling me", and mast forwards that to whoever owns the finding's state.
monitor:
ack:
tool: k8s_findings_ack
args: {window: 4h}
Which direction this runs in ¶
Every other monitor block reads. This one writes, and to a store mast does not own: the suppression lives with the producer of the transitions, because that is the only place the next cycle's classification can read it from. mast's part is smaller and is the part nothing else can do — authenticate the operator, record who asked and when, and forward. The producer owns the window and the state; mast owns the attribution.
Why the model cannot reach it ¶
For the same structural reason a collect tool cannot: an ack tool is run by mast on its own behalf, and internal/compose refuses to start if it is reachable from any roster. That fence matters more here than it does for collection. A suppression is a mute button on the monitoring, the producer's own triage-status write is typically not permission-gated, and mast's authn is therefore the only thing standing in front of it. An agent that could silence its own alerts is not a monitoring system.
What is deliberately not here ¶
A verdict, a grant, a freshness window, a change-set signature. An ack is not a mutation approval — see docs/orchestration-design.md, "Ack routing" — and giving it the write gate's machinery would put a suppression into the decision export as an adjudication, which is how "who approved this change" quietly starts meaning "who muted an alert".
And a per-request window. How long a suppression lasts is the producer's policy, set through args for the deployment; there is no consumer for a per-request one until an in-chat ack button exists, and a knob mast passes through without understanding is a knob it cannot validate.
type MonitorCollect ¶ added in v0.5.0
type MonitorCollect struct {
// Tool is the wired tool to run. It resolves against the same
// toolsets everything else does, so a name nothing wires is a
// failed cycle naming the tool — not a silent empty result.
Tool string `yaml:"tool"`
// Args are the literal arguments for the call. mast has nothing to
// derive them from: a collection call is not about any particular
// object, so unlike a precondition read there is no change to map
// arguments from.
Args map[string]any `yaml:"args,omitempty"`
// As is the key this call's result is filed under in the envelope.
// Defaults to the tool name, which is the right answer until a
// workload collects from one tool twice.
As string `yaml:"as,omitempty"`
}
MonitorCollect is one call mast makes on its OWN behalf at the top of a monitoring cycle, before the model is woken (v0.5 W4.2).
monitor:
collect:
- tool: k8s_cluster_health
as: health
- tool: k8s_findings_diff
args: {transitions: "new,escalated,resolved"}
as: transitions
The result is handed to the model as part of the wake-up envelope. The model never holds the tool.
func (MonitorCollect) Key ¶ added in v0.5.0
func (c MonitorCollect) Key() string
Key is the envelope key this call's result is filed under.
type MonitorNotify ¶ added in v0.5.0
type MonitorNotify struct {
// Conversation is the platform key switchboard posts into — for
// Slack a channel ID, or "channel:thread_ts" to post into a thread.
// Required whenever the block is present: there is no default
// channel, and a monitor that guessed one would be worse than one
// that refused to start.
Conversation string `yaml:"conversation"`
// DigestAfter is the longest this workload may stay silent. Once
// that much wall-clock has passed with nothing to report, the next
// cycle speaks anyway — a heartbeat, so that silence means "nothing
// changed" rather than "the daemon died three days ago".
//
// Wall-clock rather than a count of quiet cycles (the open question
// #242 left for W4.5): what an operator wants to state is how long
// they are willing to be in the dark, and a count only answers that
// after they have multiplied it by an interval they have to go and
// look up. A count also silently re-scales when the cadence is
// retuned, which is precisely when a deadman should not move.
//
// Empty or "0s" disables the heartbeat: the workload speaks only
// when something changed.
DigestAfter string `yaml:"digest_after,omitempty"`
}
MonitorNotify is the egress half of a monitoring cycle (v0.5 W4.5): where a cycle that has something to say says it, and how long a quiet monitor may go without saying anything at all.
monitor:
notify:
conversation: C0123ESCALATIONS
digest_after: 6h
Only on change ¶
A cycle speaks when its classification is non-empty. A cycle whose classification is empty — "we looked, and nothing changed" — does not wake the model and posts nothing, which is the whole point: an unattended monitor's ordinary output is silence, and a channel that gets a message every fifteen minutes is a channel nobody reads.
A workload that names no monitor.transitions_from has no basis to be quiet on and therefore speaks every cycle. That is a supported shape and a loud one; the load error it would deserve does not exist because "post every cycle" is a legitimate thing to ask a low-cadence workload for.
type OnMutation ¶ added in v0.3.0
type OnMutation string
OnMutation is what happens before a state-mutating tool call (docs/orchestration-design.md, hitl_policy.on_mutation). Which calls are mutating is the mutation predicate's answer, not this field's: built-in annotation or absent MCP readOnlyHint, default-deny-unknown, narrowed by the audited tool_catalog.tools[].mutating overrides.
const ( // OnMutationRequireApproval parks the call before it fires and // waits for an operator verdict. The default. OnMutationRequireApproval OnMutation = "require_approval" // OnMutationApply executes mutating calls without asking. For a // workload whose blast radius is bounded some other way — a test // fixture, a sandbox cluster, an RBAC-confined service account. OnMutationApply OnMutation = "apply" // OnMutationDryRun never executes a mutating call and tells the // agent what would have happened. OnMutationDryRun OnMutation = "dry_run" )
type Planner ¶
type Planner struct {
// Enabled switches the workload's root agent to the supervisor-body
// planner (pkg/planner) with the bundle's specialists as its
// invoke_specialist roster. When false (the default), dispatch is
// unchanged: the --dispatch coordinator/graph shapes drive the
// roster directly.
Enabled bool `yaml:"enabled,omitempty"`
}
Planner is the workload's planner block (docs/orchestration-design.md "The planner"). v0.1 scaffold subset: enabled only. Later fields — plan_review_required, reference_shapes — join when their subsystems land (v0.2 per the phasing table).
type Precondition ¶ added in v0.4.0
type Precondition struct {
// Read names the read-only tool that re-establishes the fact. It
// must be classified read-only: a freshness check that changes the
// cluster is not a check, and mast refuses to start rather than
// run one.
Read string `yaml:"read"`
// Args are literal arguments for the read.
Args map[string]any `yaml:"args,omitempty"`
// ArgsFrom maps a read argument name to the argument of the change
// being checked that supplies it, so one declaration covers every
// call to the tool.
ArgsFrom map[string]string `yaml:"args_from,omitempty"`
// Fields are dot-separated paths into the read's result to compare
// individually, so a drifted approval can say what moved. Empty
// compares the whole result, which is the right default for a
// narrow read and the wrong one for a chatty read — narrow the
// read rather than filtering it here.
Fields []string `yaml:"fields,omitempty"`
}
Precondition is the bundle spelling of a change-set freshness check (approval.Precondition, which this is converted into by internal/compose — pkg/approval does not import pkg/workload, the same separation MutationPredicate keeps).
tools:
- name: scale_deployment
mutating: true
precondition:
read: get_deployment
args_from: {name: deployment, namespace: namespace}
fields: [spec.replicas, metadata.generation]
type Revert ¶ added in v0.7.0
type Revert struct {
// Call names the tool that performs the undo. Often the same tool
// as the change; written out rather than defaulted so the record
// reads correctly on its own.
Call string `yaml:"call"`
// Args are literal arguments for the revert call.
Args map[string]any `yaml:"args,omitempty"`
// ArgsFromChange maps a revert argument name to the change's
// argument that supplies it — how the undo addresses the same object
// the change addressed.
ArgsFromChange map[string]string `yaml:"args_from_change,omitempty"`
// ArgsFromCapture maps a revert argument name to a dot-separated
// path into the captured read result: the old value, going back.
ArgsFromCapture map[string]string `yaml:"args_from_capture,omitempty"`
}
Revert is the bundle spelling of the call that undoes a change (approval.Revert).
mast never fires it. It is computed before the forward call runs, checked against the revert tool's declared input schema, and written into the durable record as a proposed change — which means undoing something goes back through the write gate like any other change, with a person answering. See pkg/approval/capture.go.
type Safety ¶ added in v0.4.0
type Safety struct {
// Watchdog is the behavioral watchdog posture for this workload:
// warn, feedback, or enforce (pkg/watchdog.Mode's ladder — each
// rung includes the one below it). Empty means unset, which is not
// the same as "warn": an unset posture falls through to the
// daemon's default, and the --watchdog flag overrides whatever is
// declared here.
//
// Enforce is the posture to reach for when the workload's tool loop
// is bounded by construction — a triage run that reads, concludes,
// and stops. Leave it unset for a workload whose steady state looks
// like a loop to a detector: a scheduler-driven daemon watching a
// rollout settle calls the same tool with the same arguments on
// purpose, and halting it is the outage.
Watchdog string `yaml:"watchdog,omitempty"`
}
Safety is the workload's runaway-backstop policy: the knobs that decide what happens when the agent starts doing something no one asked for.
It lives in the bundle rather than only on the command line because the bundle is mast's deployment unit. A workload that knows it never polls can arm the halt for itself, and a workload that does nothing but poll can stay at warn, without every invocation and every deploy manifest carrying the flag by hand.
type ScheduledTrigger ¶ added in v0.4.0
type ScheduledTrigger struct {
// Interval is the cadence as a Go duration string: "15m", "1h",
// "24h". Required whenever the block is present, because there is
// no defensible default period for "how often should this cost
// money".
Interval string `yaml:"interval,omitempty"`
// Jitter bounds a random offset added to each individual fire:
// a fire lands somewhere in [tick, tick+jitter).
//
// Non-zero by default (a tenth of the interval, capped at
// defaultMaxJitter) because the failure mode it prevents is one
// nobody declares their way into: N replicas of one deployment,
// started by one rollout, all waking on the same second and
// arriving at the same API server together. The offset applies to
// the fire and never to the anchor, so it cannot accumulate into
// drift — a jittered cadence is still the cadence that was asked
// for, sampled a little late. Set "0s" for an exactly-on-the-tick
// schedule.
Jitter string `yaml:"jitter,omitempty"`
// Prompt is the text each scheduled run opens with — what the
// workload is being woken up to do ("Sweep every namespace for
// pods in CrashLoopBackOff and report what you find").
//
// Optional, but a scheduled run that says nothing is a workload
// re-reading its own system instruction and guessing; the envelope
// mast supplies on its own carries only the tick.
Prompt string `yaml:"prompt,omitempty"`
}
ScheduledTrigger declares that the workload wakes itself on a fixed cadence (v0.4 W4.1) — the trigger for periodic work nobody POSTs to: a nightly cost sweep, a drift check, a five-minute look at a cluster that is not currently on fire.
The cadence is ANCHORED, not reset: fires land on anchor + k×interval, where the anchor is the moment mast first saw this schedule and is persisted with it. A daemon restart therefore resumes the original phase instead of re-phasing to whenever the process happened to come back. Ticks that passed while the daemon was down are skipped rather than caught up; the reasoning for that lives next to the code that acts on it, in cmd/mast/schedtrigger.go.
A workload may declare this alongside `http:` — the two triggers are independent, and an operator can still inject into a scheduled workload.
func (*ScheduledTrigger) EffectiveInterval ¶ added in v0.4.0
func (s *ScheduledTrigger) EffectiveInterval() (time.Duration, error)
EffectiveInterval parses edge_trigger.scheduled.interval. A nil trigger (no scheduled block) has no cadence and reports zero.
Like EffectiveChangeSetTTL the parse error is returned rather than swallowed: a schedule that silently failed to parse is a workload an operator believes is running and that has never once woken up.
func (*ScheduledTrigger) EffectiveJitter ¶ added in v0.4.0
func (s *ScheduledTrigger) EffectiveJitter() (time.Duration, error)
EffectiveJitter resolves edge_trigger.scheduled.jitter against the interval, which is why the default is computed here and not left to the caller: it is a fraction of a value the same block declares.
An omitted jitter means the default; an explicit "0s" means the operator asked for an exact cadence and gets one.
type ToolCatalog ¶
type ToolCatalog struct {
MCP []MCPServerRef `yaml:"mcp,omitempty"`
// Tools carries per-tool policy overrides. v0.2 subset: the
// mutation-class override consumed by the recorded-effect outbox
// (docs/orchestration-design.md's mutation predicate — MCP
// annotations are advisory AND dropped by ADK's mcptoolset, so
// unknown tools default to mutating; this is the audited un-gate
// for known-safe tools).
Tools []ToolPolicy `yaml:"tools,omitempty"`
}
ToolCatalog is the workload-scoped tool inventory. Composes with (and is intersected against) per-specialist tool allowlists at dispatch time — see docs/specialists-design.md "Allowlist semantics".
type ToolPolicy ¶ added in v0.2.0
type ToolPolicy struct {
Name string `yaml:"name"`
// Mutating overrides the tool's mutation classification: false
// un-gates a known-read-only tool from the recorded-effect outbox,
// true forces the check for a tool the defaults would miss. Nil
// (omitted) means no override. Applications are audit-logged.
Mutating *bool `yaml:"mutating,omitempty"`
// Precondition declares what a call to this tool assumes about the
// cluster, as a read this workload can make (v0.4 W7). It is what
// an approved change set is re-checked against before each of its
// remaining calls fires: mast takes the read at approval time and
// again at fire time, and asks the operator afresh if the answer
// moved.
//
// Declaring it is the workload's job because mast cannot derive
// it. mast is Kubernetes-agnostic and an MCP tool's arguments are
// opaque to it, so it has no way to know which tool reads the
// object a write call is about, or which argument names it. A tool
// with no precondition is bounded by hitl.change_set_ttl alone —
// which is a real bound, but a clock is not a fact about the
// cluster, and mast says so in the approval question rather than
// implying a check it is not making.
Precondition *Precondition `yaml:"precondition,omitempty"`
// Capture declares what to record before a call to this tool
// changes anything, so an operator asking "how do I undo this" has
// an answer in the transcript rather than in their memory (#296).
//
// Same reason the precondition is the workload's job: mast cannot
// derive which tool reads the object a write call is about. And the
// same reason again for the revert inside it — putting a captured
// value back is a call, and which call it is depends on the tool.
//
// A tool with no capture behaves exactly as it did before v0.7. A
// tool with one does not run unless the capture can be taken: see
// pkg/approval/capture.go on why fail-closed is the honest reading
// of declaring one at all.
Capture *Capture `yaml:"capture,omitempty"`
}
ToolPolicy is a per-tool policy override in the workload's tool_catalog, keyed by the tool's registered name.