config

type Access struct {
	// Viewer is who may see the pipeline at all. Anybody else is told it does not exist.
	Viewer string `yaml:"viewer,omitempty"`
	// Operator is who may trigger, approve and abort in it. Anybody else who may see it only reads.
	Operator string `yaml:"operator,omitempty"`
}

type AcrossVar struct {
	Var    string   `yaml:"var"`
	Values []string `yaml:"values,omitempty"`
	// FromFile is a workspace-relative path to a JSON array of strings, whose
	// first path component names the artifact holding it (`findings/items.json`
	// requires an artifact `findings` fetched or produced earlier in the plan —
	// the same rule dir: follows, checked by workspace.ValidateArtifactFlow).
	//
	// A file rather than a key in a store: the producing step already declares
	// the artifact in its outputs:, so the value travels the way every other
	// piece of inter-step data does, and there is nothing extra to opt into on
	// the writing side. Mutually exclusive with Values.
	FromFile string `yaml:"from_file,omitempty"`
}

type Agent struct {
	Name   string      `yaml:"name"`
	Source AgentSource `yaml:"source"`
	// Description is the human-readable summary of what this agent does. It is
	// shown to the model when another agent grants this one as a sub-agent tool
	// (see ToolSpec.Agent) with no inline description. An agent referenced as a
	// sub-agent MUST have a description — either inline on the grant or on the
	// agent itself — or pipeline load fails with a clear error.
	Description string `yaml:"description,omitempty"`
	// File loads every field of this agent but name: from a YAML
	// document at a path relative to the pipeline file's directory (see
	// LoadConfig's resolveFileIncludes), so one agent definition can be
	// shared across pipelines. Any field also set inline on this entry
	// overrides the loaded document's value for that field — the same "wins
	// when set" idiom ResolveTask already uses between a step and its tasks:
	// entry. The loaded document may not itself use file:/system_file:.
	File string `yaml:"file,omitempty"`
	// Image, when set, runs this agent's run_shell/custom-tool commands in a
	// fresh `docker run --rm` container from this image instead of on the
	// host. A step's own Image, if set, overrides this for that step only
	// (see Step.Image). Empty (the default) keeps host execution.
	Image string `yaml:"image,omitempty"`
	// Env names host environment variables this agent's run_shell/custom-tool
	// commands are allowed to see, on top of the always-allowed baseline (see
	// shell.HostEnv). Names only — see validateEnvValues. A step's own Env, if
	// non-nil, overrides this for that step only (see Step.Env).
	Env []string `yaml:"env,omitempty"`
	// User is the container user this agent's run_shell/custom-tool commands
	// execute as (docker's --user). Empty takes the platform default — see
	// shell's defaultContainerUser. Only meaningful alongside Image.
	User string `yaml:"user,omitempty"`
	// Network is the container network this agent's run_shell/custom-tool
	// commands join (docker's --network); "none" cuts off egress entirely.
	// Requires Image, except "none" beside Sandbox.
	Network string `yaml:"network,omitempty"`
	// Privileged runs this command's container with `docker run --privileged`.
	// Mirrors Concourse's privileged: (concourse-ci.org/docs/steps/task/).
	// Container-only, like Network — a host command has nothing to elevate,
	// so it is a load error without image:.
	Privileged bool `yaml:"privileged,omitempty"`
	// Limits caps the container's CPU and memory. Mirrors Concourse's
	// container_limits:; container-only for the same reason Privileged is.
	Limits *ContainerLimits `yaml:"container_limits,omitempty"`
	// Sandbox fences this entity's host commands with the OS sandbox: writes only under the step's workspace and a private TMPDIR, credential directories unreadable, and network: none becomes legal on the host. See internal/config/sandbox.go for the rules and docs/infra.md for the policy.
	Sandbox bool `yaml:"sandbox,omitempty"`
	// System is the persona/system message given to the model. Empty falls
	// back to a generic CI-agent persona.
	System string `yaml:"system,omitempty"`
	// SystemFile loads System's text from a file at a path relative to the
	// pipeline file's directory, instead of writing it inline — useful since a
	// persona is often long freeform prose. Mutually exclusive with System.
	SystemFile string `yaml:"system_file,omitempty"`
	// Generation dials, forwarded to the model when set. ReasoningEffort is
	// one of "low", "medium", "high" (for reasoning-capable models).
	Temperature     *float64 `yaml:"temperature,omitempty"`
	TopP            *float64 `yaml:"top_p,omitempty"`
	MaxTokens       int      `yaml:"max_tokens,omitempty"`
	ReasoningEffort string   `yaml:"reasoning_effort,omitempty"`
	// MaxTurns caps the tool-calling loop. Unset takes defaultTurnsFor(source)
	// — 30 for a hosted agent, none for a cli one; an explicit 0 removes the
	// cap entirely — see dials.go for the convention this shares with
	// MaxContextBytes and Timeout.
	MaxTurns *int `yaml:"max_turns,omitempty"`
	// MaxQuestions is the ask_user budget every step of this agent gets when
	// it declares none of its own. Unset takes defaultMaxQuestions; an
	// explicit 0 removes the cap. See Step.MaxQuestions for why the dial
	// counts questions rather than turns.
	MaxQuestions *int `yaml:"max_questions,omitempty"`
	// Timeout is the wall-clock deadline every step of this agent gets when
	// it declares none of its own (e.g. "20m"). Unset takes the package
	// default (30 minutes — DefaultAgentStepTimeout); "0" means no deadline
	// at all, which no other step kind needs a spelling for because omitting
	// the field already says it there.
	//
	// It lives here as well as on the step because the right deadline is
	// usually a property of the AGENT — a deep reviewer needs twenty minutes
	// whichever step invokes it — and without it a shared deadline had to be
	// copied onto every step naming the agent. Not hashed, exactly as the
	// step's own timeout: is not: a deadline is not part of what a step asks
	// for.
	Timeout string `yaml:"timeout,omitempty"`
	// Attempts is how many times a step of this agent re-issues a failed
	// REQUEST when it sets no attempts: of its own (see defaultAgentAttempts,
	// and docs/attempts-timeout.md for why a retry here is a transport
	// concern rather than a re-run of the conversation). Unset takes that
	// default; 0 is a load error, not "unlimited" — see dials.go. Never
	// hashed.
	Attempts *int `yaml:"attempts,omitempty"`
	// CompactAfterTokens caps how large a conversation's token
	// count grows before older turns are summarized away and replaced by a
	// running summary (see internal/agent/compaction.go and docs/agents.md's
	// "Compacting long conversations" section). A pointer, not a plain int,
	// because unset and explicit 0 mean different things: unset resolves to
	// defaultCompactAfterTokens (compaction ON by default), while 0 disables
	// compaction entirely — the same distinction Temperature/TopP already
	// need a pointer for. Like MaxTurns, this is agent-only: no per-step
	// override.
	CompactAfterTokens *int `yaml:"compact_after_tokens,omitempty"`
	// ContextWindow states this model's context window in tokens, for a model
	// contextWindows does not recognize — a local build, a release newer than
	// that table, or a HOST that serves a known model with a smaller window
	// than it has natively (a table keyed on model name cannot express the
	// last one at all).
	//
	// It is the "what the model is" knob to compact_after_tokens:' "what the
	// budget is": setting it keeps compactBudgetPercent applying, so an
	// operator says 200000 rather than computing 160000, and the run's own
	// compaction log reports a derived window instead of an assumed one.
	// compact_after_tokens:, when also set, still wins outright. Not hashed, for compact_after_tokens:' own reason: its only consumer is resolveCompactionBudget, so it is the same operational budget reached by another route.
	ContextWindow int `yaml:"context_window,omitempty"`
	// MaxContextBytes caps how much of a context_paths: file is handed to the
	// model at conversation start. Unset takes DefaultMaxContextBytes; an
	// explicit 0 hands over the whole file however large it is (see dials.go).
	//
	// It exists because the byte budget priming borrows was chosen for a
	// different job: context_paths is delivered as a synthetic read_file
	// result, so it inherited read_file's tool budget, and that number is sized
	// against the spill mechanics (it sits above maxToolOutputBytes so a
	// spilled output can be read back whole). Nothing in that reasoning is
	// about how much evidence a step should open holding — and on a model whose
	// context_window: is 1M, the inherited 100KB is about 2.5% of the window.
	//
	// Over the limit the file is TRUNCATED with a pointer, never refused, so
	// raising this buys context rather than turning a warning into an error.
	// Operational, like CompactAfterTokens, and excluded from the hash for the
	// same reason: it governs how much of a conversation's own history and
	// evidence is carried, not what the step is asking for.
	MaxContextBytes *int `yaml:"max_context_bytes,omitempty"`
	// Fallback lists alternate sources to use when the primary is
	// UNREACHABLE, in order. See AgentFallback. Never hashed: the primary is what the step ASKS for and is what the key names, while this is outage handling — keying it would re-run every cached step because somebody edited what happens when a provider is down.
	Fallback []AgentFallback `yaml:"fallback,omitempty"`
	// Preflight opts this agent out of (or into) the pre-run health check.
	// A pointer so unset inherits defaults.preflight. The case it exists for
	// is a model expected to be slow to WAKE — a cold local model would fail
	// a probe that a real conversation would have waited out. Never hashed: it decides whether a health probe runs BEFORE the step, and nothing about the conversation the step then has.
	Preflight *bool `yaml:"preflight,omitempty"`
	// Budget caps what one invocation of this agent may spend (see Budget).
	// Per invocation, not per job: a job budget is the cumulative ceiling and
	// lives on the job. Never hashed.
	//
	// The ceiling covers this agent AND everything it delegates to: a
	// sub-agent draws on this allowance rather than adding to it, so the
	// number bounds the whole subtree rather than one conversation in it.
	Budget *Budget `yaml:"budget,omitempty"`
	// DelegateBudgetPercent overrides how much of this agent's REMAINING
	// allowance one sub-agent call may take, for agents whose helpers are
	// unusually cheap or expensive relative to the parent. Pipeline-wide
	// default in Defaults.DelegateBudgetPercent. Never hashed, like the
	// budget it divides.
	DelegateBudgetPercent *int `yaml:"delegate_budget_percent,omitempty"`
	// Tools is the grant: the built-in tools this agent may use plus any
	// reusable custom tool definitions. A step selects a subset by name and
	// may add its own inline custom tools. Empty grants the read-only
	// built-ins (DefaultAgentToolSpecs).
	Tools []ToolSpec `yaml:"tools,omitempty"`
	// Settings opts a CLI-backed agent into the CLI's own configuration
	// scopes. The only accepted value is "project" — load the repo's
	// checked-in project scope (.claude/ settings, CLAUDE.md, hooks).
	// Absent, the subprocess loads no settings at all: a pipeline step is
	// not a personal session, and repo config shaping an agent is a
	// capability the pipeline must declare, not inherit. Rejected on hosted
	// (HTTP) agents, where there is no CLI to configure.
	Settings string `yaml:"settings,omitempty"`
	// Caches are directories this agent's commands keep between runs on the machine that ran them (see TaskCache). A referencing step's own Caches, if non-nil, override these for that step only.
	Caches []TaskCache `yaml:"caches,omitempty"`
}

type AgentFallback struct {
	Source AgentSource `yaml:"source"`
}

type AgentSource struct {
	Endpoint         string `yaml:"endpoint,omitempty"`
	Model            string `yaml:"model"`
	APIKeyEnv        string `yaml:"api_key_env,omitempty"`
	StringToolChoice *bool  `yaml:"string_tool_choice,omitempty"`
}

