factory

type Bootstrap struct {
	Prompts []GeneratedPrompt
	// Summary is the agent's account of the repository and its choices.
	Summary string
	// Dropped counts prompts in the answer that were unusable: a bad or
	// repeated name, an empty or oversized body, or past the limit.
	Dropped int
	// CostUSD is what the run cost, as claude reported it.
	CostUSD float64
}

type BootstrapOptions struct {
	Exec       sidecar.Execer
	WriteFile  sidecar.FileWriter
	Entry      *sidecar.PoolEntry
	Credential claudecode.Credential
	BaseURL    string
	Model      string        // optional; Claude Code's default when empty
	Timeout    time.Duration // DefaultBootstrapTimeout when zero
	// Commands are the project's validation commands, which run on every
	// change, so the reviews need not check what they already enforce.
	Commands []config.Command
	// History is the review comments the team left on the repository's pull
	// requests. Nil or empty, the prompts are written from the code alone.
	History *reviewhistory.History
	// OnActivity is called with each tool call and piece of text as claude
	// makes it, since reading a large project takes many minutes.
	OnActivity func(claudecode.Activity)
}

type Change struct {
	// Fingerprint identifies the content of the change, so a round in which
	// the implementer changed nothing can be detected.
	Fingerprint string
	// Stat is git's one-line summary, such as "3 files changed, 40 insertions(+)".
	Stat string
}

type Check struct {
	Name      string
	Kind      Kind
	Status    Status
	SidecarID string
	Duration  time.Duration
	// Feedback is what the implementer is told when the check failed.
	Feedback string
	// Error is why the check could not run, for StatusErrored.
	Error string
	// Findings are a review's findings, kept as data for display.
	Findings []review.Finding
	// Prose is a review's prose alongside its findings, kept for display.
	Prose string
	// ExitCode and Output are a validation command's exit code and the tail of
	// its output, kept for display and the run's log.
	ExitCode int
	Output   string
}

type Continuation struct {
	From Record
	// Guidance is what the developer adds to the original request, or "".
	// Without it the run checks the work as it is before the implementer's
	// first turn, so that turn is sent what failed.
	Guidance string
}

type Event struct {
	Kind   EventKind
	Round  int
	Prompt string
	Turn   Turn
	Change Change
	Checks []Check
}

type EventKind int

type GeneratedPrompt struct {
	Name string
	Body string
}

type Handoff struct {
	Prompt string
	// SpecOrigin is the path Prompt was read from, when it named a file rather
	// than being literal text.
	SpecOrigin string
	Diff       []byte
}

type Implementer struct {
	Exec         sidecar.Execer
	Entry        *sidecar.PoolEntry
	Credential   claudecode.Credential
	BaseURL      string
	Model        string
	Timeout      time.Duration
	Instructions string
	OnActivity   func(claudecode.Activity)
	// contains filtered or unexported fields
}

type Kind string

type Loop struct {
	// Attempts is the most rounds to check. Each round after the first starts
	// with an implementer turn fixing the previous round's failures.
	Attempts int
	// CheckFirst checks the work already there before the implementer's first
	// turn, which is then sent the prompt with what failed. Work that passes
	// as it is ends the loop without a turn. The first round counts as one of
	// the attempts.
	CheckFirst bool
	OnEvent    func(Event)
}

type Outcome struct {
	Result Result
	// Rounds is how many rounds were checked.
	Rounds int
	Change Change
	// Checks are the last round's checks.
	Checks []Check
}

type PromptSource struct {
	Prompts []review.Prompt
	// Owner, Repo and Commit make a link to a prompt's file. Without all three
	// the checks are listed without links.
	Owner, Repo, Commit string
	// Dir is the prompts' directory relative to the project root, "" for the
	// default.
	Dir string
}

type Record struct {
	RunID string `json:"run_id"`
	// Prompt is the original request. A continued run keeps it, so a chain of
	// runs is all one change.
	Prompt string `json:"prompt"`
	// SpecOrigin is the path Prompt was read from, when it named a file rather
	// than being literal text. A continued run keeps it along with Prompt.
	SpecOrigin string `json:"spec_origin,omitempty"`
	Worktree   string `json:"worktree"`
	Branch     string `json:"branch"`
	Baseline   string `json:"baseline"`
	Head       string `json:"head"`
	// Brief is what a run continuing this one tells its implementer about the
	// work, when whoever made the record knows better than the default: that
	// an earlier session started it and did not finish.
	Brief string `json:"brief,omitempty"`
	// NeedsWork means a run continuing this one refuses to start until there
	// is a change in the worktree to refine.
	NeedsWork bool `json:"needs_work,omitempty"`
	// ContinuesRunID is the run this one continued, if it did.
	ContinuesRunID string `json:"continues_run_id,omitempty"`
	// Result and Rounds are how the run ended, once it has.
	Result Result `json:"result,omitempty"`
	Rounds int    `json:"rounds,omitempty"`
	// Remote is where this run is happening, when it is on a per-run sidecar
	// rather than local. A local run never sets it.
	Remote *RemoteRun `json:"remote,omitempty"`
}

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

type RemoteRun struct {
	SidecarID string `json:"sidecar_id"`
	CommandID string `json:"command_id"`
	HostRepo  string `json:"host_repo"`
}

type Report struct {
	RunID string
	// Worktree is the run's worktree. It is kept once the implementer has
	// started, and removed, with its branch, if the run failed before that.
	Worktree Worktree
	// Started reports whether the implementer started.
	Started bool
	// Committed reports whether the work was committed on Worktree.Branch.
	Committed bool
	// Stat is the committed work's diff stat against Worktree.Baseline, "" for
	// no changes. StatErr says why it could not be worked out.
	Stat    string
	StatErr error
	// WorktreeRemoved reports that the run ended before the implementer started
	// and its worktree, holding nothing, was removed.
	WorktreeRemoved bool
	Outcome         Outcome
	// KeptSidecars are the sidecars left running with KeepSidecars.
	KeptSidecars []string
	// Log is the path of the run's log, if it kept one.
	Log string
}

