run

type AdmissionGate interface {
	// MayStart answers whether one more worker fits the current machine reading.
	MayStart() bool
	// Started counts a worker only after its factory has returned.
	Started()
	// Returned gives that worker's lane back on every return road.
	Returned()
}

type BashWorker struct {
	// contains filtered or unexported fields
}

type DelegateSetup struct {
	// Exe is codeaf's own executable, which the program runs as. Empty is this
	// process's own; a test names a script that speaks the records.
	Exe string
	// Grace overrides the launch's SIGTERM grace, for a test.
	Grace time.Duration
	// CompleterFor answers the funnel a call on a model goes out through: the
	// conversation's own completer (session.RunSpec.CompleterFor), so a
	// program's calls take the road the conversation's own do. Nil is a run
	// with no model road, whose API answers every call with that sentence.
	CompleterFor func(model string) session.Completer
	// Serves answers whether this conversation's services can take a call on a
	// model (session.RunSpec.Serves); nil answers yes for every model.
	Serves func(model string) bool
	// ModelPrice is the known per-token price for reserving model API calls.
	ModelPrice func(model string) (input, output float64, known bool)
	// Seat is the run's own work seat ([WorkSeat]): the model a call is
	// answered on when the one the program asked for cannot be reached here.
	Seat string
	// Ledger is the spending ledger the calls are written to. Empty is this
	// machine's own (session.UsageLedgerPath); a test names a file of its own.
	Ledger string
	// Keepalive overrides the model API's keepalive interval, for a test.
	Keepalive time.Duration
	// AuthKeySource names the safe credential source for the served model,
	// so a connected provider never borrows the default provider's explanation.
	AuthKeySource func(model string) string
	// PlainFolder says the program works in its folder without git
	// (session.RunSpec.PlainFolder), so the program's line carries its own
	// flags for that (delegate.Delegate.PlainFolder).
	PlainFolder bool
	// IgnoredFile is the run's start-time ignore list, and InputsFile the
	// untracked files copied into its copy with their fingerprints
	// (session.ProgramFolder.InputsFile). Both are passed to the child, whose
	// recorder keeps both out of every tree it records.
	IgnoredFile string
	InputsFile  string
	// BriefNote is the line the program's brief opens with when it works in a
	// copy of the person's repository (session.ProgramFolder.BriefNote): where
	// the copy is. Empty for a folder worked in itself.
	BriefNote string
	// Hold is the file the run's hold on the program's folder is taken on
	// (session.ProgramFolder.Hold), handed to the program's process so the
	// folder stays held until it has gone ([delegate.HoldEnv]). Nil hands none.
	Hold *os.File
	// Crew is the conversation's crew (session.RunSpec.Crew), which the
	// program's line carries in its own flags (delegate.Delegate.CrewFlags) so
	// it works on the models the person chose. Zero leaves it to its own.
	Crew delegate.Crew
	// Conversation is the id of the conversation the run belongs to
	// (session.RunSpec.Conversation), which every ledger row the program's
	// calls write names as its Root and its Session, beside the task's id, so
	// the conversation's spend and the spending page can say whose money it
	// was. Empty leaves the rows naming no conversation.
	Conversation string
	// OnCharge is told every priced call as it is metered
	// (session.RunSpec.OnCharge), for the conversation to fold the call's
	// tokens, model and dollars into its own books. Nil tells nobody.
	OnCharge func(session.RunCharge)
}

type DelegateWorker struct {
	// contains filtered or unexported fields
}

type Landing struct {
	Branch  string
	Changed []string
	Refused string
}

type Limit string

