agent

type AgentError struct {
	// Code is a machine-readable error code.
	Code string `json:"code"`

	// Message is a human-readable error message.
	Message string `json:"message"`

	// Details contains additional error context.
	Details string `json:"details,omitempty"`

	// Recoverable indicates if the error might be resolved by retry.
	Recoverable bool `json:"recoverable"`

	// Step is the step where the error occurred.
	Step int `json:"step,omitempty"`
}

type AgentLoop interface {
	// Run starts a new session and processes a query.
	//
	// Description:
	//   Creates a new session, initializes the graph, assembles context,
	//   and executes the agent loop until completion or clarification needed.
	//
	// Inputs:
	//   ctx - Context for cancellation and timeout.
	//   session - The session to run (must be in IDLE state).
	//   query - The user's query.
	//
	// Outputs:
	//   *RunResult - The execution result.
	//   error - Non-nil if an unrecoverable error occurred.
	//
	// Thread Safety: This method is safe for concurrent use with different sessions.
	Run(ctx context.Context, session *Session, query string) (*RunResult, error)

	// Continue resumes a session from CLARIFY state.
	//
	// Description:
	//   Processes the user's clarification response and continues execution.
	//   Only valid when session is in CLARIFY state.
	//
	// Inputs:
	//   ctx - Context for cancellation and timeout.
	//   sessionID - The session ID to continue.
	//   clarification - The user's clarification response.
	//
	// Outputs:
	//   *RunResult - The execution result.
	//   error - Non-nil if session not found or not in CLARIFY state.
	//
	// Thread Safety: This method is safe for concurrent use.
	Continue(ctx context.Context, sessionID string, clarification string) (*RunResult, error)

	// Abort terminates a running session.
	//
	// Description:
	//   Stops a session that is currently executing. Does not affect
	//   sessions that are already in terminal states.
	//
	// Inputs:
	//   ctx - Context for the abort operation.
	//   sessionID - The session ID to abort.
	//
	// Outputs:
	//   error - Non-nil if session not found.
	//
	// Thread Safety: This method is safe for concurrent use.
	Abort(ctx context.Context, sessionID string) error

	// GetState returns the current state of a session.
	//
	// Inputs:
	//   sessionID - The session ID to query.
	//
	// Outputs:
	//   *SessionState - The session state.
	//   error - Non-nil if session not found.
	//
	// Thread Safety: This method is safe for concurrent use.
	GetState(sessionID string) (*SessionState, error)

	// GetSession returns the full session object.
	//
	// Description:
	//   Returns the complete Session for operations that need access
	//   to CRS, trace recorder, or other internal state not exposed
	//   through SessionState.
	//
	// Inputs:
	//   sessionID - The session ID to retrieve.
	//
	// Outputs:
	//   *Session - The full session object.
	//   error - Non-nil if session not found.
	//
	// Thread Safety: This method is safe for concurrent use.
	GetSession(sessionID string) (*Session, error)

	// ListSessions returns a summary of all active sessions.
	//
	// Description:
	//   Returns basic info about all sessions in the session store.
	//   Used by debug endpoints to show CRS state across sessions.
	//
	// Outputs:
	//   []*SessionSummary - List of session summaries.
	//
	// Thread Safety: This method is safe for concurrent use.
	ListSessions() []*SessionSummary

	// CloseSession permanently closes a session and releases all resources.
	//
	// Description:
	//   Closes a session that will no longer be used. This cleans up all
	//   session-specific state including UCB1 contexts, caches, and removes
	//   the session from the session store. Unlike Abort, this is for
	//   intentional cleanup when a session is definitively finished.
	//
	//   Call this when:
	//   - User explicitly ends the conversation
	//   - Session timeout for inactive sessions
	//   - Application shutdown cleanup
	//
	// Inputs:
	//   sessionID - The session ID to close.
	//
	// Outputs:
	//   error - Non-nil if session not found.
	//
	// Thread Safety: This method is safe for concurrent use.
	CloseSession(sessionID string) error
}

type AgentState string

