agent

func AnswerFlags ¶

func AnswerFlags(ctx context.Context, pipeline string) string

AnswerFlags finish a printed answer command; with no WithAnswerDB, as under a daemon, the read commands' default database is the run's.

func CheckExportedCommands ¶

func CheckExportedCommands(export config.MCPExport) error

CheckExportedCommands refuses an export whose command would put a caller's value into the shell as syntax. The caller is not the pipeline's author, so a value that reaches sh -c bare is a command the caller chose.

func Preflight ¶

func Preflight(ctx context.Context, cfg *config.Config, agentNames []string, settings *config.Preflight) []config.Problem

Preflight checks every model and MCP server the named agents need, and returns a problem per target that failed. An empty result means the job's dependencies are all live.

Only what this job needs: a pipeline with ten agents whose job uses two checks two. Distinct (endpoint, model) pairs are checked once even when several agents share one.

func RecordOutcome ¶

func RecordOutcome(ctx context.Context, name string, up Upstream)

RecordOutcome notes what the step named name decided. A later visit of the same step replaces the earlier one: a revise loop's reader wants the verdict that just sent it back, not the one from two passes ago.

func RenderUpstream ¶

func RenderUpstream(name string, level config.FromLevel, up Upstream) string

RenderUpstream formats one step's outcome at the demanded level, or "" when there is nothing to say.

Absence is deliberately not an error. A reader that runs BEFORE its sender — the writer at the top of a revise loop, whose critic has not judged anything yet — gets nothing on the first pass and the critic's verdict on every pass after. That is the same "routed entry only" behaviour, arrived at by asking whether the sender has run rather than by inspecting the route.

func ResetProbeCache ¶

func ResetProbeCache()

ResetProbeCache clears everything preflight has verified AND every source pin it (or a mid-run cascade) selected. Tests use it to stay independent of each other; a test about the pin's own lifetime wants only the first half, since wiping the pin is what such a test is trying to observe.

Every caller must be a serial test: this is process-wide state for all agents, so a `t.Parallel()` test that reached it would clear another's.

func RunFix ¶

func RunFix(
	ctx context.Context, cfg *config.Config, jobName string, stepIndex int,
	rt config.ResolvedTask, st StepStore, failureOutput, workspaceDir string,
) error

RunFix invokes a failed task's fix: agent. It reuses the normal agent-invocation resolution (tool grant, dials, attempts, max_turns) by projecting the FixSpec onto an agent Step, then injects the parent task as a zero-arg rerun tool — the task's own run: command (never its fix:, so a rerun can't recurse), exposed under the task's name — and seeds the conversation with the captured failure output. It does no merkle/store recording: the enclosing task step records the overall outcome, and the task's re-run (not the model's word) is the verdict.

The fix conversation's run_shell/custom tools and the injected rerun tool all execute under rt.Image — the failing task's own image, never the fix agent's own Agent.Image (config.validateFixAgentImages rejects a fix agent that sets one, at LoadConfig time, precisely because it can never take effect here). The premise of the fix loop is reproducing and resolving the exact failure the task hit; running under a different image than the one that produced (and re-verifies) the failure would make the loop incoherent.

func RunHook ¶

func RunHook(ctx context.Context, cfg *config.Config, jobName string, step config.Step, bw workspace.BuildWorkspace, st StepStore, newRunner RunnerFactory) error

RunHook runs an agent step as a hook: it resolves, materializes, runs the conversation, evaluates its assert, and captures declared outputs exactly like a plan step, but records no merkle node or job_run — the enclosing step/job records the aggregate outcome (the same no-record contract as RunFix). A returned error is already outcome-marked where appropriate (see runAgentConversation), so the caller's hook classification works unchanged.

The assert runs here for the same reason a task hook's does (see internal/pipeline's executeTask -> runAssertedTask): config.validateAsserts deliberately walks hook steps, so an assert on an on_failure: agent is checked and rejected at load like any other. Evaluating it at load and then never running it made that promise a lie — the hook reported success on a mismatch its own assert existed to catch.

func UnquotedToolRefs ¶

func UnquotedToolRefs(run string) []string

UnquotedToolRefs reports each action in a custom tool's run: that prints a .args value without shellquote — the model-authored half of a tool reaching sh -c as syntax.

func WithAnswerDB ¶

func WithAnswerDB(ctx context.Context, db string) context.Context

WithAnswerDB carries a local run's own state file to the printed commands, since the read commands default to a daemon's.

func WithAnswerSeeds ¶

func WithAnswerSeeds(ctx context.Context, seeds []AnswerSeed) context.Context

WithAnswerSeeds attaches pre-seeded answers to a run's context.

func WithExportWho ¶

func WithExportWho(ctx context.Context, who ExportWho) context.Context

WithExportWho carries who is calling to the rules checking the call.

func WithOutcomes ¶

func WithOutcomes(ctx context.Context) context.Context

WithOutcomes installs a fresh outcome register on ctx. Called once per job run; a run without one simply delivers nothing, which is what every pipeline that declares no from: should see.

func WithRunBoundary ¶

func WithRunBoundary(ctx context.Context) context.Context

WithRunBoundary stamps a context with the moment its run started, which is the instant every pin read inside that run is judged against.

The lifetime still rides on the pin and is still applied wherever one is read — hanging it off a writer would leave it exactly as skippable as reconsiderPin. What this fixes is WHICH clock the read consults. Reading at wall-clock meant a job of six agent steps could cross the lifetime between steps 4 and 5: the pin vanished mid-job and the remaining steps resolved to a primary that was still down, each paying a full attempts: cycle before cascading and re-pinning. Nothing renews mid-job, because renewPinIf is reachable only from Preflight — once per job, and switched off entirely by --no-preflight, which is the configuration the lifetime exists to serve.

Judging against the run's own start makes the release land at a boundary where nothing is half-done, which is what docs/agents.md has always promised: a run decides before it starts, and one job sees a settled source throughout. internal/pipeline stamps this once per job run, beside the OpenRouter session, so concurrent jobs each carry their own.