phases

type BatchFilterer interface {
	// FilterBatch evaluates a batch of tool calls and returns filter decisions.
	//
	// Inputs:
	//   ctx - Context for cancellation/timeout.
	//   prompt - The filter prompt containing tools and similarity scores.
	//
	// Outputs:
	//   string - Response with KEEP/SKIP decisions.
	//   error - Non-nil if the filter call fails.
	FilterBatch(ctx context.Context, prompt string) (string, error)
}

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

type ClarifyPhaseOption func(*ClarifyPhase)

type ContextManager = agentcontext.Manager

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

type Dependencies struct {
	// Session is the current agent session.
	Session *agent.Session

	// Query is the user's original query.
	Query string

	// Context is the assembled context (nil until PLAN phase completes).
	Context *agent.AssembledContext

	// ContextManager handles context assembly and updates.
	ContextManager *ContextManager

	// LLMClient sends requests to the language model.
	LLMClient LLMClient

	// ToolRegistry provides access to available tools.
	ToolRegistry *ToolRegistry

	// ToolExecutor executes tool invocations.
	ToolExecutor *ToolExecutor

	// SafetyGate validates proposed changes.
	SafetyGate SafetyGate

	// EventEmitter broadcasts agent events.
	EventEmitter *EventEmitter

	// GraphProvider initializes and provides the code graph.
	GraphProvider GraphProvider

	// ResponseGrounder validates LLM responses against project reality.
	// Optional - if nil, grounding validation is skipped.
	ResponseGrounder ResponseGrounder

	// AnchoredSynthesisBuilder builds tool-anchored synthesis prompts.
	// Optional - if nil, basic synthesis prompt is used.
	AnchoredSynthesisBuilder grounding.AnchoredSynthesisBuilder

	// DirtyTracker tracks files modified by tools for graph refresh.
	// Optional - if nil, graph freshness tracking is disabled.
	DirtyTracker *graph.DirtyTracker

	// GraphRefresher handles incremental graph updates.
	// Optional - if nil, graph refresh is disabled.
	GraphRefresher *graph.Refresher

	// Coordinator orchestrates MCTS activities in response to agent events.
	// Optional - if nil, MCTS activity coordination is disabled.
	// Use HandleEvent to emit events and trigger appropriate activities.
	Coordinator *integration.Coordinator

	// CRS is the Code Reasoning State for MCTS integration.
	// Optional - if nil, CRS-based reasoning is disabled.
	// Use for session restore, checkpoint management, and proof tracking.
	CRS crs.CRS

	// PersistenceManager handles CRS checkpoint storage.
	// Optional - if nil, CRS persistence is disabled.
	// GR-33/GR-36: Required for session restore and checkpoint save.
	PersistenceManager *crs.PersistenceManager

	// Journal stores CRS deltas for replay.
	// Optional - if nil, delta journaling is disabled.
	// GR-33/GR-36: Required for session restore to replay deltas.
	// CRS-27: Changed from *crs.BadgerJournal to crs.Journal interface
	// to support NATS JetStream and other journal backends.
	Journal crs.Journal

	// GraphAnalytics provides graph analysis operations (dominators, communities, etc).
	// Required for symbol resolution in parameter extraction (CB-31d).
	// Optional - if nil, parameter extraction falls back to raw symbol names.
	GraphAnalytics *graph.GraphAnalytics

	// SymbolIndex provides fast symbol lookup by ID, name, or fuzzy search.
	// Required for symbol resolution in parameter extraction (CB-31d).
	// Optional - if nil, parameter extraction falls back to raw symbol names.
	SymbolIndex *index.SymbolIndex

	// RAGResolver resolves query tokens against the code graph before param extraction.
	// CRS-25: Optional - if nil, param extraction runs without entity grounding.
	// When available, resolves entity names (packages, symbols) from the graph
	// and injects them into the extraction context for the LLM.
	// Accepts StructuralResolver (Layer 1 only) or CombinedResolver (Layers 1+2).
	RAGResolver rag.Resolver

	// SymbolStore handles Weaviate symbol index updates for incremental refresh.
	// CRS-25b: Optional - if nil, incremental RAG refresh is disabled.
	// When available, symbols are deleted/re-indexed when files change mid-session.
	SymbolStore *rag.SymbolStore

	// ParamExtractor uses a fast LLM to extract tool parameters from queries.
	// IT-08b: Optional - nil when LLM parameter extraction is not enabled.
	// When available, enhances regex-based extraction with semantic understanding.
	ParamExtractor agent.ParamExtractor

	// StalenessChecker detects if the code graph is stale relative to the working tree.
	// CRS-19: Optional - if nil, staleness detection is disabled.
	// When available, spot-checks file mtimes before graph tool dispatch.
	StalenessChecker *graph.StalenessChecker
}