type AssembledContext struct {
	// SystemPrompt is the system instructions.
	SystemPrompt string `json:"system_prompt"`

	// CodeContext contains code snippets.
	CodeContext []CodeEntry `json:"code_context"`

	// LibraryDocs contains library documentation.
	LibraryDocs []DocEntry `json:"library_docs"`

	// ToolResults contains recent tool outputs.
	ToolResults []ToolResult `json:"tool_results"`

	// ConversationHistory contains message history.
	ConversationHistory []Message `json:"conversation_history"`

	// TotalTokens is the current token count.
	TotalTokens int `json:"total_tokens"`

	// Relevance maps entry IDs to relevance scores.
	Relevance map[string]float64 `json:"relevance"`
}

type ClarifyRequest struct {
	// Question is what the agent needs to know.
	Question string `json:"question"`

	// Options are suggested clarification options.
	Options []string `json:"options,omitempty"`

	// Context explains why clarification is needed.
	Context string `json:"context,omitempty"`
}

type CodeEntry struct {
	// ID is a unique identifier for this entry.
	ID string `json:"id"`

	// FilePath is the relative path to the file.
	FilePath string `json:"file_path"`

	// SymbolName is the symbol name if applicable.
	SymbolName string `json:"symbol_name,omitempty"`

	// Content is the code content.
	Content string `json:"content"`

	// Tokens is the estimated token count.
	Tokens int `json:"tokens"`

	// Relevance is the relevance score (0.0-1.0).
	Relevance float64 `json:"relevance"`

	// AddedAt is the step when this was added.
	AddedAt int `json:"added_at"`

	// Reason explains why this was included.
	Reason string `json:"reason"`
}

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

type DefaultLoopOption func(*DefaultAgentLoop)

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

type DependenciesFactory interface {
	// Create builds Dependencies for the given session and query.
	//
	// Inputs:
	//   session - The current session.
	//   query - The user's query.
	//
	// Outputs:
	//   any - The dependencies (typically *phases.Dependencies).
	//   error - Non-nil if creation failed.
	Create(session *Session, query string) (any, error)
}

type DocEntry struct {
	// ID is a unique identifier.
	ID string `json:"id"`

	// Library is the library name.
	Library string `json:"library"`

	// Symbol is the symbol path.
	Symbol string `json:"symbol"`

	// Content is the documentation content.
	Content string `json:"content"`

	// Tokens is the estimated token count.
	Tokens int `json:"tokens"`
}

type EnrichmentStepProvider interface {
	// EnrichmentTraceStep returns a TraceStep for the given graph's enrichment stats.
	EnrichmentTraceStep(graphID string) *crs.TraceStep
}

type GraphInitializer interface {
	// InitGraph initializes a code graph for a project.
	//
	// Inputs:
	//   ctx - Context for cancellation.
	//   projectRoot - Path to the project root.
	//
	// Outputs:
	//   string - The graph ID.
	//   error - Non-nil if initialization fails.
	InitGraph(ctx context.Context, projectRoot string) (string, error)
}

type GraphStats struct {
	// FilesParsed is the number of files in the graph.
	FilesParsed int `json:"files_parsed"`

	// SymbolsExtracted is the number of symbols extracted.
	SymbolsExtracted int `json:"symbols_extracted"`

	// EdgesBuilt is the number of edges in the graph.
	EdgesBuilt int `json:"edges_built"`

	// ParseTimeMs is how long graph construction took.
	ParseTimeMs int64 `json:"parse_time_ms"`
}

type HistoryEntry struct {
	// Step is the 0-indexed step number.
	Step int `json:"step"`

	// Type describes what happened (plan, tool_call, reflection, etc.).
	Type string `json:"type"`

	// State is the agent state at this step.
	State AgentState `json:"state"`

	// Query is the user's query (for plan entries).
	Query string `json:"query,omitempty"`

	// ToolName is the tool that was invoked (for tool_call entries).
	ToolName string `json:"tool_name,omitempty"`

	// Input contains the tool input or prompt.
	Input string `json:"input,omitempty"`

	// Output contains the tool result or LLM response.
	Output string `json:"output,omitempty"`

	// TokensUsed is the tokens consumed in this step.
	TokensUsed int `json:"tokens_used,omitempty"`

	// DurationMs is how long this step took in milliseconds.
	DurationMs int64 `json:"duration_ms"`

	// Timestamp is when this step occurred (Unix milliseconds UTC).
	Timestamp int64 `json:"timestamp"`

	// Error contains any error message from this step.
	Error string `json:"error,omitempty"`

	// ClarificationPrompt is the prompt shown when entering CLARIFY state.
	ClarificationPrompt string `json:"clarification_prompt,omitempty"`
}

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

