agent

type ActiveChannelStore interface {
	// GetActiveChannel returns the active channel name for the given adapter
	// key ("adapter:externalID"). Returns ("", nil) when no override is set.
	GetActiveChannel(ctx context.Context, adapterKey string) (string, error)

	// SetActiveChannel persists the active channel override for the given
	// adapter key.
	SetActiveChannel(ctx context.Context, adapterKey, channelName string) error

	// ClearActiveChannel removes the active channel override, reverting the
	// adapter key to config-based routing.
	ClearActiveChannel(ctx context.Context, adapterKey string) error

	// ListActiveChannels returns all active channel overrides. Used on startup
	// to populate the dispatcher's in-memory cache.
	ListActiveChannels(ctx context.Context) (map[string]string, error)
}

type AdapterBinding struct {
	Adapter    string
	ExternalID string
}

type AgentCostSummary struct {
	Agent        string  `db:"agent"            json:"agent"`
	Cost         float64 `db:"total_cost"       json:"cost"`
	InputTokens  int     `db:"total_prompt"     json:"input_tokens"`
	OutputTokens int     `db:"total_completion"  json:"output_tokens"`
	Messages     int     `db:"total_messages"   json:"messages"`
	Sessions     int     `db:"sessions"         json:"sessions"`
}

type Binding struct {
	Pattern   string // "telegram" or "telegram:12345"
	AgentName string
}

type Channel struct {
	// Name is the unique identifier for this channel (e.g. "work", "personal").
	Name string

	// AgentName is the agent that handles messages routed through this channel.
	AgentName string

	// Adapters lists the adapter bindings from the config, using the same
	// "adapter" (wildcard) or "adapter:externalID" (specific) format.
	Adapters []string

	// Delivery controls how scheduled messages are delivered through this
	// channel's adapter bindings. "broadcast" delivers through all specific
	// bindings; any other value (including empty) uses the first specific
	// binding only.
	Delivery string

	// Implicit is true when the channel was auto-synthesized from an agent's
	// adapter bindings (backward compatibility). Implicit channels are not
	// shown in /session listings unless the user explicitly opts in.
	Implicit bool

	// SessionMode is "persistent" (default) or "ephemeral". Ephemeral
	// channels create a unique conversation for each interaction.
	SessionMode string
}

type ChatEvent struct {
	Type         string  `json:"type"`                    // "tool_start", "tool_end", "thinking", "usage", "tool_approval", "content_delta", "thinking_delta"
	Tool         string  `json:"tool,omitempty"`          // tool name
	ToolID       string  `json:"tool_id,omitempty"`       // unique tool call ID (from LLM response)
	Round        int     `json:"round,omitempty"`         // 1-based tool round
	Duration     int64   `json:"duration_ms,omitempty"`   // tool execution time
	Error        string  `json:"error,omitempty"`         // tool error (if any)
	Text         string  `json:"text,omitempty"`          // human-readable status message / content delta
	Tokens       int     `json:"tokens,omitempty"`        // total tokens used (usage event)
	TokensCached int     `json:"tokens_cached,omitempty"` // cached prompt tokens (usage event)
	CostUSD      float64 `json:"cost_usd,omitempty"`      // estimated cost in USD (usage event)

	// ApprovalID and ApprovalCallback are set on "tool_approval" events so
	// the adapter can render inline approve/deny buttons.
	ApprovalID       string `json:"approval_id,omitempty"`
	ApprovalCallback string `json:"approval_callback,omitempty"` // "appr:{id}" prefix

	// ApprovalStatus distinguishes pending approvals from auto-approved ones.
	// Values: "" (pending, needs user action), "auto_approved" (rule matched),
	// "auto_denied" (identical call was denied earlier this turn),
	// "supervisor_approved", "supervisor_denied", "supervisor_escalated",
	// "supervisor_error" (supervisor LLM call failed; falls through to human).
	ApprovalStatus string `json:"approval_status,omitempty"`

	// ApprovalScope names which auto-approve rule matched, machine-readable
	// alongside the human-readable Text. Set only when ApprovalStatus is
	// "auto_approved"; values are "config" (TOML-declared), "session" or
	// "permanent". Consumers that only key on ApprovalStatus are unaffected.
	ApprovalScope string `json:"approval_scope,omitempty"`
}

type ChatEventFunc func(ChatEvent)

