tools

type APIFunction struct {
	// ID is the full node identifier.
	ID string `json:"id"`

	// Name is the function name extracted from the ID.
	Name string `json:"name"`

	// ExternalCallers is the count of external nodes calling this function.
	ExternalCallers int `json:"external_callers"`

	// InternalNodesDominated is the count of internal nodes this function dominates.
	InternalNodesDominated int `json:"internal_nodes_dominated"`

	// Coverage is the fraction of the module dominated by this function (0.0 to 1.0).
	Coverage float64 `json:"coverage"`

	// Description is a human-readable explanation.
	Description string `json:"description"`
}

type ApprovalFunc func(tool *ToolDefinition, params map[string]any) (bool, error)

type ArticulationPointInfo struct {
	// ID is the full node ID of the articulation point.
	ID string `json:"id"`

	// Name is the function name of the articulation point.
	Name string `json:"name"`

	// File is the source file containing this articulation point.
	File string `json:"file,omitempty"`

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

	// Kind is the symbol kind (function, method, etc.).
	Kind string `json:"kind,omitempty"`
}

type BackEdgeInfo struct {
	From string `json:"from"`
	To   string `json:"to"`
}

type BridgeInfo struct {
	// From is the source node ID.
	From string `json:"from"`

	// To is the target node ID.
	To string `json:"to"`

	// FromName is the source function name.
	FromName string `json:"from_name"`

	// ToName is the target function name.
	ToName string `json:"to_name"`
}

type CallChainNode struct {
	// ID is the node ID.
	ID string `json:"id"`

	// Name is the function name.
	Name string `json:"name,omitempty"`

	// File is the source file path.
	File string `json:"file,omitempty"`

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

	// Package is the package name.
	Package string `json:"package,omitempty"`

	// Depth is the BFS depth from the root node (0 for root).
	Depth int `json:"depth"`

	// CalledBy is the parent node ID in the call chain.
	CalledBy string `json:"called_by,omitempty"`

	// IsExternal indicates this node is an external dependency boundary.
	// IT-05a: Set when the node represents a call to an external library
	// that is not part of the indexed project.
	IsExternal bool `json:"is_external,omitempty"`

	// ExternalPkg is the inferred external package/module name.
	// Only set when IsExternal is true.
	ExternalPkg string `json:"external_package,omitempty"`
}

type CalleeInfo struct {
	// Name is the callee function name.
	Name string `json:"name"`

	// File is the source file path.
	File string `json:"file"`

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

	// Package is the package name.
	Package string `json:"package"`

	// Signature is the function signature.
	Signature string `json:"signature,omitempty"`

	// SourceID is the ID of the caller symbol.
	SourceID string `json:"source_id"`
}

type CallerInfo struct {
	// Name is the caller function name.
	Name string `json:"name"`

	// File is the source file path.
	File string `json:"file"`

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

	// Package is the package name.
	Package string `json:"package"`

	// Signature is the function signature.
	Signature string `json:"signature,omitempty"`
}

type CallerResult struct {
	// TargetID is the symbol ID being called.
	TargetID string `json:"target_id"`

	// CallerCount is the number of callers for this target.
	CallerCount int `json:"caller_count"`

	// Callers is the list of caller symbols.
	Callers []CallerInfo `json:"callers"`
}

type CheckReducibilityOutput struct {
	// IsReducible is true if the entire graph is reducible.
	IsReducible bool `json:"is_reducible"`

	// Score is the percentage of nodes NOT in irreducible regions (0.0 to 1.0).
	Score float64 `json:"score"`

	// QualityLabel is a human-readable quality label.
	QualityLabel string `json:"quality_label"`

	// IrreducibleRegions contains detected irreducible subgraphs.
	IrreducibleRegions []IrreducibleRegionInfo `json:"irreducible_regions,omitempty"`

	// Summary contains aggregate statistics.
	Summary CheckReducibilitySummary `json:"summary"`

	// Recommendation provides actionable guidance.
	Recommendation string `json:"recommendation"`

	// Message is an optional status message.
	Message string `json:"message,omitempty"`
}

type CheckReducibilityParams struct {
	// ShowIrreducible indicates whether to list specific irreducible regions.
	// Default: true
	ShowIrreducible bool
}

type CheckReducibilitySummary struct {
	// TotalNodes is the total nodes analyzed.
	TotalNodes int `json:"total_nodes"`

	// TotalEdges is the total edges analyzed.
	TotalEdges int `json:"total_edges"`

	// IrreducibleNodeCount is nodes in irreducible regions.
	IrreducibleNodeCount int `json:"irreducible_node_count"`

	// IrreducibleRegionCount is the number of irreducible regions.
	IrreducibleRegionCount int `json:"irreducible_region_count"`

	// CrossEdgeCount is the number of cross edges found.
	CrossEdgeCount int `json:"cross_edge_count"`

	// WellStructuredPercent is the percentage of well-structured code.
	WellStructuredPercent float64 `json:"well_structured_percent"`
}

type CommunityInfo struct {
	// ID is the community identifier.
	ID int `json:"id"`

	// Size is the number of members in this community.
	Size int `json:"size"`

	// DominantPackage is the most common package in this community.
	DominantPackage string `json:"dominant_package"`

	// Packages lists all packages represented in this community.
	Packages []string `json:"packages"`

	// IsCrossPackage indicates if this community spans multiple packages.
	IsCrossPackage bool `json:"is_cross_package"`

	// Connectivity is the ratio of internal to total edges.
	Connectivity float64 `json:"connectivity"`

	// InternalEdges is the count of edges within this community.
	InternalEdges int `json:"internal_edges"`

	// ExternalEdges is the count of edges to other communities.
	ExternalEdges int `json:"external_edges"`

	// Members is a sample of member node IDs (limited to 10).
	Members []CommunityMember `json:"members"`
}

type CommunityMember struct {
	ID string `json:"id"`
}

type ControlDependencySummary struct {
	// TotalDependencies is the total control dependencies found.
	TotalDependencies int `json:"total_dependencies"`

	// MaxDepth is the maximum depth of the dependency chain.
	MaxDepth int `json:"max_depth"`

	// TopControllers is the number of controllers with most dependents.
	TopControllers int `json:"top_controllers"`

	// NodesAnalyzed is the total nodes considered.
	NodesAnalyzed int `json:"nodes_analyzed"`
}

type ControllerInfo struct {
	// ID is the full node ID of the controller.
	ID string `json:"id"`

	// Name is the function name of the controller.
	Name string `json:"name"`

	// File is the source file path.
	File string `json:"file,omitempty"`

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

	// Package is the package name.
	Package string `json:"package,omitempty"`

	// DependentsCount is how many nodes this controller controls.
	DependentsCount int `json:"dependents_count,omitempty"`

	// Depth is the distance from target in the dependency chain.
	Depth int `json:"depth,omitempty"`
}

type CriticalFunction struct {
	ID               string  `json:"id"`
	Name             string  `json:"name"`
	File             string  `json:"file"`
	Line             int     `json:"line"`
	CriticalityScore float64 `json:"criticality_score"`
	DominatorScore   float64 `json:"dominator_score"`
	PageRankScore    float64 `json:"pagerank_score"`
	DominatedCount   int     `json:"dominated_count"`
	Quadrant         string  `json:"quadrant"`
	RiskLevel        string  `json:"risk_level"`
	Recommendation   string  `json:"recommendation"`
}

