observatory

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

type AgentAssignment struct {
	ID                 string                `json:"id"`
	TaskID             string                `json:"task_id"`
	AgentID            string                `json:"agent_id"`
	Provider           Provider              `json:"provider"`
	Status             AgentAssignmentStatus `json:"status"`
	AssignedAt         time.Time             `json:"assigned_at"`
	StartedAt          *time.Time            `json:"started_at,omitempty"`
	CompletedAt        *time.Time            `json:"completed_at,omitempty"`
	ParentAssignmentID string                `json:"parent_assignment_id,omitempty"`

	// Agent-level aggregates
	DurationMs int64   `json:"duration_ms"`
	TokensIn   int64   `json:"tokens_in"`
	TokensOut  int64   `json:"tokens_out"`
	CostUSD    float64 `json:"cost_usd"`
	ToolCalls  int     `json:"tool_calls"`
	Turns      int     `json:"turns"`
}

type AgentAssignmentStatus string

type AgentHierarchy struct {
	Agent  *AgentAssignment  `json:"agent"`
	Traces []*TraceHierarchy `json:"traces"`
}

type AgentStats struct {
	AgentID         string   `json:"agent_id"`
	Provider        Provider `json:"provider"`
	ExecutionCount  int      `json:"execution_count"`
	TotalDurationMs int64    `json:"total_duration_ms"`
	AvgDurationMs   float64  `json:"avg_duration_ms"`
	TotalTokensIn   int64    `json:"total_tokens_in"`
	TotalTokensOut  int64    `json:"total_tokens_out"`
	TotalCost       float64  `json:"total_cost"`
	TotalToolCalls  int      `json:"total_tool_calls"`
	SuccessRate     float64  `json:"success_rate"`
}

type AgentStatsResult struct {
	AgentID   string  `json:"agent_id"`
	Stages    int     `json:"stages"`
	Completed int     `json:"completed"`
	Failed    int     `json:"failed"`
	TotalCost float64 `json:"total_cost"`
	TokensIn  int     `json:"total_tokens_in"`
	TokensOut int     `json:"total_tokens_out"`
}

type ApprovalStatus string

type ApprovalType string