type Limits struct {
	// CostUSD is what the whole run may spend. Banked calls count while a worker
	// is still working and reconcile with its final Report. When the counter has
	// reached it no new worker starts, work in flight ends, and the run ends on
	// the limit word of the outcome ladder.
	CostUSD float64
	// Elapsed is how long the whole run may remain active. When it passes,
	// workers already in flight are ended and drained, no new worker starts,
	// and the run ends on the same limit word as the cost counter.
	Elapsed time.Duration
	// StepsPerTask is handed to every worker through its context, so the loop
	// a worker hosts can cap itself without the supervisor counting its steps.
	StepsPerTask int
	// StaleAfter is how long a claim may go untouched before a pass takes it
	// over: a claimed task whose owning process has not been seen for this
	// long is released so the ready set offers it again. It is a field here
	// rather than an environment variable because it bounds how long a run
	// waits on a process that may have died, and zero takes the default
	// (defaultStaleAfter) rather than meaning "no stale claim ever".
	StaleAfter time.Duration
	// ReviewRound turns the review round on. When it is set, a work-seat leaf
	// that lands done spawns one check task under its parent — whether the leaf's
	// own `plandb done` wrote the ending or this run did — and a check whose
	// result begins "does not hold" leaves its sentence as a note on the leaf it
	// read AND adds a `fix:` task under that leaf's parent which the run waits on.
	// A `fix:` task is checked in turn, but a finding on one is a note and no
	// second fix task, so a run cannot loop. It is a bool defaulting false so
	// every caller that does not ask for it keeps the run it had — no check
	// tasks, nothing new on the plan.
	ReviewRound bool
}

type Outcome string

type ProgramEndedError struct {
	// Status is the terminal record's word: fail, budget, crashed, or one
	// this build does not know.
	Status string
	// Reason is the one sentence: `senior-dev did not finish: …`.
	Reason string
	// Result is the program's account: its message, what its model claimed
	// and what it observed ([delegateResult]).
	Result string
	// Limit names a refusal made before actual spend reached the ceiling.
	Limit Limit
}

type Report struct {
	Result    string
	Steps     int
	USD       float64
	TokensIn  int
	TokensOut int
	Waiting   bool
	// Verdict is a program's own word for the finished work it handed in —
	// senior-dev's `pass` or `pass-unverified` — when a delegated run's program
	// finished; empty for every other worker ([delegate.Terminal.Verdict]).
	Verdict string
}

type Seats struct {
	Work  string
	Plan  string
	Check string
	// One is the conversation's model under `--one-model`, and when it is set
	// it is EVERY seat: the three above, the probe no door names, and any role
	// this build has not learned. Nothing here asks the profile or the check
	// seat's environment rung while it is set, because the flag promises that
	// every text call rides the model the person is talking to — and an empty
	// seat falling to the crew row is exactly how a run under it billed models
	// nobody named.
	One string
}

type Spec struct {
	// Store is the run's plan, opened by the caller and shared with the run's
	// other writers. The root task it was seeded with is the run itself.
	Store *plandb.Store
	// Workspace is the run's own working copy, carried for the worker seat
	// and the landing that follow this loop.
	Workspace string
	// Title and Brief are the run's own words. The store writes a root task's
	// title nowhere but its own open, so the title is the caller's to seed
	// there; the brief is Start's to put down — on a root opened without a
	// description it becomes the root task's description, which is the
	// assignment the root worker reads.
	Title string
	Brief string
	// Slots bounds how many workers run at once, and 0 is no bound; Limits
	// bound the run's cost and its per-task steps. Both pass through to the
	// supervisor as given.
	Slots  int
	Limits Limits
	// Factory makes the worker for every task the run dispatches. Start holds
	// no seat of its own: the root's worker comes from here like the rest.
	Factory WorkerFactory
	// Gate asks the machine before every worker, including the root and wakes.
	Gate AdmissionGate
	// OnHold announces the ids refused on a pass when their set changes.
	OnHold func([]string)
	// OnSpend observes the reconciled cumulative run spend whenever it rises.
	OnSpend func(float64)
}