type CriticalPathNode struct {
	// ID is the full node identifier.
	ID string `json:"id"`

	// Name is the function name extracted from the ID.
	Name string `json:"name"`

	// Depth is the distance from the entry point.
	Depth int `json:"depth"`

	// IsMandatory is always true for critical path nodes.
	IsMandatory bool `json:"is_mandatory"`

	// Reason explains why this node is in the path.
	Reason string `json:"reason"`
}

type CriticalitySummary struct {
	TotalAnalyzed   int     `json:"total_analyzed"`
	HighRiskCount   int     `json:"high_risk_count"`
	MediumRiskCount int     `json:"medium_risk_count"`
	AvgCriticality  float64 `json:"avg_criticality"`
}

type CrossEdgeInfo struct {
	FromCommunity int `json:"from_community"`
	ToCommunity   int `json:"to_community"`
	Count         int `json:"count"`
}

type CycleInfo struct {
	// CycleNumber is the position in the result list (1-based).
	CycleNumber int `json:"cycle_number"`

	// Length is the number of nodes in this cycle.
	Length int `json:"length"`

	// Packages lists the packages involved in this cycle.
	Packages []string `json:"packages"`

	// Nodes is the list of nodes in the cycle.
	Nodes []CycleNode `json:"nodes"`
}

