agent

type Accounting struct {
	Usage         Usage          `json:"usage"`
	Attempts      []UsageAttempt `json:"attempts"`
	ChargedTokens int            `json:"charged_tokens"`
}

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

type Backend interface {
	Name() string
	Run(context.Context, Request) (Result, error)
}

type Budgets struct {
	WallClock           time.Duration `json:"wall_clock"`
	MaxCalls            int           `json:"max_calls"`
	MaxTokens           int           `json:"max_tokens"`
	MaxProviderAttempts int           `json:"max_provider_attempts"`
	MaxRepairAttempts   int           `json:"max_repair_attempts"`
	// StallTimeout ends an attempt that has no model request open and no
	// tool running and has made no progress for this long; ToolTimeout ends
	// one whose single tool runs longer. Zero disables each. An attempt ended
	// either way is retried once, then the run fails with ReasonStalled.
	StallTimeout time.Duration `json:"stall_timeout,omitempty"`
	ToolTimeout  time.Duration `json:"tool_timeout,omitempty"`
}

type CompleteRequest struct {
	System, User string
	// Schema is the reply's JSON Schema.
	Schema []byte
	// MaxOutputTokens caps the reply; zero is the backend's default.
	MaxOutputTokens int
}

type Completer interface {
	// Complete makes the call. On an error the Completion still carries the
	// model and the usage the provider reported, when the call reached it, so
	// the caller can account for what it may have been billed.
	Complete(context.Context, CompleteRequest) (Completion, error)
}

type Completion struct {
	// Document is the reply object, expected to match the request's Schema.
	Document []byte
	// Model is the model the provider reported, else the configured one.
	Model string
	Usage Usage
	// Rejections counts the replies the harness rejected against the schema
	// (claude), and RejectionDetail is a bounded copy of the last one's
	// reason, which describes the reply's shape, for the private log.
	Rejections      int
	RejectionDetail string
}

type ConcurrentCaller interface {
	ConcurrentCalls() bool
}

type Endpoint struct {
	BaseURL string
	Key     string
}

type Event struct {
	Kind      string `json:"kind"`
	ElapsedMS int64  `json:"elapsed_ms"`
	ID        string `json:"id,omitempty"`
	Tool      string `json:"tool,omitempty"`
	Path      string `json:"path,omitempty"`
	Offset    int    `json:"offset,omitempty"`
	Limit     int    `json:"limit,omitempty"`
	Bytes     int    `json:"bytes,omitempty"`
	Status    string `json:"status,omitempty"`
	// FromProvider marks an error event whose Status was read from the
	// provider's HTTP status or a structured field of its response, not
	// guessed from free text.
	FromProvider bool `json:"from_provider,omitempty"`
	Input        int  `json:"input_tokens,omitempty"`
	Output       int  `json:"output_tokens,omitempty"`
	CacheRead    int  `json:"cache_read_tokens,omitempty"`
	CacheCreate  int  `json:"cache_creation_tokens,omitempty"`
}

type Fixer interface {
	Fix(context.Context, Request) (Result, error)
}

type Framing int

type Generator struct {
	Backend Backend
	Prompts Prompts
	// Validator checks and completes what the model returns.
	Validator *review.DocumentValidator
	// Redactor masks the secrets the model writes into identifiers; nil loads
	// the default rules for every run.
	Redactor *bundle.Redactor
	// Logger receives progress and failures; nil logs nothing.
	Logger *slog.Logger
	// RetryDelay is the wait before provider attempt n+1 after attempt n
	// (counting from 0) failed; nil waits 1<<min(n,4) seconds.
	RetryDelay func(attempt int) time.Duration
}

type IdentifierRedaction struct {
	Masked       int `json:"masked"`
	MaskedClosed int `json:"masked_closed"`
}

