delegate

type Action struct {
	// At is when codeaf received the record.
	At   time.Time `json:"at"`
	Kind string    `json:"kind"`
	// Stage, Status and Data are a stage's; Status is the ending's too.
	Stage  string          `json:"stage,omitempty"`
	Status string          `json:"status,omitempty"`
	Data   json.RawMessage `json:"data,omitempty"`
	// Tool, Step, Command, Observation and Exit are a step's.
	Tool        string `json:"tool,omitempty"`
	Step        string `json:"step,omitempty"`
	Command     string `json:"command,omitempty"`
	Observation string `json:"observation,omitempty"`
	Exit        *int   `json:"exit,omitempty"`
	// Added and Removed are a step's lines added and removed, when the program
	// counted them.
	Added   *int `json:"added,omitempty"`
	Removed *int `json:"removed,omitempty"`
	// Message is the ending's one sentence.
	Message string `json:"message,omitempty"`
}

type ActionReader func(Action) (Shown, bool)

type Body func(ctx context.Context, host Host, args []string) error

type Ceilings struct {
	CostUSD float64
	Hours   float64
}

type Command struct {
	Name string
	// Usage is the shape of the line after the command's name, for its help:
	// `[flags] -- <brief>`.
	Usage   string
	Summary string
	// Bind declares the command's own flags on fs and answers its body, which
	// reads them once the line has been parsed. It is called once per
	// invocation, so the values live in the closure and never in package
	// state. codeaf's shared flags (--dir, --max-cost, --max-hours, --json) are
	// already on fs; a command may not declare them again.
	Bind func(fs *flag.FlagSet) Body
}

type Crew struct {
	// Brain is the planning seat: the model the crew thinks hardest with.
	Brain string
	// Hands is the working seat: the model the crew does the work with.
	Hands string
	// Light is the cheap seat: summaries, and whatever needs no depth.
	Light string
	// Asked is the models the person asked this run to work with, in their
	// words' order, already resolved to ids. When it is set it is the working
	// seat in place of Hands, and a program may not swap any of it for another:
	// one it cannot use is a refusal, said before anything is spent.
	Asked []string
	// Effort is how hard the working seat is asked to think, a rung of
	// internal/effort: the one the conversation chose for this hand-off, or
	// the one written on the person's working seat. Empty leaves it to the
	// program's own default.
	Effort string
}