type CycleNode struct {
	// ID is the node ID.
	ID string `json:"id"`

	// Name is the symbol name.
	Name string `json:"name,omitempty"`

	// File is the source file path.
	File string `json:"file,omitempty"`

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

type DeadCodeSymbol struct {
	// Name is the symbol name.
	Name string `json:"name"`

	// Kind is the symbol kind (function, type, etc.).
	Kind string `json:"kind"`

	// File is the source file path.
	File string `json:"file"`

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

	// Package is the package name.
	Package string `json:"package"`

	// Exported indicates if the symbol is exported.
	Exported bool `json:"exported"`

	// Reason explains why the symbol is considered dead.
	Reason string `json:"reason"`
}

type DispatchResult struct {
	// Results contains individual tool execution results.
	Results []ExecutionResult `json:"results"`

	// FormattedOutput is the results formatted for LLM consumption.
	FormattedOutput string `json:"formatted_output"`

	// RemainingText is the LLM output text with tool calls removed.
	RemainingText string `json:"remaining_text"`

	// TotalDuration is the total time for all tool executions.
	TotalDuration time.Duration `json:"total_duration"`

	// FailedCount is the number of tools that failed.
	FailedCount int `json:"failed_count"`

	// ApprovedCount is the number of tools that required and received approval.
	ApprovedCount int `json:"approved_count"`

	// DeclinedCount is the number of tools that were declined by the approver.
	DeclinedCount int `json:"declined_count"`
}

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

type DispatcherOption func(*Dispatcher)

type DominatorInfo struct {
	// ID is the full node ID.
	ID string `json:"id"`

	// Name is the function name.
	Name string `json:"name"`

	// File is the source file path.
	File string `json:"file"`

	// Line is the line number in the source file.
	Line int `json:"line"`

	// Depth is the depth in the dominator tree (0 = entry).
	Depth int `json:"depth"`
}

type EmptyParams struct {
	// Tool is the name of the tool these empty parameters belong to.
	Tool string
}

type EnhancedParser struct {
	*Parser
	// contains filtered or unexported fields
}

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

type ExecutionResult struct {
	// Call is the original tool call.
	Call ToolCall `json:"call"`

	// Result is the execution result.
	Result *Result `json:"result"`

	// Approved indicates if the tool required and received approval.
	Approved bool `json:"approved,omitempty"`

	// Declined indicates if the user declined approval for the tool.
	Declined bool `json:"declined,omitempty"`
}

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

type ExecutorOption func(*Executor)

type ExecutorOptions struct {
	// DefaultTimeout is the default execution timeout.
	DefaultTimeout time.Duration

	// MaxOutputTokens limits output size (estimated).
	MaxOutputTokens int

	// EnableCaching enables result caching.
	EnableCaching bool

	// CacheTTL is how long cached results are valid.
	CacheTTL time.Duration
}

type ExplorePackageParams struct {
	// Package is the package name or path to explore.
	Package string

	// IncludeDependencies shows packages this package imports.
	IncludeDependencies bool

	// IncludeDependents shows packages that import this package.
	IncludeDependents bool
}

type ExplorePackageResult struct {
	Name         string         `json:"name"`
	Path         string         `json:"path"`
	Files        []FileOverview `json:"files"`
	PublicAPI    PackageAPI     `json:"public_api"`
	Dependencies []string       `json:"dependencies,omitempty"`
	Dependents   []string       `json:"dependents,omitempty"`
	Summary      string         `json:"summary"`
	Purpose      string         `json:"purpose"`
	TotalSymbols int            `json:"total_symbols"`
	IsMain       bool           `json:"is_main,omitempty"`
	IsTest       bool           `json:"is_test,omitempty"`
}

type ExtractableRegionInfo struct {
	// Entry is the single entry node ID.
	Entry string `json:"entry"`

	// EntryName is the function name of the entry.
	EntryName string `json:"entry_name"`

	// Exit is the single exit node ID.
	Exit string `json:"exit"`

	// ExitName is the function name of the exit.
	ExitName string `json:"exit_name"`

	// Size is the number of nodes in the region.
	Size int `json:"size"`

	// Depth is the nesting depth (0 = top-level).
	Depth int `json:"depth"`

	// Nodes is the list of node IDs in the region (if small enough).
	Nodes []string `json:"nodes,omitempty"`

	// HasNestedRegions indicates if this region contains nested SESE regions.
	HasNestedRegions bool `json:"has_nested_regions,omitempty"`
}

type ExtractableRegionsSummary struct {
	// TotalRegions is the total SESE regions detected (before filtering).
	TotalRegions int `json:"total_regions"`

	// ExtractableCount is the number meeting size criteria.
	ExtractableCount int `json:"extractable_count"`

	// Returned is the number returned (after top limit).
	Returned int `json:"returned"`

	// MaxDepth is the maximum nesting depth found.
	MaxDepth int `json:"max_depth"`

	// AvgSize is the average region size.
	AvgSize float64 `json:"avg_size"`

	// MinSizeUsed is the actual min_size used (after clamping).
	MinSizeUsed int `json:"min_size_used"`

	// MaxSizeUsed is the actual max_size used (after clamping).
	MaxSizeUsed int `json:"max_size_used"`
}

type FileOverview struct {
	Name      string   `json:"name"`
	Path      string   `json:"path"`
	LineCount int      `json:"line_count,omitempty"`
	Symbols   []string `json:"symbols"`
	IsTest    bool     `json:"is_test,omitempty"`
}

type FileSymbolInfo struct {
	// Name is the symbol name.
	Name string `json:"name"`

	// Kind is the symbol kind.
	Kind string `json:"kind"`

	// Line is the starting line number (1-indexed).
	Line int `json:"line"`

	// EndLine is the ending line number.
	EndLine int `json:"end_line"`

	// Exported indicates if the symbol is publicly visible.
	Exported bool `json:"exported"`

	// Signature is the type signature (if available).
	Signature string `json:"signature,omitempty"`

	// Receiver is the receiver type (for methods).
	Receiver string `json:"receiver,omitempty"`
}

type FindArticulationPointsOutput struct {
	// ArticulationPoints is the list of detected articulation points.
	ArticulationPoints []ArticulationPointInfo `json:"articulation_points"`

	// Bridges is the list of critical edges.
	Bridges []BridgeInfo `json:"bridges,omitempty"`

	// TotalComponents is the number of connected components.
	TotalComponents int `json:"total_components"`

	// FragilityScore is the ratio of articulation points to total nodes.
	FragilityScore float64 `json:"fragility_score"`

	// FragilityLevel is a human-readable fragility assessment.
	FragilityLevel string `json:"fragility_level"`

	// NodeCount is the total number of nodes analyzed.
	NodeCount int `json:"node_count"`

	// EdgeCount is the total number of edges analyzed.
	EdgeCount int `json:"edge_count"`
}

type FindArticulationPointsParams struct {
	// Top is the number of articulation points to return.
	// Default: 20, Max: 100
	Top int

	// IncludeBridges indicates whether to include critical edges (bridges).
	// Default: true
	IncludeBridges bool

	// Package filters articulation points to those in a matching package/directory.
	// CRS-13: Uses matchesPackageScope() for boundary-aware cross-language matching.
	// Empty string means no filter (all articulation points returned).
	Package string
}

type FindCalleesOutput struct {
	// FunctionName is the function that was searched for.
	FunctionName string `json:"function_name"`

	// ResolvedCount is the number of in-codebase callees.
	ResolvedCount int `json:"resolved_count"`

	// ExternalCount is the number of external/stdlib callees.
	ExternalCount int `json:"external_count"`

	// TotalCount is the total number of callees.
	TotalCount int `json:"total_count"`

	// ResolvedCallees are in-codebase callees with file locations.
	ResolvedCallees []CalleeInfo `json:"resolved_callees"`

	// ExternalCallees are external/stdlib callees (names only).
	ExternalCallees []string `json:"external_callees"`

	// ResolvedKind is the ast.SymbolKind of the resolved symbol (e.g., "type", "function").
	// IT-06b Issue 3: Used by formatText to provide kind-specific messages
	// (e.g., "HandlerFunc is a type alias, not a function with a body").
	ResolvedKind string `json:"resolved_kind,omitempty"`
}

type FindCalleesParams struct {
	// FunctionName is the name of the function to find callees for.
	FunctionName string

	// Limit is the maximum number of callees to return.
	// Default: 50, Max: 1000
	Limit int

	// PackageHint is an optional package/module context extracted from the query.
	// IT-06c Bug C: Used to disambiguate when multiple symbols share the same name.
	// For example, "Build" in Hugo matches 11 symbols; "hugolib" narrows to the right one.
	PackageHint string
}

type FindCallersOutput struct {
	// FunctionName is the function that was searched for.
	FunctionName string `json:"function_name"`

	// MatchCount is the number of matching symbol IDs.
	MatchCount int `json:"match_count"`

	// TotalCallers is the total number of callers found.
	TotalCallers int `json:"total_callers"`

	// Results contains the callers grouped by target symbol ID.
	Results []CallerResult `json:"results"`
}

type FindCallersParams struct {
	// FunctionName is the name of the function to find callers for.
	FunctionName string

	// Limit is the maximum number of callers to return.
	// Default: 50, Max: 1000
	Limit int

	// PackageHint is an optional package/module context extracted from the query.
	// IT-06c Bug C: Used to disambiguate when multiple symbols share the same name.
	PackageHint string
}

type FindCommonDependencyOutput struct {
	// LCD contains information about the lowest common dominator.
	LCD LCDInfo `json:"lcd"`

	// Targets is the list of target function names that were analyzed.
	Targets []string `json:"targets"`

	// TargetsResolved is the number of targets that were successfully resolved.
	TargetsResolved int `json:"targets_resolved"`

	// Entry is the entry point name used for dominator analysis.
	Entry string `json:"entry"`

	// EntryID is the full node ID of the entry point.
	EntryID string `json:"entry_id"`

	// PathsToTargets maps each target name to its dominator chain.
	// Each chain is a list of function names from the target up to the LCD.
	PathsToTargets map[string][]string `json:"paths_to_targets"`
}

type FindCommonDependencyParams struct {
	// Targets is the list of function names to find common dependency for.
	// Must contain at least 2 function names.
	Targets []string

	// Entry is the optional entry point for dominator analysis.
	// If empty, auto-detects main/init functions.
	Entry string
}

type FindCommunitiesOutput struct {
	// Modularity is the modularity score (0-1, higher = better separation).
	Modularity float64 `json:"modularity"`

	// ModularityQuality is a human-readable quality label.
	ModularityQuality string `json:"modularity_quality"`

	// CommunityCount is the number of communities returned.
	CommunityCount int `json:"community_count"`

	// TotalCommunities is the total number of communities detected.
	TotalCommunities int `json:"total_communities"`

	// Algorithm is the algorithm used (Leiden).
	Algorithm string `json:"algorithm"`

	// Converged indicates whether the algorithm converged.
	Converged bool `json:"converged"`

	// Iterations is the number of iterations run.
	Iterations int `json:"iterations"`

	// NodeCount is the total number of nodes in the graph.
	NodeCount int `json:"node_count"`

	// EdgeCount is the total number of edges in the graph.
	EdgeCount int `json:"edge_count"`

	// Communities is the list of detected communities.
	Communities []CommunityInfo `json:"communities"`

	// CrossPackageCommunities lists IDs of communities spanning multiple packages.
	CrossPackageCommunities []int `json:"cross_package_communities"`

	// CrossCommunityEdges lists edges between communities.
	CrossCommunityEdges []CrossEdgeInfo `json:"cross_community_edges,omitempty"`
}

type FindCommunitiesParams struct {
	// MinSize is the minimum community size to report.
	// Default: 3, Max: 100
	MinSize int

	// Resolution controls community granularity.
	// 0.1 = large communities, 1.0 = balanced, 5.0 = small communities.
	// Default: 1.0
	Resolution float64

	// Top is the number of communities to return.
	// Default: 20, Max: 50
	Top int

	// ShowCrossEdges indicates whether to show edges between communities.
	// Default: true
	ShowCrossEdges bool

	// PackageFilter limits results to communities with members in this
	// directory/package (case-insensitive substring match). Default: "" (all).
	PackageFilter string
}

type FindControlDependenciesOutput struct {
	// Target is the function that was analyzed.
	Target string `json:"target"`

	// TargetID is the resolved symbol ID.
	TargetID string `json:"target_id,omitempty"`

	// Dependencies lists the nodes that control this target's execution.
	Dependencies []ControllerInfo `json:"dependencies"`

	// DependencyCount is the total number of control dependencies.
	DependencyCount int `json:"dependency_count"`

	// Summary contains aggregate statistics.
	Summary ControlDependencySummary `json:"summary"`

	// Message is an optional status message.
	Message string `json:"message,omitempty"`
}

type FindControlDependenciesParams struct {
	// Target is the function name to analyze.
	Target string

	// Depth is the maximum dependency chain depth.
	// Default: 5, Max: 10
	Depth int
}

type FindCriticalPathOutput struct {
	// Target is the target function.
	Target string `json:"target"`

	// Entry is the entry point used.
	Entry string `json:"entry"`

	// CriticalPath is the mandatory call sequence from entry to target.
	CriticalPath []CriticalPathNode `json:"critical_path"`

	// PathLength is the number of nodes in the critical path.
	PathLength int `json:"path_length"`

	// Explanation is a human-readable description.
	Explanation string `json:"explanation"`

	// Message is an optional status message.
	Message string `json:"message,omitempty"`
}

type FindCriticalPathParams struct {
	// Target is the target function to reach.
	// Required.
	Target string

	// Entry is the entry point for analysis.
	// Optional - will auto-detect if not provided.
	Entry string
}

type FindCyclesOutput struct {
	// CycleCount is the number of cycles returned.
	CycleCount int `json:"cycle_count"`

	// Cycles is the list of detected cycles.
	Cycles []CycleInfo `json:"cycles"`
}

type FindCyclesParams struct {
	// MinSize is the minimum cycle size to report.
	// Default: 2
	MinSize int

	// Limit is the maximum number of cycles to return.
	// Default: 20, Max: 100
	Limit int

	// PackageFilter filters cycles to those involving a matching package/directory.
	// Case-insensitive substring match against cycle.Packages entries.
	// Empty string means no filter (all cycles returned).
	PackageFilter string

	// SortBy controls the sort order for cycles.
	// "length_desc" (default): largest cycles first.
	// "length_asc": smallest cycles first.
	SortBy string
}

type FindDeadCodeOutput struct {
	// DeadCodeCount is the number of dead code symbols found.
	DeadCodeCount int `json:"dead_code_count"`

	// DeadCode is the list of potentially unused symbols.
	DeadCode []DeadCodeSymbol `json:"dead_code"`
}

type FindDeadCodeParams struct {
	// IncludeExported includes exported symbols (default: false).
	IncludeExported bool

	// Package filters results to a specific package path.
	Package string

	// Limit is the maximum number of results to return.
	// Default: 50, Max: 500
	Limit int

	// ExcludeTests filters out symbols from test files (default: true).
	ExcludeTests bool
}

type FindDominatorsOutput struct {
	// Target is the resolved target node ID.
	Target string `json:"target"`

	// TargetName is the function name of the target.
	TargetName string `json:"target_name"`

	// Entry is the entry point used for analysis.
	Entry string `json:"entry"`

	// EntryAutoDetected indicates if the entry was auto-detected.
	EntryAutoDetected bool `json:"entry_auto_detected"`

	// Dominators is the list of functions that dominate the target.
	// Ordered from entry to immediate dominator (shallow to deep).
	Dominators []DominatorInfo `json:"dominators"`

	// Depth is the depth of the target in the dominator tree.
	Depth int `json:"depth"`

	// ImmediateDominator is the immediate dominator of the target.
	ImmediateDominator string `json:"immediate_dominator"`

	// Subtree contains nodes dominated by the target (when show_tree=true).
	Subtree []string `json:"subtree,omitempty"`

	// Explanation is a human-readable summary.
	Explanation string `json:"explanation"`

	// Message is an optional status message.
	Message string `json:"message,omitempty"`
}

type FindDominatorsParams struct {
	// Target is the target function name or ID to find dominators for.
	// Required.
	Target string

	// Entry is the entry point for dominator analysis.
	// If empty, auto-detects main/init.
	Entry string

	// ShowTree indicates whether to show full dominator subtree of target.
	// Default: false
	ShowTree bool
}

type FindExtractableRegionsOutput struct {
	// Regions is the list of extractable SESE regions.
	Regions []ExtractableRegionInfo `json:"regions"`

	// RegionCount is the total number of regions found.
	RegionCount int `json:"region_count"`

	// Summary contains aggregate statistics.
	Summary ExtractableRegionsSummary `json:"summary"`

	// Message is an optional status message.
	Message string `json:"message,omitempty"`
}

type FindExtractableRegionsParams struct {
	// MinSize is the minimum region size to report.
	// Default: 3
	MinSize int

	// MaxSize is the maximum region size.
	// Default: 50
	MaxSize int

	// Top is the number of regions to return.
	// Default: 10, Max: 100
	Top int
}

type FindHotspotsOutput struct {
	// HotspotCount is the number of hotspots returned.
	HotspotCount int `json:"hotspot_count"`

	// Hotspots is the list of hotspot symbols.
	Hotspots []HotspotInfo `json:"hotspots"`
}

type FindHotspotsParams struct {
	// Top is the number of hotspots to return.
	// Default: 10, Max: 100
	Top int

	// Kind filters results by symbol kind.
	// Values: "function", "method", "type", "class", "struct", "interface", "enum", "variable", "constant", "all"
	// Default: "all"
	Kind string

	// Package filters results to a specific package or module path.
	// When set, only hotspots in the matching package (or file path containing
	// the package string) are returned.
	Package string

	// ExcludeTests filters out symbols from test files.
	// When true (default), symbols in files matching test patterns
	// (*_test.go, test_*.py, *.test.ts, *.spec.js, etc.) are excluded.
	ExcludeTests bool

	// SortBy controls the ranking dimension.
	// Values: "score" (default, inDegree*2+outDegree), "in" (InDegree desc), "out" (OutDegree desc)
	SortBy string
}

type FindImplementationsOutput struct {
	// InterfaceName is the interface that was searched for.
	InterfaceName string `json:"interface_name"`

	// MatchCount is the number of matching interface IDs.
	MatchCount int `json:"match_count"`

	// TotalImplementations is the total number of implementations found.
	TotalImplementations int `json:"total_implementations"`

	// Results contains the implementations grouped by interface ID.
	Results []ImplementationResult `json:"results"`
}

type FindImplementationsParams struct {
	// InterfaceName is the name of the interface to find implementations for.
	InterfaceName string

	// Limit is the maximum number of implementations to return.
	// Default: 50, Max: 1000
	Limit int

	// PackageHint is an optional package/module context extracted from the query.
	// IT-06c: Used to disambiguate when multiple types share the same name.
	PackageHint string
}

type FindImportantOutput struct {
	// ResultCount is the number of results returned.
	ResultCount int `json:"result_count"`

	// Results is the list of important symbols.
	Results []ImportantSymbol `json:"results"`

	// Algorithm is the algorithm used (PageRank).
	Algorithm string `json:"algorithm"`
}

type FindImportantParams struct {
	// Top is the number of important symbols to return.
	// Default: 10, Max: 100
	Top int

	// Kind filters results by symbol kind.
	// Values: "function", "type", "all"
	// Default: "all"
	Kind string

	// Package filters results to a specific package or module scope.
	// Uses matchesPackageScope() with 3 strategies: Package field match,
	// FilePath segment match, and file stem match.
	// IT-07: Added to match find_hotspots package filter capability.
	// Default: "" (no filter)
	Package string

	// ExcludeTests filters out symbols from test and documentation files.
	// Default: true
	ExcludeTests bool

	// Reverse returns lowest-ranked symbols first (peripheral functions).
	// IT-R2c Fix E: Supports "lowest PageRank" / "peripheral" queries.
	// Default: false
	Reverse bool
}

type FindLoopsOutput struct {
	// Loops is the list of detected natural loops.
	Loops []LoopInfo `json:"loops"`

	// Summary contains aggregate statistics.
	Summary LoopsSummary `json:"summary"`

	// Message is an optional status message.
	Message string `json:"message,omitempty"`
}

type FindLoopsParams struct {
	// Top is the number of loops to return.
	// Default: 20, Max: 100
	Top int

	// MinSize is the minimum loop body size.
	// Default: 1
	MinSize int

	// ShowNesting indicates whether to show loop nesting hierarchy.
	// Default: true
	ShowNesting bool
}

type FindMergePointsOutput struct {
	// MergePoints is the list of detected merge points.
	MergePoints []MergePointInfo `json:"merge_points"`

	// Summary contains aggregate statistics.
	Summary MergePointsSummary `json:"summary"`

	// Message is an optional status message.
	Message string `json:"message,omitempty"`
}

type FindMergePointsParams struct {
	// Top is the number of merge points to return.
	// Default: 20, Max: 100
	Top int

	// MinSources is the minimum incoming paths to qualify as merge point.
	// Default: 2
	MinSources int
}

type FindModuleAPIOutput struct {
	// Modules is the list of analyzed modules.
	Modules []ModuleAPI `json:"modules"`

	// Summary contains aggregate statistics.
	Summary ModuleAPISummary `json:"summary"`

	// Message is an optional status message.
	Message string `json:"message,omitempty"`
}

type FindModuleAPIParams struct {
	// CommunityID is the specific community to analyze.
	// -1 means analyze all communities (default).
	CommunityID int

	// Top is the number of communities to analyze.
	// Default: 10, Max: 50.
	Top int

	// MinCommunitySize is the minimum community size to analyze.
	// Default: 3.
	MinCommunitySize int
}

type FindPathOutput struct {
	// From is the starting symbol name.
	From string `json:"from"`

	// To is the target symbol name.
	To string `json:"to"`

	// Length is the path length in hops (-1 if no path found).
	Length int `json:"length"`

	// Found indicates if a path was found.
	Found bool `json:"found"`

	// Path is the list of nodes in the path.
	Path []PathNode `json:"path,omitempty"`

	// Message is an optional status message.
	Message string `json:"message,omitempty"`
}

type FindPathParams struct {
	// From is the starting symbol name.
	From string

	// To is the target symbol name.
	To string
}

type FindReferencesOutput struct {
	// SymbolName is the symbol that was searched for.
	SymbolName string `json:"symbol_name"`

	// ResolvedName is the actual symbol name after resolution (may differ from
	// SymbolName if fuzzy matching was used).
	ResolvedName string `json:"resolved_name,omitempty"`

	// DefinedAt is where the resolved symbol is defined (file:line).
	DefinedAt string `json:"defined_at,omitempty"`

	// SymbolKind is the kind of the resolved symbol (function, struct, interface, etc.).
	SymbolKind string `json:"symbol_kind,omitempty"`

	// ReferenceCount is the number of references found.
	ReferenceCount int `json:"reference_count"`

	// References is the list of reference locations.
	References []ReferenceInfo `json:"references"`
}

type FindReferencesParams struct {
	// SymbolName is the name of the symbol to find references for.
	SymbolName string

	// Limit is the maximum number of references to return.
	// Default: 100
	Limit int

	// PackageHint is an optional package/module context extracted from the query.
	// IT-06c: Used to disambiguate when multiple symbols share the same name
	// during ResolveFunctionWithFuzzy exact-match phase.
	PackageHint string
}

type FindSimilarSymbolsOutput struct {
	// SourceSymbol is the symbol that was used as the search anchor.
	SourceSymbol string `json:"source_symbol"`

	// SourceFile is the file containing the source symbol.
	SourceFile string `json:"source_file"`

	// ResultCount is the number of similar symbols found.
	ResultCount int `json:"result_count"`

	// Results contains the ranked similar symbols.
	Results []SemanticSearchResult `json:"results"`
}

type FindSimilarSymbolsParams struct {
	// SymbolName is the name of the symbol to find similar ones for.
	SymbolName string

	// Limit is the maximum number of similar symbols to return.
	// Default: 10, Max: 50
	Limit int
}

type FindSymbolOutput struct {
	// SearchName is the name that was searched for.
	SearchName string `json:"search_name"`

	// MatchCount is the number of matching symbols.
	MatchCount int `json:"match_count"`

	// Symbols is the list of matching symbols.
	Symbols []SymbolInfo `json:"symbols"`
}

type FindSymbolParams struct {
	// Name is the symbol name to search for.
	Name string

	// Kind filters by symbol kind: function, type, interface, variable, constant, method, or all.
	Kind string

	// Package filters by package path (optional).
	Package string
}

type FindWeightedCriticalityParams struct {
	// Top is the number of critical functions to return.
	// Default: 20, Range: [1, 100].
	Top int

	// Entry is the entry point for dominator analysis.
	// Empty string triggers auto-detection.
	Entry string

	// ShowQuadrant enables quadrant classification in output.
	ShowQuadrant bool

	// Package filters critical functions to those in a matching package/directory.
	// CRS-13: Uses matchesPackageScope() for boundary-aware cross-language matching.
	// Empty string means no filter (all critical functions returned).
	Package string
}

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

type FormatterOption func(*Formatter)

type FunctionCallResponse struct {
	ID       string `json:"id"`
	Type     string `json:"type"`
	Function struct {
		Name      string `json:"name"`
		Arguments string `json:"arguments"`
	} `json:"function"`
}

type GetCallChainOutput struct {
	// FunctionName is the function that was traced.
	FunctionName string `json:"function_name"`

	// Direction is the traversal direction.
	Direction string `json:"direction"`

	// Depth is the actual depth reached.
	Depth int `json:"depth"`

	// Truncated indicates if traversal was cut short.
	Truncated bool `json:"truncated"`

	// NodeCount is the number of nodes visited.
	NodeCount int `json:"node_count"`

	// EdgeCount is the number of edges traversed.
	EdgeCount int `json:"edge_count"`

	// Nodes is the list of nodes in the call chain.
	Nodes []CallChainNode `json:"nodes"`

	// Message contains optional status message.
	Message string `json:"message,omitempty"`

	// DestinationFound indicates whether the destination (from "from X to Y" queries)
	// was found in the traversal result. Only set when DestinationName was provided.
	DestinationFound bool `json:"destination_found,omitempty"`

	// PathToDestination contains only the nodes on the path from source to destination.
	// Only populated when DestinationName was provided and found in the traversal.
	PathToDestination []CallChainNode `json:"path_to_destination,omitempty"`

	// ExternalDependencies lists external library boundaries encountered during traversal.
	// IT-05a: Populated when the call chain reaches nodes outside the indexed project.
	ExternalDependencies []string `json:"external_dependencies,omitempty"`
}

type GetCallChainParams struct {
	// FunctionName is the name of the function to trace.
	FunctionName string

	// Direction is either "downstream" (callees) or "upstream" (callers).
	Direction string

	// MaxDepth is the maximum traversal depth (1-10).
	MaxDepth int

	// DestinationName is an optional endpoint for "from X to Y" queries.
	// IT-05 R5: When set, provides the resolved destination symbol ID for
	// dual-endpoint resolution. Used to enhance output messaging.
	DestinationName string

	// PackageHint is an optional package/module context extracted from the query.
	// IT-06c: Used to disambiguate when multiple symbols share the same name.
	PackageHint string
}

type GetSignatureOutput struct {
	// Name is the symbol name.
	Name string `json:"name"`

	// Matches contains signature info for each matching symbol.
	Matches []SignatureMatch `json:"matches"`

	// MatchCount is the number of matching symbols.
	MatchCount int `json:"match_count"`
}

type GetSignatureParams struct {
	// Name is the name of the symbol to get the signature for.
	Name string
}

type GraphOverviewParams struct {
	// Depth controls traversal depth (1-3).
	Depth int

	// IncludeDependencies includes inter-package dependency graph.
	IncludeDependencies bool

	// IncludeMetrics includes symbol counts and file metrics.
	IncludeMetrics bool
}

type GraphOverviewResult struct {
	Project         string              `json:"project"`
	Packages        []PackageOverview   `json:"packages"`
	DependencyGraph []PackageDependency `json:"dependency_graph,omitempty"`
	TotalPackages   int                 `json:"total_packages"`
	TotalFiles      int                 `json:"total_files"`
	TotalSymbols    int                 `json:"total_symbols"`
	Languages       []string            `json:"languages"`
}

type GrepToolParams struct {
	// Pattern is the search pattern.
	Pattern string

	// OutputMode controls output format ("content", "files_with_matches", "count").
	OutputMode string
}

type HotspotInfo struct {
	// Rank is the position in the ranking (1-based).
	Rank int `json:"rank"`

	// Name is the symbol name.
	Name string `json:"name"`

	// Kind is the symbol kind (function, type, etc.).
	Kind string `json:"kind"`

	// File is the source file path.
	File string `json:"file"`

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

	// Package is the package name.
	Package string `json:"package"`

	// Score is the connectivity score.
	Score int `json:"score"`

	// InDegree is the number of incoming edges.
	InDegree int `json:"in_degree"`

	// OutDegree is the number of outgoing edges.
	OutDegree int `json:"out_degree"`
}

type ImplementationInfo struct {
	// Name is the implementing type name.
	Name string `json:"name"`

	// File is the source file path.
	File string `json:"file"`

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

	// Package is the package name.
	Package string `json:"package"`

	// Kind is the symbol kind (struct, type, etc.).
	Kind string `json:"kind"`
}

type ImplementationResult struct {
	// InterfaceID is the interface symbol ID.
	InterfaceID string `json:"interface_id"`

	// ImplCount is the number of implementations.
	ImplCount int `json:"impl_count"`

	// Implementations is the list of implementing types.
	Implementations []ImplementationInfo `json:"implementations"`
}

type ImportantSymbol struct {
	// Rank is the position in the ranking (1-based).
	Rank int `json:"rank"`

	// Name is the symbol name.
	Name string `json:"name"`

	// Kind is the symbol kind (function, type, etc.).
	Kind string `json:"kind"`

	// File is the source file path.
	File string `json:"file"`

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

	// Package is the package name.
	Package string `json:"package"`

	// PageRank is the PageRank score.
	PageRank float64 `json:"pagerank"`

	// DegreeScore is the degree-based score for comparison.
	DegreeScore int `json:"degree_score"`
}

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

	// ToolName is the tool to invoke.
	ToolName string `json:"tool_name"`

	// Parameters are the input parameters.
	Parameters map[string]any `json:"parameters"`

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

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

	// StartedAt is when execution started (Unix milliseconds UTC).
	StartedAt int64 `json:"started_at,omitempty"`

	// CompletedAt is when execution completed (Unix milliseconds UTC).
	CompletedAt int64 `json:"completed_at,omitempty"`

	// Result contains the execution result (after completion).
	Result *Result `json:"result,omitempty"`
}

