chatloop

type AssistantOutcome struct {
	Step         PersistedStep
	ToolCalls    []fantasy.ToolCallContent
	FinishReason fantasy.FinishReason
	ModelStopped bool
}

type BilledInterval struct {
	Start time.Time
	End   time.Time
}

type CompactionOptions struct {
	ThresholdPercent    int32
	ContextLimit        int64
	SummaryPrompt       string
	SummaryHint         string
	SystemSummaryPrefix string
	Persist             func(context.Context, CompactionResult) error
	DebugSvc            *chatdebug.Service
	ChatID              uuid.UUID
	HistoryTipMessageID int64

	ResolvedProvider string
	ResolvedModel    string
	ModelConfigID    uuid.UUID
	SummaryCall      fantasy.Call

	// Force skips the threshold gate (including the threshold=100
	// disable and the zero-usage early return). Set for manual,
	// user-requested compactions.
	Force bool
	// Source labels what triggered the compaction. Defaults to
	// CompactionSourceAutomatic when empty.
	Source CompactionSource

	// ToolCallID and ToolName identify the synthetic tool call
	// used to represent compaction in the message stream.
	ToolCallID string
	ToolName   string

	// PublishMessagePart publishes streaming parts to connected
	// clients so they see "Summarizing..." / "Summarized" UI
	// transitions during compaction.
	PublishMessagePart func(codersdk.ChatMessageRole, codersdk.ChatMessagePart)

	OnError func(error)
}

type CompactionResult struct {
	SystemSummary    string
	SummaryReport    string
	Source           CompactionSource
	ThresholdPercent int32
	UsagePercent     float64
	ContextTokens    int64
	ContextLimit     int64
	// Runtime is the wall-clock duration of the summarization model
	// call, the compaction step's billable runtime (see
	// PersistedStep.Runtime). Zero when the run was gated off before
	// calling the model.
	Runtime time.Duration
}

type CompactionSource string

type ExecuteLocalToolsOptions struct {
	Tools              []fantasy.AgentTool
	ActiveTools        []string
	AllowInactiveTools map[string]bool
	ProviderTools      []ProviderTool
	ToolCalls          []fantasy.ToolCallContent
	// ObservedToolCalls optionally carries the step's full assistant
	// tool-call batch, including calls denied before execution, so
	// step observers account for denied siblings that derivation will
	// still count. Defaults to ToolCalls.
	ObservedToolCalls []fantasy.ToolCallContent

	ExclusiveToolNames map[string]bool
	BuiltinToolNames   map[string]bool
	ModelProvider      string
	ModelName          string

	// ContextLimit is the model's context window in tokens. It is used
	// to derive a per-result byte budget so a single oversized tool
	// result cannot overflow the prompt. Zero means unknown, in which
	// case a default budget applies.
	ContextLimit int64

	// ToolNameAliases maps a non-advertised tool name to the canonical
	// tool it dispatches to. Used for backward compatibility when a tool
	// is renamed but old chat histories still reference the old name.
	ToolNameAliases map[string]string

	// UnbilledToolNames lists called tool names excluded from the batch
	// window. Include deprecated aliases.
	UnbilledToolNames map[string]bool
	// BillingRecorder observes each local call's start and completion
	// for interrupt billing. Serial calls may start after concurrent
	// siblings settle, so interrupts bill actual starts and skip calls
	// that never run. Optional.
	BillingRecorder ToolBillingRecorder

	PublishMessagePart func(codersdk.ChatMessageRole, codersdk.ChatMessagePart)
	Logger             slog.Logger
	Metrics            *Metrics
	Clock              quartz.Clock
}

type GenerateAssistantOptions struct {
	Model fantasy.LanguageModel
	// ErrorProvider labels user-facing errors with the configured provider
	// identity (e.g. "bedrock"). It differs from Model.Provider(), which
	// reflects the fantasy transport client and is "anthropic" for Bedrock
	// routed through aibridge. Metrics and prompt preparation keep using
	// Model.Provider(). When empty, Model.Provider() is used.
	ErrorProvider        string
	Messages             []fantasy.Message
	Tools                []fantasy.AgentTool
	ActiveTools          []string
	ProviderTools        []ProviderTool
	StreamSilenceTimeout time.Duration
	Clock                quartz.Clock

	ContextLimitFallback int64
	// CallTemplate is copied before GenerateAssistant attaches the prompt and
	// tools.
	CallTemplate fantasy.Call

	PublishMessagePart func(codersdk.ChatMessageRole, codersdk.ChatMessagePart)
	// OnModelStreamStart runs immediately before the provider stream is
	// opened, at the instant PersistedStep.Runtime starts measuring. It
	// lets callers record the billable window's start out of band, so an
	// interrupted attempt bills the same window a completed step reports.
	OnModelStreamStart func()
	Logger             slog.Logger
	Metrics            *Metrics
}