type LoopDependencies struct {
	// StateMachine handles state transitions.
	StateMachine *StateMachine

	// PhaseRegistry maps states to phase implementations.
	PhaseRegistry PhaseRegistry

	// SessionStore persists session state.
	SessionStore SessionStore

	// EventHandler processes agent events.
	EventHandler func(event any)
}

type ManagedModelInfo struct {
	Name      string        `json:"name"`
	IsLoaded  bool          `json:"is_loaded"`
	KeepAlive string        `json:"keep_alive"`
	LastUsed  int64         `json:"last_used"` // Unix milliseconds UTC
	LoadTime  time.Duration `json:"load_time"`
}

type Message struct {
	// Role is "user", "assistant", or "system".
	Role string `json:"role"`

	// Content is the message content.
	Content string `json:"content"`

	// ToolCalls contains any tool calls in this message.
	ToolCalls []ToolInvocation `json:"tool_calls,omitempty"`
}

type MetricField string

type ModelManager interface {
	// WarmModel pre-loads a model into VRAM with the specified keep_alive.
	WarmModel(ctx context.Context, model string, keepAlive string) error

	// GetLoadedModels returns currently tracked models.
	GetLoadedModels() []ManagedModelInfo
}

type ModelType string

type NullGraphProvider struct{}

type ParamExtractor interface {
	// ExtractParams extracts corrected parameters for a tool.
	//
	// Inputs:
	//   - ctx: Context for cancellation/timeout.
	//   - query: The user's natural language query.
	//   - toolName: The name of the selected tool.
	//   - paramSchemas: Parameter definitions for the tool.
	//   - regexHint: The regex extractor's output (used as a hint).
	//
	// Outputs:
	//   - map[string]any: Corrected parameter values.
	//   - error: Non-nil if extraction fails (caller should use regexHint).
	ExtractParams(ctx context.Context, query string, toolName string,
		paramSchemas []ParamExtractorSchema, regexHint map[string]any) (map[string]any, error)

	// IsEnabled returns true if the extractor is enabled.
	IsEnabled() bool

	// ResolveConceptualSymbol uses the LLM to pick the best symbol from candidates
	// when the query uses conceptual descriptions instead of function names.
	// IT-12: Called as a fallback when regex extraction + fuzzy resolution fail.
	// D3: Added tier0Count, tier1Count params for grouped prompt formatting.
	// D3c: Added sourceContext param — describes the source function for find_path to-side.
	//
	// Inputs:
	//   - ctx: Context for cancellation/timeout.
	//   - query: The user's natural language query.
	//   - candidates: Symbol candidates found by keyword search of the index.
	//   - tier0Count: Number of tier0 (best match) candidates in the list.
	//   - tier1Count: Number of tier1 (partial match) candidates in the list.
	//   - sourceContext: Description of the source function (e.g., "Bind (method on Context
	//     in context.go:757)"). Empty when not resolving a find_path to-side.
	//
	// Outputs:
	//   - string: The best symbol name from the candidates.
	//   - error: Non-nil if resolution fails.
	ResolveConceptualSymbol(ctx context.Context, query string,
		candidates []SymbolCandidate, tier0Count, tier1Count int,
		sourceContext string) (string, error)
}

type ParamExtractorSchema struct {
	// Name is the parameter name.
	Name string

	// Type is the parameter type (string, integer, boolean).
	Type string

	// Required indicates if the parameter is required.
	Required bool

	// Default is the default value as a string.
	Default string

	// Description explains what the parameter is for.
	Description string
}

type PhaseExecutor interface {
	// Execute runs the phase.
	Execute(ctx context.Context, deps any) (AgentState, error)

	// Name returns the phase name.
	Name() string
}

type PhaseRegistry interface {
	// GetPhase returns the phase implementation for a state.
	GetPhase(state AgentState) (PhaseExecutor, bool)
}