type IrreducibleRegionInfo struct {
	// ID is the region identifier.
	ID int `json:"id"`

	// EntryNodes are the multiple entry points.
	EntryNodes []string `json:"entry_nodes"`

	// Size is the number of nodes in the region.
	Size int `json:"size"`

	// CrossEdgeCount is the number of cross edges creating this region.
	CrossEdgeCount int `json:"cross_edge_count"`

	// Reason explains why this region is irreducible.
	Reason string `json:"reason,omitempty"`
}

type KindFilter int

type LCDInfo struct {
	// ID is the full node ID of the LCD.
	ID string `json:"id"`

	// Name is the function name of the LCD.
	Name string `json:"name"`

	// Depth is the depth of the LCD in the dominator tree.
	Depth int `json:"depth,omitempty"`
}

type ListPackagesResult struct {
	Packages   []PackageInfo `json:"packages"`
	TotalCount int           `json:"total_count"`
}

type ListSymbolsInFileOutput struct {
	// Path is the file path.
	Path string `json:"path"`

	// SymbolCount is the number of symbols found.
	SymbolCount int `json:"symbol_count"`

	// Symbols contains the symbols in the file.
	Symbols []FileSymbolInfo `json:"symbols"`
}

type ListSymbolsInFileParams struct {
	// Path is the file path relative to the project root.
	Path string
}