type Outcome struct {
	Accounting     *Accounting `json:"accounting,omitempty"`
	Model          string      `json:"model,omitempty"`
	SchemaRevision string      `json:"schema_revision"`
	// Reason is why the run failed, one of the fixed reasons (ReasonValidationRejected
	// and the budget and provider reasons). Empty means the run produced a
	// valid document.
	Reason   string `json:"reason,omitempty"`
	Findings string `json:"findings,omitempty"`
	// RejectedDocument is the last document the validator rejected when the
	// run failed, kept next to the findings so a maintainer can read both.
	RejectedDocument           json.RawMessage `json:"rejected_document,omitempty"`
	Diagnostics                []Event         `json:"diagnostics,omitempty"`
	Calls                      int             `json:"calls"`
	Tokens                     int             `json:"tokens"`
	ProviderAttempts           int             `json:"provider_attempts"`
	ErroredAttempts            int             `json:"errored_attempts"`
	ValidationRepairs          int             `json:"validation_repairs"`
	Usage                      Usage           `json:"usage"`
	StructuredOutputRejections int             `json:"structured_output_rejections"`
	// OutputMaskedSpans counts the secret spans RedactOutput masked in the
	// returned output, apart from the bundle's own count.
	OutputMaskedSpans int `json:"output_masked_spans"`
	// IdentifierRedaction is what the loop's identifier pass masked over every
	// pass of the run. The loop sets it on every outcome it builds; nil is a
	// producer that predates the pass.
	IdentifierRedaction *IdentifierRedaction `json:"identifier_redaction,omitempty"`
	// SessionID is the backend session of the last successful call, set only
	// when the run asked to persist its session (Run.PersistSession). It is
	// not part of the diagnostics.
	SessionID string `json:"-"`
	// Sessions is every session id the run's calls reported, retries and
	// repairs included, so a host can delete the CLI's files of the ones it
	// does not keep. Set only with Run.PersistSession.
	Sessions []string `json:"-"`
}

type Prompt struct {
	// Version and Digest identify the instructions in the document's generator
	// block; Digest is the sha256 of Body. The JSON tags are the hosted run
	// header's wire format.
	Version string `json:"version"`
	Body    string `json:"body"`
	Digest  string `json:"digest"`
	// Repair and RepairEnding replace RepairText(backend) when they are not
	// empty: the text that opens and closes a validation repair prompt. A host
	// whose instructions name tools differently sets both. RepairEnding takes
	// two %d verbs, the attempt number and the attempt limit. They
	// are not part of the wire format.
	Repair       string `json:"-"`
	RepairEnding string `json:"-"`
}

type Prompts interface {
	// Instructions returns the review instructions for a backend. The loop
	// ignores Version and Digest: the host records the version in the
	// document's generator.prompt_version and keeps the digest. The loop
	// appends the offered tile guidance (tilecatalogue.Instructions) to the
	// body itself.
	Instructions(ctx context.Context, backend string) (Prompt, error)
}

type RejectedError struct {
	// Status is the fixed word of the refusal.
	Status string
	Err    error
}

type Request struct {
	Logger            *slog.Logger
	Directory, Prompt string
	Schema            []byte
	// MaxCalls and MaxTokens bound the run; zero is no limit (Exceeds).
	MaxCalls, MaxTokens int
	// Endpoint replaces the backend's default provider address and key. Nil
	// leaves the backend's own.
	Endpoint *Endpoint
	// Activity receives the backend's progress, tools and turns for the
	// stall watchdog; nil when the run has none.
	Activity *Activity
	// Task marks a generic task (Generator.RunTask) rather than a review, so
	// the backend frames it without pull request review wording.
	Task bool
	// Scratch, for a Fixer, is a private directory the agent's commands may
	// write to besides Directory: their TMPDIR. Empty leaves the backend's
	// own temporary directory.
	Scratch string
	// Transcript, when set, receives each step of the run as the person
	// watching sees it (see TranscriptEntry); nil when none is kept.
	Transcript func(TranscriptEntry)
	// Usage, when set, receives the run's usage so far each time a model call
	// reports some, as the attempts Result.UsageAttempts will hold: a call
	// still running is Unreported with what it reported so far. Each report
	// replaces the previous one. It is called on the run's goroutine; a
	// backend that reports usage only at the end of a run never calls it.
	Usage func([]UsageAttempt)
	// Stage and Pass name a task's call (Generator.RunTask): the task's
	// Label, empty for a one-pass review, and 1 for its first pass, more for
	// each validation repair. Zero outside a task.
	Stage string
	Pass  int
	// PersistSession keeps the CLI's session instead of discarding it, so the
	// result's SessionID can be resumed later. Only a local Claude Code or
	// Codex run supports it; the hosted profiles, Cursor and the Anthropic API
	// backend refuse it. A ResumeSession implies it.
	PersistSession bool
	// ResumeSession is the session (Claude Code) or thread (Codex) id to
	// continue, a canonical UUID. The session is kept, as with PersistSession.
	// Run with the same Directory as the session it continues: Claude Code
	// stores sessions per working directory and Codex filters by it too. A
	// resumed Claude Code session keeps the system prompt it recorded, so put
	// per-turn framing in the user prompt.
	ResumeSession string
	// ForkSession, with ResumeSession, continues in a new session and leaves
	// the original untouched; Result.SessionID is then the new one. Without
	// ResumeSession it is an error.
	ForkSession bool
}

