agent

type Agent interface {
	Name() string
	Run(ctx context.Context, opts RunOpts) (*Result, error)
	Close() error
}

type Attempt struct {
	Agent           string
	Identity        InvocationIdentity
	Result          *Result
	Err             error
	StartedAt       time.Time
	CompletedAt     time.Time
	Session         *SessionRef
	SessionFallback bool
}

type AttemptReporter interface {
	ReportsAgentAttempts() bool
}

type GateInstructionNeutralizer interface {
	NeutralizesGateInstructions() bool
}

type InvocationIdentity struct {
	ConfiguredAgent string
	Executable      *string
	ModelArgs       []string
}

type InvocationIdentityReporter interface {
	InvocationIdentity() InvocationIdentity
}

type InvocationMetrics struct {
	// ModelRoundtrips counts the model-authored items in the turn (assistant
	// messages plus tool calls). It is a live-stream proxy for productive model
	// round-trips: because codex batches an exec into a single turn and does not
	// surface internal poll round-trips as items, every counted item is
	// productive work, not "are-we-there-yet" polling.
	ModelRoundtrips int
	// ToolCalls counts whole tool invocations (one command_execution item is one
	// tool call regardless of how many sub-commands it chains).
	ToolCalls int
	// ToolCategories is the per-sub-command histogram (see ToolCategoryCounts).
	ToolCategories ToolCategoryCounts
	// SubprocessWaitMS is the wall-clock spent inside tool subprocesses,
	// measured by the reader as the sum of each tool item's started->completed
	// interval. Combined with the invocation duration it separates subprocess
	// wait from model/reasoning time (see ModelTimeMS).
	SubprocessWaitMS int64
}

type InvocationWorkload struct {
	Files int
	Lines int
}

type LaneHealthStore interface {
	Outage(lane string) (lanehealth.Outage, bool)
	ClaimProbe(lane string) bool
	Mark(outage lanehealth.Outage) error
	ClearObservedBefore(lane string, startedAt time.Time) error
}

type LaneOutageError struct {
	Lane   string
	Until  time.Time
	Reason string
	// contains filtered or unexported fields
}

type LifecycleEvent struct {
	Agent   string
	Phase   string
	PID     int
	Message string
}

type Options struct {
	ACPRegistryOverrides map[string]string
	// DisableProjectSettings, when true, asks a supported adapter (codex,
	// claude, pi) to launch with the target repo's project-level agent
	// settings/instructions suppressed. It is the resolved, trusted-only opt-out
	// from config.Config; adapters without a verified suppression knob ignore it
	// and are refused separately by EnsureGateNeutralized when the opt-out is on.
	DisableProjectSettings bool
}

type OutputParseError struct {
	Agent   string
	Snippet string
	// contains filtered or unexported fields
}

type QuartermasterAcquireRequest struct {
	Pool    string
	Holder  string
	Purpose string
	TTL     time.Duration
	Weight  int
}

type QuartermasterClient interface {
	Acquire(context.Context, QuartermasterAcquireRequest) (QuartermasterLease, error)
	Release(context.Context, QuartermasterLease, string) error
}

type QuartermasterLease struct {
	Account string
	ID      string
	Until   time.Time
	Pool    string
	Holder  string
}

type QuartermasterOptions struct {
	Client QuartermasterClient
	Pool   string
	Holder string
	TTL    time.Duration
	Weight int
	Home   string
}

type QuartermasterRefusalError struct {
	Pool    string
	Purpose string
	Reason  string
	Cause   error
}