type Backend interface {
	// Workspace operations
	CreateWorkspace(ctx context.Context, w *Workspace) error
	GetWorkspace(ctx context.Context, id string) (*Workspace, error)
	ListWorkspaces(ctx context.Context) ([]*Workspace, error)
	UpdateWorkspace(ctx context.Context, w *Workspace) error
	DeleteWorkspace(ctx context.Context, id string) error
	GetWorkspaceStats(ctx context.Context, id string) (*WorkspaceStats, error)

	// Task operations
	CreateTask(ctx context.Context, t *Task) error
	GetTask(ctx context.Context, id string) (*Task, error)
	ListTasks(ctx context.Context, opts TaskListOptions) ([]*Task, error)
	UpdateTask(ctx context.Context, t *Task) error
	DeleteTask(ctx context.Context, id string) error

	// Agent assignment operations
	CreateAgentAssignment(ctx context.Context, a *AgentAssignment) error
	GetAgentAssignment(ctx context.Context, id string) (*AgentAssignment, error)
	ListAgentAssignments(ctx context.Context, taskID string) ([]*AgentAssignment, error)
	UpdateAgentAssignment(ctx context.Context, a *AgentAssignment) error
	DeleteAgentAssignment(ctx context.Context, id string) error
	GetAgentStats(ctx context.Context, agentID string) (*AgentStats, error)

	// Span operations
	CreateSpan(ctx context.Context, span *Span) error
	GetSpan(ctx context.Context, id string) (*Span, error)
	ListSpans(ctx context.Context, opts SpanListOptions) ([]*Span, error)
	UpdateSpan(ctx context.Context, span *Span) error
	UpdateSpanLinks(ctx context.Context, spanID, taskID, assignmentID string) error
	RecalculateTaskAggregates(ctx context.Context, taskID string) error
	DeleteSpan(ctx context.Context, id string) error
	GetTrace(ctx context.Context, traceID string) (*Trace, error)
	ListTraces(ctx context.Context, opts TraceQuery) ([]*TraceSummary, error)
	// LookupTaskBySessionID finds task hierarchy for Claude Code session correlation
	LookupTaskBySessionID(ctx context.Context, sessionID string) (taskID, assignmentID, traceID string)
	// LinkOrphanedSpansBySession updates spans with matching session.id that lack task linkage
	// Called after storing claude.execute span to retroactively link orphaned Claude Code events
	LinkOrphanedSpansBySession(ctx context.Context, sessionID, taskID, assignmentID string) (int64, error)

	// Session operations (M-SESSION-WORKSPACE-HOOKS)
	// GetSessionWorkspace returns workspace for a session (for span enrichment)
	GetSessionWorkspace(sessionID string) (string, error)
	// UpsertSession inserts or updates a session record from hook data
	UpsertSession(ctx context.Context, sessionID, workspace, version, source string) error
	// UpsertSessionWithCorrelation inserts/updates a session with correlation IDs (M-DETERMINISTIC-CHAT-LINKING)
	UpsertSessionWithCorrelation(ctx context.Context, sessionID, workspace, version, source string, corr *SessionCorrelation) error
	// UpdateSessionEnded marks a session as ended
	UpdateSessionEnded(ctx context.Context, sessionID string) error
	// InsertToolStart records the start of a tool call
	InsertToolStart(ctx context.Context, sessionID, toolUseID, toolName, toolInput string) error
	// FindLatestUnfinishedTool finds the most recent tool call that hasn't completed yet
	// Used to correlate PostToolUse with PreToolUse when tool_use_id is not provided
	FindLatestUnfinishedTool(ctx context.Context, sessionID, toolName string) (string, error)
	// UpdateToolEnd records the completion of a tool call
	UpdateToolEnd(ctx context.Context, toolUseID, toolResponse string, success bool) error
	// GetToolForSpan finds the session_tool that best matches a span by timestamp + tool name
	GetToolForSpan(ctx context.Context, sessionID, toolName string, spanTime time.Time) (*SessionTool, error)
	// BackfillSpansWorkspace updates existing spans that have session.id but missing workspace
	BackfillSpansWorkspace(ctx context.Context, sessionID, workspace string) (int64, error)

	// Span event operations
	CreateSpanEvent(ctx context.Context, e *SpanEvent) error
	GetSpanEvents(ctx context.Context, spanID string) ([]SpanEvent, error)
	DeleteSpanEvent(ctx context.Context, id int64) error

	// Message operations
	CreateMessage(ctx context.Context, m *Message) error
	GetMessage(ctx context.Context, id string) (*Message, error)
	ListMessages(ctx context.Context, opts MessageListOptions) ([]*Message, error)
	UpdateMessage(ctx context.Context, m *Message) error
	DeleteMessage(ctx context.Context, id string) error
	MarkMessageRead(ctx context.Context, id string) error
	MarkMessageArchived(ctx context.Context, id string) error

	// Aggregate operations
	GetMetricsSummary(ctx context.Context) (*MetricsSummary, error)
	GetProviderComparison(ctx context.Context) ([]*ProviderComparison, error)
	GetTaskTimeline(ctx context.Context, taskID string) ([]*TaskTimeline, error)
	// GetExecTaskHierarchy returns hierarchy of ailang command spans (exec, run, check)
	GetExecTaskHierarchy(ctx context.Context, limit int) ([]*ExecTaskNode, error)
	// GetExecTaskHierarchyWithMessages returns hierarchy grouped by triggering messages (4-level)
	GetExecTaskHierarchyWithMessages(ctx context.Context, limit int) (*ExecHierarchyWithMessages, error)
	// GetSpanHierarchy returns hierarchical tree of spans using parent_span_id relationships
	GetSpanHierarchy(ctx context.Context, limit int) (*SpanHierarchyResult, error)
	// GetToolsByTimestampRange returns session tools within a time range for enrichment
	GetToolsByTimestampRange(ctx context.Context, start, end time.Time, toolName string) ([]SessionTool, error)

	// Metric operations (Claude Code telemetry metrics)
	CreateMetric(ctx context.Context, m *Metric) error
	ListMetrics(ctx context.Context, opts MetricListOptions) ([]*Metric, error)
	GetSessionMetricsSummary(ctx context.Context, sessionID string) (*SessionMetricsSummary, error)

	// Session detail operations (M-CHAINS-SOURCE-OF-TRUTH)
	GetSession(ctx context.Context, sessionID string) (*Session, error)
	GetSessionTools(ctx context.Context, sessionID string) ([]SessionTool, error)

	// Chat message operations (M-CHAINS-SOURCE-OF-TRUTH)
	GetChatMessagesByTaskID(ctx context.Context, taskID string) ([]*ChatMessage, error)
	GetChatMessagesBySession(ctx context.Context, sessionID string, startTime, endTime time.Time) ([]*ChatMessage, error)
	CountChatMessages(ctx context.Context, q ChatMessageQuery) (total int, withTaskID int, err error)

	// Chain operations (M-CHAINS-SIMPLIFY unified hierarchy)
	CreateChain(ctx context.Context, req *ChainCreateRequest) (*ExecutionChain, error)
	GetChain(ctx context.Context, id string, opts ChainReadOptions) (*ExecutionChain, error)
	GetChainByMessageID(ctx context.Context, messageID string) (*ExecutionChain, error)
	GetChainByTaskID(ctx context.Context, taskID string) (*ExecutionChain, error)
	GetChainByGitHubIssue(ctx context.Context, repo string, issueNumber int) (*ExecutionChain, error)
	ListChains(ctx context.Context, opts ChainListOptions) ([]*ChainSummary, error)
	UpdateChainStatus(ctx context.Context, chainID string, status ChainStatus) error
	UpdateChainMetrics(ctx context.Context, id string, cost float64, tokens, turns int) error
	GetChainStats(ctx context.Context) (*ChainStats, error)
	// GetChainStatusCounts returns chain counts grouped by status (single query, M-PERF-OBSERVATORY).
	GetChainStatusCounts(ctx context.Context, createdAfter *time.Time) (*ChainStatusCounts, error)
	// GetChainStatsByAgent returns per-agent stats in a single SQL query (replaces N+1, M-PERF-OBSERVATORY).
	GetChainStatsByAgent(ctx context.Context, createdAfter *time.Time) ([]*AgentStatsResult, error)

	// Chain stage operations
	CreateStage(ctx context.Context, req *StageCreateRequest) (*ChainStage, error)
	GetStage(ctx context.Context, id string) (*ChainStage, error)
	GetChainStages(ctx context.Context, chainID string, opts ChainReadOptions) ([]*ChainStage, error)
	UpdateStageStatus(ctx context.Context, stageID string, status ChainStageStatus) error
	UpdateStageSession(ctx context.Context, stageID, sessionID string) error
	UpdateStageApproval(ctx context.Context, stageID string, status ApprovalStatus, approvalType ApprovalType, feedback string) error
	UpdateStageMetrics(ctx context.Context, stageID string, cost float64, tokensIn, tokensOut, turns, toolCalls int, durationMs int64) error
	UpdateStageError(ctx context.Context, stageID, errorMessage string) error
	GetSpansByStageID(ctx context.Context, stageID string) ([]*Span, error)
	// GetSpanLitesByStageID returns lightweight spans without attributes (M-PERF-OBSERVATORY).
	GetSpanLitesByStageID(ctx context.Context, stageID string, limit, offset int) (*SpanLitePage, error)
	LinkSpanToChain(ctx context.Context, spanID, chainID, stageID string) error
	ListPendingApprovals(ctx context.Context, limit int) ([]*PendingApprovalInfo, error)

	// Lifecycle
	Close() error
}

