subharness

type BeltEntry struct {
	Name  string
	About string
}

type CardBlock struct {
	// Head is the identity line: what it is called, which version, what it is for.
	Head string
	// Steps is the run in the order it runs, nested lanes and all.
	Steps []string
	// Foot is the bounds, one quiet sentence at a time. It is empty for a recipe
	// that decides nothing, checks nothing and was tried on nothing.
	Foot []string
}

type Derivation struct {
	A   string `json:"a"`
	B   string `json:"b"`
	Rel string `json:"rel"`
	Why string `json:"why,omitempty"`
}

type Dyn struct {
	Ladder string `json:"ladder"`
	Cap    int    `json:"cap,omitempty"`
}

type Edge [2]string

type Entry struct {
	// Name is the harness's id, its filename, and the word the offer card says
	// out loud: "research".
	Name string

	// Description is one sentence saying what this harness does, in the words a
	// person would use for it — not in the words the program uses for itself.
	// It is shown under the offer, and its content words are the second of the
	// two matching signals (detect.go).
	Description string

	// Cues are the words and phrases this harness answers to: ["research",
	// "find out", "dig into"]. They are the designer's own trigger vocabulary,
	// frozen at build time, which is what makes detection a table lookup rather
	// than a judgement — see detect.go for why that matters more than recall.
	//
	// A cue of several words matches only as a PHRASE, and counts for more than
	// a single word does: "find out" in a sentence is evidence, "find" on its
	// own is a coincidence waiting to happen.
	Cues []string

	// Revision pins the version this entry is: v1, v2, an integer that only
	// ever goes up (docs/SUBHARNESS.md). Detection does not read it — it is
	// here because an entry without it is not an entry, and a surface that
	// offers a harness should be able to say which one it offered.
	Revision int
}

type Env interface {
	// Loop runs one agent.loop node on input and returns what the worker
	// produced.
	Loop(ctx context.Context, node Node, input string) (string, error)
	// Tool calls one tool with the node's fixed arguments.
	Tool(ctx context.Context, node Node, input string) (string, error)
	// Gate asks a person the node's question and returns their answer. An
	// implementation with nobody to ask must return an answer rather than block
	// forever — see [GateAnswer] for what "nobody is there" should mean.
	Gate(ctx context.Context, node Node, state State) (GateAnswer, error)
	// Check runs one verify node. The bool is whether it passed; the string is
	// what it said, which becomes the state the next condition reads. An ERROR
	// means the check could not be run at all, which is a different fact from a
	// check that ran and failed.
	Check(ctx context.Context, node Node, state State) (bool, string, error)
	// Cond judges a branch's `when` or a loop.until's `until` when the condition
	// language cannot (predicate.go). It is the seam where "the suite is green"
	// stops being a string and becomes an answer, and it is asked ONLY for
	// conditions [ValidCondition] refuses — everything the small language can
	// decide is decided here, in this package, the same way every time.
	Cond(ctx context.Context, node Node, condition string, state State) (bool, error)
}

type Exec func(context.Context, Node) (Result, error)

type Fields map[string]string

type GateAnswer struct {
	Approved bool
	// Intervene means the person is taking over: the run ends as intervened,
	// whatever Approved says.
	Intervene bool
	// Note is what they typed — a redirect, a reason, or the instruction they
	// are continuing with.
	Note string
}

type Harness struct {
	Id        Id       `json:"id"`
	Program   Program  `json:"program"`
	Whitelist []string `json:"whitelist,omitempty"`
	Verify    Verify   `json:"verify"`
	Dyn       Dyn      `json:"dyn"`
	Tests     []Test   `json:"tests,omitempty"`
}

type Hosted struct {
	// Harness and Version identify the entry, pinned. The source stores the
	// version it mounted so a run started from this command is the harness the
	// person read about, not whatever was saved since.
	Harness string `json:"harness"`
	Version int    `json:"version"`

	// Command is the line, always `/harness <name>`.
	Command string `json:"command"`

	// AllowedArgs is the trigger's whitelist, copied so the source can complete
	// and refuse arguments without reading the harness.
	AllowedArgs []string `json:"allowed_args,omitempty"`

	// Entry is the node the command enters at — the trigger's successor — and
	// Node is the trigger itself, so a run can be attributed to the line that
	// started it.
	Entry string `json:"entry"`
	Node  string `json:"node"`

	// Desc is the harness's own one-liner, for whatever help the source renders.
	Desc string `json:"desc,omitempty"`
}

type Id struct {
	Name    string `json:"name"`
	Desc    string `json:"desc,omitempty"`
	Author  string `json:"author,omitempty"`
	Version int    `json:"version"`
}