type Approval struct {
	// Message is what the waiting approval says it is asking about. Required:
	// an approval prompt with no question is one nobody can answer
	// responsibly, and "approve job build step 3?" is not a question.
	Message string `yaml:"message"`
	// Timeout bounds the wait (e.g. "24h"). Empty means the default (see
	// defaultApprovalTimeout in internal/pipeline). An expired approval
	// classifies as ABORTED, not failed — the outcome vocabulary already
	// distinguishes "nobody answered" from "somebody said no", and conflating
	// them would make a silent expiry indistinguishable from a rejection.
	Timeout string `yaml:"timeout,omitempty"`
}

type Assert struct {
	Execution []string `yaml:"execution,omitempty"`
	// Outcome, on a Job, asserts what the plan CONCLUDED rather than which
	// steps ran: AssertOutcomeFailed or AssertOutcomeSucceeded. It exists
	// because execution: cannot express "this job should have failed" — a
	// matching execution: clears the plan's error, so a fixture for any defect
	// about error propagation or swallowing passes on the broken build and the
	// fixed build alike. See docs/control-flow.md.
	Outcome string  `yaml:"outcome,omitempty"`
	Stdout  *string `yaml:"stdout,omitempty"`
	Code    *int    `yaml:"code,omitempty"`
	// Verdict, on an agent step that declares verdicts:, asserts which one the
	// model emitted — an exact match against the declared vocabulary.
	//
	// It exists because a verdict is the one agent outcome a fixture could not
	// pin directly: stdout: tests the prose around the decision, and
	// tool_calls: could only assert that the verdict tool was CALLED, not what
	// it chose. A classifier whose whole product is the choice was therefore
	// untestable at the one place it matters.
	Verdict *string `yaml:"verdict,omitempty"`
	// ToolCalls, on an agent step, asserts the ordered trajectory of tool
	// calls the model made (see ExpectedToolCall). Agent-only: a task step
	// runs no tools. Every entry must appear, in order, as a subsequence of
	// the observed calls.
	ToolCalls []ExpectedToolCall `yaml:"tool_calls,omitempty"`
	// Files, on a task or agent step, asserts that every listed path exists
	// as a non-empty file in the step's own outputs — the one thing no other
	// assert field checks: what the step WROTE rather than what it SAID. Each
	// path is artifact-relative (ValidateArtifactPath), and its first
	// component must name one of the step's declared outputs:.
	Files []string `yaml:"files,omitempty"`
	// Nudge, on an agent step, opts the step into being TOLD about an unmet
	// files:/tool_calls: entry while the model can still act on it — a
	// message at the moment it tries to stop, up to a fixed allowance — and
	// into the verdict tool refusing a decision over the same gap. Off, the
	// assert is the silent post-hoc judge every other field is.
	//
	// Opt-in because a nudge is automatic RECOVERY, not detection: a step
	// that never writes its file fails loudly either way, but a fixture whose
	// model is always put back cannot prove its prompt asked for the file at
	// all. It may only name an unmet obligation, never a wanted conclusion:
	// alongside stdout: or verdict: it is a load error, since a classifier
	// told the answer is not a test of anything.
	Nudge bool `yaml:"nudge,omitempty"`
}

type Budget struct {
	// Tokens is the ceiling for a HOSTED agent, counted from the provider's
	// own reported usage (prompt + completion, including reasoning tokens
	// where a provider reports them) — not an estimate. 0 is not "unlimited",
	// it is rejected: a budget block that caps nothing is a typo, and reading
	// it as "no limit" would be the most expensive possible interpretation.
	Tokens int `yaml:"tokens,omitempty"`
	// USD is the ceiling for a CLI agent, enforced by the CLI itself
	// mid-conversation. It exists because a subprocess reports its spend only
	// on exit — too late for a token counter here to stop anything — while the
	// CLI has a real circuit breaker of its own that takes dollars.
	USD float64 `yaml:"usd,omitempty"`
	// ReservePerCell is what an across: block's admission control ASSUMES one
	// not-yet-finished cell will spend, so Tokens binds at any max_in_flight.
	//
	// Admission can only see what FINISHED cells reported, so without a
	// reservation the first max_in_flight cells are always admitted against a
	// total of ~0 — and when the width covers every cell there is no
	// serialization point at all and the ceiling bounds nothing. Reserving on
	// admit and settling on completion closes that: overshoot becomes bounded
	// by how wrong the reservation is rather than by how many cells got a free
	// pass.
	//
	// Across-only, like Tokens on a step. Unset falls back to the cell agent's
	// own budget.tokens (the author already declared what one invocation may
	// cost), and with neither the block behaves exactly as it did before this
	// existed. Deliberately no global default: a guessed reservation that
	// silently under-admits is worse than an honest warning.
	ReservePerCell int `yaml:"reserve_per_cell,omitempty"`
}

type Bundle map[string]string

type CacheConfig struct {
	// Resources enables the cache. A separate field rather than the block's
	// presence meaning yes, so `cache: {resources: false}` can turn it off
	// without deleting tuning alongside it.
	Resources bool `yaml:"resources"`
	// MaxEntries bounds how many cached versions are kept, oldest-used
	// evicted first. 0 takes defaultCacheMaxEntries. A cache with no ceiling
	// grows until the disk does not, which on a long-lived daemon host is a
	// question of when, not whether.
	MaxEntries int `yaml:"max_entries,omitempty"`
}

type Config struct {
	ResourceTypes []ResourceType `yaml:"resource_types"`
	Resources     []Resource     `yaml:"resources"`
	Agents        []Agent        `yaml:"agents"`
	MCPServers    []MCPServer    `yaml:"mcp_servers,omitempty"`
	// MCPExports are bundles of this pipeline's tools other people's agents may connect to through the daemon. See MCPExport.
	MCPExports []MCPExport `yaml:"mcp_exports,omitempty"`
	// Rules are named checks on a call to a shared or granted tool. See Rule.
	Rules []Rule `yaml:"rules,omitempty"`
	Tasks []Task `yaml:"tasks"`
	Jobs  []Job  `yaml:"jobs"`
	// Defaults supplies pipeline-wide fallbacks and bounds: the model an
	// agent uses when it names none, preflight tuning, the delegation budget,
	// and the version/run/memory caps. See Defaults.
	Defaults *Defaults `yaml:"defaults,omitempty"`
	// Workspace opts the pipeline into Concourse-style per-step isolation.
	// Absent (the default) keeps every step in a triggered build sharing one
	// mutable directory, exactly as before this field existed. See
	// WorkspaceConfig.
	Workspace *WorkspaceConfig `yaml:"workspace,omitempty"`
	// Assert, at the top level, names the ordered set of job names that
	// `steps test` must have run (see Assert). It's a self-verification
	// meta-check, never hashed.
	Assert *Assert `yaml:"assert,omitempty"`
	// Access narrows who may see and operate this pipeline on a daemon people
	// sign in to. See Access.
	Access *Access `yaml:"access,omitempty"`
	// Name is WHICH pipeline this is, stamped by the loader. Not YAML, never
	// hashed: it is identity, not content.
	//
	// It exists because one daemon serves several pipelines (each uploaded by
	// `steps pipeline set`), and process-wide state keyed by a name a pipeline
	// chose — an agent, a job — collides across them. The Config holds it for
	// the same reason a store.Store handle holds its pipeline: the scope has to be
	// impossible to forget.
	//
	// It is the SAME STRING the store's pipelines.name and the web UI's
	// /p/<slug> route use, and that is the whole point of it being supplied
	// rather than derived here. A path was the obvious discriminator and was
	// the wrong one: it is a second identity that disagrees with the one the
	// repo already resolves and publishes, so a pin log line said
	// /abs/infra/deploy.yml where every run record said deploy — and --name,
	// which exists precisely to say which pipeline this is, moved the store
	// and the route and not the pin.
	//
	// A Config built in a test rather than loaded has an empty Name, which
	// shares one scope with every other such Config, exactly as everything
	// did before this field existed.
	Name string `yaml:"-"`
	// Revision is WHICH configuration this is: the bytes it was parsed from,
	// and their hash. Stamped by the loader, never YAML, never hashed into a
	// node — it identifies the content, so folding it into a step's content
	// would make every step of an edited file re-run, which is the merkle
	// cache's job to decide and not this field's.
	//
	// Computed AFTER ((var)) substitution, because substitution happens
	// before the parse: one file under two --vars-files is two
	// configurations, and a revision taken from the file on disk would call
	// them one.
	//
	// A Config built in a test rather than loaded has an empty Revision, and
	// a run started from one records no revision at all — see
	// store.Store.RecordRevision.
	Revision Revision `yaml:"-"`
}

type ContainerLimits struct {
	// CPU is docker's `--cpu-shares`: a RELATIVE weight against other
	// containers, not a core count and not a percentage. 1024 is the default
	// weight, so 512 is "half the share of a default container when both are
	// contending" — and it caps nothing at all on an idle machine. Named cpu:
	// to match Concourse rather than renamed to something more honest, since a
	// pipeline moving between the two should mean the same thing in both.
	CPU int `yaml:"cpu,omitempty"`
	// Memory is docker's `--memory`, in BYTES. A container exceeding it is
	// OOM-killed by the kernel, which surfaces as exit code 137 — worth
	// knowing, because that reads as an ordinary command failure and not as a
	// limit being enforced.
	Memory int64 `yaml:"memory,omitempty"`
}

type ContextSpec struct {
	// From is what this step reads from named earlier steps: their verdict,
	// and optionally the note and response that came with it. Declared on the
	// READER — nothing arrives unasked — and the demand is what makes the
	// sender's note required. See contextfrom.go.
	From map[string]FromLevel
}

type CronSource struct {
	// Expression is a crontab: five fields, or six with seconds in front, or a descriptor like @hourly.
	Expression string `yaml:"expression"`
	// Location is the zone the expression is read in, UTC when unset.
	Location string `yaml:"location,omitempty"`
	// FireImmediately makes the first-ever check mint a version instead of waiting for a slot.
	FireImmediately bool `yaml:"fire_immediately,omitempty"`
}

type Defaults struct {
	// Model is the source.model: an agents: entry inherits when it declares
	// none. Falls back to $STEPS_MODEL when unset here.
	Model string `yaml:"model,omitempty"`
	// Preflight tunes the pre-run health check (see Preflight). It belongs
	// here, unlike attempts:/timeout:, because it changes no step's failure
	// semantics — it only decides how early a failure that WOULD happen is
	// discovered.
	Preflight *Preflight `yaml:"preflight,omitempty"`
	// DelegateBudgetPercent is how much of an agent's REMAINING token
	// allowance one sub-agent call may take, pipeline-wide (see
	// Agent.DelegateBudgetPercent for the per-agent override, and
	// DefaultDelegateBudgetPercent for the value when neither is set).
	DelegateBudgetPercent *int `yaml:"delegate_budget_percent,omitempty"`
	// VersionHistory is how many versions of each resource steps remembers.
	//
	// It belongs to the pipeline because the right number is a property of
	// the resources it watches: a git branch produces a version per push, a
	// chat feed one per message. `--version-history` supplies a default when
	// this is unset, and DefaultVersionHistory when neither is.
	//
	// The floor is not zero: history is what lets a job build a version that
	// scrolled out of a check's window, and what a `passed:` gate proves
	// against — a version pruned from history takes its green record with it,
	// so a number below what a slow downstream job needs holds that job back.
	VersionHistory *int `yaml:"version_history,omitempty"`
	// RunHistory is how many runs of each job steps keeps in full.
	//
	// It belongs next to VersionHistory because it answers the same question
	// about the other half of the database, and it was the half with no answer:
	// resource_versions was the only table with a prune path, so every run
	// recorded its nodes, its events, its usage and its agent transcripts
	// forever. Measured on a pipeline answering Slack mentions overnight, a
	// build cost about 23KB and nothing ever gave a byte back.
	//
	// Per JOB rather than pipeline-wide, for the reason the cap exists at all:
	// a global number makes the least active job the least inspectable, since a
	// busy neighbour evicts its history.
	//
	// Reaping a run takes its events, steps and usage rows with it by foreign
	// key, and the nodes no surviving run refers to with them — so the floor is
	// not free of meaning either. It is a cache horizon: a step whose content
	// has not changed since before the window runs once more instead of being
	// skipped. `--run-history` supplies a default when this is unset, and
	// DefaultRunHistory when neither is.
	RunHistory *int `yaml:"run_history,omitempty"`
	// MemoryEntries is how many entries each memory: scope keeps, the oldest
	// going first. Its own bound rather than run_history:'s, because memory
	// outlives the runs that wrote it — that is what it is for — and
	// DefaultMemoryEntries when unset.
	MemoryEntries *int `yaml:"memory_entries,omitempty"`
}