type BreakdownItem struct {
	ID         string  `json:"id"`
	Label      string  `json:"label"`
	SpanCount  int     `json:"span_count"`
	TaskCount  int     `json:"task_count,omitempty"`
	TokensIn   int64   `json:"tokens_in"`
	TokensOut  int64   `json:"tokens_out"`
	CostUSD    float64 `json:"cost_usd"`
	DurationMs int64   `json:"duration_ms"` // Total execution time in ms

	// Cache metrics
	CacheReadTokens     int64   `json:"cache_read_tokens"`
	CacheCreationTokens int64   `json:"cache_creation_tokens"`
	CacheSavingsUSD     float64 `json:"cache_savings_usd"`
}

type ChainCreateRequest struct {
	SourceType        ChainSourceType `json:"source_type"`
	SourceRef         string          `json:"source_ref,omitempty"`
	GitHubRepo        string          `json:"github_repo,omitempty"`
	GitHubIssueNumber int             `json:"github_issue_number,omitempty"`
	WorkspaceID       string          `json:"workspace_id,omitempty"`
	WorkspacePath     string          `json:"workspace_path,omitempty"`
}

type ChainListOptions struct {
	Status       ChainStatus `json:"status,omitempty"`
	SourceType   string      `json:"source_type,omitempty"`
	WorkspaceID  string      `json:"workspace_id,omitempty"`
	GitHubRepo   string      `json:"github_repo,omitempty"`
	AgentID      string      `json:"agent_id,omitempty"`
	CreatedAfter *time.Time  `json:"created_after,omitempty"`
	Limit        int         `json:"limit,omitempty"`
	Offset       int         `json:"offset,omitempty"`
}

type ChainReadOptions struct {
	IncludeStages   bool `json:"include_stages"`   // Fetch stages
	IncludeSpans    bool `json:"include_spans"`    // Fetch spans for each stage
	IncludeSessions bool `json:"include_sessions"` // Fetch session data for each stage
}

type ChainSourceType string

type ChainStage struct {
	ID          string `json:"id"` // UUID
	ChainID     string `json:"chain_id"`
	StageNumber int    `json:"stage_number"`

	// Agent info
	AgentID  string   `json:"agent_id"`
	Provider Provider `json:"provider,omitempty"`

	// Links to other tables (foreign keys or cross-DB IDs)
	MessageID string `json:"message_id,omitempty"` // -> collaboration.db:inbox_messages.id
	TaskID    string `json:"task_id,omitempty"`    // -> coordinator.db:tasks.id
	SessionID string `json:"session_id,omitempty"` // -> sessions.session_id

	// State
	Status         ChainStageStatus `json:"status"`
	ApprovalStatus ApprovalStatus   `json:"approval_status,omitempty"`
	ApprovalType   ApprovalType     `json:"approval_type,omitempty"`

	// Handoff info
	HandoffTo     string `json:"handoff_to,omitempty"`
	Iteration     int    `json:"iteration"`
	HumanFeedback string `json:"human_feedback,omitempty"`

	// Timestamps
	StartedAt   *time.Time `json:"started_at,omitempty"`
	CompletedAt *time.Time `json:"completed_at,omitempty"`

	// Summary (denormalized from spans)
	Cost       float64 `json:"cost"`
	TokensIn   int     `json:"tokens_in"`
	TokensOut  int     `json:"tokens_out"`
	Turns      int     `json:"turns"`
	ToolCalls  int     `json:"tool_calls"`
	DurationMs int64   `json:"duration_ms"`

	// Error tracking
	ErrorMessage string `json:"error_message,omitempty"`
	ErrorCount   int    `json:"error_count"`

	// Eval assessment (M-EVAL-CHAINS: populated for eval_suite chains)
	EvalAssessment *EvalAssessment `json:"eval_assessment,omitempty"`

	// Session data (populated on read with full=true)
	Session *Session `json:"session,omitempty"`

	// Spans (populated on read with include_spans=true)
	Spans []*Span `json:"spans,omitempty"`
}

