workload

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"`
}

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"`
}

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"`
}

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"`
}

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"`
}

type Bundle struct {
	// 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"`

	// 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"`

	// 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:"-"`
}

type EdgeTrigger struct {
	HTTP      *HTTPTrigger      `yaml:"http,omitempty"`
	Scheduled *ScheduledTrigger `yaml:"scheduled,omitempty"`
}

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"`
}

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"`
}

type HTTPTrigger struct {
	Path string `yaml:"path,omitempty"`
	Auth string `yaml:"auth,omitempty"`
}

type MCPServerRef struct {
	Server string `yaml:"server"`
}

type Mode string

type OnMutation string

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"`
}

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"`
}

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"`
}

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"`
}

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"`
}

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"`
}