type EventEmitter = events.Emitter

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

type ExecutePhaseOption func(*ExecutePhase)

type ForcingRequest struct {
	// Query is the user's original query.
	Query string

	// StepNumber is the current execution step.
	StepNumber int

	// ForcingRetries is the number of tool forcing retries so far.
	ForcingRetries int

	// MaxRetries is the maximum allowed forcing retries.
	MaxRetries int

	// MaxStepForForcing is the maximum step number where forcing applies.
	MaxStepForForcing int

	// AvailableTools is the list of available tool names.
	AvailableTools []string
}

type GraphProvider interface {
	// Initialize sets up the 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.
	Initialize(ctx context.Context, projectRoot string) (string, error)

	// IsAvailable checks if the graph service is available.
	//
	// Outputs:
	//   bool - True if the service is available.
	IsAvailable() bool

	// EnrichmentTraceStep returns a TraceStep describing the LSP enrichment
	// quality of the cached graph. Returns nil if no graph is cached or
	// enrichment data is unavailable.
	//
	// Description:
	//
	//	GR-76: Called by InitPhase after SetGraphID to record enrichment
	//	quality in the CRS journal. The LLM uses this to calibrate trust
	//	in graph tool results.
	//
	// Inputs:
	//
	//	graphID - The graph ID to query.
	//
	// Outputs:
	//
	//	*crs.TraceStep - The enrichment TraceStep, or nil.
	//
	// Thread Safety: Safe for concurrent use.
	EnrichmentTraceStep(graphID string) *crs.TraceStep
}

type InitPhase struct{}

type LLMClient = llm.Client

type Phase interface {
	// Name returns the phase name for logging and debugging.
	//
	// Outputs:
	//   string - The human-readable phase name.
	Name() string

	// Execute runs the phase logic.
	//
	// Description:
	//   Performs the phase-specific operations and returns the next state
	//   the agent should transition to.
	//
	// Inputs:
	//   ctx - Context for cancellation and timeout.
	//   deps - Dependencies required by the phase.
	//
	// Outputs:
	//   agent.AgentState - The next state to transition to.
	//   error - Non-nil if an unrecoverable error occurred.
	//
	// Thread Safety: Must be safe for concurrent use.
	Execute(ctx context.Context, deps *Dependencies) (agent.AgentState, error)
}

type PhaseResult struct {
	// NextState is the state to transition to.
	NextState agent.AgentState

	// UpdatedContext is the context after phase execution.
	UpdatedContext *agent.AssembledContext

	// Response is any response generated by the phase.
	Response string

	// ToolCalls are tool invocations requested by the LLM.
	ToolCalls []agent.ToolInvocation

	// ClarificationNeeded indicates if user input is required.
	ClarificationNeeded bool

	// ClarificationPrompt is the prompt to show the user.
	ClarificationPrompt string

	// Error contains any error that occurred.
	Error error
}

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

type PlanPhaseOption func(*PlanPhase)

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

type ReflectPhaseOption func(*ReflectPhase)

type ReflectionDecision string

type ReflectionInput struct {
	// StepsCompleted is the number of steps executed so far.
	StepsCompleted int

	// TokensUsed is the total tokens consumed.
	TokensUsed int

	// ToolsInvoked is the number of tool invocations.
	ToolsInvoked int

	// LastResponse is the most recent LLM response.
	LastResponse string

	// RecentResults are the recent tool results.
	RecentResults []agent.ToolResult
}

type ReflectionOutput struct {
	// Decision is what to do next.
	Decision ReflectionDecision

	// Reason explains the decision.
	Reason string

	// ClarificationPrompt is set if Decision is DecisionClarify.
	ClarificationPrompt string
}

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