type ChainStageStatus string

type ChainStats struct {
	TotalChains        int     `json:"total_chains"`
	ActiveChains       int     `json:"active_chains"`
	PendingApprovals   int     `json:"pending_approvals"`
	CompletedChains    int     `json:"completed_chains"`
	FailedChains       int     `json:"failed_chains"`
	TotalCost          float64 `json:"total_cost"`
	TotalTokens        int64   `json:"total_tokens"`
	AverageStagesCount float64 `json:"average_stages_count"`
	AverageDurationMs  float64 `json:"average_duration_ms"`
}

type ChainStatus string

type ChainStatusCounts struct {
	Total       int     `json:"total_chains"`
	Completed   int     `json:"completed"`
	Active      int     `json:"active"`
	Pending     int     `json:"pending_approval"`
	Failed      int     `json:"failed"`
	TotalCost   float64 `json:"total_cost"`
	TotalTokens int64   `json:"total_tokens"`
}

type ChainSummary struct {
	ID                string      `json:"id"`
	SourceType        string      `json:"source_type"`
	SourceRef         string      `json:"source_ref"`
	GitHubRepo        string      `json:"github_repo,omitempty"`
	GitHubIssueNumber int         `json:"github_issue_number,omitempty"`
	Status            ChainStatus `json:"status"`
	CurrentStage      int         `json:"current_stage"`
	TotalCost         float64     `json:"total_cost"`
	TotalTokens       int         `json:"total_tokens"`
	TotalTurns        int         `json:"total_turns"`
	StagesCompleted   int         `json:"stages_completed"`
	CreatedAt         time.Time   `json:"created_at"`
	CompletedAt       *time.Time  `json:"completed_at,omitempty"`
	StageCount        int         `json:"stage_count"`
	MaxStage          int         `json:"max_stage"`
	AgentFlow         string      `json:"agent_flow"` // e.g., "design-doc-creator -> sprint-planner -> sprint-executor"
}

type ChatContext struct {
	UserPrompt        string `json:"user_prompt,omitempty"`        // First 500 chars of user prompt
	AssistantResponse string `json:"assistant_response,omitempty"` // First 500 chars of response
	HasThinking       bool   `json:"has_thinking"`
	TurnNumber        int    `json:"turn_number,omitempty"`
	FullChatURL       string `json:"full_chat_url,omitempty"` // Link to full conversation
}

type ChatMessage struct {
	ID          string    `json:"id"`
	SessionID   string    `json:"session_id"`
	TurnNumber  int       `json:"turn_number"`
	Role        string    `json:"role"`
	ContentJSON string    `json:"content_json,omitempty"` // Raw JSON content blocks
	TokensIn    int       `json:"tokens_in,omitempty"`
	TokensOut   int       `json:"tokens_out,omitempty"`
	Model       string    `json:"model,omitempty"`
	Timestamp   time.Time `json:"timestamp"`
	TaskID      string    `json:"task_id,omitempty"`
	ChainID     string    `json:"chain_id,omitempty"`
}

type ChatMessageQuery struct {
	TaskID    string
	SessionID string
	StartTime time.Time
	EndTime   time.Time
	Limit     int
}

type ClaudeCodeEvent struct {
	ID             string  `json:"id"`           // span_id (also used as task_id for hierarchy lookup)
	CreatedAt      string  `json:"created_at"`   // ISO8601 timestamp (matches inbox message format)
	Type           string  `json:"message_type"` // "claude_code_turn"
	FromAgent      string  `json:"from_agent"`   // Agent ID (e.g., "design-doc-creator") or "claude-code" for user sessions
	ToInbox        string  `json:"to_inbox"`     // Agent inbox (e.g., "design-doc-creator") or "user" for user sessions
	Title          string  `json:"title"`        // "Claude Code Turn ($X.XX)"
	TaskID         string  `json:"task_id"`      // Same as ID for hierarchy lookup
	Status         string  `json:"status"`       // "read" (not actionable like inbox messages)
	CostUSD        float64 `json:"cost_usd"`
	TokensIn       int64   `json:"tokens_in"`
	TokensOut      int64   `json:"tokens_out"`
	DurationMs     int     `json:"duration_ms"`
	Workspace      string  `json:"workspace,omitempty"`       // Working directory (from resource attributes)
	Model          string  `json:"model,omitempty"`           // Model used for this event (e.g., "claude-sonnet-4-5")
	Provider       string  `json:"provider,omitempty"`        // AI provider (e.g., "claude", "gemini")
	Directive      string  `json:"directive,omitempty"`       // Initial user prompt (truncated preview)
	DirectiveFull  string  `json:"directive_full,omitempty"`  // Full directive (for detail views)
	TurnCount      int     `json:"turn_count"`                // Number of turns in session
	MetricsSummary string  `json:"metrics_summary,omitempty"` // "3 turns • $0.42 • 12.5s"
}