type ConversationInfo struct {
	ID           string    `db:"id"            json:"id"`
	Adapter      string    `db:"adapter"       json:"adapter"`
	ExternalID   string    `db:"external_id"   json:"external_id"`
	CreatedAt    time.Time `db:"created_at"    json:"created_at"`
	MessageCount int       `db:"message_count" json:"message_count"`
}

type ConversationInfoWithStats struct {
	ConversationInfo
	TotalCost    float64    `db:"total_cost"    json:"total_cost"`
	TotalPrompt  int        `db:"total_tokens_prompt"  json:"total_tokens_prompt"`
	TotalCompl   int        `db:"total_tokens_completion" json:"total_tokens_completion"`
	LastModel    string     `db:"last_model"    json:"last_model"`
	LastProvider string     `db:"last_provider" json:"last_provider"`
	UpdatedAt    *time.Time `db:"updated_at"    json:"updated_at,omitempty"`
}

type ConversationStatsRow struct {
	ConversationID  string    `db:"conversation_id"   json:"conversation_id"`
	Agent           string    `db:"agent"             json:"agent"`
	TotalMessages   int       `db:"total_messages"    json:"total_messages"`
	TotalCost       float64   `db:"total_cost"        json:"total_cost"`
	TotalPrompt     int       `db:"total_tokens_prompt"      json:"total_tokens_prompt"`
	TotalCompletion int       `db:"total_tokens_completion"  json:"total_tokens_completion"`
	TotalCached     int       `db:"total_tokens_cached"      json:"total_tokens_cached"`
	TotalToolCalls  int       `db:"total_tool_calls"  json:"total_tool_calls"`
	TotalToolErrors int       `db:"total_tool_errors" json:"total_tool_errors"`
	LastModel       string    `db:"last_model"        json:"last_model"`
	LastProvider    string    `db:"last_provider"     json:"last_provider"`
	UpdatedAt       time.Time `db:"updated_at"        json:"updated_at"`
}

type Dispatcher struct {

	// OnBroadcast, when set, is called after an adapter message (Telegram,
	// Discord, etc.) is successfully processed. The server uses this to
	// notify WebSocket clients of conversation activity from other adapters.
	OnBroadcast func(agentName, convID, adapterName, channelName, summary string)

	// OnPanic is called when a /panic command is processed. The server uses
	// this to pause the scheduler and broadcast a panic status frame.
	OnPanic func()

	// OnResume is called when a /resume command is processed.
	OnResume func()

	// Auditor emits audit events for routing/session decisions.
	Auditor audit.Emitter
	// contains filtered or unexported fields
}

type DispatcherOption func(*Dispatcher)

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

type ExecKind string

type ExecPolicy struct {
	// Kind selects the policy flavour and becomes the audit source.
	Kind ExecKind
	// Variant names the eval variant this sample belongs to (e.g. "candidate").
	// Empty for dry-runs and for the conventional incumbent.
	Variant string
	// Model overrides the agent's model for this turn only. Empty runs the
	// agent's live model. The override is applied by cloning the router
	// (llm.Router.WithModel) rather than mutating it, so a preview of a
	// candidate model cannot retarget a live turn already in flight.
	Model string
	// Provider overrides the agent's provider for this turn only, composed
	// with Model by the same clone (llm.Router.WithProvider). Empty runs the
	// agent's live provider. Safe to override freely because every agent
	// router registers every configured provider, so the clone is a pointer
	// swap rather than a rebuild.
	Provider string
	// ConvID is the in-flight conversation identity — "dryrun:{uuid}" or
	// "eval:{run}:{task}:{k}". It is used for cost tracking, audit grouping and
	// log correlation, and is never written to the conversations table.
	ConvID string
	// AsOf pins the clock for both date-injection points (the scheduled-message
	// header and the "## Current Date" prompt section), so a replay is
	// date-deterministic. Zero means "now".
	AsOf time.Time
	// HistoryFrom names a conversation whose recent messages are loaded
	// read-only as the context *preceding* this turn. Empty means a fresh turn
	// with no history. The message being answered is always appended after it,
	// so a caller replaying a stored conversation points here at the messages
	// before the one it re-runs, not at the whole thing.
	HistoryFrom string
	// History is context pinned by the caller and replayed verbatim as the
	// messages preceding this turn. It takes precedence over HistoryFrom.
	//
	// The two differ in *when* the context is chosen. HistoryFrom names a live
	// conversation and reads its most recent window at turn time, which is
	// right for "preview this against whatever the session looks like now".
	// History carries a snippet captured earlier, which is what a saved eval
	// task needs: the source conversation drifts (ClearMessages empties it,
	// retention prunes it) and its latest window is not the window that
	// preceded the saved message. A test case that silently re-scopes itself
	// between runs is not a test case.
	//
	// Only Role and Content are read; the remaining StoredMessage fields are
	// ignored by assembleMessages and may be left zero.
	History []StoredMessage
	// AuditMode is AuditFull (default) or AuditSummary.
	AuditMode string
}