type DirFS string

type Ensemble struct {
	// Agents are the members, each an ordinary agent step carrying its own
	// prompt and tool selection. They vote on the block's Verdicts, which are
	// declared once here rather than repeated per member.
	Agents []Step `yaml:"agents"`
	// Verdicts is the vocabulary every member votes in, in order of
	// precedence for decide: any — and, on the block, where the combined
	// decision sends the plan. Same list shape as a lone agent's (see
	// VerdictRoute); it sits here rather than on the step because the members
	// vote in it and the block routes on what they conclude.
	Verdicts []VerdictRoute `yaml:"verdicts"`
	// Decide is the rule (majority/unanimous/any) or the name of an agent
	// that judges the members' answers.
	Decide string `yaml:"decide"`
	// MemberErrors is what to do about a member that failed rather than
	// voted: MemberErrorsFail (the default) or MemberErrorsExclude.
	MemberErrors string `yaml:"member_errors,omitempty"`
}

type ExpectedToolCall struct {
	Name string            `yaml:"name"`
	Args map[string]string `yaml:"args,omitempty"`
}

type ExprResourceConfig struct {
	Check     string `yaml:"check,omitempty"`
	CheckFile string `yaml:"check_file,omitempty"`
	In        string `yaml:"in,omitempty"`
	InFile    string `yaml:"in_file,omitempty"`
	Out       string `yaml:"out,omitempty"`
	OutFile   string `yaml:"out_file,omitempty"`
}

type Fetched struct {
	Source  map[string]any
	Version map[string]any
}

type FileRef struct {
	Path     string
	Artifact string
}

type Files interface {
	ReadFile(name string) ([]byte, error)
}

type FixSpec struct {
	Agent string // agents: entry to invoke on failure
	// Messages is what the repair agent is asked, one user turn per entry.
	// Empty uses a default fix prompt. Named for the step field it mirrors:
	// this is the same concept, and calling it something else here would make
	// the DSL say two words for one idea.
	Messages []string
	// MessageFiles loads Messages from files, one message per file, at paths
	// relative to the pipeline file's directory. Mutually exclusive with
	// Messages. Mapping form only (a bare scalar fix: has no room for it).
	MessageFiles []string
	Dir          string     // optional working dir, relative to the workspace
	Tools        []ToolSpec // optional subset/addition to the agent's tool grant
	// Attempts is how many times the fix agent's failing REQUEST is
	// re-issued. Unset takes the agent default; 0 is a load error, like
	// attempts: anywhere else — see dials.go.
	Attempts *int
	Timeout  string // optional wall-clock deadline per fix-agent attempt
}

type FromLevel string

type GitHubCommentsSource struct {
	Repo     string `yaml:"repo"`
	TokenEnv string `yaml:"token_env,omitempty"`
	Endpoint string `yaml:"endpoint,omitempty"`
	// Author is who wrote the comment, compared without regard to case, as
	// GitHub compares logins. "@me" is the token's own user.
	Author string `yaml:"author,omitempty"`
	// Body is an RE2 pattern the comment's text must contain a match for;
	// anchor it with ^ to mean "starts with".
	Body string `yaml:"body,omitempty"`
	// Kinds are which comments to watch: conversation (a pull request's
	// timeline), review (inline, on a line of its diff), issue (an issue's
	// timeline). Default conversation and review.
	Kinds []string `yaml:"kinds,omitempty"`
	// Checkout, true unless set false, lays the tree of the pull request a
	// comment sits on into the artifact. An issue has no tree.
	Checkout *bool `yaml:"checkout,omitempty"`
	// SkipReacted is a reaction that, left by the token's own user, marks a
	// comment done: check does not report it. The mark lives on GitHub, so
	// it outlasts a wiped state database, whose first check would otherwise
	// report a page of commands already answered.
	SkipReacted string `yaml:"skip_reacted,omitempty"`
}

type GitHubConnection struct {
	Repo     string
	TokenEnv string
	Endpoint string
}

type GitHubPRsSource struct {
	Repo     string `yaml:"repo"`
	TokenEnv string `yaml:"token_env,omitempty"`
	Endpoint string `yaml:"endpoint,omitempty"`
	// Author is who opened it. "@me" is the token's own user.
	Author string `yaml:"author,omitempty"`
	// Assignee is someone it is assigned to. "@me" is the token's own user.
	Assignee string `yaml:"assignee,omitempty"`
	// ReviewRequested is someone whose review it directly requests; GitHub
	// clears the request once they submit one. "@me" is the token's own user.
	ReviewRequested string `yaml:"review_requested,omitempty"`
	// Labels must all be on it.
	Labels []string `yaml:"labels,omitempty"`
	// Base is the branch it would merge into.
	Base string `yaml:"base,omitempty"`
	// Draft, when set, keeps only drafts (true) or only ready ones (false).
	Draft *bool `yaml:"draft,omitempty"`
	// Checkout, true unless set false, lays the tree at the version's commit
	// into the artifact beside the metadata files.
	Checkout *bool `yaml:"checkout,omitempty"`
}

type GitHubPostParams struct {
	// BodyFile is the text to post, a path inside the put's inputs.
	BodyFile string `yaml:"body_file"`
	// From names the get input whose version carries the pull request's
	// number. Needed only when more than one input carries one.
	From string `yaml:"from,omitempty"`
	// Number is the pull request, for a put with no input that names one.
	Number string `yaml:"number,omitempty"`
	// InThread answers the comment a github-comments get fetched where it was
	// written: an inline review comment in its thread, any other kind in the
	// conversation, which has no threads — so a pipeline watching both kinds
	// sets it once. From then names that get.
	InThread bool `yaml:"in_thread,omitempty"`
}

type GitHubPostSource struct {
	Repo     string `yaml:"repo"`
	TokenEnv string `yaml:"token_env,omitempty"`
	Endpoint string `yaml:"endpoint,omitempty"`
}

type GitHubReactionParams struct {
	// Add is the reaction to put on the comment.
	Add string `yaml:"add,omitempty"`
	// Remove is a reaction of the token's own user to take off it, after Add
	// is on, so the comment is never without a mark. Anybody else's stays.
	Remove string `yaml:"remove,omitempty"`
	// From names the github-comments get whose comment this marks. Needed
	// only when more than one input carries one.
	From string `yaml:"from,omitempty"`
}

type GitHubReviewParams struct {
	BodyFile string `yaml:"body_file"`
	From     string `yaml:"from,omitempty"`
	Number   string `yaml:"number,omitempty"`
	// Event is comment (the default), approve, request_changes, or pending:
	// a draft only the token's user can see until they submit it, which
	// replaces that user's own earlier draft.
	Event string `yaml:"event,omitempty"`
	// CommentsFile is a JSON array of comments on lines of the diff, posted
	// as part of the same review: [{path, line, body}], with start_line for
	// a range and side LEFT for a removed line. A path inside the put's
	// inputs, like body_file. An empty array posts the body alone.
	CommentsFile string `yaml:"comments_file,omitempty"`
}

type Hooks struct {
	OnSuccess *Step `yaml:"on_success,omitempty"`
	OnFailure *Step `yaml:"on_failure,omitempty"`
	OnError   *Step `yaml:"on_error,omitempty"`
	OnAbort   *Step `yaml:"on_abort,omitempty"`
	Ensure    *Step `yaml:"ensure,omitempty"`
}

type InParallel struct {
	// Steps are the branches, each an ordinary step. Empty is a load error:
	// an in_parallel: with nothing in it is a typo, and running zero steps
	// "successfully" is the least useful reading of it.
	Steps []Step `yaml:"steps"`
	// Limit caps how many branches are in flight at once. 0 (the default) is
	// unbounded — the plan author asked for parallelism, so making them also
	// ask for a width would be a second decision for the common case.
	Limit int `yaml:"limit,omitempty"`
	// FailFast, when true, cancels the remaining branches as soon as one
	// fails. A pointer so unset is distinguishable from an explicit false.
	//
	// Either way the block FAILS when a branch does. fail_fast decides
	// whether the siblings are given a chance to finish, never whether the
	// failure counts — a swallowed failure was a real defect in the first
	// implementation of this step, and it is what assert.outcome exists to
	// catch (see docs/control-flow.md).
	FailFast *bool `yaml:"fail_fast,omitempty"`
}

type InputSpec struct {
	Names []string
	All   bool
}

type Job struct {
	Name  string `yaml:"name"`
	Plan  []Step `yaml:"plan"`
	Hooks Hooks  `yaml:",inline"`
	// Tags places every step in the plan and every job-level hook on one
	// worker, the way a step's own tags: places that step (see Step.Tags). A
	// do: or in_parallel: block's tags:, a get/put's resource tags:, or the
	// step's own override it — never union with it. Resolved onto each step at
	// load (resolveTags). Never hashed: placement, not content, see Step.Tags.
	Tags []string `yaml:"tags,omitempty"`
	// Assert, on a job, names the ordered set of task/agent/hook names the
	// job's run must have produced (see Assert). A match clears the plan's
	// failure; a mismatch fails the job. Never hashed.
	Assert *Assert `yaml:"assert,omitempty"`
	// Budget caps what every agent step in this job may spend TOGETHER (see
	// Budget). A cumulative ceiling, so the step that trips it is rarely the
	// one that cost the most. Never hashed.
	Budget *Budget `yaml:"budget,omitempty"`
	// Timeout is a wall-clock deadline for the whole job (e.g. "45m"), the
	// same ceiling Budget is in the other unit. Empty means none.
	//
	// Checked BETWEEN steps, never interrupting one. A step keeps its own
	// timeout:, and this decides whether the NEXT one starts — so the two
	// compose instead of racing, and a job never reports a deadline breach for
	// a step that was actually still making progress. The cost is that the job
	// can overrun by at most one step's duration, which is the honest price of
	// not cutting work off mid-flight.
	//
	// It FAILS the job rather than degrading, unlike an across: block's
	// budget:. Same reasoning as the token ceiling here: a job-level limit is a
	// backstop against a run that has gone wrong, and the thing you want then
	// is to stop and say so. Degrading belongs on the block whose width nobody
	// knew when they wrote the pipeline.
	//
	// Never hashed — an operational limit, like every other.
	Timeout string `yaml:"timeout,omitempty"`
	// Serial states that two builds of this job must never run at once —
	// max_in_flight: 1 in Concourse's older spelling. It matters because an
	// unset job is UNLIMITED (see EffectiveMaxInFlight): serial:/serial_groups:
	// force the effective value to 1, and setting max_in_flight: beside either
	// is a load error (checkJobMaxInFlight).
	Serial bool `yaml:"serial,omitempty"`
	// SerialGroups names locks this job holds while it runs. Two jobs sharing
	// a group never run at the same time, which is what stops two different
	// deploy jobs mutating one target concurrently.
	SerialGroups []string `yaml:"serial_groups,omitempty"`
	// MaxConsecutiveFailures holds this job's automatic triggers under `steps web` once it has
	// failed this many triggered RUNS in a row, until someone releases it or a run passes.
	//
	// It counts runs, not the attempts: retries inside one — conflating them
	// would trip the breaker on ordinary flakiness a retry would have
	// absorbed, which is the opposite of the intent. 0 (the default) means no
	// breaker.
	MaxConsecutiveFailures int `yaml:"max_consecutive_failures,omitempty"`
	// MaxInFlight caps how many builds of this job run at once under
	// `steps web`. Mirrors Concourse's job-level max_in_flight
	// (concourse-ci.org/docs/jobs/), including that serial:/serial_groups:
	// take precedence by forcing the effective value to 1.
	//
	// 0/unset is unlimited, as in Concourse — bounded in practice by
	// `steps web --max-concurrent`, which is the worker pool this runner
	// has instead of Concourse's workers.
	//
	// The same word appears on an across: step meaning cell concurrency.
	// That is Concourse's own overload, not one invented here, and the two
	// live on different things: a job field and a step field.
	MaxInFlight int `yaml:"max_in_flight,omitempty"`
	// Concourse's interruptible: and its default of false: a `steps web` shutdown waits (bounded) for this job's running build, because a deploy half-applied by a daemon restart is the case it exists for, while `steps run` is a person at a terminal and ctrl-C there means now (internal/scheduler's LocalRunner.runContext).
	Interruptible bool `yaml:"interruptible,omitempty"`
	// Line is the job's source line in the pipeline file, filled in after
	// decoding (see stampLines). Never written in YAML and never hashed.
	Line int `yaml:"-"`
}