type Result struct {
	// Output is structured JSON returned by the agent. Text-parsed fallback
	// results are validated before return, and optional fields may be
	// nullable there.
	Output json.RawMessage
	// Text is the raw text output.
	Text string
	// Usage tracks token consumption for the invocation.
	Usage         TokenUsage
	UsageReported bool
	// SessionID is the adapter-native session identity of this invocation
	// when the adapter reports one. Callers persist it to resume later.
	SessionID string
	// Resumed reports whether this invocation resumed opts.Session.ID.
	Resumed bool
	// Model is the model the adapter reported serving this invocation, when
	// available. Instrumentation only.
	Model string
	// ModelProvider is the provider that served the model (e.g. "openai",
	// "anthropic"), when the adapter can report it. Instrumentation only.
	ModelProvider string
	// Provider is the adapter provider that served this invocation. It lets
	// fallback wrappers persist a session against the provider that minted it.
	Provider string
	// Metrics is the bounded per-invocation activity evidence the adapter
	// extracted from its event stream (round-trips, tool calls + categories,
	// subprocess wait time). Nil means the adapter reported nothing, which is
	// recorded as unknown (NULL) rather than a fabricated zero.
	Metrics *InvocationMetrics
	// CacheCreationReported reports whether Usage.CacheCreationTokens is a
	// meaningful value. Adapters whose provider does not surface cache-creation
	// cost (codex) leave it false so the field is recorded as unknown instead of
	// a fabricated zero.
	CacheCreationReported bool
	// SessionUsageCumulative reports that Usage accumulates across a resumed
	// durable session, so round N's counters include rounds 1..N-1. The pipeline
	// uses it to record correct per-round token deltas (see PerRoundTokens).
	SessionUsageCumulative bool
}

type RunOpts struct {
	Prompt string
	// Env appends invocation-scoped environment entries to the agent process.
	// Entries later in the slice override inherited values.
	Env         []string
	CWD         string
	JSONSchema  json.RawMessage      // structured output schema (optional)
	OnChunk     func(text string)    // streaming text callback (optional)
	OnLifecycle func(LifecycleEvent) // native agent lifecycle callback (optional)
	// Session, when non-nil, asks a session-capable adapter (see
	// SessionResumer) to start or resume a durable native session. Adapters
	// without session support ignore it and run cold; the caller detects the
	// fallback via an empty Result.SessionID.
	Session *SessionRef
	// SessionFallback marks this invocation as the fresh-session retry after
	// a failed resume. Instrumentation only; adapters ignore it.
	SessionFallback bool
	// Purpose labels the pipeline duty this invocation serves (review,
	// review-fix, test-evidence, ...). Instrumentation only; adapters
	// ignore it.
	Purpose string
	// SessionFallbackReason is the low-cardinality reason a failed resume forced
	// this fresh-session retry (see db.FallbackReason*). Set only when
	// SessionFallback is true. Instrumentation only; adapters ignore it.
	SessionFallbackReason string
	// Workload, when non-nil, records the bounded size of the change this
	// invocation is working over (files and net lines), so review/fix telemetry
	// can be normalized without external git archaeology. Instrumentation only;
	// adapters ignore it.
	Workload *InvocationWorkload
	// OnAttempt receives each concrete adapter attempt, including retries and
	// fallback-provider attempts, after it completes. It is instrumentation
	// only and must not change invocation behavior.
	OnAttempt func(Attempt)
	// contains filtered or unexported fields
}

type ServerPIDInfo struct {
	PID            int       `json:"pid"`
	Owner          string    `json:"owner,omitempty"`
	OwnerPID       int       `json:"owner_pid,omitempty"`
	OwnerStartedAt time.Time `json:"owner_started_at,omitempty"`
	Agent          string    `json:"agent"`
	Bin            string    `json:"bin"`
	Port           int       `json:"port"`
	StartedAt      time.Time `json:"started_at"`
}

type SessionProviderMatcher interface {
	SupportsSessionProvider(string) bool
}

type SessionRef struct {
	// ID is the adapter-native session identity to resume. Empty starts a
	// new resumable session whose identity is reported via Result.SessionID.
	ID    string
	Agent string
}

type SessionResumer interface {
	SupportsSessionResume() bool
}

type TokenUsage struct {
	InputTokens         int
	OutputTokens        int
	CacheReadTokens     int
	CacheCreationTokens int
	// ReasoningTokens is the output tokens the model spent on hidden reasoning,
	// when the provider reports it separately. Zero when not reported.
	ReasoningTokens       int
	Reported              bool
	CacheCreationReported bool
}

type ToolCategory string

type ToolCategoryCounts struct {
	Wait     int
	TestLint int
	Edit     int
	Read     int
	Git      int
	Other    int
}