type ProposedChange struct {
	// FilePath is the file to modify.
	FilePath string `json:"file_path"`

	// ChangeType is create, modify, or delete.
	ChangeType string `json:"change_type"`

	// OldContent is the original content (for modify).
	OldContent string `json:"old_content,omitempty"`

	// NewContent is the new content.
	NewContent string `json:"new_content"`

	// Reason explains why this change is needed.
	Reason string `json:"reason"`
}

type QueryIntent struct {
	// Type is the query type (explore, modify, explain, debug, refactor).
	Type string `json:"type"`

	// Scope is the query scope (file, function, package, project).
	Scope string `json:"scope"`

	// Targets are specific symbols/files mentioned.
	Targets []string `json:"targets"`

	// Confidence is how certain we are about the classification (0.0-1.0).
	Confidence float64 `json:"confidence"`
}

type ReasoningSummary struct {
	// NodesExplored is the total number of nodes in the proof index.
	NodesExplored int `json:"nodes_explored"`

	// NodesProven is the count of nodes with PROVEN status.
	NodesProven int `json:"nodes_proven"`

	// NodesDisproven is the count of nodes with DISPROVEN status.
	NodesDisproven int `json:"nodes_disproven"`

	// NodesUnknown is the count of nodes with UNKNOWN or EXPANDED status.
	NodesUnknown int `json:"nodes_unknown"`

	// ConstraintsApplied is the number of active constraints.
	ConstraintsApplied int `json:"constraints_applied"`

	// ExplorationDepth is the number of history entries (proxy for depth).
	ExplorationDepth int `json:"exploration_depth"`

	// ConfidenceScore is the ratio of proven nodes to explored nodes.
	// Value is between 0.0 and 1.0. Use with caution - this is a coverage
	// metric, not a statistical confidence interval.
	ConfidenceScore float64 `json:"confidence_score"`
}

type RunResult struct {
	// State is the current agent state after execution.
	State AgentState `json:"state"`

	// Response is the final response text (for COMPLETE state).
	Response string `json:"response,omitempty"`

	// NeedsClarify contains clarification details (for CLARIFY state).
	NeedsClarify *ClarifyRequest `json:"needs_clarify,omitempty"`

	// ToolsUsed lists all tool invocations made.
	ToolsUsed []ToolInvocation `json:"tools_used"`

	// TokensUsed is the total tokens consumed.
	TokensUsed int `json:"tokens_used"`

	// StepsTaken is the number of steps executed.
	StepsTaken int `json:"steps_taken"`

	// SafetyChecks contains any safety analysis results.
	SafetyChecks []SafetyResult `json:"safety_checks,omitempty"`

	// Error contains error details (for ERROR state).
	Error *AgentError `json:"error,omitempty"`

	// ReasoningSummary provides high-level metrics about the reasoning process.
	// Populated when CRS is enabled for the session.
	ReasoningSummary *ReasoningSummary `json:"reasoning_summary,omitempty"`
}

type SafetyConstraintInfo struct {
	// IssueCode is the safety issue code (e.g., "SUPPLY_CHAIN_INSTALL").
	IssueCode string `json:"issue_code"`

	// Pattern describes what triggered the violation.
	Pattern string `json:"pattern"`

	// Reason explains why this is blocked.
	Reason string `json:"reason"`
}

type SafetyResult struct {
	// Passed indicates if all safety checks passed.
	Passed bool `json:"passed"`

	// Issues contains security issues found.
	Issues []SecurityIssue `json:"issues"`

	// Blocked indicates if the operation was blocked.
	Blocked bool `json:"blocked"`

	// BlockReason explains why the operation was blocked.
	BlockReason string `json:"block_reason,omitempty"`
}

type SafetyViolation struct {
	// NodeID is the MCTS node where the violation occurred.
	NodeID string `json:"node_id"`

	// ErrorMessage is the safety error message.
	ErrorMessage string `json:"error_message"`

	// Timestamp is when the violation was recorded (Unix milliseconds UTC).
	Timestamp int64 `json:"timestamp"`

	// Constraints are the extracted constraints for CDCL.
	Constraints []SafetyConstraintInfo `json:"constraints,omitempty"`
}