type InterestingTurn struct {
	MessageID      int64     `db:"message_id"`
	ConversationID string    `db:"conversation_id"`
	Content        string    `db:"content"`
	CreatedAt      time.Time `db:"created_at"`
	// Agent is the agent that handled the conversation, empty when its stats
	// row was pruned.
	Agent string `db:"agent"`
	// ToolCalls, MaxRound, Faults, ReplyCost and ReplyContent describe the
	// assistant reply to this turn: the next assistant message in the
	// conversation. ReplyContent is capped at replyPreviewMax runes.
	ToolCalls    int     `db:"tool_calls"`
	MaxRound     int     `db:"max_round"`
	Faults       int     `db:"faults"`
	ReplyCost    float64 `db:"reply_cost"`
	ReplyContent string  `db:"reply_content"`
	// CommandMatches counts skills that matched this turn via a command
	// trigger (match_type 'command'), as opposed to ambient or scheduled.
	CommandMatches int `db:"command_matches"`
	// Preceding holds up to precedingTurns messages immediately before this
	// one, oldest first, each capped at precedingContentMax runes.
	Preceding []TurnMessage `db:"-"`
}

type InterestingTurnStore interface {
	ListInterestingTurns(ctx context.Context, agent string, since time.Time, limit int) ([]InterestingTurn, error)
}

type MemoryStore interface {
	GetOrCreateConversation(ctx context.Context, adapter, externalID string) (string, error)
	// GetOrCreateConversationByID ensures a conversation row exists for the
	// given convID. The adapter and externalID are stored as metadata so that
	// ListConversations can report the correct source (e.g. "ws", "api",
	// "sched"). If the row already exists (INSERT OR IGNORE) the stored
	// adapter/externalID are left unchanged.
	GetOrCreateConversationByID(ctx context.Context, convID, adapter, externalID string) error
	AddMessage(ctx context.Context, convID string, msg StoredMessage) (int64, error)
	GetMessages(ctx context.Context, convID string, limit int) ([]StoredMessage, error)
	ListConversations(ctx context.Context, opts SessionListOpts) ([]ConversationInfo, int, error)
	// DeleteConversation removes a conversation and all its messages by ID.
	// Returns nil if the conversation does not exist (idempotent).
	DeleteConversation(ctx context.Context, convID string) error
	// ClearMessages removes all messages, tool calls, skill usages, and stats
	// for a conversation but keeps the conversation row itself. This allows
	// the session identity to be preserved while starting fresh.
	ClearMessages(ctx context.Context, convID string) error
	// ReplaceMessages atomically clears all messages and telemetry for a
	// conversation and inserts a single replacement message in one transaction.
	ReplaceMessages(ctx context.Context, convID string, replacement StoredMessage) error
	Close() error
}

type MessageSearchHit struct {
	ID             int64     `db:"id"              json:"id"`
	ConversationID string    `db:"conversation_id" json:"conversation_id"`
	Role           string    `db:"role"            json:"role"`
	CreatedAt      time.Time `db:"created_at"      json:"created_at"`
	Snippet        string    `db:"snippet"         json:"snippet"`
}

type ModelCostSummary struct {
	Model        string  `db:"model"          json:"model"`
	Provider     string  `db:"provider"       json:"provider"`
	TotalCost    float64 `db:"total_cost"     json:"total_cost"`
	MessageCount int     `db:"message_count"  json:"message_count"`
	TotalPrompt  int     `db:"total_prompt"   json:"total_tokens_prompt"`
	TotalCompl   int     `db:"total_completion" json:"total_tokens_completion"`
	TotalCached  int     `db:"total_cached"   json:"total_tokens_cached"`
}