type ClaudeEvent struct {
	Type         string         `json:"type"` // "tool_call", "approval", "error"
	Timestamp    time.Time      `json:"timestamp"`
	ToolName     string         `json:"tool_name,omitempty"`
	ToolInput    map[string]any `json:"tool_input,omitempty"`
	ToolResult   string         `json:"tool_result,omitempty"`
	Approved     *bool          `json:"approved,omitempty"`
	ErrorMessage string         `json:"error_message,omitempty"`
}

type ClaudeMetrics struct {
	SessionID     string    `json:"session_id"`
	TaskID        string    `json:"task_id,omitempty"`
	Model         string    `json:"model"`
	TotalTokensIn int64     `json:"total_input_tokens"`
	TotalTokenOut int64     `json:"total_output_tokens"`
	TotalCostUSD  float64   `json:"total_cost_usd"`
	DurationMs    int64     `json:"duration_ms"`
	TurnCount     int       `json:"turn_count"`
	ToolCalls     int       `json:"tool_calls"`
	StartTime     time.Time `json:"start_time"`
	EndTime       time.Time `json:"end_time"`
	Status        string    `json:"status"` // "completed", "failed", "cancelled"
	ErrorMessage  string    `json:"error_message,omitempty"`

	// Events captured during session
	Events []ClaudeEvent `json:"events,omitempty"`
}

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

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

type CompositeConfig struct {
	Local   Backend   // Required: local storage backend
	Remotes []Backend // Optional: remote backends for trace queries
}

type ControlPlaneFilter struct {
	SourceType string // eval, coordinator, direct_api, local, other
	Provider   string // claude, gemini, openai, etc.
	Model      string // claude-sonnet-4-5, gemini-2-5-pro, etc.
	Workspace  string // workspace ID
	StartDate  string // YYYY-MM-DD format for time range filter (inclusive)
	EndDate    string // YYYY-MM-DD format for time range filter (inclusive)
}

type CumulativePoint struct {
	SpanIndex    int       `json:"span_index"`
	SpanName     string    `json:"span_name"`
	Timestamp    time.Time `json:"timestamp"`
	Value        float64   `json:"value"`         // Value of this span
	Cumulative   float64   `json:"cumulative"`    // Running total up to this span
	DeltaPercent float64   `json:"delta_percent"` // This span's contribution as % of final total
}

type EvalAssessment struct {
	// Identity
	BenchmarkID string `json:"benchmark_id"`
	Model       string `json:"model"`
	Language    string `json:"language"`
	Condition   string `json:"condition,omitempty"`
	EvalMode    string `json:"eval_mode"`          // "agent" or "standard"
	Executor    string `json:"executor,omitempty"` // "claude", "gemini"
	Seed        int64  `json:"seed"`

	// Assessment results
	CompileOk     bool   `json:"compile_ok"`
	RuntimeOk     bool   `json:"runtime_ok"`
	StdoutOk      bool   `json:"stdout_ok"`
	ErrorCategory string `json:"error_category"`

	// Self-repair
	FirstAttemptOk bool   `json:"first_attempt_ok"`
	RepairUsed     bool   `json:"repair_used"`
	RepairOk       bool   `json:"repair_ok"`
	ErrCode        string `json:"err_code,omitempty"`

	// Contract verification
	VerifyOk        bool `json:"verify_ok"`
	VerifyVerified  int  `json:"verify_verified"`
	VerifyCounterex int  `json:"verify_counterexample"`
	VerifySkipped   int  `json:"verify_skipped"`
	VerifyErrors    int  `json:"verify_errors"`

	// Reproducibility
	PromptVersion string `json:"prompt_version,omitempty"`
	CodeHash      string `json:"code_hash,omitempty"`

	// Output (truncated for storage efficiency)
	Code           string `json:"code,omitempty"`
	Stdout         string `json:"stdout,omitempty"`
	ExpectedStdout string `json:"expected_stdout,omitempty"`
	Stderr         string `json:"stderr,omitempty"`
}

type EvalQueryOptions struct {
	ChainID     string // Filter by chain
	Model       string // Filter by model
	Language    string // Filter by language
	BenchmarkID string // Filter by benchmark
	Condition   string // Filter by experimental condition
	EvalMode    string // "standard" or "agent"
	SuccessOnly bool   // Only passing benchmarks (stdout_ok = true)
	FailureOnly bool   // Only failing benchmarks (stdout_ok = false)
	Limit       int
}