type Result struct {
	Events                     []Event
	Document                   []byte
	Model                      string
	Calls, Tokens              int
	UsageAttempts              []UsageAttempt
	ModelSource                string
	Usage                      Usage
	StructuredOutputRejections int
	// LastRejection is a bounded copy of the last rejection's detail, which
	// describes the document's shape, not repository content.
	LastRejection string
	// SessionID is the session (Claude Code) or thread (Codex) id the CLI
	// reported for this call; with Request.ForkSession, the new session's id.
	// Empty when the CLI reported none.
	SessionID string
}

type Run struct {
	Bundle *bundle.Bundle
	// EncodedBundle is the bundle's JSON, as given to the model.
	EncodedBundle []byte
	// Directory is the run directory: the checkout's head and merge-base trees
	// and the attachments are unpacked in it. The Generator adds bundle.json,
	// schema.json and the rejected-N.json files of the repairs, and the backend
	// runs there.
	Directory string
	// TileKinds is the tile allow-list: the only kinds the run offers the model
	// and keeps from what it returns.
	TileKinds []string
	// TileEntries, when set, are the catalogue entries offered in the prompt
	// instead of the shipped entries of TileKinds (tilecatalogue.WithCandidates).
	// Evaluation uses it to try selection guidance; none (nil or empty) keeps the shipped ones.
	TileEntries []tilecatalogue.Entry
	Budgets     Budgets
	// Endpoint is how the backend reaches the model; nil leaves its own.
	Endpoint *Endpoint
	// Decorate, when set, adds to every document the model returns what the
	// host decides and the model never writes, such as a group review's
	// stack and its sections' members, before the document is masked and
	// validated. It must not fail: a document it cannot read is returned
	// as it came, for the validator to report.
	Decorate func([]byte) []byte
	// ModelSchema, when set, adjusts the model schema the run offers, such
	// as a group review's, which asks the model to name the group. What it
	// asks for must still prepare into a document the validator accepts,
	// with Decorate's help.
	ModelSchema func([]byte) ([]byte, error)
	// PersistSession keeps the backend's session of every call, so the
	// Outcome's SessionID can be resumed later (Request.PersistSession).
	PersistSession bool
}

type StageOutcome struct {
	Outcome
	// Written, Reused and Failed name, for the details stage, the sections
	// whose details the model wrote, those taken from the previous version,
	// and those left without details.
	Written []string `json:"written,omitempty"`
	Reused  []string `json:"reused,omitempty"`
	Failed  []string `json:"failed,omitempty"`
}

type StagedOutcome struct {
	Outcome
	Outline StageOutcome
	Details StageOutcome
	Context StageOutcome
}

type StagedProgress struct {
	// Stage is StageOutline, StageDetails or StageContext.
	Stage string
	// Section is the section whose details landed, for StageDetails.
	Section string
	// Reused marks details taken from the previous version; Failed details
	// or a context that could not be written.
	Reused, Failed bool
	// Document is the authored document so far (review.AssembleStaged): the
	// outline, the sections written, every other section without its
	// details (pending, or failed once they failed), and the context once
	// written. It is not redacted: a host masks it before it shows it, and
	// completes it with review.DocumentValidator.CompleteStaged.
	Document []byte
	// MaskedClosed says the identifier pass has masked a secret in a closed
	// value: the host rejects the run (RejectSecrets), so it shows no draft.
	MaskedClosed bool
}

type StagedPrompt struct {
	Version, Digest string
	Shared          string
	Outline         string
	Details         string
	Context         string
}

type StagedPrompts interface {
	// StagedInstructions returns the staged review instructions for a
	// backend. The loop ignores Version and Digest, as it does a Prompt's.
	StagedInstructions(ctx context.Context, backend string) (StagedPrompt, error)
}