type Step struct {
	Kind string `json:"kind"`
	// Step is the step's number, counted from one over the task across its wakes.
	Step int `json:"step"`
	// Command is what the worker asked the belt to run, as the model spelled
	// it — the command a resumed worker must not repeat blind, and the one
	// address the record has for what this step was.
	Command string `json:"command"`
	// Observation is the head of what came back, cut the way the belt cuts.
	Observation string `json:"observation,omitempty"`
	// FullOutput names the file the whole output was filed in, set only when
	// the step's output was cut — the belt files it beside the worker's
	// transcript, and this is where the next reader finds it.
	FullOutput string `json:"full_output,omitempty"`
	// Writes are the plandb verbs the command ran: the store writes the step
	// made, read off the command's own words, because the verbs are the words
	// the store was addressed by.
	Writes []string `json:"writes,omitempty"`
	// Children are the ids of the tasks this step created under the task, read
	// off the store after the command rather than parsed out of its output.
	Children []string `json:"children,omitempty"`

	// NotRun is established by the engine when the ended tool event is an
	// answer the harness wrote rather than a call the belt ran. The requested
	// command and the answer remain in the record; a surface reads this fact and
	// never the answer's words. False also preserves records written before the
	// field existed.
	NotRun bool `json:"not_run,omitempty"`
	// Refused narrows NotRun to the one kind a person wants to see: AN ACTION THE
	// WORKER ATTEMPTED AND A DOOR REFUSED ([session.Event.Refused]). A NotRun
	// step without it is a correction about the form of the worker's reply, where
	// nothing was attempted on the world. The engine records the difference here
	// because the event is where an attempted action is known; a surface cannot
	// recover it from the record afterwards.
	Refused bool `json:"refused,omitempty"`

	// ExitCode is the command's own exit status when the belt ran one and the
	// recorder knew it: zero for a step that ended, the non-zero code for one
	// that failed. It is a pointer so a step written before this field existed,
	// or one whose exit is unknown, decodes to nil and is never read as a zero a
	// real exit could equal. A holds verdict rests only on a recorded zero exit.
	ExitCode *int `json:"exit_code,omitempty"`

	// The ending line's fields. Steps is the run's whole step count, Result is
	// the worker's own account of the work, and Reason is why the loop ended —
	// a turn that ended, a step cap, a wall.
	Steps  int    `json:"steps,omitempty"`
	Result string `json:"result,omitempty"`
	Reason string `json:"reason,omitempty"`

	// StartedAt and EndedAt are a PROGRAM's own clock on the ending line of the
	// task it was handed: the instant codeaf started its process and the
	// instant that process was gone — the pair the program record carries
	// (delegate.ProgramRecord). They are zero on every other line, on an ending
	// written by a road that never started a process, and on every line a
	// worker of this conversation's own wrote. Step lines never carry them, so
	// the session's mirror of the step line (PlanStep) has no use for them.
	StartedAt time.Time `json:"started_at,omitzero"`
	EndedAt   time.Time `json:"ended_at,omitzero"`

	// ExitsRecorded is stamped true by a build that records each command's
	// exit, on the OPENING line it writes before any step and on the ending
	// line; bashworker.go sets it at both. A reader uses it to tell a record
	// that observed no run, or was cut off before its ending, from one written
	// before exits were recorded: the first refuses a holds verdict that never
	// ran its checks, the second falls back to reading.
	ExitsRecorded bool `json:"exits_recorded,omitempty"`

	// Notes is the notes line's one field: the ids of the task's notes a worker
	// of it has had, handed over or written itself ([trajectoryNotesKind]).
	Notes []string `json:"notes,omitempty"`
}

type Summary struct {
	Outcome Outcome
	// Result is the root's own result: what the run's last worker reported
	// when the tree finished whole, and empty whenever it did not.
	Result string
	// Failure is the run's own account when it did not finish: the root
	// worker's error, kept so the receipt can say why.
	Failure string
	// Limit is which bound a person set ended the run, and empty on every
	// run that did not end on one. The outcome word is the same sentence for
	// both limits; this is what tells them apart.
	Limit Limit
	// Program is how a delegated run's program ended when it ended without
	// finishing: its status word and its own account ([ProgramEndedError]).
	// Nil for a run that finished, and for every run no program worked.
	Program *ProgramEndedError
	// Verdict is a delegated run's program's own word for the work it
	// finished ([Report.Verdict]): senior-dev's `pass` or `pass-unverified`.
	// Empty for every other run.
	Verdict string
	// Cut is every task the run's own ending cut mid-flight, by store id: its
	// wall, its spend ceiling, or a person's stop ended the context their
	// workers ran under. A task that failed on its own before the ending is
	// not here. This is the fact a surface draws those rows with, so a row the
	// person's bound took down is never read as a fault; it is carried typed
	// and never parsed out of a stored error sentence.
	Cut       []string
	Nodes     int
	Steps     int
	USD       float64
	TokensIn  int
	TokensOut int
	Seconds   float64
}

type Supervisor struct {
	// Owner is the process that holds this run's claims: "<hostname>:<pid>",
	// so each claim names the process answerable for it and a claim nobody
	// touches reads stale. It is set from the running process when the
	// supervisor is built; a test sets it to stand in for a second process
	// sharing one store.
	Owner string
	// contains filtered or unexported fields
}

type Worker interface {
	Run(ctx context.Context, task plandb.Task) (Report, error)
}

type WorkerFactory func(task plandb.Task) Worker