adapter

type Adapter interface {
	// Name is the adapter's identifier, one per CLI ("claude", "kimi",
	// "fake"): the name a runner's advertisement pairs it with (§5.1)
	// and the agents table keys on (§11).
	Name() string

	// Command builds the headless command for job, to run in workdir.
	// resumeSessionID is empty for a fresh run; otherwise the command
	// resumes that harness session with its context kept (§5.3).
	//
	// The environment is the adapter's to build, under one policy: the
	// worker's own login state is its business — the ambient
	// environment, the vendor CLI's tokens and configuration, are what
	// it needs to run (§5.3) — but the adapter
	// must not add brigada's own secrets to it. The runner enforces the
	// line from its side: whatever variables its git credentials ride
	// (Config.GitEnv) are stripped from the command's environment
	// before it starts, whether the adapter put them there or they came
	// from the ambient set.
	Command(job Job, workdir, resumeSessionID string) (*exec.Cmd, error)

	// ParseEvent parses one line of the CLI's JSON event stream. false
	// means the line is not an event the runner tracks — a banner, a
	// blank line, anything the CLI prints that is not one of its
	// events. Only the CLI's own error event is an error: a stray line
	// on its stdout must not fail an otherwise good run.
	ParseEvent(line []byte) (Event, bool)

	// ParseErrEvent parses one line of the CLI's stderr, which rides
	// the same event pipeline as stdout: some failures print only there
	// — a resume-not-found before any JSON, a limit or an auth message
	// — and must become error events all the same. false means the line
	// carries nothing to act on, like a progress note or a warning.
	ParseErrEvent(line []byte) (Event, bool)

	// ResultText returns the worker's final message from the events it
	// parsed: the text the result contract (§5.4) is read from.
	ResultText(events []Event) string

	// ProbeCommand builds the cheap probe of the CLI for the
	// broken-agent recovery (§8 "Health"): a command bound to ctx — a
	// version or status check — that exits 0 when the CLI answers. The
	// runner runs it against an agent broken by repeated failures with a
	// short deadline; a passing probe clears the agent, a failing one
	// backs the next probe off. The command is built with ctx so the
	// deadline kills it: a hung CLI reads as a failing probe, never a
	// stuck runner.
	ProbeCommand(ctx context.Context) *exec.Cmd
}

type ErrorKind string

type Event struct {
	Usage *Usage
	Kind  EventKind
	Time  time.Time // when the adapter parsed it; the runner's clock
	Text  string
	// Args is a tool call's arguments as the CLI's stream carried them,
	// empty for a CLI that prints none (or a kind that has none): with
	// Text it names the call, so the runner's loop watch (§5.6) tells
	// two calls of one tool apart.
	Args string
	// SessionID may accompany any kind when the CLI puts its id in
	// every envelope (including an error before a session-start event).
	SessionID string
	ErrorKind ErrorKind
	// LimitUntil is a limit error's reset time, RFC3339, when the CLI's
	// text carried one machine-readably; empty when unknown (§4.4).
	LimitUntil string
	// Final marks an error event as the CLI's closing verdict on the run
	// (codex's turn.failed): it names the failure over any earlier error
	// event of the same stream.
	Final bool
	// Notice marks an error event that is only a warning while the
	// turn has not started (codex's startup notices): the runner, which
	// tracks each job's turn through TurnMarker, downgrades it to a
	// warning until then.
	Notice bool
}

type EventKind string

type Interactive interface {
	// AttachCommand builds the interactive command for job, to run in
	// workdir on the caller's terminal: the adapter wires none of the
	// process's streams — stdin is the user's, and the caller connects
	// it. The opening prompt (job.Prompt) reaches the CLI the way it
	// takes one interactively; the MCP config and the model ride as in
	// Command. resumeSessionID is the key's current harness session,
	// empty when the foreman has never run; newSessionID is the id the
	// client generated for the session this chat forks into — the CLI
	// names it itself, so the client knows what to write back on detach
	// (§4.2) without reading the CLI's own files.
	AttachCommand(job Job, workdir, resumeSessionID, newSessionID string) (*exec.Cmd, error)
}

type Job struct {
	Prompt string
	Model  string
	// Review selects the harness's read-only review policy, where supported.
	Review bool
	// Effort is the reasoning-effort level for the run, one of the harness's
	// accepted levels (ValidateEffort); empty adds nothing. An adapter whose
	// CLI has no effort control refuses a non-empty one.
	Effort string
	// MCPConfig names the harness's MCP config for the run: a config
	// file's path, offered to the CLI through its own flag. It is where
	// the `brigada mcp` bridge (§12.2) will hand the foreman's harness
	// brigada's tool server; empty — every job today — adds nothing.
	MCPConfig string
	// ReadDirs names absolute directories outside the worktree the
	// worker must be able to read but never write: the extra
	// repositories' checkouts (§5.8). The adapter opens them to the
	// worker as its CLI allows, and the checkouts' read-only files
	// refuse writes all the same; codex's and dsh's sandboxes already
	// allow reads outside the workspace, and kimi has no directory
	// flag, so those adapters ignore it. Empty adds nothing.
	ReadDirs []string
	// Tools is the worker's tool scope in Claude's spelling
	// (`Bash(go test:*)`), for a harness that maps it onto its own
	// permission rules; nil is the Go default scope. Claude takes its
	// scope from its adapter's config instead and ignores this.
	Tools []string
	// StatusLine is a shell command whose one line of output an
	// interactive session shows in its status bar, re-run every few
	// seconds (§10): the attach sets it to `brigada status --line`, so
	// the user sees what the workers are doing while they chat with the
	// foreman. Only AttachCommand reads it, and an adapter whose CLI has
	// no status bar ignores it; empty adds nothing.
	StatusLine string
}

type SessionWriteback interface {
	// WritebackSessionID names the session id an ended attach leaves the
	// key on, bound to ctx for the discovery a fresh chat needs.
	WritebackSessionID(ctx context.Context, workdir, resumeSessionID string) (string, error)
}

type TurnMarker interface {
	// StartsTurn reports whether the stdout line opens the turn.
	StartsTurn(line []byte) bool
}

type Usage struct {
	InputTokens       *int64   `json:"input_tokens,omitempty"`
	OutputTokens      *int64   `json:"output_tokens,omitempty"`
	CachedInputTokens *int64   `json:"cached_input_tokens,omitempty"`
	ReasoningTokens   *int64   `json:"reasoning_tokens,omitempty"`
	CostUSD           *float64 `json:"cost_usd,omitempty"`
	ModelCalls        *int64   `json:"model_calls,omitempty"`
	// CostCumulative marks CostUSD as the running total of a resumable
	// session, not this invocation's own spend; the engine turns it into
	// a per-job delta. Unset for adapters whose cost is per invocation.
	CostCumulative bool `json:"cost_cumulative,omitempty"`
}