type SecurityIssue struct {
	// ID is a unique identifier for this issue type.
	ID string `json:"id"`

	// Title is a short description.
	Title string `json:"title"`

	// Description provides details.
	Description string `json:"description"`

	// Severity is the issue severity (critical, high, medium, low).
	Severity string `json:"severity"`

	// Category is the issue category (injection, secrets, etc.).
	Category string `json:"category"`

	// FilePath is where the issue was found.
	FilePath string `json:"file_path,omitempty"`

	// Line is the line number.
	Line int `json:"line,omitempty"`

	// Code is the problematic code snippet.
	Code string `json:"code,omitempty"`
}

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

type Session struct {

	// ID is the unique session identifier.
	ID string `json:"id"`

	// ProjectRoot is the absolute path to the project.
	ProjectRoot string `json:"project_root"`

	// GraphID is the Trace graph ID (set after init).
	GraphID string `json:"graph_id,omitempty"`

	// State is the current agent state.
	State AgentState `json:"state"`

	// Config holds the session configuration.
	Config *SessionConfig `json:"config"`

	// History records all execution steps.
	History []HistoryEntry `json:"history"`

	// Metrics tracks session metrics.
	Metrics *SessionMetrics `json:"metrics"`

	// CurrentContext holds the current assembled context.
	CurrentContext *AssembledContext `json:"-"`

	// LastQuery is the most recent user query.
	LastQuery string `json:"last_query,omitempty"`

	// LastIntent is the classified intent of the last query.
	LastIntent *QueryIntent `json:"last_intent,omitempty"`

	// CreatedAt is when the session was created (Unix milliseconds UTC).
	CreatedAt int64 `json:"created_at"`

	// LastActiveAt is when the session was last active (Unix milliseconds UTC).
	LastActiveAt int64 `json:"last_active_at"`

	// CRS is the Code Reasoning State for MCTS-based reasoning.
	// Optional - nil when MCTS is not enabled.
	CRS crs.CRS `json:"-"`
	// contains filtered or unexported fields
}

type SessionCleanupFunc func(sessionID string)

