refactor: consolidate nvim crates, extract server library, and update workspace dependencies

server/src/tools.rs

@@ -18,14 +18,14 @@ pub struct WriteClipboardTool {
     pub image_path: Option<String>,
 }
 
-/// Create new entities in the knowledge graph.
+/// Create new entities in the knowledge graph. Note: entity_type MUST ALWAYS be PascalCase (e.g. DatabaseTable, McpTool, File).
 #[derive(Debug, Deserialize, Serialize, JsonSchema)]
 pub struct CreateEntitiesTool {
     /// Array of entities to create.
     pub entities: Vec<crate::models::Entity>,
 }
 
-/// Create new relations between entities in the knowledge graph.
+/// Create new relations between entities in the knowledge graph. Note: relation_type MUST ALWAYS be snake_case (e.g. depends_on, calls, implements).
 #[derive(Debug, Deserialize, Serialize, JsonSchema)]
 pub struct CreateRelationsTool {
     /// Array of relations to create.
@@ -77,6 +77,8 @@ pub struct DeleteRelationsTool {
 pub struct ReadGraphTool {
     /// Optional namespace to restrict the read to.
     pub namespace: Option<String>,
+    /// Optional token budget cap. Truncates graph outputs to fit within the specified token budget.
+    pub max_tokens: Option<usize>,
 }
 
 /// Search for entities in the knowledge graph by name or type.
@@ -110,6 +112,10 @@ pub struct LogCodeChangeTool {
     pub git_commit: Option<String>,
     /// The associated git branch, if any.
     pub git_branch: Option<String>,
+    /// Optional symbol references (e.g. ['MemoryIndex', 'switchTab']) modified in this change.
+    pub symbol_references: Option<Vec<String>>,
+    /// Optional line range (e.g. 'L123-L145') modified in the target file.
+    pub line_range: Option<String>,
 }
 
 /// Query recently logged code changes.
@@ -125,11 +131,39 @@ pub struct VisualizeGraphTool {
     pub namespace: Option<String>,
 }
 
+#[derive(Debug, Deserialize, Serialize, JsonSchema, PartialEq)]
+#[serde(rename_all = "snake_case")]
+pub enum StickyNoteAction {
+    Add,
+    Read,
+    Delete,
+    Clear,
+}
+
+/// Manage ephemeral sticky notes with TTL (add, read, delete, clear).
+#[derive(Debug, Deserialize, Serialize, JsonSchema)]
+pub struct ManageStickyNotesTool {
+    /// Action to perform: 'add', 'read', 'delete', or 'clear'.
+    pub action: StickyNoteAction,
+    /// Content of the sticky note (required for 'add').
+    pub content: Option<String>,
+    /// 1-indexed position of the sticky note to delete (required for 'delete').
+    pub index: Option<usize>,
+    /// Optional time-to-live in seconds (for 'add').
+    pub ttl_seconds: Option<u64>,
+    /// Optional flag to auto-expire the note at the end of the current session (for 'add').
+    pub session_only: Option<bool>,
+}
+
 /// Add a sticky note for unstructured thoughts or reminders.
 #[derive(Debug, Deserialize, Serialize, JsonSchema)]
 pub struct AddStickyNoteTool {
     /// The content of the sticky note.
     pub content: String,
+    /// Optional time-to-live in seconds. Automatically expires the note after specified duration.
+    pub ttl_seconds: Option<u64>,
+    /// Optional flag to auto-expire the note at the end of the current session.
+    pub session_only: Option<bool>,
 }
 
 /// Read all active sticky notes.
@@ -193,6 +227,10 @@ pub struct UpdateTaskStatusTool {
 pub struct ListActiveTasksTool {
     /// Optional git branch to filter tasks by.
     pub git_branch: Option<String>,
+    /// Optional summary level: 'compact' (IDs and titles), 'detailed', or 'full'. Defaults to 'detailed'.
+    pub summary_level: Option<String>,
+    /// Optional token budget cap. Truncates results to stay within max_tokens.
+    pub max_tokens: Option<usize>,
 }
 
 /// Store a reusable code snippet.
@@ -206,16 +244,39 @@ pub struct StoreSnippetTool {
     pub code: String,
     /// A description of what the snippet does.
     pub description: String,
+    /// Optional classification tags (e.g. ['rust', 'async', 'mcp']).
+    pub tags: Option<Vec<String>>,
 }
 
-/// Search through stored code snippets.
+/// Add classification tags to an existing code snippet.
+#[derive(Debug, Deserialize, Serialize, JsonSchema)]
+pub struct TagSnippetTool {
+    /// The name of the snippet to tag.
+    pub name: String,
+    /// Array of tags (e.g. ['rust', 'async', 'mcp']).
+    pub tags: Vec<String>,
+}
+
+#[derive(Debug, Deserialize, Serialize, JsonSchema, PartialEq)]
+#[serde(rename_all = "snake_case")]
+pub enum SnippetSearchMode {
+    Hybrid,
+    Keyword,
+    Semantic,
+}
+
+/// Search stored code snippets using Hybrid BM25 + Vector ranking or keyword search.
 #[derive(Debug, Deserialize, Serialize, JsonSchema)]
 pub struct SearchSnippetsTool {
     /// The search query.
     pub query: String,
-    /// Limit the number of results to avoid context limit overflow. Defaults to 5.
+    /// Search mode: 'hybrid' (BM25 + Semantic Tags), 'keyword', or 'semantic'. Defaults to 'hybrid'.
+    pub mode: Option<SnippetSearchMode>,
+    /// Optional classification tags to filter by.
+    pub tags: Option<Vec<String>>,
+    /// Limit the number of results to avoid context limit overflow. Defaults to 10.
     pub limit: Option<usize>,
-    /// Include the full code content of the matched items. If false, returns only IDs and descriptions (recommended for LLMs to prevent context bloat). Defaults to false.
+    /// Include the full code content of the matched items. If false, returns only IDs and descriptions. Defaults to false.
     pub include_body: Option<bool>,
 }
 
@@ -226,6 +287,77 @@ pub struct DeleteSnippetTool {
     pub name: String,
 }
 
+#[derive(Debug, Deserialize, Serialize, JsonSchema, PartialEq)]
+#[serde(rename_all = "snake_case")]
+pub enum SubgraphFormat {
+    Json,
+    MarkdownTree,
+}
+
+/// Extract a multi-hop neighborhood subgraph around a specific root entity node as JSON or Markdown topology tree.
+#[derive(Debug, Deserialize, Serialize, JsonSchema)]
+pub struct GetSubgraphTool {
+    /// The root entity name to start the subgraph search from.
+    pub root_entity: Option<String>,
+    /// Legacy alias for root_entity.
+    pub root_node: Option<String>,
+    /// Maximum search depth (hops). Defaults to 2.
+    pub depth: Option<u32>,
+    /// Output format: 'json' (raw entities and relations) or 'markdown_tree' (compact topology tree). Defaults to 'json'.
+    pub format: Option<SubgraphFormat>,
+    /// Optional namespace filter.
+    pub namespace: Option<String>,
+    /// Target maximum token length for generated summary when format is 'markdown_tree'. Defaults to 1000.
+    pub max_tokens: Option<usize>,
+}
+
+/// Search historical error fixes using keyword search or semantic vector similarity and return matching solutions.
+#[derive(Debug, Deserialize, Serialize, JsonSchema)]
+pub struct SuggestErrorFixTool {
+    /// The exact stack trace or error signature.
+    pub stack_trace: String,
+    /// Maximum number of suggested fixes to return. Defaults to 3.
+    pub limit: Option<usize>,
+}
+
+#[derive(Debug, Deserialize, Serialize, JsonSchema, PartialEq)]
+#[serde(rename_all = "snake_case")]
+pub enum CheckpointAction {
+    Create,
+    Restore,
+    List,
+    Delete,
+}
+
+/// Save, restore, list, or delete point-in-time memory state snapshot checkpoints.
+#[derive(Debug, Deserialize, Serialize, JsonSchema)]
+pub struct ManageCheckpointTool {
+    /// Action to perform: 'create', 'restore', 'list', or 'delete'.
+    pub action: CheckpointAction,
+    /// Unique name or ID for the snapshot checkpoint.
+    pub name_or_id: Option<String>,
+    /// Optional description of why this checkpoint was created.
+    pub description: Option<String>,
+    /// Optional namespace filter.
+    pub namespace: Option<String>,
+}
+
+/// Save a named memory snapshot checkpoint before risky operations or subagent invocations.
+#[derive(Debug, Deserialize, Serialize, JsonSchema)]
+pub struct CheckpointStateTool {
+    /// The unique name for this state snapshot checkpoint.
+    pub name: String,
+    /// Optional description of why this checkpoint was created.
+    pub description: Option<String>,
+}
+
+/// Restore a previously saved memory snapshot checkpoint.
+#[derive(Debug, Deserialize, Serialize, JsonSchema)]
+pub struct RestoreStateTool {
+    /// The name of the checkpoint to restore.
+    pub name: String,
+}
+
 /// Log an architectural decision record (ADR).
 #[derive(Debug, Deserialize, Serialize, JsonSchema)]
 pub struct LogDecisionTool {
@@ -296,16 +428,22 @@ pub struct LogErrorFixTool {
     pub git_commit: Option<String>,
     /// The associated git branch, if any.
     pub git_branch: Option<String>,
+    /// Optional symbol references (e.g. ['MemoryIndex', 'switchTab']) associated with the error.
+    pub symbol_references: Option<Vec<String>>,
+    /// Optional line range (e.g. 'L123-L145') associated with the error.
+    pub line_range: Option<String>,
 }
 
-/// Search through previously logged error fixes.
+/// Search historical error fixes using keyword query or stack trace vector similarity.
 #[derive(Debug, Deserialize, Serialize, JsonSchema)]
 pub struct SearchErrorFixesTool {
-    /// The search query.
-    pub query: String,
+    /// The search query string.
+    pub query: Option<String>,
+    /// Exact stack trace or error signature for vector cosine matching.
+    pub stack_trace: Option<String>,
     /// Limit the number of results to avoid context limit overflow. Defaults to 5.
     pub limit: Option<usize>,
-    /// Include the full solution details. If false, returns only error signatures (recommended for LLMs to prevent context bloat). Defaults to false.
+    /// Include the full solution details. If false, returns only error signatures. Defaults to false.
     pub include_body: Option<bool>,
 }
 
@@ -514,6 +652,10 @@ pub struct LogTechDebtTool {
     pub git_commit: Option<String>,
     /// The associated git branch, if any.
     pub git_branch: Option<String>,
+    /// Optional symbol references (e.g. ['MemoryIndex', 'switchTab']) associated with the tech debt.
+    pub symbol_references: Option<Vec<String>>,
+    /// Optional line range (e.g. 'L123-L145') associated with the tech debt.
+    pub line_range: Option<String>,
 }
 
 /// Resolve a technical debt record.
@@ -531,6 +673,10 @@ pub struct ListTechDebtTool {
     pub namespace: String,
     /// Whether to include resolved technical debt in the results.
     pub include_resolved: bool,
+    /// Optional summary level: 'compact' (IDs and descriptions), 'detailed', or 'full'. Defaults to 'detailed'.
+    pub summary_level: Option<String>,
+    /// Optional token budget cap. Truncates results to stay within max_tokens.
+    pub max_tokens: Option<usize>,
 }
 
 /// Save the current context workspace.
@@ -574,7 +720,7 @@ pub struct DeleteContextWorkspaceTool {
     pub name: String,
 }
 
-/// Search across all memory stores (Graph, Tasks, Snippets, ADRs, etc.).
+/// Search across all memory stores (Graph, Tasks, Snippets, ADRs, Error Fixes, Tech Debt) using Hybrid Reciprocal Rank Fusion (BM25 + Dense Vectors).
 /// Highly recommended for discovery. Supports Lucene query syntax.
 #[derive(Debug, Deserialize, Serialize, JsonSchema)]
 pub struct OmniSearchTool {
@@ -586,6 +732,8 @@ pub struct OmniSearchTool {
     pub limit: Option<usize>,
     /// Include the full body/content of the matched items. If false, returns only IDs and titles (recommended for LLMs to prevent context bloat). Defaults to false.
     pub include_body: Option<bool>,
+    /// Optional token budget cap. Dynamically caps and truncates search results to stay within max_tokens.
+    pub max_tokens: Option<usize>,
 }
 
 /// Get a health digest of the project.
@@ -620,6 +768,62 @@ pub struct VerifyAcceptanceCriteriaTool {
     pub proof: String,
 }
 
+/// Audit the knowledge graph to detect orphaned entities, compute name similarity for potential duplicate merges, and optionally auto-prune orphans.
+#[derive(Debug, Deserialize, Serialize, JsonSchema)]
+pub struct SweepGraphHealthTool {
+    /// Optional flag to automatically prune orphaned nodes with 0 relations. Defaults to false.
+    pub auto_prune_orphans: Option<bool>,
+    /// Minimum string similarity threshold (0.0 to 1.0) to report duplicate entity pairs. Defaults to 0.8.
+    pub similarity_threshold: Option<f32>,
+}
+
+/// Trace the causal provenance and historical lineage linking a task, ADR, git commit, code change, or error fix.
+#[derive(Debug, Deserialize, Serialize, JsonSchema)]
+pub struct QueryLineageTool {
+    /// The task ID, file path, symbol name, or git commit to query lineage for.
+    pub query: String,
+}
+
+/// Topological task resolver that returns unblocked, ready-to-run active tasks.
+#[derive(Debug, Deserialize, Serialize, JsonSchema)]
+pub struct GetNextActionableTasksTool {
+    /// Optional git branch filter.
+    pub git_branch: Option<String>,
+    /// Limit the number of actionable tasks returned. Defaults to 5.
+    pub limit: Option<usize>,
+}
+
+/// Log a structured diagnostic hypothesis, tested evidence, and status during problem solving.
+#[derive(Debug, Deserialize, Serialize, JsonSchema)]
+pub struct LogHypothesisTool {
+    /// Optional task ID associated with this hypothesis.
+    pub task_id: Option<String>,
+    /// The diagnostic hypothesis or potential root cause.
+    pub hypothesis: String,
+    /// Status: 'unverified', 'verified', or 'rejected'. Defaults to 'unverified'.
+    pub status: Option<String>,
+    /// Evidence or test results supporting or disproving the hypothesis.
+    pub evidence: Option<String>,
+}
+
+/// Query previously logged diagnostic hypotheses and test results.
+#[derive(Debug, Deserialize, Serialize, JsonSchema)]
+pub struct QueryHypothesesTool {
+    /// Optional task ID to filter hypotheses for.
+    pub task_id: Option<String>,
+    /// Optional search query text.
+    pub query: Option<String>,
+}
+
+/// Compare two saved context workspaces and return a structured diff of pinned files, active tasks, and metadata.
+#[derive(Debug, Deserialize, Serialize, JsonSchema)]
+pub struct DiffContextWorkspacesTool {
+    /// The name of the first context workspace.
+    pub workspace_a: String,
+    /// The name of the second context workspace.
+    pub workspace_b: String,
+}
+
 #[cfg(test)]
 mod tests {
     use super::*;
@@ -714,6 +918,25 @@ pub struct RestoreSnapshotTool {
     pub snapshot_id: String,
 }
 
+#[derive(Debug, Deserialize, Serialize, JsonSchema, PartialEq)]
+#[serde(rename_all = "snake_case")]
+pub enum SubagentNamespaceAction {
+    Create,
+    Condense,
+    Purge,
+}
+
+/// Manage isolated memory namespaces for subagent sessions (create, condense/promote, or purge).
+#[derive(Debug, Deserialize, Serialize, JsonSchema)]
+pub struct ManageSubagentNamespaceTool {
+    /// Action to perform: 'create', 'condense', or 'purge'.
+    pub action: SubagentNamespaceAction,
+    /// Subagent namespace ID.
+    pub subagent_id: String,
+    /// For 'condense': whether to auto-purge the subagent namespace after promotion. Defaults to true.
+    pub purge_after_promotion: Option<bool>,
+}
+
 /// Create an isolated memory namespace for a subagent session.
 #[derive(Debug, Deserialize, Serialize, JsonSchema)]
 pub struct CreateSubagentNamespaceTool {
@@ -725,3 +948,138 @@ pub struct CreateSubagentNamespaceTool {
 pub struct PurgeSubagentNamespaceTool {
     pub subagent_id: String,
 }
+
+/// Find all source locations and AST chunks where a specific symbol (function, struct, method, type) is referenced or called.
+#[derive(Debug, Deserialize, Serialize, JsonSchema)]
+pub struct FindSymbolReferencesTool {
+    /// The symbol name (e.g. 'MemoryState', 'handle_search', 'AppError').
+    pub symbol: String,
+    /// Optional maximum number of reference locations to return. Defaults to 10.
+    pub limit: Option<usize>,
+}
+
+/// Find all caller functions or methods that invoke a specified target function or method name.
+#[derive(Debug, Deserialize, Serialize, JsonSchema)]
+pub struct GetCallersTool {
+    /// The target function or method name (e.g. 'generate_embeddings_async', 'keyword_search').
+    pub function_name: String,
+    /// Optional maximum number of callers to return. Defaults to 10.
+    pub limit: Option<usize>,
+}
+
+/// Query git commit history, diffs, and change ledger entries using keyword or semantic search.
+#[derive(Debug, Deserialize, Serialize, JsonSchema)]
+pub struct QueryGitDiffsTool {
+    /// Search query (e.g. 'deploy-server', 'shutdown', 'debounce', 'rename trick').
+    pub query: String,
+    /// Optional maximum number of commit diff entries to return. Defaults to 5.
+    pub limit: Option<usize>,
+}
+
+/// Promote a transient sticky note or active task observation into a permanent Knowledge Graph entity.
+#[derive(Debug, Deserialize, Serialize, JsonSchema)]
+pub struct PromoteToEntityTool {
+    /// Note text or content to promote.
+    pub content: String,
+    /// Target entity name to create or merge into.
+    pub entity_name: String,
+    /// Entity type (e.g. 'Component', 'Decision', 'BugFix', 'Architecture').
+    pub entity_type: String,
+    /// Optional namespace. Defaults to 'default'.
+    #[serde(default = "crate::models::default_namespace")]
+    pub namespace: String,
+}
+
+/// Analyze the potential downstream breaking impact of modifying a function, struct, or file across AST callers and Knowledge Graph relations.
+#[derive(Debug, Deserialize, Serialize, JsonSchema)]
+pub struct AnalyzeImpactTool {
+    /// Target function, struct, or symbol name (e.g. 'MemoryState', 'execute', 'AppError').
+    pub target_symbol: String,
+    /// Optional file path.
+    pub file_path: Option<String>,
+}
+
+/// Auto-condense a subagent's memory namespace and promote its high-value entities/relations to the global Knowledge Graph.
+#[derive(Debug, Deserialize, Serialize, JsonSchema)]
+pub struct CondenseSubagentNamespaceTool {
+    /// The subagent namespace ID to consolidate.
+    pub subagent_id: String,
+    /// Whether to auto-purge the subagent namespace after promotion. Defaults to true.
+    pub purge_after_promotion: Option<bool>,
+}
+
+/// Get a consolidated 1-page executive summary of current active branch, active task, pinned files, open tech debt, and diagnostic hypotheses in 1 turn.
+#[derive(Debug, Deserialize, Serialize, JsonSchema)]
+pub struct GetPreflightContextTool {
+    /// Optional namespace. Defaults to 'default'.
+    #[serde(default = "crate::models::default_namespace")]
+    pub namespace: String,
+    /// Optional git branch to filter context for.
+    pub git_branch: Option<String>,
+}
+
+/// Inspect Knowledge Graph entities, observations, and tech debt symbol/line references against current files on disk and AST, flagging and healing stale or broken pointers.
+#[derive(Debug, Deserialize, Serialize, JsonSchema)]
+pub struct ResolveStaleSymbolsTool {
+    /// Optional entity or file path to check. If omitted, checks all graph entities and tech debts.
+    pub target: Option<String>,
+    /// Whether to automatically update or remove broken references. Defaults to true.
+    pub auto_heal: Option<bool>,
+}
+
+/// Generate a compact, LLM-optimized Markdown topology or summary of a graph component capped within a strict token budget.
+#[derive(Debug, Deserialize, Serialize, JsonSchema)]
+pub struct SummarizeSubgraphTool {
+    /// The root entity name to center the summary on (e.g. 'MemoryState', 'ServerRouter').
+    pub root_entity: String,
+    /// Search depth from root entity. Defaults to 2.
+    pub depth: Option<usize>,
+    /// Target maximum token length for the generated summary. Defaults to 1000.
+    pub max_tokens: Option<usize>,
+}
+
+/// Broadcast a real-time signal or status transition to other subagents on the inter-agent signal bus.
+#[derive(Debug, Deserialize, Serialize, JsonSchema)]
+pub struct BroadcastAgentSignalTool {
+    /// Sender agent ID or role (e.g. 'PrePushAuditor', 'MemoryLibrarian').
+    pub sender: String,
+    /// Signal type or event category (e.g. 'AUDIT_PASSED', 'REPRODUCER_READY', 'TESTS_FAILED').
+    pub signal_type: String,
+    /// JSON or text payload containing event details or artifact URIs.
+    pub payload: String,
+    /// Optional Time-To-Live in seconds for the signal. Defaults to 3600 (1 hour).
+    pub ttl_seconds: Option<u64>,
+}
+
+/// Query active inter-agent signals published by subagents on the inter-agent signal bus.
+#[derive(Debug, Deserialize, Serialize, JsonSchema)]
+pub struct QueryAgentSignalsTool {
+    /// Optional sender filter (e.g. 'PrePushAuditor').
+    pub sender: Option<String>,
+    /// Optional signal_type filter (e.g. 'AUDIT_PASSED').
+    pub signal_type: Option<String>,
+    /// Optional limit on returned signals. Defaults to 20.
+    pub limit: Option<usize>,
+}
+
+/// Trigger an automated context checkpoint, summarizing active tasks, hypotheses, recent commits, and open tech debt into a permanent HandoffMemo.
+#[derive(Debug, Deserialize, Serialize, JsonSchema)]
+pub struct AutoSessionCheckpointTool {
+    /// Author or agent ID creating the checkpoint. Defaults to 'AutoCheckpoint'.
+    pub author: Option<String>,
+    /// Optional namespace. Defaults to 'default'.
+    #[serde(default = "crate::models::default_namespace")]
+    pub namespace: String,
+}
+
+/// Hybrid BM25 & semantic tag search across stored code snippets, returning ranked code patterns with relevance scores.
+#[derive(Debug, Deserialize, Serialize, JsonSchema)]
+pub struct SearchSnippetsHybridTool {
+    /// Query string (e.g. 'rate limiter', 'websocket client', 'shutdown poll').
+    pub query: String,
+    /// Optional tags to filter by.
+    pub tags: Option<Vec<String>>,
+    /// Maximum number of snippets to return. Defaults to 10.
+    pub limit: Option<usize>,
+}
+