type LoopInfo struct {
	// Header is the full node ID of the loop header.
	Header string `json:"header"`

	// HeaderName is the function name of the loop header.
	HeaderName string `json:"header_name"`

	// BodySize is the number of nodes in the loop body.
	BodySize int `json:"body_size"`

	// RecursionType describes the type of recursion (direct, mutual, complex).
	RecursionType string `json:"recursion_type"`

	// Body is the list of node IDs in the loop body.
	Body []string `json:"body"`

	// BackEdges are the edges that form this loop.
	BackEdges []BackEdgeInfo `json:"back_edges,omitempty"`

	// Depth is the nesting depth of this loop.
	Depth int `json:"depth,omitempty"`

	// ParentHeader is the header of the enclosing loop (if any).
	ParentHeader string `json:"parent_header,omitempty"`

	// NestedLoops lists headers of loops nested within this one.
	NestedLoops []string `json:"nested_loops,omitempty"`
}

type LoopsSummary struct {
	// TotalLoops is the total number of loops detected.
	TotalLoops int `json:"total_loops"`

	// Returned is the number of loops returned in this result.
	Returned int `json:"returned"`

	// DirectRecursion is the count of self-calling functions.
	DirectRecursion int `json:"direct_recursion"`

	// MutualRecursion is the count of two-function cycles.
	MutualRecursion int `json:"mutual_recursion"`

	// ComplexCycles is the count of larger cycles (3+ nodes).
	ComplexCycles int `json:"complex_cycles"`

	// MaxNesting is the maximum nesting depth.
	MaxNesting int `json:"max_nesting"`

	// DeepestLoop is the header of the deepest nested loop.
	DeepestLoop string `json:"deepest_loop,omitempty"`
}

