run

type BashWorker 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 Report struct {
	Result  string
	Steps   int
	USD     float64
	Waiting bool
}

type Seats struct {
	Work  string
	Plan  string
	Check 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 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
	// 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"`

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

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