type JobInput struct {
	Resource string
	Trigger  bool
	Passed   []string
}

type MCPExport struct {
	// Name is the export's address under the pipeline: /mcp/x/<pipeline>/<name>.
	Name string `yaml:"name"`
	// Access is who may connect, a rule over the signed-in person, required:
	// an export with no rule would be one anybody signed in could use.
	Access string `yaml:"access"`
	// Tools are what a connected agent may call.
	Tools []ToolSpec `yaml:"tools"`
	// Rules names rules: entries that check every call of every tool in the export, before the rules of the tool itself.
	Rules []string `yaml:"rules,omitempty"`
	// Rate bounds calls per person, as "<n>/<s|m|h>"; empty is unbounded.
	Rate string `yaml:"rate,omitempty"`
	// Image runs the export's custom run: commands in a container from this image, a fresh one per command; empty runs them on the daemon's machine.
	Image string `yaml:"image,omitempty"`
	// User, Network, Privileged and Limits are the container's, as on a task, and need Image.
	User       string           `yaml:"user,omitempty"`
	Network    string           `yaml:"network,omitempty"`
	Privileged bool             `yaml:"privileged,omitempty"`
	Limits     *ContainerLimits `yaml:"container_limits,omitempty"`
}

type MCPReadiness int

type MCPResourceConfig struct {
	Server string       `yaml:"server"`
	Check  *MCPToolCall `yaml:"check,omitempty"`
	In     *MCPToolCall `yaml:"in,omitempty"`
	Out    *MCPToolCall `yaml:"out,omitempty"`
}

type MCPServer struct {
	Name     string   `yaml:"name"`
	Endpoint string   `yaml:"endpoint,omitempty"`
	Command  string   `yaml:"command,omitempty"`
	Args     []string `yaml:"args,omitempty"`
	// Cwd is the working directory a stdio server's subprocess is spawned
	// in. An ABSOLUTE path is used verbatim — a fixed location on the host,
	// resolved identically for every step. A RELATIVE path is resolved
	// against the agent step's own working directory (see
	// WithResolvedMCPCwd), which is what lets a server be pointed at an
	// input artifact — `cwd: repo` for a language server that must index the
	// same materialized tree the agent's file tools read. Empty inherits the
	// steps process's own cwd.
	//
	// Relative only makes sense where a step workspace exists, so it is
	// rejected for a server backing a resource type's mcp: config — a
	// check/in/out runs with no agent step to resolve against.
	Cwd  string        `yaml:"cwd,omitempty"`
	Auth MCPServerAuth `yaml:"auth,omitempty"`
}

type MCPServerAuth struct {
	Type            string   `yaml:"type"`
	APIKeyEnv       string   `yaml:"api_key_env,omitempty"`
	ClientID        string   `yaml:"client_id,omitempty"`
	ClientSecretEnv string   `yaml:"client_secret_env,omitempty"`
	CallbackPort    int      `yaml:"callback_port,omitempty"`
	Scopes          []string `yaml:"scopes,omitempty"`
}

type MCPStatus struct {
	Readiness MCPReadiness
	// Detail is the whole cell, written for somebody who has to act on it — `$GITHUB_PAT is not set`, not `false`.
	Detail string
}

type MCPToolCall struct {
	Tool string         `yaml:"tool"`
	Args map[string]any `yaml:"args,omitempty"`
}

type ParamSpec struct {
	// MaxLength and MinLength count characters, not bytes. String parameters only.
	MaxLength *int `yaml:"max_length,omitempty"`
	MinLength *int `yaml:"min_length,omitempty"`
	// Pattern is a Go (RE2) regular expression the value must match somewhere; anchor it with ^ and $ to match all of it. String parameters only.
	Pattern string `yaml:"pattern,omitempty"`
	// Enum lists every value the parameter may take.
	Enum []string `yaml:"enum,omitempty"`
	// Min and Max bound a number. Number parameters only.
	Min *float64 `yaml:"min,omitempty"`
	Max *float64 `yaml:"max,omitempty"`
	// Default fills the argument when it is missing, which also makes it optional.
	Default *string `yaml:"default,omitempty"`
}

type Preflight struct {
	// Disabled turns the check off entirely. Spelled as the negative so the
	// zero value — an absent preflight: block — is ON, which is the useful
	// default: the check exists because nobody thinks to enable it until
	// after it would have saved them.
	Disabled bool `yaml:"disabled,omitempty"`
	// Timeout bounds one check. A model that has not answered in this long is
	// reported as unavailable rather than waited on.
	Timeout string `yaml:"timeout,omitempty"`
	// Cache is how long a verified target is trusted for. It is a real
	// requirement, not an afterthought: without it every `steps web` poll
	// pays for a probe request against every model in the pipeline.
	Cache string `yaml:"cache,omitempty"`
}

type Problem struct {
	// Target names what is wrong, e.g. `agent "coder"` or `mcp "gopls"`.
	Target string
	// Detail says what about it is wrong, and where possible how to fix it.
	Detail string
	// Transient marks a problem that WAITING could fix — a server that did
	// not answer, a token that needs refreshing — as opposed to one no amount
	// of time will change, like a tool the server does not expose or required
	// arguments the pipeline never sends.
	//
	// It exists because the same problem deserves opposite reactions from the
	// two callers. `steps run` refuses either way: a person is waiting, and
	// starting a run that cannot finish wastes their time and money. `steps
	// web` is a daemon, and quitting because a VPN was not up yet — or
	// because a token needed the refresh the next poll would have done — is
	// how a daemon that should have recovered on its own ends up dead all
	// weekend.
	Transient bool
}

type Race struct {
	// Steps are the racers. Fewer than two is a load error: a race with one
	// runner is a step with extra words, and a race with none is a typo.
	Steps []Step `yaml:"steps"`
}

type ResolvedInvocation struct {
	AgentName   string
	Description string
	BaseURL     string
	ModelName   string
	APIKeyEnv   string
	RequiresKey bool
	// CLI, when non-empty, names the coding-agent CLI that runs this
	// invocation as a subprocess instead of an HTTP conversation (see
	// cliagent.go). BaseURL is empty in that case, and ModelName is the model
	// the CLI is asked for (e.g. "sonnet"). Hashed as `cli`, so moving an
	// agent between a CLI and a hosted provider invalidates its cache.
	CLI string
	// CLISettings is the CLI configuration scope the subprocess loads (see
	// Agent.Settings): "" loads none, CLISettingsProject loads the repo's
	// checked-in .claude/ scope. Hashed as `cli_settings` — repo config
	// shaping the agent is part of what the step asked for.
	CLISettings string
	Persona     string
	// ContextPaths mirrors Step.ContextPaths once resolved — populated from
	// the step, not the agent definition, since concrete input paths are
	// only known at the step level.
	ContextPaths []string
	// MaxContextBytes is the resolved per-file cap for ContextPaths (see
	// Agent.MaxContextBytes). 0 means no cap — an author asked for it, since
	// resolution substitutes the default for an unset field.
	MaxContextBytes int
	// Generation dials, mirroring Agent's own fields once resolved. Kept flat
	// here (rather than a nested type) so this package doesn't need to depend
	// on anything LLM-client-specific — internal/agent assembles its own
	// request-config shape from these.
	Temperature     *float64
	TopP            *float64
	MaxTokens       int
	ReasoningEffort string // "", "low", "medium", or "high"
	// MaxTurns is the resolved tool-calling cap; 0 means no cap, which an
	// explicit max_turns: 0 produces and so does an unset cap on a cli source
	// (see defaultTurnsFor).
	MaxTurns int
	// TurnsDefaulted records that neither the step nor the agent named a turn
	// cap, so MaxTurns is this package's answer rather than the author's.
	//
	// Kept because the default is the one dial whose value depends on the
	// SOURCE KIND, and a failover crosses that boundary: WithSource has to
	// re-derive it, and can only tell "the author chose 0" from "nobody chose"
	// if resolution says which happened.
	TurnsDefaulted bool
	// MaxQuestions is the resolved ask_user budget; 0 means no cap, which
	// only an explicit max_questions: 0 produces.
	MaxQuestions int
	Attempts     int
	// Timeout is the resolved wall-clock deadline per attempt. Empty means
	// "take internal/agent's default"; "0" means no deadline. Unlike every
	// other step kind, an agent step's empty is NOT "no deadline" — see
	// Step.Timeout.
	Timeout string
	// CompactAfterTokens is the already-resolved conversation-size budget (see
	// Agent.CompactAfterTokens); 0 means compaction is disabled for this
	// invocation.
	CompactAfterTokens int
	// ContextWindow is the model's context window when this package
	// recognizes the model (see contextWindows), 0 when it does not. It is
	// what CompactAfterTokens was derived from, carried so a run can SAY
	// "compacting at 102400 against a 1000000 window" — the mismatch that was
	// previously invisible until compaction stalled.
	ContextWindow int
	// BudgetTokens is the ceiling on provider-reported tokens this one
	// invocation may spend (see Agent.Budget); 0 means no ceiling. Never
	// hashed — it is an operational limit, like Timeout.
	BudgetTokens int
	// BudgetUSD is the dollar ceiling a CLI agent hands its subprocess (see
	// Budget.USD); 0 means no ceiling. Never hashed, for the same reason
	// BudgetTokens is not.
	BudgetUSD float64
	ToolSpecs []ToolSpec
	// StringOnlyToolChoice, when true, forces a required tool call (see
	// forceRequiredTool in internal/agent) via tool_choice: "required"
	// instead of a named function object — for providers whose
	// OpenAI-compat server rejects the object form. See resolveAgentTarget.
	StringOnlyToolChoice bool
	// Env names the host environment variables this step's commands may see
	// beyond the baseline. See Agent.Env/Step.Env.
	Env []string
	// User is the container user this step's commands run as. See
	// Agent.User/Step.User.
	User string
	// Network is the container network this step's commands join. See
	// Agent.Network/Step.Network.
	Network string
	// Privileged runs this step's container with --privileged. See
	// Agent.Privileged/Step.Privileged.
	Privileged bool
	// Limits caps this step's container CPU/memory. See
	// Agent.Limits/Step.Limits.
	Limits *ContainerLimits
	// Sandbox fences this agent's run_shell/custom tools on the host. From the agents: entry only; see Agent.Sandbox.
	Sandbox bool
	// Image, when non-empty, runs this step's run_shell/custom-tool commands
	// in a container from this image instead of on the host. See
	// Agent.Image/Step.Image.
	Image string
	// Caches are the directories this step's commands keep between runs. See TaskCache.
	Caches []TaskCache
}

