engine

type BudgetMetrics struct {
	Type  string     `json:"type"`
	Used  float64    `json:"used"`
	Limit float64    `json:"limit"`
	Run   RunMetrics `json:"run"`
}

type CompactionCommitRequest struct {
	CompactionRequest
	Result          compaction.Result
	ActiveMessages  []session.Message
	Completion      event.Event
	RequestEstimate contextpolicy.RequestEstimate
	ContextPressure contextpolicy.ContextPressure
}

type CompactionCommitter interface {
	CommitCompaction(context.Context, CompactionCommitRequest) (compaction.Result, []session.Message, error)
}

type CompactionManager interface {
	Compact(context.Context, CompactionRequest) (compaction.Result, []session.Message, error)
}

type CompactionRequest struct {
	RunID                     string
	ThreadID                  string
	TurnID                    string
	TraceID                   string
	PromptScopeID             string
	Step                      int
	OperationID               string
	RequestID                 string
	Source                    string
	SupplementalAnchorEntryID string
	History                   []session.Message
	Policy                    contextpolicy.Policy
	Trigger                   compaction.Trigger
	Reason                    compaction.Reason
	Phase                     compaction.Phase
	Provider                  provider.Provider
	ProviderName              string
	Model                     string
	PreviousCompactionID      string
	PreviousGeneration        int
	PreviousWindowID          string
	PreviousSummary           string
	ContextUsage              contextpolicy.Usage
	Details                   map[string]string
}

type CompletionReason string

type Config struct {
	Provider     provider.Provider
	Tools        *tools.Registry
	Store        session.TranscriptStore
	Prompt       cache.Store
	SystemPrompt string
	Sink         event.Sink
	StopHook     StopHook
	Compactor    CompactionManager
	Options      Options
}

type ContextCompactionResult struct {
	FailureOrigin FailureOrigin
	Status        Status
	Err           error
	Metrics       RunMetrics
	Messages      []session.Message
	Compaction    compaction.Result
	ProviderState *provider.State
}

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

type ContinuationReason string

type ControlDisposition string

type ControlSignal struct {
	Disposition ControlDisposition
	Name        string
	CallID      string
	ErrorCode   string
	Payload     map[string]any
	Activity    *tools.ActivityPresentation
	// OutputText is the human-readable control result. For ControlContinue it is
	// provider-visible; host-only details must stay in Payload.
	OutputText string
	ArgsHash   string
	Labels     map[string]string
}

type ControlSpec struct {
	Definitions []tools.ToolDefinition
	Project     func(provider.ToolCall) (ControlSignal, bool, error)
}

type EffectResultFinalizationRequest struct {
	RunID      string
	ThreadID   string
	TurnID     string
	ToolCallID string
	Message    session.Message
	FullOutput *artifact.FullOutput
}

type EffectResultFinalizationResult struct {
	Handled          bool
	Message          session.Message
	Replayed         bool
	CanonicalEntryID string
}

type EffectResultFinalizer func(context.Context, EffectResultFinalizationRequest) (EffectResultFinalizationResult, error)

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

type ExecutionIdentity struct {
	RunID         string
	ThreadID      string
	TurnID        string
	TraceID       string
	PromptScopeID string
}

type FailureOrigin string

type LocalCompactionManager struct {
	Generator compaction.SummaryGenerator
	Now       func() time.Time
}

type ManualCompactionPollRequest struct {
	RunID         string
	ThreadID      string
	TurnID        string
	TraceID       string
	PromptScopeID string
	Step          int
}

type ManualCompactionRequest struct {
	RequestID string
	Source    string
}

type ManualCompactionSource interface {
	PollManualCompaction(context.Context, ManualCompactionPollRequest) (ManualCompactionRequest, bool, error)
}

