types

type AgentReviewer interface {
	// Name returns the agent's registry key (e.g., "claude-code", "codex",
	// "gemini"). Stable identifier; do not change after release without
	// updating settings migration.
	Name() string

	// Start spawns the agent with the given run configuration. The returned
	// Process exposes streaming events via Events() and a Wait() that returns
	// when the process exits.
	//
	// Implementations MUST set the ENTIRE_REVIEW_* env vars on the spawned
	// child process (see cmd/entire/cli/review/env.go) so the agent's
	// lifecycle hooks adopt the session as a review session.
	//
	// Errors from Start indicate failure to construct or launch the process
	// (e.g., binary not on PATH at exec.Cmd.Start time, invalid argv). Once
	// Start returns nil, errors during the run flow through Process.Events
	// (as RunError) and Process.Wait.
	Start(ctx context.Context, run RunConfig) (Process, error)
}

type AgentRun struct {
	Name   string
	Status AgentStatus
	Tokens Tokens

	// Buffer accumulates the full event log per agent for post-hoc
	// rendering (DumpSink, TUI dump, synthesis).
	//
	// TODO(memory): At review lengths typical today (~100s of events,
	// ~few KB) this is fine. If profiling shows reviews regularly
	// exceed ~10MB of buffered events or ~10000 events, swap to a
	// token-budgeted ring or stream events to sinks incrementally
	// and drop the buffer.
	Buffer []Event

	StartedAt time.Time
	Duration  time.Duration
	Err       error
}

type AgentStatus int

type AssistantText struct {
	Text string
}

type Event interface {
	// contains filtered or unexported methods
}

type Finished struct {
	Success bool
}

type Process interface {
	// Events returns a channel that emits structured events as the agent
	// produces output. The channel is closed when the process exits — cleanly,
	// with error, or via context cancellation. Consumers should range over it.
	Events() <-chan Event

	// Wait blocks until the process exits and returns:
	//   - nil on clean exit (exit code 0)
	//   - ctx.Err() on cancellation
	//   - an error wrapping *exec.ExitError on non-zero exit
	//   - other error types for I/O or pipe failures
	//
	// Wait must be called exactly once per Process. It is safe to call Wait
	// after the Events channel has closed. Consumers must drain Events until
	// close before calling Wait; otherwise an implementation that forwards
	// parsed events from another goroutine may block while sending.
	Wait() error
}

type ProcessError struct {
	AgentName string
	Err       error
	Stderr    string
}

type ReviewerTemplate struct {
	// AgentName is returned by Name(). Stable identifier per agent.
	AgentName string

	// BuildCmd constructs the *exec.Cmd to spawn the agent process,
	// including argv, stdin (if any), and ENTIRE_REVIEW_* env vars.
	// The command MUST NOT have started yet; the template will call Start.
	BuildCmd func(ctx context.Context, cfg RunConfig) *exec.Cmd

	// Parser converts the agent's stdout stream into a sequence of Events.
	// The returned channel must close when stdout closes. Implementations
	// must emit Started first, Finished{Success: ...} or RunError last,
	// and check scanner.Err() before emitting Finished{Success: true}.
	Parser func(stdout io.Reader) <-chan Event
}

type RunConfig struct {
	// PromptOverride, when non-empty, is the exact prompt sent to the agent.
	// It preserves settings.ReviewConfig.Prompt's existing verbatim-override
	// contract: configured skills are still recorded as structured metadata,
	// but they are not prepended to the prompt text.
	PromptOverride string

	// Skills are skill invocation strings passed to the agent verbatim.
	Skills []string

	// AlwaysPrompt is the per-agent always-prompt configured in settings.
	// Concatenated with Skills + PerRunPrompt + a scope clause to form the
	// composed agent prompt.
	AlwaysPrompt string

	// PerRunPrompt is optional textarea input from a single invocation.
	PerRunPrompt string

	// ScopeBaseRef is the git ref the review is scoped against (mainline by
	// default — origin/HEAD → origin/main → origin/master → main → master —
	// or whatever `--base` overrides it to). Used to compose the scope clause
	// and as the base for `git diff` operations the agent may perform.
	ScopeBaseRef string

	// CheckpointContext is best-effort context derived from checkpoints in the
	// branch review scope. It is appended to generated prompts so every agent
	// can use checkpoint IDs, file summaries, and transcript lookup commands
	// while reviewing. PromptOverride remains verbatim and does not receive
	// this context.
	CheckpointContext string

	// StartingSHA is HEAD at invocation time, propagated to the lifecycle
	// hook via ENTIRE_REVIEW_STARTING_SHA so checkpoint metadata records
	// the commit that was reviewed.
	StartingSHA string

	// EnrichSummary optionally updates the completed run summary before sinks
	// receive RunFinished. It is used for post-process data such as token
	// totals that are only available after agent lifecycle hooks flush state.
	//
	// Timing: called on the orchestrator goroutine after every per-agent
	// goroutine has exited, immediately before Sink.RunFinished is fanned
	// out. The full RunSummary is consumed; any field the callback
	// returns reaches the sinks.
	//
	// Contract: nil is valid (no enrichment). The callback must not block on
	// a sink (deadlock), must not panic (no orchestrator-side recovery), and
	// should honor ctx for cancellation when doing I/O.
	EnrichSummary func(context.Context, RunSummary) RunSummary

	// EnrichAgentRun optionally updates a single agent run after that agent
	// exits, before the overall multi-agent run has necessarily completed.
	//
	// Timing: called on the per-agent forwarding goroutine in RunMulti,
	// after proc.Wait() returns and after any synthetic RunError is queued.
	// Only the returned Tokens field is consumed (emitted as a synthetic
	// Tokens event so sinks see live token totals before sibling agents
	// finish); other field changes are discarded. Returning Tokens{In:0,
	// Out:0} suppresses emission entirely.
	//
	// Contract: nil is valid (no enrichment). The callback must be
	// goroutine-safe across N agents and must not block on a sink. A panic
	// is recovered; no synthetic Tokens event is emitted on panic.
	EnrichAgentRun func(context.Context, AgentRun) AgentRun
}

type RunError struct {
	Err error
}

type RunSummary struct {
	StartedAt  time.Time
	FinishedAt time.Time

	// Cancelled is true iff the orchestrator's run context was cancelled
	// during the run (or before it started). For single-agent runs this
	// is equivalent to AgentRuns[0].Status == AgentStatusCancelled. Under
	// multi-agent runs (CU8), Cancelled means "the run as a whole was
	// cancelled" — individual AgentRuns may have other terminal states
	// if they finished before cancellation propagated.
	Cancelled bool

	AgentRuns []AgentRun
}

type Sink interface {
	// AgentEvent is called for every event emitted by an agent's
	// process during the run. Events are delivered in-order within a
	// single agent; across agents (CU8 multi-agent) the orchestrator
	// serializes calls so sinks see one event at a time.
	AgentEvent(agent string, ev Event)

	// RunFinished is called once when the run terminates (cleanly,
	// failed, or cancelled). Sinks that only act post-run (DumpSink,
	// synthesis sink) implement only this method (with a no-op
	// AgentEvent).
	RunFinished(summary RunSummary)
}

type Started struct{}

type Tokens struct {
	In  int
	Out int
}

type ToolCall struct {
	Name string
	Args string
}