type ResolvedTask struct {
	Name    string
	Run     string
	Fix     *FixSpec
	Inputs  []string
	Outputs []string
	// InputMapping/OutputMapping rename declared inputs/outputs onto plan-
	// artifact names under workspace: isolation (see Step.InputMapping). Always
	// from the step (tasks: entries carry no mapping); empty leaves names
	// unmapped.
	InputMapping  map[string]string
	OutputMapping map[string]string
	// Image, when non-empty, runs this task's run: (and any fix-loop
	// re-runs) in a container from this image instead of on the host. See
	// Task.Image/Step.Image.
	Image string
	// Env names the host environment variables this task's commands may see
	// beyond the baseline. See Task.Env/Step.Env.
	Env []string
	// User is the container user this task's commands run as. See
	// Task.User/Step.User.
	User string
	// Network is the container network this task's commands join. See
	// Task.Network/Step.Network.
	Network string
	// Privileged runs this task's container with --privileged. See
	// Task.Privileged/Step.Privileged.
	Privileged bool
	// Limits caps this task's container CPU/memory. See
	// Task.Limits/Step.Limits.
	Limits *ContainerLimits
	// Sandbox fences this task's host commands. Always the tasks: entry's: a step has no spelling for it, and an inline run: has no entry. See Task.Sandbox.
	Sandbox bool
	// Timeout is a wall-clock deadline per attempt (e.g., "2m", "30s"). Empty
	// means no timeout. Step.Timeout overrides Task.Timeout when set.
	Timeout string
	// Assert, when set, checks the task's captured stdout/exit code (see
	// Assert). It always comes from the step (top-level tasks: entries carry
	// no assert), so a matching assert makes a non-zero-exit task a success.
	Assert *Assert
	// Caches are the directories this task keeps between runs. See TaskCache.
	Caches []TaskCache
}

type Resource struct {
	Name   string         `yaml:"name"`
	Type   string         `yaml:"type"`
	Source map[string]any `yaml:"source"`
	// Env names host environment variables THIS resource's check/in/out may
	// see, ON TOP OF whatever its resource type's own env: already allows —
	// the two lists union at run time, rather than one replacing the other.
	//
	// It exists for the case a type's own env: cannot cover: a resource type
	// is shared by every resource of that type in the pipeline, so its env:
	// names ONE fixed credential variable — but two resources of the same
	// type may need two DIFFERENT-named tokens (two Slack bots in one
	// pipeline), or an operator's secret may already be named something
	// other than the type's documented default. Widening the type's own
	// env: would grant every resource of that type the new name; this grants
	// only the one resource that asked for it, so the type's declared
	// allow-list stays the complete picture of what a shared, possibly
	// third-party type can read.
	//
	// Names only — see validateEnvValues. Meaningful only for an expr:- or
	// shell-backed type; an mcp-backed type authenticates via its
	// mcp_servers: entry and never consults env: at all.
	Env []string `yaml:"env,omitempty"`
	// Tags names the worker this resource's check, in and out run on, for a
	// source only reachable from that machine's network. A get or put step's
	// own tags: overrides it for that step, and it overrides a tag the step
	// would inherit from a job or block; empty runs them here.
	//
	// A deliberate divergence from Concourse, whose resource tags place only
	// the check and must be repeated on every get and put: a get's own
	// version check and its in: have to land on the same machine, and the
	// repetition is the papercut Concourse's docs warn about. Same shape as a
	// step's tags: — one entry, not hashed (see Step.Tags).
	Tags []string `yaml:"tags,omitempty"`
}

type ResourceBackend string

type ResourceType struct {
	Name string `yaml:"name"`
	// Image, when set, runs check/in/out in a fresh `docker run --rm`
	// container from this image instead of on the host. Empty (the default)
	// keeps host execution, byte-identical to before this field existed.
	Image string `yaml:"image,omitempty"`
	// Env names host environment variables check/in/out are allowed to see,
	// on top of the always-allowed baseline (see shell.HostEnv). Names only —
	// see validateEnvValues. This is how a resource type reaches a registry
	// credential or deploy token without it being written into the pipeline.
	Env []string `yaml:"env,omitempty"`
	// User is the container user check/in/out execute as (docker's --user).
	// Empty takes the platform default — see shell's defaultContainerUser.
	User string `yaml:"user,omitempty"`
	// Network is the container network check/in/out join (docker's
	// --network); "none" cuts off egress entirely. Requires Image (except
	// "none" beside Sandbox) — and note
	// that most resource types exist to reach the network, so this is rarely
	// what you want on one.
	Network string `yaml:"network,omitempty"`
	// Privileged runs this command's container with `docker run --privileged`.
	// Mirrors Concourse's privileged: (concourse-ci.org/docs/steps/task/).
	// Container-only, like Network — a host command has nothing to elevate,
	// so it is a load error without image:.
	Privileged bool `yaml:"privileged,omitempty"`
	// Limits caps the container's CPU and memory. Mirrors Concourse's
	// container_limits:; container-only for the same reason Privileged is.
	Limits *ContainerLimits `yaml:"container_limits,omitempty"`
	// Sandbox fences this entity's host commands with the OS sandbox: writes only under the step's workspace and a private TMPDIR, credential directories unreadable, and network: none becomes legal on the host. See internal/config/sandbox.go for the rules and docs/infra.md for the policy.
	Sandbox bool               `yaml:"sandbox,omitempty"`
	Config  ResourceTypeConfig `yaml:"config"`
}

type ResourceTypeConfig struct {
	Check string              `yaml:"check,omitempty"`
	In    string              `yaml:"in,omitempty"`
	Out   string              `yaml:"out,omitempty"`
	MCP   *MCPResourceConfig  `yaml:"mcp,omitempty"`
	Expr  *ExprResourceConfig `yaml:"expr,omitempty"`
	// Webhook marks the built-in webhook type, which no YAML can declare: its versions arrive as deliveries rather than from a check.
	Webhook bool `yaml:"-"`
	// Cron marks the built-in cron type, which no YAML can declare either: its check reads a clock against an expression, and runs nothing.
	Cron bool `yaml:"-"`
	// GitHub names which built-in github-* type this is (see github.go), which no YAML can declare: steps calls the API itself. Keyed, unlike Cron and Webhook, because several share a source: shape and do different things with it.
	GitHub string `yaml:"-"`
}

type Revision struct {
	SHA    string
	Source string
	// Includes is path→content, the path exactly as the pipeline names it: the string is hashed, so a resolved path made ci/app.yml and /repo/ci/app.yml two configurations of the same bytes.
	Includes map[string]string
}

type Rule struct {
	// Name is how an export or a tool refers to the rule, and what a refusal and the activity log call it.
	Name string `yaml:"name"`
	// When is an expression over the call — tool, args (after pins and defaults) and who — that must hold for the call to go out. fail("why") refuses with a reason; a plain false says "refused by rule <name>".
	When string `yaml:"when,omitempty"`
	// Accept is the same over what came back, with result (text, content, error) in scope as well, and must hold for the caller to see it.
	Accept string `yaml:"accept,omitempty"`
	// JudgedBy names an agents: entry that is shown the call and answers allow or deny. A judge that fails or answers neither refuses the call.
	JudgedBy string `yaml:"judged_by,omitempty"`
}