type Result string

type ReviewerTree struct {
	Round     int
	SidecarID string
	// Fingerprint is the reviewer's change; Want is the implementer's.
	Fingerprint string
	Want        string
	// Err is why the reviewer's fingerprint could not be read.
	Err error
}

type RunOptions struct {
	// Root is the developer's repository root. The run's worktree is made from
	// it, and the pool's state is kept in it, where the dashboard finds it.
	Root string
	// Prompt is what the implementer is asked to do. A continued run makes its
	// own from Continue, and ignores this.
	Prompt string
	// SpecOrigin is the path Prompt was read from, when it named a file rather
	// than being literal text. A continued run keeps the earlier run's
	// instead, and ignores this.
	SpecOrigin string
	// Continue, when set, picks up the work of an earlier run instead of
	// starting from the developer's files.
	Continue *Continuation
	// Attempts is the most rounds to check. A continued run that checks the
	// work first counts that round as one of them.
	Attempts int
	// Reviewers is how many reviewer sidecars to run; see ReviewerCount.
	Reviewers int
	Prompts   []review.Prompt
	Commands  []config.Command

	Client *circleci.Client
	OrgID  string
	Image  string
	// KeepSidecars leaves the sidecars running when the run ends.
	KeepSidecars bool

	Credential              claudecode.Credential
	BaseURL                 string
	Model                   string
	ImplementerInstructions string
	ImplementTimeout        time.Duration
	ReviewTimeout           time.Duration

	// Exec runs commands on the sidecars; sidecar.ClientExec when nil.
	Exec sidecar.Execer

	// Log is where to keep a plain-text log of the run, with its full context
	// whatever a display of it filters out: a path, LogDefault for
	// DefaultLogPath, or "" for none.
	Log string
	// Verbose adds the review prompts, the output of commands that passed,
	// and a check each round that every reviewer has the implementer's change
	// to the log. It implies a log.
	Verbose bool

	// Status reports progress, warnings included. It must be set.
	Status iostream.StatusFunc
	// The rest report what the run is doing, and may be nil. OnStart is
	// called once the run's worktree exists.
	OnStart    func(runID string, wt Worktree)
	OnEvent    func(Event)
	OnActivity func(claudecode.Activity)
	// Warm is sidecars made ahead of a continued run, which it uses instead
	// of making its own when they are for the run it continues. The run owns
	// them from then on.
	Warm             *WarmPool
	OnReviewProgress func(review.ProgressEvent)
	OnCheckStart     func(name string)
	OnCheck          func(Check)
}

type Sidecars struct {
	Exec        sidecar.Execer
	Implementer *Implementer
	// Acquire and Release hand out reviewer sidecars: the pool's own, with the
	// implementer's member already checked out.
	Acquire func(context.Context) (*sidecar.PoolEntry, error)
	Release func(*sidecar.PoolEntry)
	// Reviewers are the members the implementer's tree is relayed to. When
	// WaitReviewers is set, it supplies them instead, once the first round's
	// checks need them.
	Reviewers []*sidecar.PoolEntry
	// WaitReviewers waits for the rest of the pool and returns its members
	// other than the implementer. The implementer starts as soon as its own
	// member is ready; nothing needs the reviewers until there is work to
	// check, and by then they have usually been ready a while.
	WaitReviewers func(context.Context) ([]*sidecar.PoolEntry, error)
	Relay         *Relay
	// Request is the original change the implementer was asked to make. It is
	// included in every review, including rounds where the implementer is sent
	// only feedback from the preceding checks.
	Request  string
	Prompts  []review.Prompt
	Review   review.Options
	Commands []config.Command
	// OnCheckStart is called with a validation command's name as it starts.
	OnCheckStart func(name string)
	// OnCheck is called as each validation command finishes. Reviews report
	// their progress through Review.ProgressFn.
	OnCheck func(Check)
	// BeforeValidate, when set, is waited for before the validation commands
	// run, such as commands warming up the implementer's sidecar that must
	// not overlap them.
	BeforeValidate func(context.Context) error
	// OnReviewerTree, when set, is called each round for every reviewer, in
	// Reviewers order, with whether the change it is about to review is the
	// implementer's. It is a canary for the relay; a mismatch does not stop the
	// round.
	OnReviewerTree func(ReviewerTree)
	// contains filtered or unexported fields
}

type Status string

type Steps interface {
	// Implement runs one implementer turn with prompt.
	Implement(ctx context.Context, prompt string) (Turn, error)
	// Collect describes the implementer's work so far.
	Collect(ctx context.Context) (Change, error)
	// Check reviews and validates the implementer's work so far.
	Check(ctx context.Context, round int) ([]Check, error)
}

type Turn struct {
	Summary  string
	Duration time.Duration
	CostUSD  float64
}

type WarmPool struct {
	// RunID is the started run the sidecars are for.
	RunID string
	// Reviewers, OrgID and Image are what the sidecars were made with. A run
	// that wants other ones does not use them.
	Reviewers    int
	OrgID, Image string
	// contains filtered or unexported fields
}

type Worktree struct {
	Path   string
	Branch string
	// Baseline is the commit the branch starts from: the developer's HEAD, or
	// their uncommitted work committed on top of it.
	Baseline string
	// Head is the developer's HEAD when the run started. It differs from
	// Baseline when their uncommitted work was committed as the baseline.
	Head string
}