type StagedRun struct {
	Run
	Prompts StagedPrompts
	// Progress, when set, is told of each stage result as it lands: the
	// outline accepted, each section's details written, reused or failed, and
	// the context written or failed, with the authored document so far.
	// Calls come from the stages' goroutines, one at a time, and hold up the
	// stage that made them, so it must return quickly.
	Progress func(StagedProgress)
	// Outline, when set, continues a review whose outline was accepted
	// before, such as a saved version some of whose sections failed: it is
	// prepared as an outline reply (PrepareOutline) instead of being written,
	// and the run writes no context. Only the details of the sections Reuse
	// cannot supply are written, with every call and token of the budgets.
	// Context is the context the review keeps, prepared with the outline
	// (PrepareContext); nil, or one that no longer validates, leaves the
	// document without one.
	Outline, Context []byte
	// Reuse is the version whose complete section details are reused
	// (review.ReusableSectionDetails); nil is Run.Bundle.Previous. A host
	// that continues a saved version passes that version here and the
	// version before it as the bundle's, which completion reconciles with.
	Reuse *bundle.PreviousVersion
}

type StaticPrompts map[string]Prompt

type Task struct {
	// Directory is the run directory: the checkout and the task's input
	// files. RunTask adds schema.json and the rejected-N.json files of the
	// repairs (named by Label when set), and the backend runs there.
	Directory string
	Prompt    string
	// Schema is the JSON Schema of the reply, given to the backend as the
	// output schema and checked against every reply.
	Schema []byte
	// Check is the workflow's own check of a reply the schema accepts; it
	// returns findings, empty when the reply is valid. Nil checks nothing more.
	Check    func(document []byte) (findings string)
	Budgets  Budgets
	Endpoint *Endpoint
	// PassPrompt, when set, is the prompt of each pass instead of Prompt and,
	// on a repair, the standard repair text.
	PassPrompt func(TaskPass) (string, error)
	// Accept, when set, checks each reply instead of the schema and Check:
	// it returns the document the reply stands for, the findings that send it
	// back for a repair, or Stop to reject it without another repair.
	Accept func(ctx context.Context, pass TaskPass, document []byte, outcome *Outcome) (Verdict, error)
	// Framing is how the backend frames the task; the zero value frames a
	// generic task.
	Framing Framing
	// PersistSession keeps the backend's session of every call, so the
	// Outcome's SessionID can be resumed later (Request.PersistSession).
	PersistSession bool
	// Label, when set, names the task's files in the run directory
	// (TaskSchemaFile), so that tasks running in one directory at once do not
	// overwrite each other's: lowercase letters, digits and dashes. Empty
	// keeps schema.json and rejected-N.json.
	Label string
}

type TaskPass struct {
	Number, Repairs int
	Rejected        []byte
	Findings        string
}

type TranscriptEntry struct {
	Time time.Time `json:"time"`
	// Kind is "message", "reasoning", "tool", "error", or "call": the host's
	// mark of one model call of a run that makes several, by ID like a tool,
	// with its name in Title.
	Kind string `json:"kind"`
	// ID, Tool, Title and Status are a tool entry's: the harness's id, the
	// tool ("command", "file_change", "Read", ...), its command line or name
	// and main argument, and "running", "completed" or "failed".
	ID     string `json:"id,omitempty"`
	Tool   string `json:"tool,omitempty"`
	Title  string `json:"title,omitempty"`
	Status string `json:"status,omitempty"`
	// Text is a message's or reasoning's text, or a finished tool's output.
	Text string `json:"text,omitempty"`
	// Call, set by the host, names the call of a run of several the entry
	// belongs to, as its "call" entry's Title does.
	Call string `json:"call,omitempty"`
}

type Usage struct {
	Input, Output, CacheRead, CacheCreate int64
	// CacheCreate1h is the part of CacheCreate written with the 1-hour TTL and
	// Speed the speed ("standard" or "fast") every call ran at. Nil means the
	// agent did not report it, or its calls differed (a run spans many calls).
	CacheCreate1h *int64
	Speed         *string
	// MinPrompt and MaxPrompt bound the prompt (input plus cache reads and
	// writes) of the single model calls the usage covers, which decides each
	// call's long-prompt tier. They are set only when every call of the run
	// reported usage; nil means unknown, and the total is then priced with no
	// range. Codex's agent reports no per-call usage, so its range is unknown.
	MinPrompt, MaxPrompt *int64
	// Unreported means the backend could not report usage, so the zero buckets
	// are unknown rather than free.
	Unreported bool
}

type UsageAttempt struct {
	ModelSource   string `json:"model_source,omitempty"`
	Model         string `json:"model"`
	Usage         Usage  `json:"usage"`
	Calls         int    `json:"calls"`
	ChargedTokens int    `json:"charged_tokens"`
	Failed        bool   `json:"failed"`
}

type Verdict struct {
	Document []byte
	Findings string
	Stop     bool
}