type Step struct {
	Get     string `kind:"get"               yaml:"get,omitempty"`
	Trigger bool   `yaml:"trigger,omitempty"`
	// Version selects which version(s) a get step fetches: unset/"latest"
	// (default) picks the single latest version; "every" runs the rest of
	// the plan once per version returned by check; a map pins to a specific
	// version. Mirrors Concourse's get.version field, including that a
	// failed version's build does not stop "every" from attempting the
	// remaining versions — see docs/conformance.md and
	// internal/pipeline/conformance_test.go's
	// TestConformanceGetVersionEveryContinuesPastFailure.
	Version any `yaml:"version,omitempty"`
	// Task labels a task step. If Run is also set, the step is inline and
	// Run/Fix below are used as-is. If Run is empty, Task instead names a
	// tasks: entry (see Task) to resolve run/fix from; this step's own Fix,
	// if set, overrides the referenced task's Fix for this step only.
	Task string `kind:"task"          yaml:"task,omitempty"`
	Run  string `yaml:"run,omitempty"`
	// RunFile loads Run's text from a file at a path relative to the pipeline
	// file's directory, instead of writing it inline (see LoadConfig's
	// resolveFileIncludes). Mutually exclusive with Run. Task steps only.
	RunFile string `yaml:"run_file,omitempty"`
	// Fix, on a task step, names an agent to invoke when a run misses the
	// step's own success criteria — its Assert when it declares one, a
	// nonzero exit otherwise. The agent is seeded with that verdict and the
	// captured output and given the task itself as a rerun tool; the command
	// is then re-run and judged by the same rule. A run that already passes
	// never constructs the agent. See FixSpec.
	Fix *FixSpec `yaml:"fix,omitempty"`
	// Put names a resource to run its out command against.
	Put string `kind:"put" yaml:"put,omitempty"`
	// Params are passed through to the resource command this step runs, as
	// {{ .params.x }}: a put's reach out:, a get's reach in:. Mirrors
	// Concourse, where params on a get are how a resource is told HOW to
	// fetch (git's depth:/submodules:, s3's unpack:) — see
	// concourse-ci.org/docs/steps/get/ and docs/conformance.md.
	//
	// A get's params fold into its node hash (see merkle.GetNodeContent):
	// they change what lands in the artifact, so two gets of one version
	// differing in params are two different fetches and must not share a
	// cache entry.
	Params map[string]any `yaml:"params,omitempty"`
	// Agent names an agents: entry this step invokes. Prompt is the task
	// given to the model (not templated — freeform text is likely to contain
	// literal {{ }} that isn't meant as a template). Dir is the step's
	// working directory relative to the job's workspace, since there's no
	// run: string to embed a cd in. Tools selects a subset of the agent's
	// granted tools by name and may add inline custom tools for this task
	// (empty means all of the agent's tools). Attempts overrides the agent's
	// default retry count (attempts: 3 = up to 3 total tries, including the
	// first); 0/unset inherits the agent's default (which itself defaults
	// to 1).
	Agent string `kind:"agent" yaml:"agent,omitempty"`
	// Messages is what this step says to the agent: one user turn per entry.
	//
	// A list rather than a single string because a conversation is a list, and
	// exposing only its first element was an arbitrary restriction rather than
	// a design. The agent runs each message to completion — tool calls and all
	// — before the next one is sent, so a later message is written against an
	// answer that already exists. That is the whole difference from putting
	// both asks in one message, where the model composes its answer to the
	// second while it is still deciding the first.
	//
	// The agent's standing instructions are not here: they are its own
	// system:. These are the per-invocation asks.
	Messages []string `yaml:"messages,omitempty"`
	// MessageFiles supplies Messages from files instead of inline text, one
	// message per file, in either of FileRef's two forms: a scalar path
	// relative to the pipeline file's directory, resolved at load time exactly
	// like RunFile/SystemFile; or a {artifact, path} mapping naming a file
	// inside an artifact this step declares in its inputs:, read at run time
	// once that artifact is fetched. The run-time form exists only here (not
	// for a task's run:, not for an agent's own definition/persona) — see
	// docs/agents.md. It costs no merkle caching: an agent step's chain is
	// already unconditionally unskippable (see internal/merkle's
	// planNonGetNode), so there is nothing to lose by resolving it after plan
	// time.
	//
	// Mutually exclusive with Messages, in BOTH forms. Two ordered lists
	// cannot be interleaved, so a step that declared both would be asking for
	// an order neither field states; refusing is the only answer that does not
	// invent one.
	MessageFiles []*FileRef `yaml:"message_files,omitempty"`
	Dir          string     `yaml:"dir,omitempty"`
	Tools        []ToolSpec `yaml:"tools,omitempty"`
	// Attempts is how many times this step's work is tried before it fails.
	// Unset takes 1 for task/get/put steps and defaultAgentAttempts for agent
	// steps (where a retry is a transport concern, not a re-run). An explicit
	// 0 is a load error — see dials.go for why attempts: sits outside the
	// zero-means-no-limit convention the other dials follow.
	Attempts *int `yaml:"attempts,omitempty"`
	// MaxTurns overrides the agent entry's max_turns for this one step:
	// tool-calling turns per attempt. Unset inherits the agent's value (which
	// itself defaults to defaultMaxAgentTurns); an explicit 0 removes the cap
	// for this step alone. Agent steps only — one long-horizon step can buy
	// more turns without every step of the same agent paying for them.
	MaxTurns *int `yaml:"max_turns,omitempty"`
	// MaxQuestions caps how many ask_user calls this step may make. Unset
	// inherits the agent entry's value (itself defaulting to
	// defaultMaxQuestions); an explicit 0 removes the cap for this step alone,
	// per the zero-means-no-limit convention. Agent steps only.
	//
	// It lives on the STEP, unlike ask_user's other dials, for the reason
	// max_turns: does: how much one step may spend is a property of that step.
	// And it is denominated in questions rather than turns because the thing
	// being spent is a person's attention — a model that asks twenty questions
	// burns somebody's afternoon, not a token budget, and max_turns: cannot
	// say anything about that.
	MaxQuestions *int `yaml:"max_questions,omitempty"`
	// Timeout is a wall-clock deadline per attempt (e.g., "2m", "30s"). Empty
	// means no timeout on a task/get/put step, and the agent entry's timeout:
	// — or the 30-minute package default — on an agent step, which is the one
	// step kind that gets a deadline it never asked for. "0" there is how a
	// long-horizon agent step says it wants none; on any other step kind it
	// is a load error, since omitting the field already says that.
	//
	// Valid on all step kinds (a get step's timeout bounds both its check and
	// in commands); for task/put steps it overrides the referenced
	// task/agent's Timeout.
	Timeout string `yaml:"timeout,omitempty"`
	// Try wraps an inner step so a task-level failure of that step doesn't
	// stop the plan. The wrapper is transparent: the inner step runs exactly
	// as it would unwrapped (its when: guard, hooks and outcome are all real),
	// and everything that observes the outcome — the wrapper's own hooks, its
	// to: route, the recorded node — sees the truth. Only the plan walker is
	// lied to, and only for an outcome.Failed inner step: an infrastructure
	// error or an abort still stops the run (see internal/pipeline's
	// tolerateTryFailure). Composes with attempts:/timeout: on the inner step,
	// and with try: itself (a doubled try: is legal, if pointless).
	//
	// The wrapper is the plan-positioned step, so to:/max_visits: belong on it
	// and are rejected on the step it wraps; verdicts: stays on the agent step
	// being wrapped, since that is what internal/agent reads. Also
	// valid as a hook body, where it tolerates the hook's failure the same way.
	Try *Step `kind:"try" yaml:"try,omitempty"`
	// Do runs several steps one after another, as a single plan step.
	//
	// Sequential execution is what a plan does anyway, so the ordering is not
	// the point — the containment is. A hook on the block observes the whole
	// group's outcome, which is the only way to say "roll back if any of these
	// three failed" without repeating the hook on each step or hoisting it to
	// the job. Mirrors Concourse's do: (concourse-ci.org/docs/steps/do/).
	//
	// The block is a container like in_parallel:/race:: it takes no operation
	// fields of its own (no inputs:, run:, image: — those belong on the steps
	// inside), and it carries hooks, when:, try: and to: as any positioned
	// step does.
	Do []Step `kind:"do" yaml:"do,omitempty"`
	// InParallel runs several steps at the same time instead of one after
	// another. See InParallel.
	InParallel *InParallel `kind:"in_parallel" yaml:"in_parallel,omitempty"`
	// Race runs several steps at once and keeps whichever finishes
	// successfully first. See Race.
	Race *Race `kind:"race" yaml:"race,omitempty"`
	// Ensemble asks several agents the same question and combines their
	// answers into one verdict to route on. See Ensemble.
	Ensemble *Ensemble `kind:"ensemble" yaml:"ensemble,omitempty"`
	// Approval pauses the plan until a person approves or rejects. See
	// Approval.
	Approval *Approval `kind:"approval" yaml:"approval,omitempty"`
	// LoadVar captures a value produced DURING the run — the contents of
	// VarFile, trimmed — into a pipeline var that later steps reference as
	// ((name)). See validateVars.
	LoadVar string `kind:"load_var" yaml:"load_var,omitempty"`
	// VarFile is the workspace-relative file a load_var: step reads.
	VarFile string `yaml:"file,omitempty"`
	// Passed, on a get step, names upstream jobs this version must ALREADY
	// have succeeded in before this job will run against it. See
	// validatePassed.
	Passed []string `yaml:"passed,omitempty"`
	// Across runs this step once per combination of the listed values,
	// substituting {{ .vars.<name> }} into its fields. Expanded at load, so
	// each cell is an ordinary plan step. See AcrossVar.
	Across []AcrossVar `yaml:"across,omitempty"`
	// Budget caps what every cell of an across: block may spend TOGETHER, and
	// unlike the job and agent ceilings it DEGRADES rather than failing: when
	// the matrix has spent its allowance, no further cell is started, the ones
	// already finished keep their work, and the plan carries on.
	//
	// That difference is the point. A job ceiling is a backstop against a
	// runaway, so failing is right. A runtime fan-out is the one step whose
	// cost nobody could know when they wrote the pipeline — its width is
	// decided mid-run, usually by a model — and there, "review eight of the
	// twelve dimensions and publish" beats "spend the same money and publish
	// nothing".
	//
	// Cells that never started are simply not run: they record nothing, so a
	// rerun with a larger ceiling picks up exactly where this one stopped
	// (finished cells are cached, unstarted ones are not).
	//
	// across: steps only, tokens only. Never hashed, like every other
	// operational limit — adding one must not invalidate a cached cell.
	Budget *Budget `yaml:"budget,omitempty"`
	// MaxInFlight bounds how many across: cells run at once. Unset or 1 keeps
	// the serial declaration-order walk this modifier has always had; anything
	// higher runs that many cells concurrently, and a value at or above the
	// cell count is effectively unbounded. Opt-in, unlike in_parallel:'s
	// limit: where an absent value means unbounded — each default matches the
	// contract its own block already had.
	//
	// Cells are one step's clones — same output names, same paths — and each
	// materializes its own directory, so concurrent cells never collide.
	//
	// NOT hashed, unlike in_parallel:'s limit:/fail_fast:. Those change which
	// steps run at all; this only changes how many run at once, and the cell
	// set is identical at any width — so raising it must not re-run a matrix
	// whose cells are all cached.
	MaxInFlight int `yaml:"max_in_flight,omitempty"`
	// Parallelism shards this task step: N copies of one command, run
	// concurrently, each knowing its slot. Sugar for across: over an implicit
	// 1-based index axis — desugared at load (desugarParallelism), so what
	// runs, hashes and caches is an ordinary matrix. What the sugar adds over
	// writing the axis: MaxInFlight defaults to N rather than serial (an
	// authored value wins), and cells render {{ .vars.count }}, the width no
	// hand-written axis can carry. Task steps only; invalid beside across:,
	// which declares its own axes, and on hooks, which never expand one. A
	// pointer like Attempts, so an explicit 0 is a load error rather than a
	// silent single copy. Still set after desugar — the marker (Sharded) the
	// count injection and the parallelism-worded diagnostics key on.
	Parallelism *int `yaml:"parallelism,omitempty"`
	// Inputs/Outputs declare which named artifacts a task/agent/put step
	// draws from and (task/agent only) produces. Each name is either a
	// resource fetched by an earlier get step or an output produced by an
	// earlier task/agent step. Both are optional and default to empty: an
	// absent inputs: means "sees nothing declared" (there is no requirement to
	// declare them). When present, an inputs: naming an artifact nothing
	// produces is caught by workspace.ValidateArtifactFlow. Declarations only
	// change what a step physically sees under a top-level workspace: block
	// (see WorkspaceConfig); without one they are a validated contract, not
	// isolation, and are never folded into a node's hash (see internal/merkle).
	// Inputs is a *InputSpec so an absent key (nil) is distinguishable from an
	// explicit empty list — which matters for ResolveTask's override rule (a
	// step's inputs: override its tasks: entry only when declared) — and so put
	// steps can accept the scalar `inputs: all` (every available artifact) in
	// addition to a sequence of names. Invalid on get steps; Outputs is
	// additionally invalid on put steps.
	Inputs  *InputSpec `yaml:"inputs,omitempty"`
	Outputs []string   `yaml:"outputs,omitempty"`
	// Image, on a task or agent step, overrides the referenced task's/
	// agent's Image for this step only (inherit-only: a non-empty step Image
	// always wins, there is no way to force host execution from a step when
	// the task/agent sets one). Invalid on get/put steps — a put's execution
	// image comes from its resource type, and a get has no task/agent to
	// override.
	Image string `yaml:"image,omitempty"`
	// Env, on a task or agent step, overrides the referenced task's/agent's
	// Env for this step only (declared-wins, like Inputs: an explicit empty
	// list means "nothing beyond the baseline", which is distinguishable from
	// absent). Invalid on get/put steps, matching Image: a put's environment
	// comes from its resource type, and a get has no task/agent to override.
	Env []string `yaml:"env,omitempty"`
	// User, on a task or agent step, overrides the referenced task's/agent's
	// User for this step only (non-empty-wins, like Image). Invalid on
	// get/put steps, for the same reason Image is.
	User string `yaml:"user,omitempty"`
	// Network, on a task or agent step, overrides the referenced task's/
	// agent's Network for this step only (non-empty-wins, like Image).
	// Invalid on get/put steps, for the same reason Image is.
	Network string `yaml:"network,omitempty"`
	// Tags names the worker a step's commands run on: a capability the step
	// needs, mapped to a machine by the invocation (--worker), never by the
	// pipeline. Empty runs on this machine, which is what nearly every step
	// does.
	//
	// One entry. Concourse intersects a step's tags against a pool of workers
	// advertising theirs; there is no pool here, so a second tag would name a
	// second machine and the step would have no home.
	//
	// NOT hashed. Placement decides where a step runs, not what it produces —
	// the same reasoning as timeout: and attempts: — and a tree that crossed a
	// wire digests identically to one that never left (see internal/wire).
	// Retagging a step, or repointing a tag at another machine, therefore does
	// not invalidate work that already succeeded.
	//
	// On a get or put it overrides the resource's own tags: (Resource.Tags)
	// for that step. On a do: or in_parallel: block it places the steps
	// inside instead, the way Job.Tags places a whole plan: a step with none
	// takes its own, else its resource's, else the nearest enclosing block's,
	// else the job's — override, never union. A step's hooks inherit what
	// the step resolved to (see visitPlacements).
	//
	// Invalid on try:, race: and ensemble: steps, on an agent without image:
	// or a CLI agent, on a task with fix: (each would leave half a step on
	// each machine), and on a get or put whose type is not shell-backed —
	// inherited or not.
	Tags []string `yaml:"tags,omitempty"`
	// Privileged, on a task or agent step, overrides the referenced task's/
	// agent's Privileged for this step only. True-wins, like Image's
	// non-empty-wins: there is no way to force UNprivileged from a step when
	// the task/agent asked for it, matching how every other execution setting
	// inherits. Invalid on get/put steps, for the reason Image is.
	Privileged bool `yaml:"privileged,omitempty"`
	// Limits, on a task or agent step, overrides the referenced task's/agent's
	// container_limits: for this step only (set-wins, like Image).
	Limits *ContainerLimits `yaml:"container_limits,omitempty"`
	// Volatile marks a step whose result must never be reused: it reads
	// something the pipeline never declared — a clock, a network endpoint, a
	// path outside its inputs — so a recorded answer is a stale one. Off by
	// default, because a step's declared inputs are what identify its work,
	// which is the contract a task's run: has always had. Valid only on task
	// and agent steps: they are the two kinds the step cache reuses at all.
	Volatile bool `yaml:"volatile,omitempty"`
	// Caches, on a task or agent step, overrides the referenced task's/agent's caches: for this step only (declared-wins, like Env). See TaskCache.
	Caches []TaskCache `yaml:"caches,omitempty"`
	// When, on a task/put/agent step, gates whether the step runs at all: an
	// explicit command whose exit code decides (0 runs, nonzero skips). See
	// WhenSpec. Invalid on get steps — a get fans the remainder of the plan
	// out per version, so a conditional get has no coherent meaning.
	When *WhenSpec `yaml:"when,omitempty"`
	// To, on a task/put/verdict-less agent step, routes to another step in the
	// SAME get-segment based on this step's binary outcome: "success" and
	// "failure" are the only keys, and both are reserved. An open map (not a
	// fixed struct) so a later exit-code routing extension needs no new type.
	// Invalid on get steps, hook steps, and any step declaring Verdicts —
	// which carry their own targets. Absent, the plan falls through in
	// declaration order exactly as before. See validateStepTransitions and
	// internal/pipeline's resolveTransition.
	To map[string]string `yaml:"to,omitempty"`
	// MaxVisits caps how many times THIS step may execute in one run. It is
	// required (LoadConfig) whenever any To target routes backward (a target
	// at or before this step's own position within its segment); 0/unset means
	// unbounded, which is only legal when every To target is strictly forward.
	MaxVisits int `yaml:"max_visits,omitempty"`
	// Verdicts, on an agent step, declares the outcome vocabulary the model
	// emits AND where each outcome sends the plan. Its presence turns on
	// verdict mode: internal/agent synthesizes a required `verdict` tool whose
	// enum is exactly these names, and the model must call it. An entry may be
	// a bare name (record the verdict, carry on) or a `name: target` pair
	// (record it and jump); `failure:` is the reserved catch for a step that
	// errored or emitted nothing. Order is significant — it is the tool enum,
	// and an ensemble's decide: any precedence. Agent-only, and mutually
	// exclusive with To. See VerdictRoute.
	Verdicts []VerdictRoute `yaml:"verdicts,omitempty"`
	// ContextPaths lists files whose contents are injected at conversation
	// start as synthetic read_file tool results — the agent sees the file
	// contents as if it had called read_file itself, without consuming a
	// turn. Paths are relative to the step's working directory and confined
	// to it (ConfinedPath): the step root without Dir, where each input is a
	// directory (["repo/CLAUDE.md"]), and Dir itself with one, so a sibling
	// input is out of reach. Only valid on agent steps. An absolute or
	// escaping spelling is refused at load (checkContextPathConfined); a
	// missing file, or a symlink out, fails the step at preparation, before a
	// token is spent; one merely over MaxContextBytes is truncated, with a
	// note saying so.
	ContextPaths []string `yaml:"context_paths,omitempty"`
	// MaxContextBytes overrides the agent's max_context_bytes: for this step
	// only, capping how much of each ContextPaths file is handed over. Unset
	// (the common case) defers to the agent's, which itself falls back to
	// DefaultMaxContextBytes; an explicit 0 hands the files over whole.
	//
	// It belongs here as well as on the agent because context_paths: is itself
	// a step-level field: two steps sharing one agents: entry routinely hand
	// it different evidence — a 400KB diff to the reviewer, a small manifest
	// to the gatekeeper — and without a step-level ceiling the only way to
	// give them different ones is to duplicate the whole agent under a second
	// name for the sake of one number. (context_window: has no step spelling
	// for the mirror-image reason: it describes the MODEL, and the model is
	// the agent's.) Operational, like the agent's, and likewise never hashed.
	MaxContextBytes *int `yaml:"max_context_bytes,omitempty"`
	// Hooks are the step's on_success/on_failure/on_error/on_abort/ensure
	// reaction steps (see Hooks). Inlined so they sit alongside the step's
	// own fields in YAML.
	Hooks Hooks `yaml:",inline"`
	// Assert, on a task/agent step, checks the step's captured output/exit
	// code (see Assert). A matching assert makes a non-zero-exit task a
	// success; a mismatch fails the step. Invalid on get/put steps.
	Assert *Assert `yaml:"assert,omitempty"`
	// Label is COMPUTED at expansion (never written in YAML): the name this
	// step is KNOWN BY, when that differs from the name it is RESOLVED by.
	//
	// task:/agent:/put: each do two jobs — they identify the step (routing
	// target, recorded node, assert.execution) and they look something up
	// (FindTask, FindAgent, the resource). An across: matrix needs its cells to
	// be distinguishable, so it used to append coordinates to the very field
	// the lookup keys on: a cell over a shared tasks: entry then failed with
	// `no task named "shared [shard=b]"`, and an agent cell could not be
	// renamed at all, since FindAgent has no inline escape the way ResolveTask
	// does. So every agent cell of a matrix answered to one name, which is why
	// context: is still rejected there.
	//
	// Label carries the identity half, leaving the lookup half alone. Empty on
	// an ordinary step, where the two names are the same thing — see stepName.
	Label string `yaml:"-"`
	// OutputSubdir is COMPUTED at expansion (never written in YAML): this
	// cell's coordinates as a path — one segment per axis value, declaration
	// order ("alpha/fast"). A matrix that declares outputs: captures each
	// cell's outputs under it (findings/alpha/fast/...), which is what lets N
	// cells share one declared output name without clobbering each other; see
	// CollectedOutputMapping. Empty on an ordinary step, and ignored on a cell
	// that declares no outputs.
	OutputSubdir string `yaml:"-"`
	// Memory, on an agent step, is the scope it keeps facts under between
	// runs: what that scope holds is handed to the model as it starts, and the
	// remember/forget builtins write to it. See StepMemory and docs/agents.md.
	Memory *StepMemory `yaml:"memory,omitempty"`
	// Context, on an agent or task step, opts into reading named earlier
	// steps' decisions: `context: { from: { <step>: verdict|note|full } }`.
	// Never a hook — see validateContextSteps and contextfrom.go.
	Context *ContextSpec `yaml:"context,omitempty"`
	// NoteRequired is COMPUTED at load (never written in YAML): some other
	// step declared context: { from: { <this step>: note|full } }, so this
	// step's verdict note stops being optional. The obligation lives here
	// rather than on the reader because internal/agent builds the sender's
	// tool set and never sees the reader. See validateContextFrom.
	NoteRequired bool `yaml:"-"`
	// InputMapping/OutputMapping rename a task step's declared inputs/outputs
	// onto plan-artifact names, mirroring Concourse's input_mapping/
	// output_mapping (see docs/conformance.md;
	// TestRunJobIsolatedGetAliasMappingAndPutAll in
	// workspace_integration_test.go; Concourse doc: concourse-ci.org/docs/
	// steps/task/): each entry is {task-config-name: plan-artifact-name}, so
	// a reusable tasks: entry with pinned input names can be pointed at
	// whatever a job actually fetched/produced without editing the task. Keys
	// must be a subset of the resolved task's declared inputs:/outputs:. Task
	// steps only (a load-time error elsewhere); mapping renames a materialized
	// directory. Absent/empty leaves names unmapped.
	InputMapping  map[string]string `yaml:"input_mapping,omitempty"`
	OutputMapping map[string]string `yaml:"output_mapping,omitempty"`
	// Resource, on a get or put step, names the resource to fetch or publish
	// to when it differs from the step's own name. On a get the fetched
	// artifact (and the directory, step name, and to: target) is Get, while the
	// resource whose check/in runs is Resource — mirroring Concourse's
	// get.resource, including that two aliased get steps for the same
	// underlying resource share one version history rather than tracking
	// separately (see docs/conformance.md;
	// TestResourcesAndAffectedJobsResolveGetAlias in
	// internal/trigger/trigger_test.go; Concourse doc: concourse-ci.org/docs/
	// steps/get/). On a put the step name, to: target and execution entry are
	// Put, while the resource whose out: runs is Resource — Concourse's
	// put.resource (concourse-ci.org/docs/steps/put/). This lets one resource
	// appear under a task-friendly name, or several times in a plan under
	// several names. Empty (the default) means the resource name equals Get or
	// Put.
	Resource string `yaml:"resource,omitempty"`
	// Line is the step's source line in the pipeline file, filled in after
	// decoding (see stampLines) so a validation error can point at a place in
	// the file. Never written in YAML and never hashed.
	Line int `yaml:"-"`
}

