chatloop

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

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

	// 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
	ThresholdPercent int32
	UsagePercent     float64
	ContextTokens    int64
	ContextLimit     int64
}

type ExecuteLocalToolsOptions struct {
	Tools         []fantasy.AgentTool
	ActiveTools   []string
	ProviderTools []ProviderTool
	ToolCalls     []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

	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
	ModelConfig          codersdk.ChatModelCallConfig
	ProviderOptions      fantasy.ProviderOptions

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

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

	ThresholdPercent     int32
	ContextLimit         int64
	ContextLimitFallback int64
	SummaryPrompt        string
	SystemSummaryPrefix  string
	Timeout              time.Duration
	StepUsage            fantasy.Usage
	StepMetadata         fantasy.ProviderMetadata

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

	PublishMessagePart func(codersdk.ChatMessageRole, codersdk.ChatMessagePart)
}

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
}

type PendingToolCall struct {
	ToolCallID string
	ToolName   string
	Args       string
}

type PersistedStep struct {
	Content            []fantasy.Content
	Usage              fantasy.Usage
	ContextLimit       sql.NullInt64
	ProviderResponseID string
	// Runtime is the wall-clock duration of this step,
	// covering LLM streaming, tool execution, and retries.
	// Zero indicates the duration was not measured (e.g.
	// interrupted steps).
	Runtime time.Duration
	// 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
	ReloadMessages   func(context.Context) ([]fantasy.Message, error)
	DisableChainMode func()
	// PrepareMessages is called at least once before each LLM step
	// with the current message history. If it returns non-nil, the
	// returned slice replaces messages for this and all subsequent
	// steps.
	// Used to inject system context that becomes available mid-loop
	// (e.g. AGENTS.md after create_workspace).
	// NOTE: It may be called more than once per step in case of a
	// retry, so callbacks should avoid duplicating messages.
	PrepareMessages func([]fantasy.Message) []fantasy.Message

	// 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 ToolExecutionOutcome struct {
	Step PersistedStep
}