type Event struct {
	Type      WSEventType `json:"type"`
	Timestamp time.Time   `json:"timestamp"`
	Data      any         `json:"data"`
}

type EventType string

type ExecHierarchyWithMessages struct {
	Messages []*MessageNode  `json:"messages,omitempty"` // Messages that triggered execs
	Orphan   []*ExecTaskNode `json:"orphan,omitempty"`   // Execs without a triggering message
	Count    int             `json:"count"`
}

type ExecTaskNode struct {
	TaskID       string          `json:"task_id"`
	ParentTaskID string          `json:"parent_task_id"`
	Command      string          `json:"command"`   // exec, run, check, turn, tool_use
	Provider     string          `json:"provider"`  // for exec: claude, gemini, etc.
	Workspace    string          `json:"workspace"` // for exec
	FilePath     string          `json:"file_path"` // for run, check
	Status       string          `json:"status"`
	StartTime    *time.Time      `json:"start_time,omitempty"`
	DurationMs   int             `json:"duration_ms,omitempty"`
	Children     []*ExecTaskNode `json:"children,omitempty"`
	// Turn/tool specific fields
	TurnNumber  int    `json:"turn_number,omitempty"`  // for turn spans
	ToolName    string `json:"tool_name,omitempty"`    // for tool_use spans
	ToolInput   string `json:"tool_input,omitempty"`   // for tool_use spans
	ToolOutput  string `json:"tool_output,omitempty"`  // for tool_use spans
	DisplayName string `json:"display_name,omitempty"` // enriched name from session_tools (e.g., "Read: /path/file.go")
}

type ExecutionChain struct {
	ID string `json:"id"` // UUID

	// Source (what triggered this chain)
	SourceType        ChainSourceType `json:"source_type"`
	SourceRef         string          `json:"source_ref,omitempty"`
	GitHubRepo        string          `json:"github_repo,omitempty"`
	GitHubIssueNumber int             `json:"github_issue_number,omitempty"`

	// Current state
	Status       ChainStatus `json:"status"`
	CurrentStage int         `json:"current_stage"`

	// Workspace context
	WorkspaceID   string `json:"workspace_id,omitempty"`
	WorkspacePath string `json:"workspace_path,omitempty"`

	// Timestamps
	CreatedAt   time.Time  `json:"created_at"`
	UpdatedAt   *time.Time `json:"updated_at,omitempty"`
	CompletedAt *time.Time `json:"completed_at,omitempty"`

	// Summary metrics (denormalized for quick queries)
	TotalCost       float64 `json:"total_cost"`
	TotalTokens     int     `json:"total_tokens"`
	TotalTurns      int     `json:"total_turns"`
	StagesCompleted int     `json:"stages_completed"`

	// Stages (populated on read)
	Stages []*ChainStage `json:"stages,omitempty"`
}

type FilterPattern struct {
	Type    string // "prefix", "exact", "suffix"
	Pattern string // The pattern to match against span name
	Service string // Optional: only match spans from this service (service.name)
}

type GCPConfig struct {
	ProjectID       string
	CredentialsPath string        // optional - uses default credentials if empty
	CacheTTL        time.Duration // Cache TTL for trace results (default: 60s)
}

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

type GeminiOTELSpan struct {
	TraceID           string        `json:"traceId"`
	SpanID            string        `json:"spanId"`
	ParentSpanID      string        `json:"parentSpanId,omitempty"`
	Name              string        `json:"name"`
	Kind              int           `json:"kind"` // OTEL span kind enum
	StartTimeUnixNano int64         `json:"startTimeUnixNano"`
	EndTimeUnixNano   int64         `json:"endTimeUnixNano"`
	Attributes        []KeyValue    `json:"attributes,omitempty"`
	Status            *OTELStatus   `json:"status,omitempty"`
	Events            []OTELEvent   `json:"events,omitempty"`
	Resource          *OTELResource `json:"resource,omitempty"`
}

type HealthAction string

type HeatmapDataPoint struct {
	Date        string  `json:"date"`         // YYYY-MM-DD
	SpanCount   int     `json:"span_count"`   // Number of spans
	TaskCount   int     `json:"task_count"`   // Number of distinct tasks
	Cost        float64 `json:"cost"`         // Total cost USD
	SuccessRate float64 `json:"success_rate"` // 0.0 to 1.0
	TokensIn    int64   `json:"tokens_in"`
	TokensOut   int64   `json:"tokens_out"`
}