type ProviderCostSummary struct {
	Provider     string  `db:"provider"          json:"provider"`
	Cost         float64 `db:"total_cost"        json:"cost"`
	InputTokens  int     `db:"total_prompt"      json:"input_tokens"`
	OutputTokens int     `db:"total_completion"   json:"output_tokens"`
	CachedTokens int     `db:"total_cached"      json:"cached_tokens"`
	Messages     int     `db:"messages"          json:"messages"`
}

type ReplyGuard struct {
	Enabled bool
	// OnRoleMarkup, OnOversized and OnNoToolCalls are GuardOff/GuardWarn/
	// GuardWithhold. An unset action reads as GuardOff.
	OnRoleMarkup  string
	OnOversized   string
	OnNoToolCalls string
	// MaxReplyBytes is the largest final reply, in bytes. Non-positive
	// disables the byte measure.
	MaxReplyBytes int
	// MaxCompletionTokens bounds provider-reported completion tokens.
	// Non-positive disables the token measure, which is the default: it
	// measures the same thing as bytes and doubles the false-positive surface.
	MaxCompletionTokens int
	// ExcerptBytes is how much of the raw reply reaches the audit detail.
	ExcerptBytes int
}

type ReplyGuardVerdict struct {
	// Signals lists every signal that tripped, in evaluation order.
	Signals []string `json:"signals"`
	// Action is the strongest action any tripped signal asked for
	// ("warn" or "withhold").
	Action string `json:"action"`
	// Notice is the operator notice a live turn would have delivered in place
	// of the reply. Empty when the action is only "warn".
	Notice string `json:"notice,omitempty"`
}

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

type SendFunc func(ctx context.Context, msg adapter.OutgoingMessage) error

type SessionListOpts struct {
	Limit  int // 0 = no limit (return all)
	Offset int
	Agent  string // filter by agent prefix in conversation ID
}

type SkillRevision struct {
	ID           int64  `db:"id"            json:"id"`
	Agent        string `db:"agent"         json:"agent"`
	TransitionID string `db:"transition_id" json:"transition_id"`
	// Seq orders revisions within one transition. It is assigned by
	// AppendSkillRevision; whatever a caller sets here is ignored.
	Seq       int    `db:"seq"        json:"seq"`
	Op        string `db:"op"         json:"op"`
	SkillName string `db:"skill_name" json:"skill_name"`
	// PriorName is the name before a rename; nil for every other op.
	PriorName *string `db:"prior_name" json:"prior_name,omitempty"`
	// PriorPayload is the raw file content before the mutation; nil when no
	// file existed (always so for SkillOpCreate).
	PriorPayload *string `db:"prior_payload" json:"prior_payload,omitempty"`
	// NewVersion and PriorVersion are the frontmatter versions after and
	// before the mutation. They are the join key against tool_calls
	// (skill_name/skill_version), i.e. by_tool_skill in GetTelemetrySummary —
	// not skill_usage, which is version-less. Empty means unknown (e.g. the
	// prior bytes did not parse).
	NewVersion   string    `db:"new_version"   json:"new_version,omitempty"`
	PriorVersion string    `db:"prior_version" json:"prior_version,omitempty"`
	Actor        string    `db:"actor"         json:"actor"`
	CreatedAt    time.Time `db:"created_at" json:"created_at"`
	// RevertedAt is nil while the revision is armed (revertible) and set once
	// it has been disposed of by a revert.
	RevertedAt *time.Time `db:"reverted_at" json:"reverted_at,omitempty"`
}

type SkillUsageRecord struct {
	ID             int64     `db:"id"              json:"id"`
	MessageID      int64     `db:"message_id"      json:"message_id"`
	ConversationID string    `db:"conversation_id" json:"conversation_id"`
	SkillName      string    `db:"skill_name"      json:"skill_name"`
	MatchType      string    `db:"match_type"      json:"match_type"`
	CreatedAt      time.Time `db:"created_at"      json:"created_at"`
}

type SkillUsageStats struct {
	SkillName     string     `db:"skill_name" json:"skill_name"`
	AgentName     string     `db:"agent_name" json:"agent_name"`
	ViewCount     int        `db:"view_count" json:"view_count"`
	UseCount      int        `db:"use_count" json:"use_count"`
	PatchCount    int        `db:"patch_count" json:"patch_count"`
	LastViewedAt  *time.Time `db:"last_viewed_at" json:"last_viewed_at,omitempty"`
	LastUsedAt    *time.Time `db:"last_used_at" json:"last_used_at,omitempty"`
	LastPatchedAt *time.Time `db:"last_patched_at" json:"last_patched_at,omitempty"`
	CreatedAt     time.Time  `db:"created_at" json:"created_at"`
	State         string     `db:"state" json:"state"`
	Pinned        bool       `db:"pinned" json:"pinned"`
	ArchivedAt    *time.Time `db:"archived_at" json:"archived_at,omitempty"`
	Origin        string     `db:"origin" json:"origin"`
}