type SessionConfig struct {
	// MaxSteps is the maximum number of agent steps allowed.
	// Default: 50
	MaxSteps int `json:"max_steps"`

	// MaxTokensPerStep is the maximum tokens per LLM call.
	// Default: 4000
	MaxTokensPerStep int `json:"max_tokens_per_step"`

	// MaxTotalTokens is the total token budget for the session.
	// Default: 100000
	MaxTotalTokens int `json:"max_total_tokens"`

	// MaxToolCallsPerStep limits tool calls in a single step.
	// Default: 5
	MaxToolCallsPerStep int `json:"max_tool_calls_per_step"`

	// StepTimeout is the maximum duration for a single step.
	// Default: 30s
	StepTimeout time.Duration `json:"step_timeout"`

	// TotalTimeout is the maximum duration for the entire session.
	// Default: 10m
	TotalTimeout time.Duration `json:"total_timeout"`

	// InitialContextBudget is the token budget for initial context assembly.
	// Default: 8000
	InitialContextBudget int `json:"initial_context_budget"`

	// ContextEvictionPolicy determines how context is evicted when over budget.
	// Options: "lru", "relevance", "hybrid"
	// Default: "hybrid"
	ContextEvictionPolicy string `json:"context_eviction_policy"`

	// SummarizationThreshold is tokens before summarizing context.
	// Default: 50000
	SummarizationThreshold int `json:"summarization_threshold"`

	// RequireSafetyCheck enables safety checks before code changes.
	// Default: true
	RequireSafetyCheck bool `json:"require_safety_check"`

	// SafetyCheckScope determines what to analyze for safety.
	// Options: "changed_files", "blast_radius", "full"
	// Default: "blast_radius"
	SafetyCheckScope string `json:"safety_check_scope"`

	// BlockOnCritical blocks operations with critical security issues.
	// Default: true
	BlockOnCritical bool `json:"block_on_critical"`

	// EnabledToolSets specifies which tool categories are enabled.
	// Options: "exploration", "reasoning", "safety", "file"
	// Default: ["exploration", "reasoning", "safety", "file"]
	EnabledToolSets []string `json:"enabled_tool_sets"`

	// DisabledTools lists specific tools to disable.
	DisabledTools []string `json:"disabled_tools"`

	// ToolPriorities assigns priority weights to tools (higher = prefer).
	ToolPriorities map[string]int `json:"tool_priorities"`

	// ReflectionThreshold is steps before triggering reflection.
	// Default: 10
	ReflectionThreshold int `json:"reflection_threshold"`

	// ConfidenceThreshold triggers reflection below this confidence.
	// Default: 0.7
	ConfidenceThreshold float64 `json:"confidence_threshold"`

	// DegradationMode determines behavior when services unavailable.
	// Options: "fallback", "fail", "ask"
	// Default: "fallback"
	DegradationMode string `json:"degradation_mode"`

	// MainModel overrides the main reasoning LLM for this session.
	// CB-62: When non-empty, overrides OLLAMA_MODEL / TRACE_MAIN_MODEL env vars.
	// Set by the proxy when forwarding the user's model selection from OpenWebUI.
	// Default: "" (use environment/startup config).
	MainModel string `json:"main_model"`

	// ToolRouterEnabled enables the micro-LLM tool router for faster tool selection.
	// When enabled, a fast model (like granite4:micro-h) pre-selects tools before
	// the main reasoning LLM, reducing latency.
	// Default: false (opt-in feature)
	ToolRouterEnabled bool `json:"tool_router_enabled"`

	// ToolRouterModel is the Ollama model to use for tool routing.
	// Should be a small, fast model like "granite4:micro-h" or "granite4:3b-h".
	// Default: "granite4:micro-h"
	ToolRouterModel string `json:"tool_router_model"`

	// ToolRouterTimeout is the maximum time for a routing decision.
	// GR-44: If exceeded, the process fails (no fallback to main LLM).
	// Default: 20s
	ToolRouterTimeout time.Duration `json:"tool_router_timeout"`

	// ToolRouterConfidence is the minimum confidence for accepting a routing decision.
	// Below this threshold, falls back to main LLM tool selection.
	// Default: 0.7
	ToolRouterConfidence float64 `json:"tool_router_confidence"`

	// ParamExtractorModel is the Ollama model for LLM parameter extraction.
	// IT-08e: Should be a small, fast model optimized for JSON structured output.
	// Runs in parallel with the tool router on a separate model to avoid
	// Ollama serialization bottlenecks.
	// Default: "ministral-3:3b"
	ParamExtractorModel string `json:"param_extractor_model"`
}

type SessionMetrics struct {
	// TotalSteps is the number of steps executed.
	TotalSteps int `json:"total_steps"`

	// TotalTokens is the total tokens consumed.
	TotalTokens int `json:"total_tokens"`

	// TotalDurationMs is the total execution time in milliseconds.
	TotalDurationMs int64 `json:"total_duration_ms"`

	// ToolCalls is the number of tool invocations.
	ToolCalls int `json:"tool_calls"`

	// ToolErrors is the number of failed tool calls.
	ToolErrors int `json:"tool_errors"`

	// LLMCalls is the number of LLM API calls.
	LLMCalls int `json:"llm_calls"`

	// CacheHits is the number of cache hits.
	CacheHits int `json:"cache_hits"`

	// DegradedMode indicates if running in degraded mode.
	DegradedMode bool `json:"degraded_mode"`

	// GroundingRetries is the number of grounding validation retries.
	GroundingRetries int `json:"grounding_retries"`

	// ToolForcingRetries is the number of tool forcing retries.
	ToolForcingRetries int `json:"tool_forcing_retries"`

	// GraphStats contains Trace graph statistics.
	GraphStats *GraphStats `json:"graph_stats,omitempty"`
}

type SessionState struct {
	// ID is the session identifier.
	ID string `json:"id"`

	// ProjectRoot is the project being analyzed.
	ProjectRoot string `json:"project_root"`

	// GraphID is the Trace graph ID.
	GraphID string `json:"graph_id,omitempty"`

	// State is the current agent state.
	State AgentState `json:"state"`

	// StepCount is the number of steps executed.
	StepCount int `json:"step_count"`

	// TokensUsed is the total tokens consumed.
	TokensUsed int `json:"tokens_used"`

	// CreatedAt is when the session started (Unix milliseconds UTC).
	CreatedAt int64 `json:"created_at"`

	// LastActiveAt is when the session was last active (Unix milliseconds UTC).
	LastActiveAt int64 `json:"last_active_at"`

	// DegradedMode indicates if running with limited tools.
	DegradedMode bool `json:"degraded_mode"`
}