type Kind struct {
	Name   string
	Desc   string
	MinDyn string
	Specs  []spec
	Valid  func(Fields) error
}

type LastRun struct {
	// At is when the run happened. A zero time is a program nobody has run, and
	// it is the one case that draws nothing at all.
	At time.Time
	// Finished is whether the run reached the end it promised.
	Finished bool
	// CostUSD is what it cost, and zero is "nobody said" rather than "free".
	CostUSD float64
}

type Loader interface {
	Load(name string, version int) (Harness, error)
}

type Match struct {
	Entry Entry
	Score float64
}

type ModelExecOpts struct {
	// Harness is the program being run, and it is REQUIRED. An [Exec] is handed
	// one Node at a time and can see nothing around it, so the shape a node sits
	// in — which harness's whitelist bounds it, which nodes lead into it — has
	// to be closed over here.
	Harness Harness

	// RunTool calls one whitelisted tool with the node's fixed arguments. Nil
	// means this surface has no tools, and a tool.call under it FAILS rather
	// than returning nothing: a program that asked to run the suite and was
	// quietly told "" would go on to verify that "" looks fine.
	RunTool func(ctx context.Context, tool, args string) (string, error)

	// Toolbelt is what an agent.loop that NAMES tools is handed. A zero one is a
	// surface that can run a tool.call and not a tool loop, and a node under it
	// is told as much rather than being offered a belt that goes nowhere.
	Toolbelt Toolbelt

	// Ask puts a human.gate's question to a person and returns what they typed.
	// Nil is nobody there — see the note at the top of this file.
	Ask func(ctx context.Context, question string) (string, error)

	// MaxTurnsDefault is what an agent.loop that declares no max_turns is told
	// it was budgeted. Zero takes this file's own default.
	MaxTurnsDefault int

	// Store, when set, is where a subharness.call resolves the harness it names
	// and where that child's own trace is saved. Nil means this bridge cannot
	// make calls, and a program that tries says so.
	Store *Store

	// Model is what THIS RUN was asked to think with: the default model for
	// every agent.loop node that did not pin one of its own. Empty is the
	// ordinary run, on the client's model. exec_model_model.go holds the rule
	// and says why a node's own `model` still wins.
	Model string

	// Usage, when set, is the ledger every model call this run makes is folded
	// into — the run's own bill, which is a thing no caller can reconstruct
	// afterwards because the calls are this file's and the trace records their
	// outputs rather than their cost (usage.go).
	//
	// It is a pointer the CALLER allocates and reads after the run, rather than
	// a figure on the trace, because a trace is saved to disk and a saved run's
	// price is not the same claim as what this process just spent: the trace
	// outlives the session, and a number in it would be read back tomorrow as
	// though somebody had paid it again. Nil is a caller that is not counting.
	Usage *Usage

	// DepthCap bounds subharness.call nesting: how many harnesses deep a call
	// may go below the one this bridge was built for. Zero takes
	// [MaxCallDepth]. It is a caller's knob rather than only the constant
	// because the surface driving the bridge is what knows how much recursion
	// it is willing to pay for — a chat turn and an unattended runner are not
	// the same appetite.
	DepthCap int
	// contains filtered or unexported fields
}

type Node struct {
	Id     string `json:"id"`
	Kind   string `json:"kind"`
	Fields Fields `json:"fields,omitempty"`
}

type Op struct {
	// Op is the verb, one of the constants above.
	Op string `json:"op"`
	// Node is the node id the edit lands on — or, for an edge, its source.
	Node string `json:"node,omitempty"`
	// Field is which field is being written, where the verb needs telling.
	Field string `json:"field,omitempty"`
	// Text is the new value — or, for an edge, its target.
	Text string `json:"text,omitempty"`
	// NodeJSON is a whole node, for add_node, in the page's own node shape.
	NodeJSON json.RawMessage `json:"node_json,omitempty"`
}

type OpResult struct {
	Op  Op
	Err error
}

type Program struct {
	Nodes []Node `json:"nodes"`
	Edges []Edge `json:"edges,omitempty"`
}

type Result struct {
	// Out is the node's output, condensed for the trail. The full artifact
	// belongs wherever the executor keeps artifacts; what lands here is what a
	// person reading the run needs to see.
	Out string
	// Next is a branch node's choice: the id of the one successor to take.
	// Empty means the first successor in program order. Ignored by every other
	// kind.
	Next string
	// Done is a loop.until node's condition: true when the loop may stop.
	// Ignored by every other kind.
	Done bool
}

type RunPage func(ctx context.Context, name, text, model string, step func(Trail)) (string, Usage, error)