type SkillUsageSummary struct {
	SkillName  string `db:"skill_name"  json:"skill_name"`
	MatchCount int    `db:"match_count" json:"match_count"`
	MatchTypes string `db:"match_types" json:"match_types"`
}

type StoredMessage struct {
	ID               int64     `db:"id"`
	ConversationID   string    `db:"conversation_id"`
	Role             string    `db:"role"`
	Content          string    `db:"content"`
	ReasoningContent string    `db:"reasoning_content"`
	TokensUsed       int       `db:"tokens_used"`
	Cost             float64   `db:"cost"`
	Model            string    `db:"model"`
	Provider         string    `db:"provider"`
	TokensPrompt     int       `db:"tokens_prompt"`
	TokensCompletion int       `db:"tokens_completion"`
	TokensCached     int       `db:"tokens_cached"`
	CreatedAt        time.Time `db:"created_at"`
}

type TelemetryStore interface {
	AddToolCalls(ctx context.Context, convID string, messageID int64, calls []ToolCallRecord) error
	AddSkillUsages(ctx context.Context, convID string, messageID int64, skills []SkillUsageRecord) error
	UpdateConversationStats(ctx context.Context, convID, agent string, msg StoredMessage, toolCallCount, toolErrorCount int) error
	GetConversationStats(ctx context.Context, convID string) (*ConversationStatsRow, error)
	ListConversationsWithStats(ctx context.Context, opts SessionListOpts) ([]ConversationInfoWithStats, int, error)
	GetToolCalls(ctx context.Context, convID string) ([]ToolCallRecord, error)
	GetSkillUsages(ctx context.Context, convID string) ([]SkillUsageRecord, error)
	GetTelemetrySummary(ctx context.Context, since, until *time.Time) (*TelemetrySummary, error)
	GetCostsByAgent(ctx context.Context) ([]AgentCostSummary, error)
	GetCostsByProvider(ctx context.Context) ([]ProviderCostSummary, error)
	PruneByCount(ctx context.Context, maxConversations int) (int, error)

	BumpSkillView(ctx context.Context, agent, skill string) error
	BumpSkillUse(ctx context.Context, agent, skill string) error
	BumpSkillPatch(ctx context.Context, agent, skill string) error
	GetSkillUsage(ctx context.Context, agent, skill string) (*SkillUsageStats, error)
	ListSkillUsage(ctx context.Context, agent string) ([]SkillUsageStats, error)
	SetSkillState(ctx context.Context, agent, skill, state string) error
	SetSkillPinned(ctx context.Context, agent, skill string, pinned bool) error
	SetSkillOrigin(ctx context.Context, agent, skill, origin string) error

	SearchMessages(ctx context.Context, query string, limit int, agentFilter string) ([]MessageSearchHit, error)
}

type TelemetrySummary struct {
	ByModel []ModelCostSummary  `json:"by_model"`
	ByTool  []ToolUsageSummary  `json:"by_tool"`
	BySkill []SkillUsageSummary `json:"by_skill"`
	// ByToolSkill breaks tool reliability down per owning (skill, version) so
	// callers can compare a skill's tool behaviour across versions (e.g. did an
	// edit reduce failures?). Only attributed tool calls appear here.
	ByToolSkill []ToolSkillUsageSummary `json:"by_tool_skill"`
}