type GenerateCompactionOptions struct {
	Model    fantasy.LanguageModel
	Messages []fantasy.Message

	ThresholdPercent     int32
	ContextLimit         int64
	ContextLimitFallback int64
	SummaryPrompt        string
	SummaryHint          string
	SystemSummaryPrefix  string
	StepUsage            fantasy.Usage
	StepMetadata         fantasy.ProviderMetadata

	// Force skips the threshold gate (including the threshold=100
	// disable and the zero-usage early return). Set for manual,
	// user-requested compactions.
	Force bool
	// Source labels what triggered the compaction. Defaults to
	// CompactionSourceAutomatic when empty.
	Source CompactionSource

	DebugSvc            *chatdebug.Service
	ChatID              uuid.UUID
	HistoryTipMessageID int64
	ToolCallID          string
	ToolName            string

	// ResolvedProvider, ResolvedModel, and ModelConfigID identify the
	// summary model, which can differ from the chat model when a
	// compaction override is configured. Debug runs record these.
	ResolvedProvider string
	ResolvedModel    string
	ModelConfigID    uuid.UUID

	// SummaryCall is copied before GenerateCompaction attaches the summary
	// prompt.
	SummaryCall fantasy.Call

	PublishMessagePart func(codersdk.ChatMessageRole, codersdk.ChatMessagePart)

	// Clock measures the summary call duration. Required.
	Clock quartz.Clock

	// OnModelStreamStart runs immediately before the summary model call,
	// at the instant CompactionResult.Runtime starts measuring.
	OnModelStreamStart func()
}

type Metrics struct {
	Chats                     *prometheus.GaugeVec
	MessageCount              *prometheus.HistogramVec
	PromptSizeBytes           *prometheus.HistogramVec
	ToolResultSizeBytes       *prometheus.HistogramVec
	ToolResultTruncatedTotal  *prometheus.CounterVec
	ToolErrorsTotal           *prometheus.CounterVec
	TTFTSeconds               *prometheus.HistogramVec
	CompactionTotal           *prometheus.CounterVec
	StepsTotal                *prometheus.CounterVec
	StreamRetriesTotal        *prometheus.CounterVec
	StreamBufferDroppedTotal  prometheus.Counter
	FindToolsCallsTotal       prometheus.Counter
	FindToolsEmptyTotal       prometheus.Counter
	FindToolsMatchCount       prometheus.Histogram
	FindToolsActivationsTotal prometheus.Counter
}

type PendingToolCall struct {
	ToolCallID string
	ToolName   string
	Args       string
}

type PersistedStep struct {
	Content      []fantasy.Content
	Usage        fantasy.Usage
	ContextLimit sql.NullInt64
	// Runtime is the wall-clock duration from opening to consuming the
	// model stream.
	Runtime time.Duration
	// BatchRuntime is the union of billed local-tool execution intervals.
	// Parallel calls count once and serial calls count from their own start.
	BatchRuntime time.Duration
	// BatchBilledCalls counts the executed calls whose intervals produced
	// BatchRuntime. Audit metadata for the batch usage record.
	BatchBilledCalls int
	// PendingDynamicToolCalls lists tool calls that target
	// dynamic tools. When non-empty the chatloop exits with
	// ErrDynamicToolCall so the caller can execute them
	// externally and resume the loop.
	PendingDynamicToolCalls []PendingToolCall
	// ToolCallCreatedAt maps tool-call IDs to the time
	// the model emitted each tool call. Applied by the
	// persistence layer to set CreatedAt on persisted
	// tool-call ChatMessageParts.
	ToolCallCreatedAt map[string]time.Time
	// ToolResultCreatedAt maps tool-call IDs to the time
	// each tool result was produced (or interrupted).
	// Applied by the persistence layer to set CreatedAt
	// on persisted tool-result ChatMessageParts.
	ToolResultCreatedAt map[string]time.Time
	// ReasoningStartedAt and ReasoningCompletedAt are parallel
	// slices indexed by the occurrence order of reasoning
	// content in Content. The persistence layer walks reasoning
	// parts in order and applies these timestamps to the
	// corresponding ChatMessageParts so the frontend can render
	// reasoning duration. Reasoning parts have no provider-side
	// stable ID, so order is the only correlation we have.
	ReasoningStartedAt   []time.Time
	ReasoningCompletedAt []time.Time
}