type Runner struct {
	// Env is what makes the nodes do anything. Required.
	Env Env
	// Loader resolves subharness.call. Nil means this runner cannot make calls,
	// and a program that tries gets an error rather than a silent skip.
	Loader Loader
	// Saver, when set, is where a called harness's own trace is written.
	Saver Saver
	// Depth is how many calls deep this runner already is. The top level is 0.
	Depth int
}

type Salvaged struct {
	// JSON is text encoding/json has already agreed to read.
	JSON []byte
	// Rung is the name of the step that produced it — [SalvageStrict] when the
	// reply needed nothing, which is the only outcome worth being quiet about.
	Rung string
	// Climbed names every rung attempted, in order, ending at Rung.
	Climbed []string
}

type Saver interface {
	SaveRun(Trace) (string, error)
}

type Source interface {
	AddTrigger(Hosted) error
}

type State struct {
	Last string
	OK   bool
}

type Status string

type Store struct {

	// Now stamps a run file. It is a field so a test can run two harnesses in
	// the same second and still get two names it chose.
	Now func() time.Time
	// contains filtered or unexported fields
}

type Test struct {
	Name   string `json:"name"`
	Input  string `json:"input,omitempty"`
	Expect string `json:"expect,omitempty"`
}

type Toolbelt struct {
	// Defs is every tool this surface can run, in the shape the wire wants. A
	// node is offered only the ones it named; the rest never leave this struct.
	Defs []ai.ToolDefinition

	// Call runs one of them on the arguments the model wrote, and answers with
	// the tool's own text — the same thing RunTool answers with. An error is the
	// tool refusing, and the loop hands it back to the model rather than failing
	// the node, because reacting to a tool that said no is what a loop is FOR.
	Call func(ctx context.Context, tool string, args map[string]any) (string, error)
}

type Trace struct {
	Id      Id            `json:"id"`
	Started time.Time     `json:"started"`
	Elapsed time.Duration `json:"elapsed"`
	Trail   []Trail       `json:"trail"`
	Edges   []Edge        `json:"edges,omitempty"`
	// Spent is how much of Dyn.Cap the run used. A run that spent nothing took
	// the shape the program already had.
	Spent int `json:"spent,omitempty"`
	// Err is the failure that ended the run early, if one did. It is recorded
	// rather than only returned because a saved trace outlives the call.
	Err string `json:"err,omitempty"`
	// Status is how the run ended in one word (exec.go). The walk fills in the
	// two it can tell apart on its own — ok and failed — and a [Runner] refines
	// it with the three that are somebody else's news: a person declined at a
	// gate, took the run over, or the context died. It is a field rather than a
	// reading of Err because "a person said no" is not a failure, and a history
	// that could only spell it as one would punish the gate for working.
	Status Status `json:"status,omitempty"`
	// Out is the run's own output: what the last node left behind, as the
	// executor condensed it. The trail holds every step's output; this is the
	// one the caller was waiting for.
	Out string `json:"out,omitempty"`
}

type Trail struct {
	Step    int           `json:"step"`
	Id      string        `json:"id"`
	Kind    string        `json:"kind"`
	Out     string        `json:"out,omitempty"`
	Err     string        `json:"err,omitempty"`
	Elapsed time.Duration `json:"elapsed"`
}

type Turn struct {
	Text string
}

type Usage struct {
	// Model is what the run ran on as the PROVIDER reported it, and it is empty
	// when the calls did not agree — a run whose nodes pinned models of their
	// own is not a run one name describes, and picking one of them would be
	// this package stating a fact nobody gave it.
	Model string

	// Calls is every request the run made, the intermediate rounds of a tool
	// loop included. A call the provider reported no usage for is still counted:
	// a missing count is not a call that did not happen.
	Calls int

	// Input and Output are the provider's token counts, summed in the same
	// spelling the session's own accounting keeps them: Input is prompt tokens
	// as reported, with cache reads beside it rather than inside it.
	Input  int
	Output int

	// CacheRead and CacheWrite are the prompt-cache accounting, read through
	// ai.Usage's accessors so that both dialects — Anthropic-native and the
	// OpenAI-style nesting — land in the same field.
	CacheRead  int
	CacheWrite int

	// CostUSD is the provider's OWN figure, summed. Zero is "the provider did
	// not say", which is not the same fact as "free" — a caller that wants a
	// price for a quiet provider has to derive one from the tokens, and a
	// caller that cannot show nothing (the emptiness law).
	CostUSD float64
	// contains filtered or unexported fields
}

type Verify struct {
	Ladder string `json:"ladder"`
}