type HierarchicalSpan struct {
	ID           string              `json:"id"`
	TraceID      string              `json:"trace_id"`
	ParentSpanID string              `json:"parent_span_id,omitempty"`
	Name         string              `json:"name"`
	DisplayName  string              `json:"display_name,omitempty"`
	StartTime    time.Time           `json:"start_time"`
	EndTime      *time.Time          `json:"end_time,omitempty"`
	DurationMs   int64               `json:"duration_ms"`
	Status       SpanStatus          `json:"status"`
	Attributes   map[string]any      `json:"attributes,omitempty"`
	Provider     Provider            `json:"provider,omitempty"`
	Model        string              `json:"model,omitempty"`
	TokensIn     int64               `json:"tokens_in,omitempty"`
	TokensOut    int64               `json:"tokens_out,omitempty"`
	CostUSD      float64             `json:"cost_usd,omitempty"`
	TaskID       string              `json:"task_id,omitempty"`
	ChatContext  *ChatContext        `json:"chat_context,omitempty"`
	Children     []*HierarchicalSpan `json:"children,omitempty"`
}

type HierarchyOptions struct {
	// MaxDepth limits the span tree depth (0 = unlimited)
	MaxDepth int
	// IncludeSpans controls whether to include individual spans
	IncludeSpans bool
	// Workspace filters spans to only include those belonging to this workspace path
	// This prevents cross-workspace span bleeding in hierarchy views
	Workspace string
	// WorkspaceID filters spans by workspace_id directly (set automatically from task)
	WorkspaceID string
}

type HierarchyTraceSummary struct {
	SpanCount    int     `json:"span_count"`
	TotalTokens  int64   `json:"total_tokens"`
	TotalCostUSD float64 `json:"total_cost_usd"`
	DurationMs   int64   `json:"duration_ms"`
	ErrorCount   int     `json:"error_count"`
}

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

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

type JaegerConfig struct {
	Endpoint string // Jaeger query endpoint (e.g., http://localhost:16686)
	Username string // Optional basic auth
	Password string
}

type JourneyResponse struct {
	ChainID string        `json:"chain_id"`
	Steps   []JourneyStep `json:"steps"`
	Summary string        `json:"summary"` // "Design doc approved -> Sprint planned -> Implementation in progress"
}

type JourneyStep struct {
	StageNumber    int     `json:"stage_number"`
	AgentID        string  `json:"agent_id"`
	Action         string  `json:"action"`                    // "Created design doc", "Planned sprint", etc.
	Status         string  `json:"status"`                    // completed, failed, running, etc.
	ApprovalStatus string  `json:"approval_status,omitempty"` // approved, rejected, pending
	Iteration      int     `json:"iteration"`
	Feedback       string  `json:"feedback,omitempty"`      // Truncated human feedback
	ErrorExcerpt   string  `json:"error_excerpt,omitempty"` // First line of error
	Cost           float64 `json:"cost"`
	DurationMs     int64   `json:"duration_ms"`
}

type KeyValue struct {
	Key   string     `json:"key"`
	Value ValueUnion `json:"value"`
}

type Message struct {
	ID          string        `json:"id"`
	TaskID      string        `json:"task_id,omitempty"`
	Inbox       string        `json:"inbox"`
	FromAgent   string        `json:"from_agent"`
	Title       string        `json:"title"`
	Content     string        `json:"content"`
	MessageType string        `json:"message_type"`
	Status      MessageStatus `json:"status"`
	Priority    string        `json:"priority"`

	// GitHub sync
	GitHubIssueNumber int    `json:"github_issue_number,omitempty"`
	GitHubRepo        string `json:"github_repo,omitempty"`

	// Correlation
	CorrelationID string `json:"correlation_id,omitempty"`
	ReplyToID     string `json:"reply_to_id,omitempty"`

	CreatedAt  time.Time  `json:"created_at"`
	ReadAt     *time.Time `json:"read_at,omitempty"`
	ArchivedAt *time.Time `json:"archived_at,omitempty"`

	// Search
	ContentHash string `json:"content_hash,omitempty"`
}

type MessageListOptions struct {
	Inbox     string
	Status    MessageStatus
	TaskID    string
	FromAgent string
	Limit     int
	Offset    int
}

type MessageNode struct {
	MessageID   string          `json:"message_id"`
	Title       string          `json:"title"`
	FromAgent   string          `json:"from_agent"`
	ToInbox     string          `json:"to_inbox"`
	MessageType string          `json:"message_type"`
	Status      string          `json:"status"`
	CreatedAt   *time.Time      `json:"created_at,omitempty"`
	Execs       []*ExecTaskNode `json:"execs,omitempty"`
}

type MessageStatus string

type Metric struct {
	ID        int64  `json:"id,omitempty"`
	Name      string `json:"name"`
	Type      string `json:"metric_type"` // "counter", "gauge"
	SessionID string `json:"session_id,omitempty"`
	Workspace string `json:"workspace,omitempty"`
	Provider  string `json:"provider,omitempty"`

	// Denormalized labels for efficient queries
	LabelType     string `json:"label_type,omitempty"`     // "added"/"removed" for LOC
	LabelTool     string `json:"label_tool,omitempty"`     // tool name for tool metrics
	LabelDecision string `json:"label_decision,omitempty"` // "approved"/"rejected" for code_edit_tool
	LabelLanguage string `json:"label_language,omitempty"` // language for LOC
	LabelModel    string `json:"label_model,omitempty"`    // model name for model-specific metrics

	// Values (only one will be set based on metric type)
	ValueInt   int64   `json:"value_int,omitempty"`
	ValueFloat float64 `json:"value_float,omitempty"`

	// Full labels as JSON (for provider-specific data)
	Labels             map[string]any `json:"labels,omitempty"`
	ResourceAttributes map[string]any `json:"resource_attributes,omitempty"`

	Timestamp time.Time `json:"timestamp"`
	CreatedAt time.Time `json:"created_at"`
}