type ProviderTool struct {
	Definition fantasy.Tool
	Runner     fantasy.AgentTool
	// ResultProviderMetadata extracts provider-specific metadata from successful
	// local runner responses. The chat loop attaches returned metadata to the tool
	// result sent back to the model. OpenAI computer-use uses this to request
	// original screenshot detail for image results.
	ResultProviderMetadata func(response fantasy.ToolResponse) fantasy.ProviderMetadata
}

type RunOptions struct {
	Model    fantasy.LanguageModel
	Messages []fantasy.Message
	Tools    []fantasy.AgentTool
	MaxSteps int
	// StreamSilenceTimeout bounds how long each model attempt
	// may go without receiving a stream part before the
	// attempt is canceled and retried. Zero uses the
	// production default.
	StreamSilenceTimeout time.Duration
	// Clock creates stream silence guard timers. In production
	// use a real clock; tests can inject quartz.NewMock(t) to
	// make timeout behavior deterministic.
	Clock quartz.Clock

	ActiveTools          []string
	ContextLimitFallback int64

	// DynamicToolNames lists tool names that are handled
	// externally. When the model invokes one of these tools
	// the chatloop persists partial results and exits with
	// ErrDynamicToolCall instead of executing the tool.
	DynamicToolNames map[string]bool
	// StopAfterTools lists tool names that, when they produce a
	// successful result, cause the run to stop after persisting
	// the current step. This is used for plan turns where
	// propose_plan should terminate the run on success.
	StopAfterTools map[string]struct{}
	// ExclusiveToolNames lists tool names that must be called
	// alone in a batch. When any exclusive tool appears
	// alongside other locally-executed tools, every tool in the
	// batch receives a policy error and nothing executes.
	ExclusiveToolNames map[string]bool

	// ModelConfig holds per-call LLM parameters (temperature,
	// max tokens, etc.) read from the chat model configuration.
	ModelConfig codersdk.ChatModelCallConfig
	// ProviderOptions are provider-specific call options
	// converted from ModelConfig.ProviderOptions. This is a
	// separate field because the conversion requires knowledge
	// of the provider, which lives in chatd, not chatloop.
	ProviderOptions fantasy.ProviderOptions

	// ProviderTools are provider-native tools (like web search
	// and computer use) whose definitions are passed directly
	// to the provider API. When a ProviderTool has a non-nil
	// Runner, tool calls are executed locally; otherwise the
	// provider handles execution (e.g. web search).
	ProviderTools []ProviderTool

	PersistStep        func(context.Context, PersistedStep) error
	PublishMessagePart func(
		role codersdk.ChatMessageRole,
		part codersdk.ChatMessagePart,
	)
	// Callers should attach correlation fields (chat_id, owner_id, etc.)
	// using Logger.With before passing the logger in.
	Logger     slog.Logger
	Compaction *CompactionOptions

	// PrepareTools is called once before each LLM step with the
	// current tool list. If it returns non-nil, the returned slice
	// replaces opts.Tools for this and all subsequent steps, and any
	// new tool names are appended to opts.ActiveTools so they become
	// callable immediately. Used to inject tools that become available
	// mid-turn (e.g. workspace MCP tools discovered after
	// create_workspace).
	//
	// The chatloop tracks whether tools have already been replaced so
	// PrepareTools is not retried on subsequent steps once it has
	// returned a non-nil slice. Callbacks may still be invoked on later
	// steps when they previously returned nil.
	PrepareTools func([]fantasy.AgentTool) []fantasy.AgentTool

	// OnRetry is called before each retry attempt when the LLM
	// stream fails with a retryable error. It provides the attempt
	// number, raw error, normalized classification, and backoff
	// delay so callers can publish status events to connected
	// clients. Callers should also clear any buffered stream state
	// from the failed attempt in this callback to avoid sending
	// duplicated content.
	OnRetry chatretry.OnRetryFn

	OnInterruptedPersistError func(error)

	// Metrics records Prometheus metrics for the chatd subsystem.
	// When nil, no metrics are recorded.
	Metrics *Metrics

	// BuiltinToolNames lists tool names that are built into chatd.
	BuiltinToolNames map[string]bool
}

type ToolBillingRecorder interface {
	RecordStart(dispatchIndex int, startedAt time.Time)
	RecordComplete(dispatchIndex int, completedAt time.Time)
}