type StepKind string

type StepMemory struct {
	// ScopeFrom is <input>/<path>: a file in one of the step's inputs whose
	// content (trimmed) is the scope — a Slack user id, say. Read when the
	// step runs; an empty or missing file fails the step rather than falling
	// back to a scope everyone shares.
	ScopeFrom string `yaml:"scope_from"`
}

type Task struct {
	Name string `yaml:"name"`
	Run  string `yaml:"run"`
	// File loads every field of this task but name: from a YAML
	// document at a path relative to the pipeline file's directory (see
	// LoadConfig's resolveFileIncludes), so one task definition can be shared
	// across pipelines. Any field also set inline on this entry overrides the
	// loaded document's value for that field — the same "wins when set" idiom
	// ResolveTask already uses between a step and its tasks: entry. The
	// loaded document may not itself use file:/run_file:.
	File string `yaml:"file,omitempty"`
	// RunFile loads Run's text from a file at a path relative to the pipeline
	// file's directory, instead of writing it inline. Mutually exclusive with
	// Run.
	RunFile string   `yaml:"run_file,omitempty"`
	Fix     *FixSpec `yaml:"fix,omitempty"`
	// Image, when set, runs this task's run: (and its verdict re-run) in a
	// fresh `docker run --rm` container from this image instead of on the
	// host. A referencing step's own Image, if non-empty, overrides this for
	// that step only — mirroring how Fix works. Empty (the default) keeps
	// host execution, byte-identical to before this field existed.
	Image string `yaml:"image,omitempty"`
	// Env names host environment variables this task's run: is allowed to
	// see, on top of the always-allowed baseline (see shell.HostEnv). Names
	// only — see validateEnvValues. A referencing step's own Env, if
	// non-nil, overrides this for that step only, mirroring how Fix works.
	Env []string `yaml:"env,omitempty"`
	// User is the container user this task's run: executes as (docker's
	// --user). Empty takes the platform default — see shell's
	// defaultContainerUser. Only meaningful alongside Image.
	User string `yaml:"user,omitempty"`
	// Network is the container network this task's run: joins (docker's
	// --network); "none" cuts off egress entirely. Requires Image, except
	// "none" beside Sandbox.
	Network string `yaml:"network,omitempty"`
	// Privileged runs this command's container with `docker run --privileged`.
	// Mirrors Concourse's privileged: (concourse-ci.org/docs/steps/task/).
	// Container-only, like Network — a host command has nothing to elevate,
	// so it is a load error without image:.
	Privileged bool `yaml:"privileged,omitempty"`
	// Limits caps the container's CPU and memory. Mirrors Concourse's
	// container_limits:; container-only for the same reason Privileged is.
	Limits *ContainerLimits `yaml:"container_limits,omitempty"`
	// Sandbox fences this entity's host commands with the OS sandbox: writes only under the step's workspace and a private TMPDIR, credential directories unreadable, and network: none becomes legal on the host. See internal/config/sandbox.go for the rules and docs/infra.md for the policy.
	Sandbox bool `yaml:"sandbox,omitempty"`
	// Timeout is a wall-clock deadline per attempt (e.g., "2m", "30s"). Empty
	// (default) means no timeout. Inherited by task steps unless overridden.
	Timeout string `yaml:"timeout,omitempty"`
	// Inputs/Outputs are consulted only when a pipeline sets workspace: (see
	// WorkspaceConfig); a referencing step's own Inputs/Outputs, if
	// non-nil, override these for that step only — mirroring how Fix works.
	//
	// Inputs is the same *InputSpec a step carries, so `inputs:` means one
	// thing in the schema rather than two types that happened to share a
	// name. The list form decodes identically; only the scalar `all` differs,
	// and that stays put-only (validateTaskInputsAll) — a reusable task
	// declaring "everything available" would depend on whichever job called
	// it, which is the opposite of reusable.
	Inputs  *InputSpec `yaml:"inputs,omitempty"`
	Outputs []string   `yaml:"outputs,omitempty"`
	// Caches are directories this task keeps between runs on the machine that ran it (see TaskCache). A referencing step's own Caches, if non-nil, override these for that step only.
	Caches []TaskCache `yaml:"caches,omitempty"`
}