type Delegate struct {
	// Name is one lowercase word with single hyphens: the chat command
	// (`/<name> <brief>`), the command line's verb (`codeaf <name>`) and the
	// word every row says out loud.
	Name string
	// Summary is one sentence saying what it does, in a person's words: the
	// command row's tail and its line in `codeaf --help`.
	Summary string
	// Guide is the program describing itself to the model that hands it work:
	// what it is for, what its brief must hold, and what it needs of its
	// folder. The conversation prints it under the program's name, where the
	// model reads which programs it can name in `via`, and says nothing about
	// the program of its own.
	//
	// THE PROGRAM OWNS WHAT IS TRUE OF IT, AND CODEAF OWNS WHAT IS TRUE OF
	// EVERY PROGRAM. The folder a program works in, where its work is left and
	// the fact that nobody can be asked anything are codeaf's mechanics, stated
	// once beside the list; a guide that restated them would be one more copy
	// to drift. A second program brings its own guide, and the conversation's
	// page never has to learn its name.
	//
	// IT RIDES EVERY REQUEST OF EVERY TURN, because the paragraph is part of
	// the conversation's fixed prefix (internal/session's prefixbudget_test.go
	// weighs it), so it is one paragraph of at most [GuideMax] bytes.
	Guide string
	// Lands is LandsTree or LandsText. Empty reads as LandsTree, because a
	// program that edits a tree is the one this was built for.
	Lands string
	// PlainFolder is the flags the default command takes to work in a folder
	// with no git history, which codeaf puts on the line itself when the folder
	// it hands a tree program is one ([ChildArgs]). Empty is a program that
	// needs no flag for it, or cannot work there and says so in its ending.
	//
	// CODEAF DECIDES, BECAUSE CODEAF KNOWS. The folder is the one the task was
	// proposed on, and whether the program works there on a branch of its own
	// is read by codeaf before the program starts: a folder with no history, or
	// in a repository at the home folder, is worked in without git, and the
	// program is told so on its line. The program says only how it is told, so
	// codeaf never has to learn its flag's name.
	PlainFolder []string
	// Notes is the folder, relative to the folder it works in, where the
	// program keeps its own records while it works: its copy of the brief, its
	// checklist, its session's database and its whole conversation with its
	// model. Empty is a program that keeps nothing there.
	//
	// THE NOTES ARE MOVED OUT OF THE FOLDER. A program works in the person's
	// folder itself, so its records were left there when it ended — 46 files
	// for one senior-dev run, a database and the full conversation among them —
	// where a `git add -A` would commit them and the next run would read them
	// as its own. codeaf moves the folder this names into the run's own record
	// folder when the run ends, unless it was there before the run began.
	Notes string
	// CrewFlags is the flags the default command takes to use the models of
	// the conversation's crew ([Crew]), which codeaf puts on the line of every
	// run it starts from a conversation. Nil is a program that picks its own
	// models whatever the crew says.
	//
	// THE PERSON'S CREW IS THE DEFAULT, AND THE PROGRAM SAYS HOW IT HEARS IT.
	// A person who set which models do the thinking and the typing expects a
	// program they hand work to to use them too, rather than a list of its
	// own they never chose; codeaf knows the crew and nothing of the program's
	// flags, so the program turns the one into the other.
	CrewFlags func(Crew) []string
	// StageWords is the word a person reads for each stage the program reports
	// (its `stage` record), keyed by the stage's own name. The task's row and
	// the line over its conversation show the word, never the name: a program's
	// stages are its machinery — senior-dev's say `agent-runtime` and
	// `router-cancellation` — and this house draws no machinery vocabulary.
	// A stage with no word leaves the word shown before it standing, so a
	// program's inner phases need not each be named. Nil shows every stage by
	// its own name, for a program that has not said.
	StageWords map[string]string
	// Present is the program's own vocabulary for its task's page: it makes a
	// reader ([ActionReader]) that turns each line of its action log
	// ([Action]) — a stage, a step or its ending — into the words a person
	// reads, under the word for the step of its process it served ([Shown]),
	// and answers false for a line the page leaves out. Nil reads every line
	// plainly ([Delegate.Reader]).
	//
	// THE PROGRAM KNOWS WHAT ITS RECORDS MEAN, AND CODEAF KNOWS HOW A PAGE IS
	// DRAWN. A stage named `submit` with `patch_files` in its data is
	// senior-dev's machinery; that it reads `handed in its work · 4 files` is
	// senior-dev's to say, once, beside the words it gives its stages. The page
	// draws whatever a program says here, and the same step word leads the
	// task's row while the program is in that step.
	Present func() ActionReader
	// Default is the command a bare brief runs: `/<name> <brief>` in the chat
	// and `codeaf <name> <brief>` in a shell. It names one of Commands.
	Default string
	// Commands is the program's own verbs, each with its own flags. codeaf owns
	// the dispatch and the flags every program shares; the program owns these.
	Commands []Command
	// Page is the name of its page in the chat's manual (internal/manual/chat):
	// what it does, how to ask it, what a run costs, where the work lands. It is
	// compiled in with the rest of the manual, so the manual law's own gates
	// hold it to that.
	Page string
}

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

type Ending struct {
	// Status is StatusPass, StatusFail, StatusBudget or StatusCrashed.
	Status string
	// Message is one sentence saying why.
	Message string
	// CostUSD is the program's own reading of what it spent, zero for none.
	// codeaf's model API meters every call itself; this figure is kept for the
	// record and never trusted over that one.
	CostUSD float64
	// Reason is the longer reason, when there is one.
	Reason string
	// Claim is what the program's model said it did, and Observed is what the
	// program itself verified. They are two witnesses and stay two fields.
	Claim    string
	Observed string
	// Deliverable is the answer text of a program that lands text.
	Deliverable string
	// Extra is any other data the program wants on the record. It never
	// overrides a field above.
	Extra map[string]any
}

type Hello struct {
	Protocol int      `json:"protocol"`
	Delegate string   `json:"delegate"`
	Stages   []string `json:"stages,omitempty"`
}

type Host interface {
	// Workspace is the folder the program works in, absolute.
	Workspace() string
	// Ceilings are the limits codeaf set for this run. The program keeps them
	// itself so it can end cleanly, and codeaf enforces them whatever it does.
	Ceilings() Ceilings
	// Hello, Stage, Step and Terminal are the records (protocol.go). Hello
	// comes first and Terminal last, once.
	Hello(stages []string)
	Stage(stage StageRecord)
	Step(step StepRecord)
	Terminal(end Ending)
	// Models is this run's model API.
	Models() ModelAPI
}