type SessionStore interface {
	// Get retrieves a session by ID.
	Get(id string) (*Session, bool)

	// Put stores a session.
	Put(session *Session)

	// Delete removes a session.
	Delete(id string)

	// List returns all active session IDs.
	List() []string
}

type SessionSummary struct {
	// ID is the session identifier.
	ID string `json:"id"`

	// State is the current agent state.
	State AgentState `json:"state"`

	// TraceStepCount is the number of CRS trace steps recorded.
	TraceStepCount int `json:"trace_step_count"`

	// CircuitBreakerActive indicates if the circuit breaker has fired.
	CircuitBreakerActive bool `json:"circuit_breaker_active"`

	// CreatedAt is when the session started (Unix milliseconds UTC).
	CreatedAt int64 `json:"created_at"`

	// ToolCalls is the total number of tool calls made.
	ToolCalls int `json:"tool_calls"`
}

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

type SymbolCandidate struct {
	// Name is the symbol name (e.g., "_setMaterial").
	Name string

	// Kind is the symbol kind (e.g., "method", "function").
	Kind string

	// FilePath is the file where the symbol is defined.
	FilePath string

	// Line is the line number where the symbol is defined.
	Line int

	// Receiver is the receiver type name for methods (e.g., "Context" for Context.Bind).
	// D3c: Used to show method ownership in the LLM prompt so the model can
	// distinguish validateHeader (method on Context) from validate (function).
	// Empty for non-method symbols.
	Receiver string

	// OutEdges is the number of outgoing call edges (functions this symbol calls).
	// IT-12 Rev 4: Populated when graph is available. Zero means unknown or no edges.
	OutEdges int

	// InEdges is the number of incoming call edges (functions that call this symbol).
	// IT-12 Rev 4: Populated when graph is available. Zero means unknown or no edges.
	InEdges int
}

type ToolHistoryEntry struct {
	// Tool is the tool name that was called.
	Tool string `json:"tool"`

	// Summary is a brief description of what was found/returned.
	// Example: "Found 5 callers of parseConfig in pkg/config/"
	Summary string `json:"summary"`

	// Success indicates whether the tool call succeeded.
	Success bool `json:"success"`

	// StepNumber when this tool was called.
	StepNumber int `json:"step_number,omitempty"`
}

type ToolInvocation struct {
	// ID is a unique identifier for this invocation.
	ID string `json:"id"`

	// Tool is the tool name.
	Tool string `json:"tool"`

	// Parameters are the tool input parameters.
	Parameters *ToolParameters `json:"parameters"`

	// Reason explains why the agent chose this tool.
	Reason string `json:"reason,omitempty"`

	// StepNumber is the step when this was invoked.
	StepNumber int `json:"step_number"`

	// Result contains the tool execution result.
	Result *ToolResult `json:"result,omitempty"`
}

type ToolParameters struct {
	// RawJSON contains the raw JSON parameters for flexible tool inputs.
	// Use encoding/json to unmarshal into tool-specific parameter structs.
	RawJSON []byte `json:"raw_json,omitempty"`

	// StringParams contains string-typed parameters.
	StringParams map[string]string `json:"string_params,omitempty"`

	// IntParams contains integer-typed parameters.
	IntParams map[string]int `json:"int_params,omitempty"`

	// BoolParams contains boolean-typed parameters.
	BoolParams map[string]bool `json:"bool_params,omitempty"`
}