type MapParams struct {
	// Tool is the name of the tool these parameters belong to.
	Tool string

	// Params is the raw parameter map from JSON unmarshaling.
	Params map[string]any
}

type MergePointInfo struct {
	// ID is the full node ID of the merge point.
	ID string `json:"id"`

	// Name is the function name of the merge point.
	Name string `json:"name"`

	// File is the source file containing this merge point.
	File string `json:"file,omitempty"`

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

	// ConvergingPaths is the number of code paths that converge at this point.
	ConvergingPaths int `json:"converging_paths"`

	// SourceNodes lists the nodes whose dominance frontier includes this merge point.
	SourceNodes []string `json:"source_nodes,omitempty"`

	// HasMoreSources indicates if there are more source nodes than shown.
	HasMoreSources bool `json:"has_more_sources,omitempty"`
}

type MergePointsSummary struct {
	// TotalMergePoints is the total number of merge points detected.
	TotalMergePoints int `json:"total_merge_points"`

	// Returned is the number of merge points returned in this result.
	Returned int `json:"returned"`

	// MaxConvergence is the maximum convergence count among returned merge points.
	MaxConvergence int `json:"max_convergence"`

	// AvgConvergence is the average convergence count among returned merge points.
	AvgConvergence float64 `json:"avg_convergence"`
}

type MockTool struct {
	ExecuteFunc func(ctx context.Context, params TypedParams) (*Result, error)
	// contains filtered or unexported fields
}

type ModuleAPI struct {
	// CommunityID is the community identifier.
	CommunityID int `json:"community_id"`

	// Name is a human-readable module name.
	Name string `json:"name"`

	// DominantPackage is the package containing most nodes.
	DominantPackage string `json:"dominant_package"`

	// Size is the number of nodes in this community.
	Size int `json:"size"`

	// APISurface is the list of entry point functions.
	APISurface []APIFunction `json:"api_surface"`

	// InternalOnly is the list of internal-only functions (not externally callable).
	InternalOnly []string `json:"internal_only,omitempty"`

	// Note is an optional message about this module.
	Note string `json:"note,omitempty"`
}