type TaskCache struct {
	// Path is relative to the step's working directory. It may sit inside an input, which it then shadows, as Concourse's own node_modules example does; it may not be or contain an input, nor touch an output, which would carry the cache into the step's results.
	Path string `yaml:"path"`
}

type ToolSpec struct {
	Builtin     string // set when the entry is a bare builtin name
	Name        string // custom tool: function name exposed to the model
	Description string // custom tool (and sub-agent tool): description shown to the model
	Run         string // custom tool: sh -c template, {{ .args.X }} interpolated
	// Agent, when set, makes this tool a sub-agent delegation: the named
	// agents: entry is exposed to the model as a callable tool taking a single
	// `request` string; each call runs that agent's own fresh tool-calling
	// conversation (its own model/persona/dials/tool grant) in the caller's
	// working directory, and its final text answer is the tool result. A
	// sub-agent tool sets no builtin/name/run and can never be required:
	// (enforced at LoadConfig by validateAgentGraph). Sub-agents may
	// themselves grant sub-agents, up to maxSubAgentDepth, with no cycles.
	Agent string
	// MCP, when set, makes this a passthrough to one or more tools on a
	// configured mcp_servers: entry (MCP names the server). Three forms:
	//   - MCPTool set ({mcp, tool} in YAML): grants that one remote tool;
	//     only this form may also set Description/Required/MaxCalls/Args.
	//   - MCPTools set ({mcp, tools: [...]} in YAML): grants that named
	//     subset, each keeping its own server-advertised description.
	//   - neither set ({mcp} alone): grants every tool the server exposes.
	// Like a sub-agent tool, an MCP grant must live on the agents: entry
	// (or a fix:'s own tools:), never introduced inline on a step
	// (enforced by validateMCPToolGrants/resolveEffectiveTools).
	MCP      string
	MCPTool  string
	MCPTools []string
	// Required marks a custom tool's command as a resource-like action that
	// must succeed: a nonzero exit aborts the agent step (and, once attempts
	// are exhausted, the job) instead of being reported to the model as
	// {"error": ...} data for it to react to. Ignored on builtins; invalid on
	// sub-agent tools.
	Required bool
	// MaxCalls caps how many times this custom tool may be invoked within one
	// attempt's conversation (0/unset = unlimited). The (N+1)th call is
	// rejected as ordinary tool-result data ({"error": "... call budget
	// exhausted ..."}), never an aborted attempt. The counter resets on an
	// attempts: restart (a fresh conversation is a fresh budget). Invalid on
	// builtins and sub-agent tools.
	MaxCalls int
	// Args pins argument values: merged OVER the model's own arguments at
	// call time (pinned always wins), and excluded from the parameter schema
	// shown to the model, so the model can neither see nor override them —
	// "the model chooses when, the machine chooses where." Values are plain
	// strings; not templated. On a custom tool they are keys its run:
	// template may reference. On a single-tool MCP grant each must be a
	// top-level property the server's input schema declares, and is sent as
	// that property's scalar type (internal/agent pinMCPArgs). Invalid on
	// builtins, sub-agent tools, and the tools:/bare MCP forms.
	Args map[string]string
	// Allow narrows the web_fetch builtin to the named hosts: an entry
	// matches its exact hostname and any subdomain of it, and every hop of a
	// redirect chain is re-checked. Empty means any PUBLIC http(s) URL:
	// loopback, link-local, private and multicast addresses are refused at
	// connect time unless an entry names the host, which is the only opt-in
	// (internal/agent webFetchTransport). Invalid on
	// every other tool form (validateWebFetchAllowShape).
	Allow []string
	// AnsweredBy names an agents: entry that answers this grant's ask_user
	// questions BEFORE a person is asked — the first rung of the ladder in
	// docs/agents.md. It is deliberately not the same thing as granting that
	// agent as a sub-agent tool: a sub-agent is delegation the asking model
	// chose and paid for out of its own reasoning, while a responder is an
	// ESCALATION a person can still intercept, and the recorded row says which
	// one answered. Empty parks the question for a person straight away.
	// Invalid on every tool but the ask_user builtin (validateAskUserShape).
	AnsweredBy string
	// Default is the answer ask_user resolves to when its wait expires. The
	// model is told it was a default and that nobody answered — an
	// indistinguishable default is the runtime telling a model a person
	// confirmed something no person saw. With no default declared, an expiry
	// ABORTS the step instead, matching approval: exactly: aborted, not
	// failed, because nobody decided anything. Invalid on every other tool.
	Default string
	// OptionsRequired refuses an answer that is not one of the options the
	// model offered. Off by default, and that default is the design: a wrong
	// option list must never trap the person answering, so the free-text
	// escape is what makes offering options safe. Turn it on for a question
	// whose answer a later step will match on. Invalid on every other tool.
	OptionsRequired bool
	// MaxOutputBytes sets the inline output budget for this one tool
	// (0/unset = the global default, maxToolOutputBytes in internal/agent).
	// An explicit value wins in either direction, bounded above by the spill
	// ceiling (shell.SpillMaxBytes, 10MB).
	//
	// Narrowing is for a tool whose output is known to be mostly noise: a
	// fuzzy search that returns a ranked list where the answer is the first
	// few entries, where the tail costs context on every subsequent turn and
	// buys nothing. Narrowing loses no data — the overflow still spills to a
	// file the model can read back — it only shrinks what lands in the
	// conversation. Widening is the declared trade the other way: a bigger
	// inline result instead of a spill pointer, for a tool whose output the
	// model needs whole.
	//
	// Deliberately NOT valid on a built-in: those carry their own output
	// contract (read_file pages, list_dir counts entries, search_files is
	// bounded by arithmetic), and a second, conflicting bound on top of a
	// designed one is a bug surface rather than a knob. Also invalid on a
	// sub-agent tool, whose result is another agent's considered answer, not
	// a data dump. Valid on custom tools and on all three MCP grant forms.
	MaxOutputBytes int
	// Timeout bounds one call of this tool (empty/unset = no per-call bound;
	// the step's own deadline still holds). An expired call comes back to the
	// model as {"error": "... timed out after ..."} — ordinary data it can
	// react to on its next turn, the same as a nonzero exit — never an
	// aborted attempt: a deadline says how long a tool may take, not that the
	// step is over.
	//
	// Valid on every tool form, unlike max_output_bytes: a deadline collides
	// with no designed per-tool contract, and run_shell — a builtin — is the
	// likeliest thing in the system to hang. It binds only where the tool is
	// GRANTED, except on an inline custom tool, which a step defines rather
	// than selects (see validateToolTimeoutShape). A cli source used to be an
	// exception — a builtin ran as the CLI's own native tool, which the
	// deadline never reached — but since issue #100 every tool a CLI agent
	// calls goes through the bridge, the same impl a hosted agent's deadline
	// already binds to, so a builtin's timeout: on a cli source binds exactly
	// like any other form.
	//
	// On ask_user the deadline is the WAIT, and what a breach resolves to is
	// that tool's own contract: the declared default: with answered: false,
	// or an aborted step when none was declared. That is the one place this
	// word bends, and it bends the way web_fetch's hard 30s cap already
	// established a built-in may.
	//
	// It is enforced through the call's context, so it stops what honors one:
	// shell-backed tools (the sh -c process is killed, though not its own
	// grandchildren — see shell.cancelWaitDelay), MCP calls, sub-agent
	// conversations. The purely local built-ins (read_file, list_dir,
	// search_files, write_file, edit_file) take no context and so run to
	// completion; an over-deadline call there is reported only if it failed
	// on its own, never relabeled from success (see withToolTimeout).
	// web_fetch carries a hard 30s client-side cap of its own, so a timeout:
	// there can only tighten.
	Timeout string
	// Params limits what each argument of this tool may be (see ParamSpec). Keys are the argument names the caller sees; a pinned argument is not one. Valid on a custom tool, a sub-agent tool and a single-tool MCP grant, where the tool is granted.
	Params map[string]ParamSpec
	// Rules names rules: entries that check each call of this tool (see Rule), in order, after any rules of the export it is in. Where the tool is granted.
	Rules []string
}

type VerdictRoute struct {
	Name   string `json:"name"`
	Target string `json:"target,omitempty"`
}

type WebhookSignature struct {
	Header    string `yaml:"header"`
	Prefix    string `yaml:"prefix,omitempty"`
	Encoding  string `yaml:"encoding,omitempty"`
	Algorithm string `yaml:"algorithm,omitempty"`
	Signed    string `yaml:"signed,omitempty"`
	Timestamp string `yaml:"timestamp,omitempty"`
}

type WebhookSource struct {
	Provider  string `yaml:"provider"`
	SecretEnv string `yaml:"secret_env"`
	MaxBody   int64  `yaml:"max_body,omitempty"`
	// Filter, ID and Version are expressions over the verified delivery; see exprlang.Webhook.
	Filter    string            `yaml:"filter,omitempty"`
	ID        string            `yaml:"id,omitempty"`
	Version   map[string]string `yaml:"version,omitempty"`
	Signature *WebhookSignature `yaml:"signature,omitempty"`
}

type WhenSpec struct {
	Run string
}

type WorkspaceConfig struct {
	// Strategy is "copy", the only one, kept so a pipeline spelling out the default still loads. It uses copy-on-write where the filesystem offers it (APFS clonefile on macOS, reflink on Linux) and a plain recursive copy otherwise.
	Strategy string `yaml:"strategy,omitempty"`
	// Root is where isolated build workspaces are materialized; the system temp directory when unset.
	Root string `yaml:"root,omitempty"`
	// Cache, when set, opts into the cross-build resource cache: a fetched
	// resource version is kept under Root and reused by later builds instead
	// of being re-fetched. Off by default, deliberately — see CacheConfig.
	Cache *CacheConfig `yaml:"cache,omitempty"`
}