type ToolCallRecord struct {
	ID             int64  `db:"id"              json:"id"`
	MessageID      int64  `db:"message_id"      json:"message_id"`
	ConversationID string `db:"conversation_id" json:"conversation_id"`
	ToolName       string `db:"tool_name"       json:"tool_name"`
	ServerName     string `db:"server_name"     json:"server_name"`
	Round          int    `db:"round"           json:"round"`
	DurationMs     int64  `db:"duration_ms"     json:"duration_ms"`
	Success        bool   `db:"success"         json:"success"`
	// Outcome refines Success: "ok", "rejected" (healthy tool, bad args),
	// "failed" (transport/exec failure), "denied" (approval denied),
	// "cached" (identical idempotent call served from the within-turn cache;
	// Success true, DurationMs 0, nothing executed), or "suppressed" (a write
	// refused by a dry-run/eval execution policy; Success true, nothing ran).
	Outcome string `db:"outcome"    json:"outcome"`
	// Arguments and Result are in-memory only — AddToolCalls inserts an
	// explicit column list, so these never reach the database. They exist so a
	// caller holding the returned records (the dry-run transcript, an eval
	// sample) can show what the call actually did; live turns still persist
	// name/server/round/outcome only.
	Arguments string `db:"-" json:"arguments,omitempty"`
	Result    string `db:"-" json:"result,omitempty"`
	// SkillName / SkillVersion identify the skill that owned the turn this
	// call ran under, when ownership is unambiguous (single-skill/scheduled
	// turns). Blank for interactive multi-match or unmatched turns.
	SkillName    string    `db:"skill_name"    json:"skill_name,omitempty"`
	SkillVersion string    `db:"skill_version" json:"skill_version,omitempty"`
	ErrorMsg     string    `db:"error_msg"  json:"error_msg,omitempty"`
	CreatedAt    time.Time `db:"created_at" json:"created_at"`
}

type ToolSkillUsageSummary struct {
	SkillName      string  `db:"skill_name"      json:"skill_name"`
	SkillVersion   string  `db:"skill_version"   json:"skill_version"`
	ToolName       string  `db:"tool_name"       json:"tool_name"`
	ServerName     string  `db:"server_name"     json:"server_name"`
	CallCount      int     `db:"call_count"      json:"call_count"`
	RejectionCount int     `db:"rejection_count" json:"rejection_count"`
	FailureCount   int     `db:"failure_count"   json:"failure_count"`
	DenialCount    int     `db:"denial_count"    json:"denial_count"`
	CachedCount    int     `db:"cached_count"    json:"cached_count"`
	AvgDuration    float64 `db:"avg_duration"    json:"avg_duration_ms"`
}

type ToolUsageSummary struct {
	ToolName   string `db:"tool_name"     json:"tool_name"`
	ServerName string `db:"server_name"   json:"server_name"`
	CallCount  int    `db:"call_count"    json:"call_count"`
	// The non-ok outcomes are split into RejectionCount (healthy tool, bad
	// args), FailureCount (transport/exec failures), and DenialCount (approval
	// denials), so a "healthy but argued-with" or denied tool isn't reported as
	// broken. The legacy combined error_count field (rejected + failed + denied)
	// was removed from the payload — it conflated denials with real failures and
	// was misread as a "broken tool" signal (see issue #215). Reconstruct the old
	// total as RejectionCount + FailureCount + DenialCount if needed.
	RejectionCount int `db:"rejection_count" json:"rejection_count"`
	FailureCount   int `db:"failure_count"   json:"failure_count"`
	DenialCount    int `db:"denial_count"    json:"denial_count"`
	// CachedCount counts calls served from the within-turn idempotent-result
	// cache. Included in CallCount (the model did make the call) but excluded
	// from AvgDuration (0ms hits would make a slow tool look fast).
	CachedCount int     `db:"cached_count"    json:"cached_count"`
	AvgDuration float64 `db:"avg_duration"    json:"avg_duration_ms"`
}

type TraceMessage struct {
	Role    string `json:"role"`
	Content string `json:"content"`
}

type TracePayload struct {
	SystemPrompt string           `json:"system_prompt"`
	History      []TraceMessage   `json:"history"`
	Prompt       string           `json:"prompt"`
	Response     string           `json:"response"`
	Rounds       []TraceRound     `json:"rounds"`
	Truncation   *TraceTruncation `json:"truncation,omitempty"`
}

type TraceRound struct {
	Round     int             `json:"round"`
	ToolCalls []TraceToolCall `json:"tool_calls"`
}

type TraceSink interface {
	SaveTrace(ctx context.Context, t TurnTrace) error
}

type TraceToolCall struct {
	Tool       string `json:"tool"`
	Server     string `json:"server,omitempty"`
	Outcome    string `json:"outcome"`
	DurationMs int64  `json:"duration_ms"`
	Arguments  string `json:"arguments,omitempty"`
	Result     string `json:"result,omitempty"`
	Error      string `json:"error,omitempty"`
}

