specialists

type Budget struct {
	MaxTurns            int     `yaml:"max_turns,omitempty"`
	MaxWallclockSeconds int     `yaml:"max_wallclock_seconds,omitempty"`
	MaxCostUSD          float64 `yaml:"max_cost_usd,omitempty"`
}

type BuildOptions struct {
	// Model is the parent's model — the default every specialist runs
	// on when it declares no `model:` override.
	Model model.LLM

	// Resolve resolves per-specialist `model:` overrides. Nil is legal
	// only when no Spec in the roster declares an override; Build
	// refuses a declared override it cannot resolve rather than
	// silently running the specialist on the parent's model (the bug
	// this field fixes — see docs/v0.3-plan.md W1.1).
	Resolve ModelResolver

	// ResolveTier resolves per-specialist `tier:` declarations. Nil is
	// legal only when no Spec in the roster declares one; a declared
	// tier with no resolver is a build error for the same reason a
	// declared `model:` with no Resolve is.
	ResolveTier TierResolver

	Tools    []tool.Tool
	Toolsets []tool.Toolset

	// OnStall, when non-nil, installs mastagent.FinishOnStall on every
	// Task-mode specialist Build creates, using the payload this function
	// returns for that spec. Returning nil selects
	// mastagent.DefaultStallPayload.
	//
	// It is opt-in and it is per-spec, in that order of importance.
	//
	// Opt-in because the guard fabricates a tool call. Every other default in
	// this package is a property of the wiring — which model, which toolsets,
	// whether transfer is offered — and can be argued for without knowing what
	// the roster does. This one puts words in a specialist's mouth on its
	// behalf, and a roster that would rather see the delegation die should not
	// have to discover the field to get that.
	//
	// Per-spec because the payload has to satisfy the spec's own
	// output_schema, and only the roster knows what an empty value means in
	// its own contract. Requesting the guard for a spec that declares a schema
	// without returning a payload for it is a build error rather than a
	// fallback, for the same reason a declared-but-unresolvable model override
	// is: the fallback would produce a finish_task call the runtime refuses,
	// leaving exactly the unresolved delegation the guard exists to prevent,
	// and it would do it at run time on the one turn nobody is watching.
	OnStall func(spec Spec) mastagent.StallPayload
}

type Capability string

type Frontmatter struct {
	Name        string        `yaml:"name,omitempty"`
	Description string        `yaml:"description"`
	Mode        Mode          `yaml:"mode,omitempty"`
	Model       string        `yaml:"model,omitempty"`
	Tier        string        `yaml:"tier,omitempty"`
	Capability  Capability    `yaml:"capability,omitempty"`
	Budget      Budget        `yaml:"budget,omitempty"`
	Tools       ToolAllowlist `yaml:"tools,omitempty"`

	// OutputSchema is a path to a JSON-Schema document, relative to the
	// .tmpl file's own directory. It is a reference rather than an
	// inline block on purpose — see the comment at the top of schema.go.
	OutputSchema string `yaml:"output_schema,omitempty"`
}

type MCPAllowlist struct {
	Server string   `yaml:"server"`
	Tools  []string `yaml:"tools,omitempty"`
}

type Mode string

type ModelResolver func(name string) (model.LLM, error)

type Spec struct {
	// Filename is the path (or filename) the spec was loaded from,
	// preserved for diagnostics.
	Filename string

	// Frontmatter fields, promoted for convenience.
	Name        string
	Description string
	Mode        Mode
	Model       string
	Tier        string
	Capability  Capability
	Budget      Budget
	Tools       ToolAllowlist

	// Instruction is the body of the .tmpl file — the specialist's
	// system prompt, verbatim.
	Instruction string

	// OutputSchema is the loaded, normalized and checked contract this
	// specialist's output must satisfy, or nil when the spec declares
	// none. Loaded eagerly by LoadFile so a broken schema is a load
	// error rather than a surprise on the first live turn.
	OutputSchema *genai.Schema

	// OutputSchemaPath is the resolved path OutputSchema came from,
	// preserved for diagnostics. Empty when the spec declares none.
	OutputSchemaPath string
}

type TierResolver func(tier string) (model.LLM, error)

type ToolAllowlist struct {
	Builtin []string       `yaml:"builtin,omitempty"`
	MCP     []MCPAllowlist `yaml:"mcp,omitempty"`
	Skills  []string       `yaml:"skills,omitempty"`
}