type ToolResult struct {
	// InvocationID links back to the invocation.
	InvocationID string `json:"invocation_id"`

	// Success indicates if the tool succeeded.
	Success bool `json:"success"`

	// Output is the tool's output.
	Output string `json:"output"`

	// Error contains any error message.
	Error string `json:"error,omitempty"`

	// Duration is how long execution took (serialized as nanoseconds).
	Duration time.Duration `json:"duration"`

	// TokensUsed is the estimated tokens in the output.
	TokensUsed int `json:"tokens_used"`

	// Cached indicates if result came from cache.
	Cached bool `json:"cached"`

	// Truncated indicates if output was truncated.
	Truncated bool `json:"truncated"`

	// Tool is the tool name that produced this result.
	// IT_CRS_03 AC-3: Used by getSingleFormattedResult() for tool-specific
	// pass-through decisions instead of fragile substring matching.
	Tool string `json:"tool,omitempty"`

	// ProofDelta overrides the default CRS proof delta when non-zero.
	// IT_CRS_03 AC-8: Higher values = stronger signal (exact match = 2, fuzzy = 1).
	ProofDelta int `json:"proof_delta,omitempty"`
}

type ToolRouter interface {
	// SelectTool chooses the best tool for the given query and context.
	//
	// Inputs:
	//   - ctx: Context for cancellation/timeout.
	//   - query: The user's question or request.
	//   - availableTools: Tools currently available for selection.
	//   - codeContext: Optional context about the codebase.
	//
	// Outputs:
	//   - *ToolRouterSelection: The selected tool with confidence.
	//   - error: Non-nil if routing fails (caller should fall back to main LLM).
	SelectTool(ctx context.Context, query string, availableTools []ToolRouterSpec, codeContext *ToolRouterCodeContext) (*ToolRouterSelection, error)

	// Model returns the model being used for routing.
	Model() string

	// Close releases any resources held by the router.
	Close() error
}

type ToolRouterCodeContext struct {
	Language       string            `json:"language,omitempty"`
	Files          int               `json:"files,omitempty"`
	Symbols        int               `json:"symbols,omitempty"`
	CurrentFile    string            `json:"current_file,omitempty"`
	RecentTools    []string          `json:"recent_tools,omitempty"`
	PreviousErrors []ToolRouterError `json:"previous_errors,omitempty"`

	// ToolHistory contains the sequence of tools used with their results.
	// This enables history-aware routing where the router can see what
	// was already tried and what was learned from each tool.
	ToolHistory []ToolHistoryEntry `json:"tool_history,omitempty"`

	// Progress describes the current state of information gathering.
	// Example: "Found 3 entry points, read 2 files, identified main handler"
	Progress string `json:"progress,omitempty"`

	// StepNumber is the current execution step (1-indexed).
	StepNumber int `json:"step_number,omitempty"`
}

type ToolRouterError struct {
	Tool      string `json:"tool"`
	Error     string `json:"error"`
	Timestamp string `json:"timestamp,omitempty"`
}

type ToolRouterSelection struct {
	// Tool is the selected tool name.
	Tool string `json:"tool"`

	// Confidence is the router's confidence (0.0-1.0).
	Confidence float64 `json:"confidence"`

	// ParamsHint contains optional parameter suggestions.
	ParamsHint map[string]string `json:"params_hint,omitempty"`

	// Reasoning explains why this tool was selected.
	Reasoning string `json:"reasoning,omitempty"`

	// Duration is how long the routing decision took.
	Duration time.Duration `json:"duration,omitempty"`
}

type ToolRouterSpec struct {
	// Name is the tool name.
	Name string `json:"name"`

	// Description explains what the tool does.
	Description string `json:"description"`

	// BestFor contains keywords that should trigger this tool.
	// CB-31e: Now populated from WhenToUse.Keywords.
	BestFor []string `json:"best_for,omitempty"`

	// UseWhen describes when to use this tool.
	UseWhen string `json:"use_when,omitempty"`

	// AvoidWhen describes when NOT to use this tool.
	AvoidWhen string `json:"avoid_when,omitempty"`

	// InsteadOf lists tools this should replace.
	InsteadOf []ToolRouterSubstitution `json:"instead_of,omitempty"`

	// Params lists parameter names.
	Params []string `json:"params,omitempty"`

	// Category is the tool category.
	Category string `json:"category,omitempty"`
}

type ToolRouterSubstitution struct {
	// Tool is the name of the tool to replace.
	Tool string `json:"tool"`

	// When describes when substitution applies.
	When string `json:"when"`
}