type MetricListOptions struct {
	SessionID string     `json:"session_id,omitempty"`
	Workspace string     `json:"workspace,omitempty"`
	Name      string     `json:"name,omitempty"` // e.g., "claude_code.lines_of_code.count"
	TimeRange *TimeRange `json:"time_range,omitempty"`
	Limit     int        `json:"limit,omitempty"`
	Offset    int        `json:"offset,omitempty"`
}

type MetricsSummary struct {
	TotalWorkspaces int     `json:"total_workspaces"`
	TotalTasks      int     `json:"total_tasks"`
	TotalSpans      int     `json:"total_spans"`
	TotalAgents     int     `json:"total_agents"`
	TotalTokensIn   int64   `json:"total_tokens_in"`
	TotalTokensOut  int64   `json:"total_tokens_out"`
	TotalCostUSD    float64 `json:"total_cost_usd"`
	SuccessRate     float64 `json:"success_rate"`

	// Cache metrics (from spans)
	TotalCacheReadTokens     int64   `json:"total_cache_read_tokens,omitempty"`
	TotalCacheCreationTokens int64   `json:"total_cache_creation_tokens,omitempty"`
	CacheSavingsUSD          float64 `json:"cache_savings_usd,omitempty"`

	// Lines of Code metrics (from metrics table)
	LinesAdded   int64 `json:"lines_added,omitempty"`
	LinesRemoved int64 `json:"lines_removed,omitempty"`

	// Activity metrics (from metrics table)
	CommitCount      int64 `json:"commit_count,omitempty"`
	PullRequestCount int64 `json:"pull_request_count,omitempty"`
	ActiveTimeMs     int64 `json:"active_time_ms,omitempty"`

	// Session metrics
	TurnCount  int `json:"turn_count,omitempty"`
	ToolCalls  int `json:"tool_calls,omitempty"`
	ErrorCount int `json:"error_count,omitempty"`
}

type OTELEvent struct {
	Name         string     `json:"name"`
	TimeUnixNano int64      `json:"timeUnixNano"`
	Attributes   []KeyValue `json:"attributes,omitempty"`
}

type OTELResource struct {
	Attributes []KeyValue `json:"attributes,omitempty"`
}

type OTELStatus struct {
	Code    int    `json:"code"` // 0=Unset, 1=OK, 2=Error
	Message string `json:"message,omitempty"`
}

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

type OutlierAnalysis struct {
	TaskID       string             `json:"task_id"`
	TaskTitle    string             `json:"task_title"`
	SpanCount    int                `json:"span_count"`
	Stats        []*TaskMetricStats `json:"stats"`                    // Per-metric statistics
	Outliers     []*SpanOutlier     `json:"outliers"`                 // Detected outliers (sorted by |z-score| desc)
	RateOfChange *RateAnalysis      `json:"rate_of_change,omitempty"` // Optional rate analysis
	Threshold    float64            `json:"threshold"`                // Z-score threshold used
	AnalyzedAt   time.Time          `json:"analyzed_at"`
}

type OutlierOptions struct {
	Threshold float64 // Z-score threshold (default: 2.0)
	Metric    string  // Filter to specific metric: "cost", "duration", "tokens", or "" for all
	ShowRate  bool    // Include rate-of-change analysis
	Limit     int     // Max outliers to return (default: 10)
}

type PendingApprovalInfo struct {
	ChainID        string       `json:"chain_id"`
	SourceType     string       `json:"source_type"`
	SourceRef      string       `json:"source_ref"`
	StageID        string       `json:"stage_id"`
	StageNumber    int          `json:"stage_number"`
	AgentID        string       `json:"agent_id"`
	ApprovalStatus string       `json:"approval_status"`
	ApprovalType   ApprovalType `json:"approval_type"`
	TaskID         string       `json:"task_id"`
	SessionID      string       `json:"session_id"`
	Cost           float64      `json:"cost"`
	Turns          int          `json:"turns"`
	StageCreated   time.Time    `json:"stage_created"`
}

type Provider string

type ProviderComparison struct {
	Provider        Provider `json:"provider"`
	TotalExecutions int      `json:"total_executions"`
	TotalTokensIn   int64    `json:"total_tokens_in"`
	TotalTokensOut  int64    `json:"total_tokens_out"`
	TotalCost       float64  `json:"total_cost"`
	AvgDurationMs   float64  `json:"avg_duration_ms"`
	SuccessRate     float64  `json:"success_rate"`
}

type ProviderNormalizer struct{}