type Options struct {
	Steering *SteeringControl
	// RetrySourceEntryID is supplied only by the canonical harness retry admission.
	RetrySourceEntryID    string
	RunID                 string
	LogicalRequestID      string
	ThreadID              string
	TurnID                string
	TraceID               string
	PromptScopeID         string
	ProviderName          string
	Model                 string
	StateCompatibilityKey string
	Labels                RunLabels
	CacheNamespace        string
	CacheRetention        cache.Retention
	ContextPolicy         contextpolicy.Policy
	Reasoning             provider.ReasoningSelection

	ProviderRequestTimeoutPolicy providerattempt.RequestTimeoutPolicy

	ProviderRetryPolicy     providerretry.Policy
	MaxEmptyProviderRetries int
	NoProgressLimit         int
	DuplicateToolLimit      int
	WallTime                time.Duration
	MaxInputTokens          int64
	MaxTotalTokens          int64
	MaxCostUSD              float64
	MaxToolCalls            int
	HostedToolDefinitions   []provider.HostedToolDefinition
	ControlSpec             ControlSpec
	PreviousProviderState   *provider.State
	AdmitParentEvents       func(context.Context) (session.Message, error)
	AdmitModelContext       func(context.Context, *session.ModelContextSnapshot) (session.Message, error)
	CommitProviderContext   func(context.Context, *provider.State, []session.Message, bool) error

	MaxLengthContinuations   int
	MaxStopHookContinuations int
	ManualCompactions        ManualCompactionSource
	ToolSurfaceProvider      ToolSurfaceProvider
	EffectBatchPreflight     tools.EffectBatchPreflight
	EffectDispatcher         tools.EffectDispatcher
	EffectResultFinalizer    EffectResultFinalizer
	ProviderRequestGate      func(context.Context) (func(), error)
	SupplementalContext      []TurnSupplementalContextItem
	// contains filtered or unexported fields
}

type PressureAnchorState = cache.PressureAnchorState

type ProviderToolSurface struct {
	SystemPrompt          string
	ToolDefinitions       []tools.ToolDefinition
	HostedToolDefinitions []provider.HostedToolDefinition
}

type ProviderUsageContextStatus struct {
	PayloadFingerprint   string                        `json:"payload_fingerprint,omitempty"`
	AttemptID            string                        `json:"attempt_id,omitempty"`
	AttemptEpoch         int                           `json:"attempt_epoch,omitempty"`
	Phase                string                        `json:"phase"`
	RequestID            string                        `json:"request_id,omitempty"`
	LogicalRequestID     string                        `json:"logical_request_id,omitempty"`
	Attempt              int                           `json:"attempt,omitempty"`
	Usage                provider.Usage                `json:"usage"`
	RequestEstimate      contextpolicy.RequestEstimate `json:"request_estimate"`
	ContextPressure      contextpolicy.ContextPressure `json:"context_pressure"`
	UsedRatio            float64                       `json:"used_ratio,omitempty"`
	ThresholdRatio       float64                       `json:"threshold_ratio,omitempty"`
	Status               string                        `json:"status"`
	CompactionGeneration int                           `json:"compaction_generation,omitempty"`
	CompactionWindowID   string                        `json:"compaction_window_id,omitempty"`
}

type RequestShapeHashes = cache.RequestShapeHashes

type Result struct {
	Status             Status
	FailureOrigin      FailureOrigin
	Output             string
	Err                error
	Metrics            RunMetrics
	Messages           []session.Message
	CompletionReason   CompletionReason
	ContinuationReason ContinuationReason
	FinishReason       provider.FinishReason
	RawFinishReason    string
	FinishInferred     bool
	ControlSignal      *ControlSignal
	ProviderState      *provider.State
	ProviderStateFresh bool
}

type RunDecision struct {
	CompletionReason   CompletionReason
	ContinuationReason ContinuationReason
	FinishReason       provider.FinishReason
	RawFinishReason    string
	FinishInferred     bool
	Detail             string
	ControlSignal      *ControlSignal
	Metadata           map[string]any
}

type RunInput struct {
	RunID                 string
	ThreadID              string
	TurnID                string
	TraceID               string
	PromptScopeID         string
	Labels                RunLabels
	PreviousProviderState *provider.State
	History               []session.Message
	SupplementalContext   []TurnSupplementalContextItem
}