type Invocation struct {
	Program Delegate
	Command Command
	// Workspace is --dir, absolute; the current folder when it was not given.
	Workspace string
	// Ceilings are --max-cost and --max-hours.
	Ceilings Ceilings
	// JSON is --json: the records on stdout instead of readable lines. A child
	// of a host always writes records, so for it the flag only says so aloud.
	JSON bool
	// Args is what the flags left: the brief's words.
	Args []string
	// Line is the arguments exactly as given after the name, so a host can hand
	// its child the same line it was handed.
	Line []string
	// ExplicitFlags records values the caller actually wrote, so a host can
	// distinguish a model pin from a program's default after parsing.
	ExplicitFlags map[string]string
	// contains filtered or unexported fields
}

type Launch struct {
	// Name is the program's name, for the errors this launch writes.
	Name string
	// Bin and Args are the process: codeaf's own executable and the program's
	// line ([ChildArgs]).
	Bin  string
	Args []string
	// Env is the child's whole environment ([ChildEnv]). Nil inherits this
	// process's, which only a test wants: it would hand a program every key.
	Env []string
	// Dir is the folder the process starts in.
	Dir string
	// StderrPath is the file the program's stderr is appended to. Empty
	// discards it, which no real caller wants: stderr is where a program says
	// why it could not start.
	StderrPath string
	// Grace overrides DefaultGrace, for a test that must not wait fifteen
	// seconds for a process that ignores SIGTERM.
	Grace time.Duration
	// Hold is the file the run's hold on its folder is taken on
	// (session.ProgramFolder.Hold), which the program's process is handed as
	// well ([HoldEnv]); nil hands it nothing.
	Hold *os.File
}

type ModelAPI struct {
	BaseURL string
	Token   string
}

type ProgramRecord struct {
	Name   string   `json:"name"`
	Stages []string `json:"stages,omitempty"`
	// CeilingUSD is the dollar ceiling the run handed the program, zero for
	// none. It is written here because the run works it out when it starts and
	// keeps it nowhere a page could read it afterwards, and a page that shows
	// the spend without the ceiling beside it leaves out half the reading.
	CeilingUSD float64 `json:"ceiling_usd,omitempty"`
	// StartedAt and EndedAt are the program's own clock: the instant codeaf
	// started its process and the instant that process was gone, written by
	// whoever ran it (the run's worker, or the shell verb). They are the ONE
	// record of how long the program itself ran, because every other pair of
	// times near a run brackets something else — the store is seeded before
	// the copy is cut, and the row settles after the landing. EndedAt is zero
	// while the program runs, and both are zero in a record written before
	// they existed, which a reader draws as no time rather than a wrong one.
	StartedAt time.Time `json:"started_at,omitzero"`
	EndedAt   time.Time `json:"ended_at,omitzero"`
	// Models and Effort are the models the program said it works on and how
	// hard it asks them to think ([StageRecord.Models]), so the task's page can
	// name what a run was launched on instead of leaving a person to remember
	// the flags. Both are empty until the program says, and stay empty for a
	// program that never does.
	Models []string `json:"models,omitempty"`
	Effort string   `json:"effort,omitempty"`
}

type Reading struct {
	Hello      *Hello
	LastStage  string
	LastStatus string
	Steps      int
	Terminal   *Terminal
	Ignored    int
}

type Result struct {
	Reading Reading
	// ExitCode is the process's own, -1 when it was ended by a signal or never
	// ran. The verdict is NOT read from it (§3): a program that failed its task
	// exits zero with a terminal saying `fail`.
	ExitCode int
	// Stopped is true when the caller's context ended the program: SIGTERM,
	// and SIGKILL when the grace passed. The reading may still hold a terminal
	// the program wrote inside the grace.
	Stopped bool
	// Killed is true when SIGKILL was needed.
	Killed bool
	// Elapsed is the process's wall time.
	Elapsed time.Duration
}

type RunFacts struct {
	// Plain says the folder has no git history.
	Plain bool
	// Crew is the conversation's crew; zero for a run no conversation started.
	Crew Crew
}

type Said struct {
	// Role is "system", "user" or "tool", as the program sent it.
	Role string `json:"role"`
	Tool string `json:"tool,omitempty"`
	Text string `json:"text"`
}