type RepetitionDetectorOption func(*RepetitionDetector)

type ResponseGrounder = grounding.Grounder

type SafetyCheckResult struct {
	// Blocked indicates if the operation should be blocked.
	Blocked bool

	// Result is the full safety check result.
	Result *safety.Result

	// ErrorMessage is the error message for learning.
	ErrorMessage string

	// Constraints are the extracted constraints for CDCL.
	Constraints []safety.SafetyConstraint
}

type SafetyGate = safety.Gate

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

type SemanticCircuitBreakerOption func(*SemanticCircuitBreaker)

type SemanticInfo struct {
	Similarity float64
	Status     string // "allowed", "penalized", or "blocked"
}

type SymbolResolution struct {
	// SymbolID is the fully qualified symbol ID (e.g., "pkg/file.go:SymbolName").
	SymbolID string

	// Confidence is a strategy-based constant (0.0-1.0) indicating resolution quality.
	// IT-00a-1 Phase 4 note: These are hardcoded per-strategy constants, NOT computed
	// from match quality data (e.g., levenshtein distance, score margins). They provide
	// coarse ordering between strategies for observability but should not be used for
	// branching logic. If confidence-based branching is needed in the future, compute
	// from real signals (score margin, match count, edit distance).
	//
	// Current values:
	//   1.0  = exact match by ID
	//   0.95 = single exact name match
	//   0.8  = disambiguated name or substring match
	//   0.7  = fuzzy search match (function/method)
	//   0.6  = disambiguated name match (non-function)
	//   0.5  = fuzzy search match (non-function)
	Confidence float64

	// Strategy is the resolution strategy used ("exact", "name", "fuzzy").
	Strategy string
}

type SynthesisQualityResult struct {
	// Score is the quality score from 0.0 to 1.0.
	//   1.0: Response references specific symbols from results
	//   0.5: Response mentions general findings but no specific symbols
	//   0.0: Response contradicts or ignores tool results
	Score float64

	// SymbolsExpected is the number of distinct symbols extracted from tool results.
	SymbolsExpected int

	// SymbolsFound is the number of expected symbols mentioned in the response.
	SymbolsFound int

	// HasResultCount indicates whether the response mentions result counts from tools.
	HasResultCount bool

	// MentionsScope indicates whether the response mentions scope when scope was applied.
	MentionsScope bool

	// ScopeRelevant indicates whether scope was applied to any tool result.
	ScopeRelevant bool

	// Reason is a short diagnostic string explaining the score.
	Reason string
}

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

type TokenTrackerOption func(*TokenTracker)

type ToolExecutor = tools.Executor

type ToolForcingPolicy interface {
	// ShouldForce determines if tool usage should be forced.
	//
	// Description:
	//   Evaluates the request context to determine if the LLM should be
	//   prompted to use tools instead of answering directly.
	//
	// Inputs:
	//   ctx - Context for tracing and cancellation. Must not be nil.
	//   req - The forcing request context. Must not be nil.
	//
	// Outputs:
	//   bool - True if tool usage should be forced.
	//
	// Example:
	//   if policy.ShouldForce(ctx, &ForcingRequest{Query: "What tests exist?"}) {
	//       // Inject forcing hint
	//   }
	//
	// Thread Safety: This method is safe for concurrent use.
	ShouldForce(ctx context.Context, req *ForcingRequest) bool

	// BuildHint creates the forcing hint message to inject into conversation.
	//
	// Description:
	//   Generates a prompt that encourages the LLM to use tools before
	//   answering. The hint should include the suggested tool if available.
	//
	// Inputs:
	//   ctx - Context for tracing. Must not be nil.
	//   req - The forcing request context. Must not be nil.
	//
	// Outputs:
	//   string - The forcing hint to inject as a user message.
	//
	// Example:
	//   hint := policy.BuildHint(ctx, &ForcingRequest{
	//       Query: "What tests exist?",
	//       AvailableTools: []string{"find_entry_points"},
	//   })
	//
	// Thread Safety: This method is safe for concurrent use.
	BuildHint(ctx context.Context, req *ForcingRequest) string
}

type ToolRegistry = tools.Registry