type RunLabels struct {
	Correlation map[string]string
	Host        map[string]string
}

type RunMetrics struct {
	Usage       provider.Usage `json:"usage"`
	Steps       int            `json:"steps"`
	LLMRequests int            `json:"llm_requests"`
	ToolCalls   int            `json:"tool_calls"`
	Compactions int            `json:"compactions"`
	Retries     int            `json:"retries"`
	WallTimeMS  int64          `json:"wall_time_ms,omitempty"`
}

type Status string

type SteeringControl struct {
	CanContinue func(error) bool
	Begin       func(context.Context, func() error) (context.Context, []session.Message, error)
	Finish      func(context.Context) (bool, error)
}

type StepMetrics struct {
	Step               int            `json:"step"`
	Provider           string         `json:"provider,omitempty"`
	Model              string         `json:"model,omitempty"`
	Usage              provider.Usage `json:"usage"`
	ProviderLatencyMS  int64          `json:"provider_latency_ms,omitempty"`
	ToolLatencyMS      int64          `json:"tool_latency_ms,omitempty"`
	ToolCalls          int            `json:"tool_calls,omitempty"`
	Retries            int            `json:"retries,omitempty"`
	FinishReason       string         `json:"finish_reason,omitempty"`
	RawFinishReason    string         `json:"raw_finish_reason,omitempty"`
	FinishInferred     bool           `json:"finish_inferred,omitempty"`
	CompletionReason   string         `json:"completion_reason,omitempty"`
	ContinuationReason string         `json:"continuation_reason,omitempty"`
}

type StepOutput struct {
	Sources         []citation.Source
	Text            string
	Reasoning       string
	Calls           []provider.ToolCall
	Usage           provider.Usage
	ResponseID      string
	Retry           bool
	Truncated       bool
	FinishReason    provider.FinishReason
	RawFinishReason string
	FinishInferred  bool
	ResponseState   *provider.State
	// contains filtered or unexported fields
}

type StopHook func(context.Context, StopHookContext) (StopHookResult, error)

type StopHookContext struct {
	RunID         string
	ThreadID      string
	TurnID        string
	TraceID       string
	PromptScopeID string
	Step          int

	LastAssistant   session.Message
	Messages        []session.Message
	FinishReason    provider.FinishReason
	RawFinishReason string
	FinishInferred  bool
	Metrics         RunMetrics
}

type StopHookResult struct {
	Continue bool
	Prompt   string
	Reason   string
}

type ToolSurface struct {
	ModelContextSnapshot *session.ModelContextSnapshot

	// RefreshProviderSurface opts into resolving system text and tool definitions
	// at each provider request. Model, reasoning, context policy and historical
	// checkpoints stay fixed. The zero value preserves the first Turn surface.
	RefreshProviderSurface bool
	Tools                  *tools.Registry
	ToolDefinitions        []tools.ToolDefinition
	HostedToolDefinitions  []provider.HostedToolDefinition
	SystemPrompt           string
	HostContext            map[string]string
	Epoch                  string
	Reason                 string
}

type ToolSurfaceProvider func(context.Context, ToolSurfaceRequest) (ToolSurface, error)

type ToolSurfaceRequest struct {
	// InitialProviderSurface is the first checkpoint of this Turn, or nil before
	// the first provider checkpoint. Hosts can retain capabilities unrelated to a live policy change.
	// Mutating it cannot alter stored requests.
	InitialProviderSurface *ProviderToolSurface
	RunID                  string
	ThreadID               string
	TurnID                 string
	TraceID                string
	PromptScopeID          string
	Step                   int
	Phase                  string
	Labels                 RunLabels
	HostContext            map[string]string
}

type TurnSupplementalContextItem struct {
	Kind      string
	Title     string
	Text      string
	Metadata  map[string]string
	Sensitive bool
	Truncated bool
}