type TraceTruncation struct {
	DroppedRounds  int    `json:"dropped_rounds,omitempty"`
	DroppedHistory int    `json:"dropped_history,omitempty"`
	ClampedText    bool   `json:"clamped_text,omitempty"`
	Note           string `json:"note"`
}

type TurnMessage struct {
	Role    string `db:"role"    json:"role"`
	Content string `db:"content" json:"content"`
}

type TurnResult struct {
	// ConversationID is the in-flight identity the turn ran under.
	ConversationID string `json:"conversation_id"`
	// Prompt is the message text that was sent, after any header injection.
	Prompt string `json:"prompt"`
	// Response is the final assistant text.
	Response string `json:"response"`
	// ToolCalls are the calls this turn made, in execution order, carrying
	// arguments and results (in-memory only — nothing was written).
	ToolCalls []ToolCallRecord `json:"tool_calls"`
	// Rounds is the number of tool-call rounds the turn used.
	Rounds int `json:"rounds"`
	// StopReason is why the tool loop ended, as a machine-readable slug
	// ("repeated_calls", "max_rounds", "stop_requested"). Empty means the model
	// finished on its own — the ordinary case. It is the only non-textual
	// signal that a turn was cut short: the alternative is scraping the
	// "[engine: turn ended early — …]" marker out of the response body.
	StopReason string `json:"stop_reason,omitempty"`
	// Tokens and Cost cover the whole turn, accumulated across rounds.
	Tokens  llm.TokenUsage `json:"tokens"`
	CostUSD float64        `json:"cost_usd"`
	// Model and Provider identify what actually answered — read back from the
	// response, so an override that the provider silently redirected shows the
	// model that really ran rather than the one that was asked for.
	Model    string `json:"model"`
	Provider string `json:"provider"`
	// Upstream is the provider-reported serving upstream (OpenRouter's routed
	// provider), empty when the provider has no such concept.
	Upstream string `json:"upstream,omitempty"`
	// RequestedModel is the override the caller asked for, empty when the turn
	// ran the agent's live model. The pair is what lets a transcript say "this
	// is not your live model" without the UI having to know the agent config.
	RequestedModel string `json:"requested_model,omitempty"`
	// ReplyGuard is the reply sanity guard verdict, omitted when nothing
	// tripped. A preview evaluates the guard but never substitutes the text,
	// so this is the only place a previewed trip is visible — Response still
	// holds what the model actually produced.
	ReplyGuard *ReplyGuardVerdict `json:"reply_guard,omitempty"`
	// AsOf is the clock the turn ran under.
	AsOf time.Time `json:"as_of"`
	// DurationMs is wall-clock time for the whole turn.
	DurationMs int64 `json:"duration_ms"`
	// Trace is the full L1 turn trace — the built system prompt, the history
	// window as sent, and the per-round tool calls with their payloads. A
	// policy turn always builds one and never persists it: isolation is
	// structural, so the caller decides where it goes (the eval runner stores
	// it; a dry-run preview renders it and drops it).
	Trace *TurnTrace `json:"trace,omitempty"`
}

type TurnTrace struct {
	ID             int64  `json:"id"`
	Agent          string `json:"agent"`
	ConversationID string `json:"conversation_id"`
	Source         string `json:"source"`
	Model          string `json:"model,omitempty"`
	Provider       string `json:"provider,omitempty"`
	// RequestedModel is the override the turn asked for, empty when it ran the
	// agent's live model.
	RequestedModel string `json:"requested_model,omitempty"`
	// Upstream is the provider-reported serving upstream, empty for providers
	// without the concept.
	Upstream   string         `json:"upstream,omitempty"`
	Rounds     int            `json:"rounds"`
	StopReason string         `json:"stop_reason,omitempty"`
	Tokens     llm.TokenUsage `json:"tokens"`
	CostUSD    float64        `json:"cost_usd"`
	LatencyMs  int64          `json:"latency_ms"`
	StartedAt  time.Time      `json:"started_at"`
	CreatedAt  time.Time      `json:"created_at"`
	// Truncated reports that the byte cap removed something; the detail is in
	// Payload.Truncation.
	Truncated bool `json:"truncated"`
	// Bytes is the encoded payload size after truncation.
	Bytes   int          `json:"bytes"`
	Payload TracePayload `json:"payload"`
	// contains filtered or unexported fields
}