type ModuleAPISummary struct {
	// CommunitiesAnalyzed is the number of communities analyzed.
	CommunitiesAnalyzed int `json:"communities_analyzed"`

	// CommunitiesFiltered is the number filtered by min_size.
	CommunitiesFiltered int `json:"communities_filtered"`

	// TotalAPIFunctions is the total count of API functions across all modules.
	TotalAPIFunctions int `json:"total_api_functions"`

	// AvgAPISize is the average number of API functions per module.
	AvgAPISize float64 `json:"avg_api_size"`
}

type PackageAPI struct {
	Types      []SymbolSummary `json:"types,omitempty"`
	Functions  []SymbolSummary `json:"functions,omitempty"`
	Interfaces []SymbolSummary `json:"interfaces,omitempty"`
	Constants  []SymbolSummary `json:"constants,omitempty"`
	Variables  []SymbolSummary `json:"variables,omitempty"`
}

type PackageDependency struct {
	From string `json:"from"`
	To   string `json:"to"`
	Type string `json:"type"` // "import"
}

type PackageInfo struct {
	Name        string   `json:"name"`
	Path        string   `json:"path"`
	Files       []string `json:"files"`
	FileCount   int      `json:"file_count"`
	SymbolCount int      `json:"symbol_count"`
	Types       int      `json:"types"`
	Functions   int      `json:"functions"`
	IsTest      bool     `json:"is_test,omitempty"`
}

type PackageOverview struct {
	Name        string   `json:"name"`
	Path        string   `json:"path"`
	FileCount   int      `json:"file_count"`
	SymbolCount int      `json:"symbol_count"`
	TypeCount   int      `json:"type_count"`
	FuncCount   int      `json:"func_count"`
	IsMain      bool     `json:"is_main,omitempty"`
	IsTest      bool     `json:"is_test,omitempty"`
	TopFiles    []string `json:"top_files,omitempty"`
	DependsOn   []string `json:"depends_on,omitempty"`
	DependedBy  []string `json:"depended_by,omitempty"`
}

type ParamDef struct {
	// Type is the parameter type.
	Type ParamType `json:"type"`

	// Description explains what the parameter is for.
	Description string `json:"description"`

	// Required indicates if the parameter must be provided.
	Required bool `json:"required"`

	// Default is the default value if not provided.
	// Uses `any` for JSON schema flexibility - can be string, number, boolean, etc.
	Default any `json:"default,omitempty"`

	// Enum restricts values to a set of options.
	// Uses `[]any` for JSON schema flexibility - enum values match the param type.
	Enum []any `json:"enum,omitempty"`

	// MinLength is the minimum string length (for string type).
	MinLength int `json:"minLength,omitempty"`

	// MaxLength is the maximum string length (for string type).
	MaxLength int `json:"maxLength,omitempty"`

	// Minimum is the minimum value (for numeric types).
	Minimum *float64 `json:"minimum,omitempty"`

	// Maximum is the maximum value (for numeric types).
	Maximum *float64 `json:"maximum,omitempty"`

	// Items defines array item type (for array type).
	Items *ParamDef `json:"items,omitempty"`

	// Properties defines object properties (for object type).
	Properties map[string]ParamDef `json:"properties,omitempty"`
}

type ParamType string

type ParseFormat string

type ParseResult struct {
	// ToolCalls contains extracted tool calls.
	ToolCalls []ToolCall

	// CleanedText is the text with tool calls removed.
	CleanedText string

	// Fallback indicates no format matched.
	Fallback bool

	// Partial indicates format partially matched (malformed).
	Partial bool

	// Error is non-nil if parse error occurred.
	Error error
}

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

type PathNode struct {
	// Hop is the position in the path (0-indexed).
	Hop int `json:"hop"`

	// ID is the node ID.
	ID string `json:"id"`

	// Name is the symbol name.
	Name string `json:"name,omitempty"`

	// File is the source file path.
	File string `json:"file,omitempty"`

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

	// Kind is the symbol kind.
	Kind string `json:"kind,omitempty"`
}

type ReadFileOutput struct {
	// Path is the file path.
	Path string `json:"path"`

	// Language is the detected language.
	Language string `json:"language"`

	// TotalLines is the total number of lines in the file.
	TotalLines int `json:"total_lines"`

	// StartLine is the first line returned (1-indexed).
	StartLine int `json:"start_line"`

	// EndLine is the last line returned (1-indexed).
	EndLine int `json:"end_line"`

	// Source is the file content.
	Source string `json:"source"`

	// Truncated indicates if the response was limited by max lines (500).
	Truncated bool `json:"truncated"`
}

type ReadFileParams struct {
	// Path is the file path relative to the project root.
	Path string

	// StartLine is the first line to read (1-indexed, inclusive). Default: 1.
	StartLine int

	// EndLine is the last line to read (1-indexed, inclusive). Default: 200.
	EndLine int

	// Truncated is true when the requested range exceeded 500 lines and was clamped.
	Truncated bool
}

type ReadSymbolMatch struct {
	// Name is the symbol name.
	Name string `json:"name"`

	// FilePath is the file containing the symbol.
	FilePath string `json:"file_path"`

	// StartLine is the first line of the symbol (1-indexed).
	StartLine int `json:"start_line"`

	// EndLine is the last line of the symbol (1-indexed).
	EndLine int `json:"end_line"`

	// Language is the source language.
	Language string `json:"language"`

	// Kind is the symbol kind.
	Kind string `json:"kind"`

	// Source is the source code of the symbol.
	Source string `json:"source"`

	// Truncated indicates if the source was truncated (over 500 lines).
	Truncated bool `json:"truncated"`

	// LineCount is the total number of lines in the symbol.
	LineCount int `json:"line_count"`
}

type ReadSymbolOutput struct {
	// Name is the symbol name.
	Name string `json:"name"`

	// Matches contains the source code for each matching symbol.
	Matches []ReadSymbolMatch `json:"matches"`

	// MatchCount is the number of matching symbols.
	MatchCount int `json:"match_count"`
}

type ReadSymbolParams struct {
	// Name is the name of the symbol to read source code for.
	Name string

	// Kind is an optional filter for the symbol kind (function, class, etc.).
	Kind string

	// PackageHint is an optional package/module context for disambiguation.
	PackageHint string
}

type RecoveryResult struct {
	// OriginalError is the error that was analyzed.
	OriginalError string `json:"original_error"`

	// Category is the type of error (e.g., "file_not_found", "timeout").
	Category string `json:"category"`

	// Suggestion is the recovery suggestion.
	Suggestion string `json:"suggestion"`

	// Retryable indicates if the operation might succeed on retry.
	Retryable bool `json:"retryable"`
}

type ReferenceInfo struct {
	// SymbolID is the symbol ID being referenced.
	SymbolID string `json:"symbol_id"`

	// Package is the package containing the reference.
	Package string `json:"package"`

	// File is the source file path.
	File string `json:"file"`

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

	// Column is the column number.
	Column int `json:"column"`
}

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

type ResolveFuzzyOpt func(*resolveFuzzyConfig)

type ResolvedTarget struct {
	Name string
	ID   string
}