type Shown struct {
	At time.Time `json:"at"`
	// Step is the word for the part of the program's process the action
	// served, printed once at the head of each run of actions in it. Empty is
	// an action inside whatever step is under way.
	Step string `json:"step,omitempty"`
	// Text is the action in words: `read internal/auth/middleware.go`.
	Text string `json:"text"`
	// Outcome is how it came out, in a word or two: `passes`, `fails · exit 2`,
	// `4 files`. Empty when there is nothing to say.
	Outcome string `json:"outcome,omitempty"`
	// Detail is the whole of the step as the log kept it — the command or
	// argument, and what came back — which the page opens under the action's
	// one line when it is clicked. Empty for a line with nothing more to show.
	Detail string `json:"detail,omitempty"`
	// Lines says the action changed a file and counted how: Added and Removed
	// are its lines added and removed, drawn as `+N,-M` in the diff's own
	// colours beside the action. False for every other action.
	Lines   bool `json:"lines,omitempty"`
	Added   int  `json:"added,omitempty"`
	Removed int  `json:"removed,omitempty"`
	// Steer marks the program steering its own model — a nudge, a last turn, a
	// retry after a dropped call, a correction — rather than working through it.
	Steer bool `json:"steer,omitempty"`
	// Memory marks the action that says the program compacted its memory, and
	// Model names the model an action says it moved to, with Reason why. The
	// page reads both beside the conversation log, which says the same two
	// things from the model's side, so one compaction or one switch is drawn
	// once.
	Memory bool   `json:"memory,omitempty"`
	Model  string `json:"model,omitempty"`
	Reason string `json:"reason,omitempty"`
}

type Sink interface {
	// Hello is the program's first record, told once.
	Hello(h Hello)
	// Stage is a phase change: the live step, and one line of the program's
	// action log. Its data is already held to [StageDataCap].
	Stage(record StageRecord)
	// Step is one finished action: command and the observation head, both
	// already capped, and the tool, step and exit the program said.
	Step(record StepRecord)
	// Terminal is the result. It is told at most once; a second terminal on
	// the stream is ignored, because the contract says exactly one and the
	// first is the one the program wrote on purpose.
	Terminal(t Terminal)
}

type StageRecord struct {
	Stage  string `json:"stage"`
	Status string `json:"status"`
	// Data is a JSON object of at most [StageDataCap] bytes, or nothing. It is
	// OPTIONAL AND ADDITIVE: a reader of version 2 that predates it reads the
	// record without it.
	Data json.RawMessage `json:"data,omitempty"`
}

type StepRecord struct {
	// Command is the action on one line, `<tool>: <what it was about>`.
	Command string `json:"command"`
	// Observation is the head of what came back.
	Observation string `json:"observation,omitempty"`
	// Tool is the tool's own name.
	Tool string `json:"tool,omitempty"`
	// Step is the program's own id for the part of its process the action
	// served (senior-dev's are app.Steps). It is the program's word, drawn
	// through the program's own vocabulary ([Delegate.Present]).
	Step string `json:"step,omitempty"`
	// Exit is a command's exit code, present only for an action that ran a
	// command and learned how it exited — which is why it is a pointer: a
	// command that exited 0 and an action that ran none are two facts.
	Exit *int `json:"exit,omitempty"`
	// Added and Removed are the lines an action that changed a file added and
	// removed, present only when the program counted them.
	Added   *int `json:"added,omitempty"`
	Removed *int `json:"removed,omitempty"`
}

type Terminal struct {
	Status  string                     `json:"status"`
	Message string                     `json:"message"`
	Data    map[string]json.RawMessage `json:"data"`
}

type ToolUse struct {
	Name string `json:"name"`
	Args string `json:"args,omitempty"`
}

type Turn struct {
	Seq int `json:"seq"`
	// Thread tells conversations apart when a program holds more than one at
	// once (a summary of its own history, a helper agent): the call's cache key
	// or its own id, MainThread when it gave none.
	Thread  string    `json:"thread,omitempty"`
	Started time.Time `json:"started"`
	Ended   time.Time `json:"ended,omitempty"`
	// Model is the model the program asked for; Served is the one that
	// answered, when codeaf's router answered with another.
	Model  string `json:"model"`
	Served string `json:"served,omitempty"`
	// Sent is what the program sent that the thread's previous call did not:
	// its brief first, then its tools' results and its own words. Restarted is
	// true when the program rewrote its history instead of adding to it (a
	// compaction), so Sent is then everything it sent.
	Sent      []Said `json:"sent,omitempty"`
	Restarted bool   `json:"restarted,omitempty"`
	// Reply is the model's text, and Calls the tools it asked the program to run.
	Reply string    `json:"reply,omitempty"`
	Calls []ToolUse `json:"calls,omitempty"`
	// The call's size and price, as the funnel metered them.
	TokensIn  int     `json:"tokens_in,omitempty"`
	TokensOut int     `json:"tokens_out,omitempty"`
	Cached    int     `json:"cached,omitempty"`
	CostUSD   float64 `json:"cost_usd,omitempty"`
	// Refused is codeaf's own refusal — the ceiling, a run that has ended — set
	// when the call never reached a model. Failed is the model's side failing.
	Refused string `json:"refused,omitempty"`
	Failed  string `json:"failed,omitempty"`
}