types

type AgentReviewer interface {
	// Name returns the agent's registry key (e.g., "claude-code", "codex",
	// "gemini-cli"). 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 (typically the
	// closest ancestor branch). 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
}

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
}