type Result struct {
	// Success indicates if the tool succeeded.
	Success bool `json:"success"`

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

	// OutputText is a text representation of the output.
	OutputText string `json:"output_text"`

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

	// Duration is how long execution took.
	Duration time.Duration `json:"duration"`

	// TokensUsed estimates the output token count.
	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"`

	// ModifiedFiles lists files written or modified by this tool.
	// Used by DirtyTracker to trigger incremental graph refresh.
	// Tools that write to the file system should populate this.
	ModifiedFiles []string `json:"modified_files,omitempty"`

	// Metadata contains additional result metadata.
	Metadata map[string]any `json:"metadata,omitempty"`

	// TraceStep is the CRS trace step for this tool execution.
	// Tools that want full CRS integration should populate this.
	// The dispatcher/execute phase will record it to the session.
	TraceStep *crs.TraceStep `json:"trace_step,omitempty"`

	// ResultCount is the number of discrete results the tool produced.
	// Used by CRS Layer 2 to detect empty-result conditions for CDCL clause generation.
	// Tools should set this; if 0, the phase will attempt extraction from TraceStep metadata.
	ResultCount int `json:"result_count,omitempty"`

	// ScopeApplied is the package/directory scope filter that was applied to this result.
	// CRS-SCOPE-01: Used by scope relaxation to detect empty scoped results
	// that should be retried with a wider scope.
	ScopeApplied string `json:"scope_applied,omitempty"`

	// PreScopeCount is the number of results before scope filtering was applied.
	// CRS-SCOPE-01: When ResultCount==0 and PreScopeCount>0, scope relaxation
	// knows that results exist but were filtered out by the scope.
	PreScopeCount int `json:"pre_scope_count,omitempty"`

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

type SanitizeResult struct {
	// Content is the sanitized output safe for context injection.
	Content string

	// OriginalLength is the byte length before sanitization.
	OriginalLength int

	// WasTruncated indicates if output was cut short.
	WasTruncated bool

	// TruncatedBytes is how many bytes were removed.
	TruncatedBytes int

	// EscapedPatterns lists which patterns were escaped.
	EscapedPatterns []string

	// SuspiciousPatterns lists concerning patterns found (for logging).
	SuspiciousPatterns []string

	// Modified indicates if any changes were made.
	Modified bool
}

type SanitizerConfig struct {
	// MaxOutputBytes is hard limit on output size (default: 100KB).
	MaxOutputBytes int

	// MaxOutputTokens is soft limit for context budget (default: 30k).
	MaxOutputTokens int

	// CustomDangerousPatterns adds additional patterns to escape.
	CustomDangerousPatterns []string

	// CustomSuspiciousPatterns adds additional suspicious patterns.
	CustomSuspiciousPatterns []string

	// EnableSuspiciousLogging logs when suspicious content detected.
	EnableSuspiciousLogging bool

	// Logger for warnings (optional).
	Logger *slog.Logger
}

type SemanticSearchOutput struct {
	// Query is the search query that was executed.
	Query string `json:"query"`

	// ResultCount is the number of results found.
	ResultCount int `json:"result_count"`

	// Results contains the ranked search results.
	Results []SemanticSearchResult `json:"results"`
}

type SemanticSearchParams struct {
	// Query is the natural language search query.
	Query string

	// Limit is the maximum number of results to return.
	// Default: 10, Max: 50
	Limit int

	// MinScore is the minimum similarity threshold (0.0-1.0).
	// Default: 0.5
	MinScore float64
}

type SemanticSearchResult struct {
	// Name is the symbol name.
	Name string `json:"name"`

	// Kind is the symbol kind (function, method, class, etc.).
	Kind string `json:"kind"`

	// PackagePath is the package/module path.
	PackagePath string `json:"package_path"`

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

	// Score is the similarity score (0.0-1.0, higher is more similar).
	Score float64 `json:"score"`
}

type SignatureMatch struct {
	// Name is the symbol name.
	Name string `json:"name"`

	// Kind is the symbol kind (function, method, class, etc.).
	Kind string `json:"kind"`

	// FilePath is the file containing the symbol.
	FilePath string `json:"file_path"`

	// StartLine is the first line of the symbol (1-indexed).
	StartLine int `json:"start_line"`

	// Signature is the type signature or declaration.
	Signature string `json:"signature"`

	// DocComment is the extracted documentation comment.
	DocComment string `json:"doc_comment"`

	// Exported indicates if the symbol is publicly visible.
	Exported bool `json:"exported"`

	// Package is the package or module name.
	Package string `json:"package"`

	// Receiver is the receiver type (for Go methods).
	Receiver string `json:"receiver,omitempty"`
}

type SymbolInfo struct {
	// ID is the symbol's unique identifier.
	ID string `json:"id"`

	// Name is the symbol name.
	Name string `json:"name"`

	// Kind is the symbol kind.
	Kind string `json:"kind"`

	// File is the source file path.
	File string `json:"file"`

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

	// Package is the package name.
	Package string `json:"package"`

	// Signature is the function/method signature.
	Signature string `json:"signature,omitempty"`

	// Exported indicates if the symbol is exported.
	Exported bool `json:"exported"`
}

type SymbolSummary struct {
	Name      string `json:"name"`
	Kind      string `json:"kind"`
	Signature string `json:"signature,omitempty"`
	File      string `json:"file"`
	Line      int    `json:"line"`
	Exported  bool   `json:"exported"`
}

type Tool interface {
	// Name returns the unique tool name.
	Name() string

	// Category returns the tool category.
	Category() ToolCategory

	// Definition returns the tool's parameter schema.
	Definition() ToolDefinition

	// Execute runs the tool with the given parameters.
	//
	// Inputs:
	//   ctx - Context for cancellation and timeout
	//   params - Typed parameters (use params.ToMap() to access raw map)
	//
	// Outputs:
	//   *Result - Execution result
	//   error - Non-nil if execution failed
	Execute(ctx context.Context, params TypedParams) (*Result, error)
}

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

	// Name is the tool name to invoke.
	Name string `json:"name"`

	// Params contains the parsed parameters.
	Params json.RawMessage `json:"params"`

	// Raw is the original text for debugging.
	Raw string `json:"raw"`
}

type ToolCategory string

type ToolDefinition struct {
	// Name is the unique identifier for the tool.
	Name string `json:"name"`

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

	// Parameters defines the input parameters.
	Parameters map[string]ParamDef `json:"parameters"`

	// Category is the tool category (exploration, reasoning, safety, file).
	Category ToolCategory `json:"category"`

	// Priority influences tool selection (higher = prefer).
	Priority int `json:"priority"`

	// Requires lists dependencies (e.g., "graph_initialized").
	Requires []string `json:"requires,omitempty"`

	// SideEffects indicates if the tool modifies state.
	SideEffects bool `json:"side_effects"`

	// Timeout is the default execution timeout.
	Timeout time.Duration `json:"timeout,omitempty"`

	// Examples provides usage examples.
	Examples []ToolExample `json:"examples,omitempty"`

	// WhenToUse provides structured routing guidance for the tool router.
	// CB-31e: Part of the tool contract - every new tool should define this.
	WhenToUse WhenToUse `json:"when_to_use,omitempty" yaml:"when_to_use,omitempty"`
}

type ToolExample struct {
	// Description explains what the example demonstrates.
	Description string `json:"description"`

	// Parameters are the example input parameters.
	Parameters map[string]any `json:"parameters"`

	// ExpectedOutput describes what output to expect.
	ExpectedOutput string `json:"expected_output,omitempty"`
}

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

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

	// When describes the scenario where substitution applies.
	When string `json:"when" yaml:"when"`
}

type TypedParams interface {
	// ToMap converts the typed parameters to the untyped map consumed
	// by Tool.Execute(). This is the ONLY place where typed params
	// become untyped — all upstream code works with concrete types.
	ToMap() map[string]any

	// ToolName returns the name of the tool these parameters belong to.
	// Used for validation and logging.
	ToolName() string
}

type ValidationError struct {
	// Parameter is the parameter name that failed validation.
	Parameter string `json:"parameter"`

	// Message describes the validation failure.
	Message string `json:"message"`

	// Expected describes what was expected.
	Expected string `json:"expected,omitempty"`

	// Actual describes what was received.
	Actual string `json:"actual,omitempty"`
}