@phuetz/code-buddy 1.6.1 → 2.0.0

package/dist/codebuddy/tools.js

@@ -4,6 +4,7 @@
  * Main entry point for tool definitions and management.
  * Tools are now organized in modular files under tool-definitions/.
  */
+import { setDeferredMCPSchemas } from "../tools/deferred-schema-state.js";
 import { MCPManager } from "../mcp/client.js";
 import { loadMCPConfig } from "../mcp/config.js";
 import { getToolSelector, selectRelevantTools } from "../tools/tool-selector.js";
@@ -12,18 +13,95 @@ import { getToolRegistry } from "../tools/registry.js";
 import { createRegisterToolTool } from "../tools/register-tool-handler.js";
 import { loadAuthoredTools } from "../agent/self-improvement/tool-skill-mutator.js";
 import { applyToolFilter } from "../utils/tool-filter.js";
-import { TOOL_METADATA } from "../tools/metadata.js";
+import { getActiveToolMetadata } from "../tools/metadata.js";
 import { getPluginMarketplace } from "../plugins/marketplace.js";
+import { getWorkspace } from '../workspace/workspace-config.js';
+import { filterToolNamesForSurface, filterToolsForSurface, } from '../config/feature-surface.js';
 // Import modular tool definitions
-import { CORE_TOOLS, MORPH_EDIT_TOOL, isMorphEnabled, SEARCH_TOOLS, TODO_TOOLS, KANBAN_TOOLS, MESSAGING_TOOLS, YUANBAO_TOOLS, HOMEASSISTANT_TOOLS, MOA_TOOLS, SPOTIFY_TOOLS, X_SEARCH_TOOLS, FEISHU_TOOLS, CRON_TOOLS, WEB_TOOLS, ADVANCED_TOOLS, MULTIMODAL_TOOLS, COMPUTER_CONTROL_TOOLS, BROWSER_TOOLS, CANVAS_TOOLS, AGENT_TOOLS, FIRECRAWL_TOOLS, LSP_TOOLS, SECRETS_TOOLS, ADVISOR_TOOLS, ASK_USER_QUESTION_TOOLS, EXIT_PLAN_MODE_TOOLS, CODEBASE_REPLACE_TOOLS, SESSION_TOOLS, CODE_EXPLORER_TOOLS, WINDOWS_TOOLS, } from "./tool-definitions/index.js";
+import { CORE_TOOLS, SELF_DESCRIBE_TOOLS, SELF_EVOLUTION_TOOLS, MORPH_EDIT_TOOL, isMorphEnabled, SEARCH_TOOLS, WORKSPACE_TOOLS, TODO_TOOLS, KANBAN_TOOLS, MESSAGING_TOOLS, YUANBAO_TOOLS, HOMEASSISTANT_TOOLS, MOA_TOOLS, SPOTIFY_TOOLS, X_SEARCH_TOOLS, FEISHU_TOOLS, CRON_TOOLS, WEB_TOOLS, RESEARCH_TOOLS, CODE_EXEC_TOOLS, MEETING_TOOLS, COMFY_RECIPE_TOOLS, ADVANCED_TOOLS, MULTIMODAL_TOOLS, COMPUTER_CONTROL_TOOLS, BROWSER_TOOLS, CANVAS_TOOLS, AGENT_TOOLS, FIRECRAWL_TOOLS, LSP_TOOLS, SECRETS_TOOLS, ADVISOR_TOOLS, VERIFY_TOOLS, DELEGATE_AGENT_TOOLS, BUG_FINDER_TOOLS, DOCUMENT_GENERATOR_TOOLS, ASK_USER_QUESTION_TOOLS, EXIT_PLAN_MODE_TOOLS, CODEBASE_REPLACE_TOOLS, MERGE_CONFLICT_TOOLS, VULN_SCANNER_TOOLS, SESSION_TOOLS, CODE_EXPLORER_TOOLS, WINDOWS_TOOLS, } from "./tool-definitions/index.js";
 import { FLEET_TOOLS } from "./fleet-tool-defs.js";
+import { isContextZoomEnabled } from '../context/segment-archive.js';
+// 20 pre-authored tool definitions (wired into the registry as AUTHORED_EXTRA_TOOLS).
+// Loosely-typed literal definitions → cast the group to CodeBuddyTool[] below.
+import { SCAFFOLD_APP_TOOL_DEFINITION } from "../tools/scaffold-app-tool.js";
+import { PROJECT_MAP_TOOL_DEFINITION } from "../tools/project-map-tool.js";
+import { DEP_INSPECT_TOOL_DEFINITION } from "../tools/dep-inspect-tool.js";
+import { CODE_STATS_TOOL_DEFINITION } from "../tools/code-stats-tool.js";
+import { GIT_SUMMARY_TOOL_DEFINITION } from "../tools/git-summary-tool.js";
+import { TODO_SCAN_TOOL_DEFINITION } from "../tools/todo-scan-tool.js";
+import { JSON_QUERY_TOOL_DEFINITION } from "../tools/json-query-tool.js";
+import { CSV_PREVIEW_TOOL_DEFINITION } from "../tools/csv-preview-tool.js";
+import { ENV_DOCTOR_TOOL_DEFINITION } from "../tools/env-doctor-tool.js";
+import { PORT_CHECK_TOOL_DEFINITION } from "../tools/port-check-tool.js";
+import { LINT_PROJECT_TOOL_DEFINITION } from "../tools/lint-project-tool.js";
+import { TEST_RUNNER_TOOL_DEFINITION } from "../tools/test-runner-tool.js";
+import { FORMAT_PROJECT_TOOL_DEFINITION } from "../tools/format-project-tool.js";
+import { BUNDLE_ANALYZE_TOOL_DEFINITION } from "../tools/bundle-analyze-tool.js";
+import { BUILD_PROJECT_TOOL_DEFINITION } from "../tools/build-project-tool.js";
+import { LICENSE_CHECK_TOOL_DEFINITION } from "../tools/license-check-tool.js";
+import { SBOM_GENERATE_TOOL_DEFINITION } from "../tools/sbom-generate-tool.js";
+import { HTTP_PROBE_TOOL_DEFINITION } from "../tools/http-probe-tool.js";
+import { FILE_SEARCH_TOOL_DEFINITION } from "../tools/file-search-tool.js";
+import { DIFF_FILES_TOOL_DEFINITION } from "../tools/diff-files-tool.js";
+/**
+ * The 20 pre-authored tools, exposed to the LLM. Their adapters are registered
+ * for interactive dispatch in `ToolHandler.initializeRegistry()` via
+ * `createAuthoredExtraTools()` — keep both in lockstep (dispatch ⊇ exposed).
+ */
+const AUTHORED_EXTRA_TOOLS = [
+    SCAFFOLD_APP_TOOL_DEFINITION,
+    PROJECT_MAP_TOOL_DEFINITION,
+    DEP_INSPECT_TOOL_DEFINITION,
+    CODE_STATS_TOOL_DEFINITION,
+    GIT_SUMMARY_TOOL_DEFINITION,
+    TODO_SCAN_TOOL_DEFINITION,
+    JSON_QUERY_TOOL_DEFINITION,
+    CSV_PREVIEW_TOOL_DEFINITION,
+    ENV_DOCTOR_TOOL_DEFINITION,
+    PORT_CHECK_TOOL_DEFINITION,
+    LINT_PROJECT_TOOL_DEFINITION,
+    TEST_RUNNER_TOOL_DEFINITION,
+    FORMAT_PROJECT_TOOL_DEFINITION,
+    BUNDLE_ANALYZE_TOOL_DEFINITION,
+    BUILD_PROJECT_TOOL_DEFINITION,
+    LICENSE_CHECK_TOOL_DEFINITION,
+    SBOM_GENERATE_TOOL_DEFINITION,
+    HTTP_PROBE_TOOL_DEFINITION,
+    FILE_SEARCH_TOOL_DEFINITION,
+    DIFF_FILES_TOOL_DEFINITION,
+];
+/** Opt-in exact recovery for summaries annotated with [segment:…]. */
+export const CONTEXT_EXPAND_TOOL = {
+    type: 'function',
+    function: {
+        name: 'context_expand',
+        description: 'Expand the exact original messages archived for a compacted [segment:…] summary in the current session. Use context_expand whenever a [segment:…] summary is insufficient to answer precisely.',
+        parameters: {
+            type: 'object',
+            properties: {
+                segment_id: {
+                    type: 'string',
+                    description: 'Segment identifier shown inside a [segment:…] marker.',
+                },
+                max_tokens: {
+                    type: 'number',
+                    description: 'Maximum tokens to return (default 4000, hard maximum 8000).',
+                },
+            },
+            required: ['segment_id'],
+        },
+    },
+};
 // Explicit re-exports from tool-definitions (no blanket export *)
-export { CORE_TOOLS, MORPH_EDIT_TOOL, isMorphEnabled, SEARCH_TOOLS, TODO_TOOLS, KANBAN_TOOLS, MESSAGING_TOOLS, YUANBAO_TOOLS, HOMEASSISTANT_TOOLS, MOA_TOOLS, SPOTIFY_TOOLS, X_SEARCH_TOOLS, FEISHU_TOOLS, CRON_TOOLS, WEB_TOOLS, ADVANCED_TOOLS, MULTIMODAL_TOOLS, COMPUTER_CONTROL_TOOLS, BROWSER_TOOLS, CANVAS_TOOLS, REASON_TOOL, EXECUTE_CODE_TOOL, WINDOWS_TOOLS, } from "./tool-definitions/index.js";
+export { CORE_TOOLS, SELF_DESCRIBE_TOOLS, SELF_EVOLUTION_TOOLS, MORPH_EDIT_TOOL, isMorphEnabled, CODE_EXEC_TOOLS, SEARCH_TOOLS, TODO_TOOLS, KANBAN_TOOLS, MESSAGING_TOOLS, YUANBAO_TOOLS, HOMEASSISTANT_TOOLS, MOA_TOOLS, SPOTIFY_TOOLS, X_SEARCH_TOOLS, FEISHU_TOOLS, CRON_TOOLS, WEB_TOOLS, RESEARCH_TOOLS, ADVANCED_TOOLS, MULTIMODAL_TOOLS, LSP_TOOLS, COMPUTER_CONTROL_TOOLS, BROWSER_TOOLS, CANVAS_TOOLS, REASON_TOOL, EXECUTE_CODE_TOOL, WINDOWS_TOOLS, } from "./tool-definitions/index.js";
 export function getBuiltinToolNames() {
     const groups = [
         CORE_TOOLS,
+        SELF_DESCRIBE_TOOLS,
+        SELF_EVOLUTION_TOOLS,
         [MORPH_EDIT_TOOL],
         SEARCH_TOOLS,
+        WORKSPACE_TOOLS,
         TODO_TOOLS,
         KANBAN_TOOLS,
         MESSAGING_TOOLS,
@@ -35,6 +113,10 @@ export function getBuiltinToolNames() {
         FEISHU_TOOLS,
         CRON_TOOLS,
         WEB_TOOLS,
+        RESEARCH_TOOLS,
+        CODE_EXEC_TOOLS,
+        MEETING_TOOLS,
+        COMFY_RECIPE_TOOLS,
         ADVANCED_TOOLS,
         MULTIMODAL_TOOLS,
         COMPUTER_CONTROL_TOOLS,
@@ -45,15 +127,27 @@ export function getBuiltinToolNames() {
         LSP_TOOLS,
         SECRETS_TOOLS,
         ADVISOR_TOOLS,
+        VERIFY_TOOLS,
+        DELEGATE_AGENT_TOOLS,
+        BUG_FINDER_TOOLS,
+        DOCUMENT_GENERATOR_TOOLS,
         ASK_USER_QUESTION_TOOLS,
         EXIT_PLAN_MODE_TOOLS,
         CODEBASE_REPLACE_TOOLS,
+        MERGE_CONFLICT_TOOLS,
+        VULN_SCANNER_TOOLS,
         SESSION_TOOLS,
         FLEET_TOOLS,
         CODE_EXPLORER_TOOLS,
         WINDOWS_TOOLS,
+        AUTHORED_EXTRA_TOOLS,
+        [CONTEXT_EXPAND_TOOL],
     ];
-    return Array.from(new Set(groups.flatMap((tools) => tools.map((tool) => tool.function.name))));
+    const names = Array.from(new Set(groups.flatMap((tools) => tools.map((tool) => tool.function.name))));
+    const surfaceNames = isContextZoomEnabled()
+        ? names
+        : names.filter((name) => name !== 'context_expand');
+    return filterToolNamesForSurface(surfaceNames);
 }
 // ============================================================================
 // Tool Registry Initialization
@@ -66,7 +160,7 @@ export function initializeToolRegistry() {
     if (isRegistryInitialized)
         return;
     const registry = getToolRegistry();
-    const metadataMap = new Map(TOOL_METADATA.map(m => [m.name, m]));
+    const metadataMap = new Map(getActiveToolMetadata().map(m => [m.name, m]));
     const registerGroup = (tools, isEnabled = () => true) => {
         for (const tool of tools) {
             const name = tool.function.name;
@@ -82,6 +176,9 @@ export function initializeToolRegistry() {
     };
     // Register all tool groups
     registerGroup(CORE_TOOLS);
+    registerGroup(SELF_DESCRIBE_TOOLS);
+    registerGroup(SELF_EVOLUTION_TOOLS);
+    registerGroup([CONTEXT_EXPAND_TOOL], () => process.env.CODEBUDDY_CONTEXT_ZOOM === 'true');
     // Register Morph tool separately with its own enabled check
     const morphMetadata = metadataMap.get('edit_file') || {
         name: 'edit_file',
@@ -91,19 +188,23 @@ export function initializeToolRegistry() {
         description: 'High-speed file editing with Morph'
     };
     registry.registerTool(MORPH_EDIT_TOOL, morphMetadata, isMorphEnabled);
-    // Self-improvement: expose `register_tool` + reload persisted authored tools,
-    // only when opted in.
+    // The legacy `register_tool` shortcut remains opt-in. Persisted authored
+    // tools are always re-gated and reloaded because `extension_forge` is a
+    // default, confirmation-gated authoring surface.
     if (process.env.CODEBUDDY_SELF_IMPROVE === 'true') {
         const schema = createRegisterToolTool().getSchema();
         registry.registerTool({ type: 'function', function: { name: schema.name, description: schema.description, parameters: schema.parameters } }, { name: schema.name, category: 'system', keywords: ['authored', 'self-extension', 'register', 'tool'], priority: 6, description: schema.description });
+    }
+    if (process.env.CODEBUDDY_LOAD_AUTHORED_TOOLS !== 'false') {
         try {
             const loaded = loadAuthoredTools();
             if (loaded.length > 0)
-                logger.info(`[self-improve] reloaded ${loaded.length} authored tool(s): ${loaded.join(', ')}`);
+                logger.debug(`[self-improve] reloaded ${loaded.length} authored tool(s): ${loaded.join(', ')}`);
         }
         catch { /* persisted store optional */ }
     }
     registerGroup(SEARCH_TOOLS);
+    registerGroup(WORKSPACE_TOOLS, () => getWorkspace() !== null);
     registerGroup(TODO_TOOLS);
     registerGroup(KANBAN_TOOLS);
     registerGroup(MESSAGING_TOOLS);
@@ -115,6 +216,10 @@ export function initializeToolRegistry() {
     registerGroup(FEISHU_TOOLS);
     registerGroup(CRON_TOOLS);
     registerGroup(WEB_TOOLS);
+    registerGroup(RESEARCH_TOOLS);
+    registerGroup(CODE_EXEC_TOOLS);
+    registerGroup(MEETING_TOOLS);
+    registerGroup(COMFY_RECIPE_TOOLS);
     registerGroup(ADVANCED_TOOLS);
     registerGroup(MULTIMODAL_TOOLS);
     registerGroup(COMPUTER_CONTROL_TOOLS);
@@ -123,12 +228,26 @@ export function initializeToolRegistry() {
     registerGroup(AGENT_TOOLS);
     // Firecrawl tools — gated by API key (Native Engine v2026.3.14)
     registerGroup(FIRECRAWL_TOOLS, () => !!process.env.FIRECRAWL_API_KEY);
-    // LSP rename/refactor tools
+    // LSP navigation/diagnostics and rename/refactor tools
     registerGroup(LSP_TOOLS);
     // Secrets detector tools
     registerGroup(SECRETS_TOOLS);
     // Advisor tool (second opinion from a stronger reviewer)
     registerGroup(ADVISOR_TOOLS);
+    // Verify tool (explicit delegation to the independent Verifier agent)
+    registerGroup(VERIFY_TOOLS);
+    // delegate_agent — reaches the built-in specialized agents (pdf/excel/
+    // data_analysis/sql/archive/swe) via AgentRegistry.executeOn(). DataAnalysis
+    // and SQL have no covering single-shot tool, so this closes a real capability
+    // gap; the LLM bridge for the SWE agent is wired at boot (setDelegateAgentProvider).
+    registerGroup(DELEGATE_AGENT_TOOLS);
+    // find_bugs (regex static analysis) + generate_document (PPTX/DOCX/XLSX/PDF).
+    // Both are finished features with real implementations that were exported but
+    // never added to any exposition group — dispatched by ToolHandler now, so
+    // this makes them reachable. generate_document complements the read-only
+    // `document` tool (whose own output references it).
+    registerGroup(BUG_FINDER_TOOLS);
+    registerGroup(DOCUMENT_GENERATOR_TOOLS);
     // AskUserQuestion tool (structured multi-option mid-task questions)
     registerGroup(ASK_USER_QUESTION_TOOLS);
     // ExitPlanMode tool (request approval to leave plan mode)
@@ -137,6 +256,12 @@ export function initializeToolRegistry() {
     registerGroup(WINDOWS_TOOLS, () => process.platform === 'win32');
     // Codebase replace tools
     registerGroup(CODEBASE_REPLACE_TOOLS);
+    // Merge-conflict resolver (resolve_conflicts) + vulnerability scanner
+    // (scan_vulnerabilities). Both are dispatched by ToolHandler.initializeRegistry()
+    // (createMergeConflictTools / createVulnScannerTools) but were never exposed to
+    // the LLM — this closes that gap so the finished features are reachable.
+    registerGroup(MERGE_CONFLICT_TOOLS);
+    registerGroup(VULN_SCANNER_TOOLS);
     // Session tools — multi-agent coordination (Phase E wake of SessionToolExecutor).
     // Always available; the SessionRegistry is lazy-instantiated by getSessionRegistry()
     // singleton on first use. Persistence + cleanup timer require [multi_agent_system.sessions].enabled
@@ -147,6 +272,37 @@ export function initializeToolRegistry() {
     registerGroup(FLEET_TOOLS);
     // CodeExplorer tools
     registerGroup(CODE_EXPLORER_TOOLS);
+    // 20 pre-authored tools (scaffold_app, project_map, git_summary, file_search, …).
+    // Dispatch adapters registered in ToolHandler.initializeRegistry() via
+    // createAuthoredExtraTools() so exposition and dispatch stay in lockstep.
+    registerGroup(AUTHORED_EXTRA_TOOLS);
+    // tool_search — the progressive-disclosure escape hatch. The class existed
+    // (ToolSearchTool, dispatched via ToolHandler.initializeRegistry) but was
+    // never EXPOSED here, so the model literally could not call it and the
+    // alwaysInclude('tool_search') in tool selection silently added nothing.
+    registerGroup([
+        {
+            type: 'function',
+            function: {
+                name: 'tool_search',
+                description: 'Search for available tools by keyword. Use this when the tool you need is not in your current tool list — it returns matching tool names and descriptions (and loads deferred schemas).',
+                parameters: {
+                    type: 'object',
+                    properties: {
+                        query: {
+                            type: 'string',
+                            description: 'Search query — keywords describing what you need to do.',
+                        },
+                        max_results: {
+                            type: 'number',
+                            description: 'Maximum number of results (default: 10).',
+                        },
+                    },
+                    required: ['query'],
+                },
+            },
+        },
+    ]);
     isRegistryInitialized = true;
     logger.debug('Tool registry initialized with built-in tools');
 }
@@ -161,21 +317,66 @@ export function getMCPManager() {
     }
     return mcpManager;
 }
+/** The Code Explorer engine ships under two MCP server names — `code-explorer` (user config)
+ *  and `gitnexus` (the committed repo template). Match BOTH so detection/steering work
+ *  regardless of which name the user wired (previously only `code-explorer` was recognized,
+ *  silently un-steering anyone using the committed `gitnexus` entry). */
+const CODE_EXPLORER_TOOL_RE = /^(mcp__(?:code-explorer|gitnexus)__)/;
+/** Pure: the Code Explorer tool prefix present in a list of tool names, or null. Testable
+ *  without a live MCP manager. */
+export function matchCodeExplorerPrefix(toolNames) {
+    for (const name of toolNames) {
+        const m = name.match(CODE_EXPLORER_TOOL_RE);
+        if (m)
+            return m[1];
+    }
+    return null;
+}
 /**
- * True when the Code Explorer (code-explorer) MCP tools are connected — i.e. at least
- * one `mcp__code-explorer__*` tool is registered. Used to conditionally steer the
- * agent toward Code Explorer for relationship/impact questions. Returns false
- * (no behavior change) whenever Code Explorer is not installed.
+ * True when the Code Explorer MCP tools are connected (server named `code-explorer` OR
+ * `gitnexus`). Used to conditionally steer the agent toward Code Explorer for
+ * relationship/impact questions. Returns false (no behavior change) when not installed.
  */
 export function isCodeExplorerAvailable() {
     try {
-        return getMCPManager().getTools().some((t) => t.name.startsWith('mcp__code-explorer__'));
+        return matchCodeExplorerPrefix(getMCPManager().getTools().map((t) => t.name)) !== null;
     }
     catch {
         return false;
     }
 }
-export async function initializeMCPServers() {
+/** The live Code Explorer tool prefix (`mcp__code-explorer__` or `mcp__gitnexus__`), or null
+ *  when not connected. Lets callers build the right `mcp__<server>__<op>` tool name. */
+export function codeExplorerToolPrefix() {
+    try {
+        return matchCodeExplorerPrefix(getMCPManager().getTools().map((t) => t.name));
+    }
+    catch {
+        return null;
+    }
+}
+let mcpServersInitPromise = null;
+/** Drop the process-wide MCP singleton (tests / one-shot CLI teardown). */
+export async function resetMCPManager() {
+    const current = mcpManager;
+    mcpManager = null;
+    mcpServersInitPromise = null;
+    if (current) {
+        await current.dispose();
+    }
+}
+export function initializeMCPServers() {
+    if (mcpServersInitPromise)
+        return mcpServersInitPromise;
+    const run = initializeMCPServersOnce();
+    const tracked = run.finally(() => {
+        if (mcpServersInitPromise === tracked)
+            mcpServersInitPromise = null;
+    });
+    mcpServersInitPromise = tracked;
+    return tracked;
+}
+async function initializeMCPServersOnce() {
     const manager = getMCPManager();
     const config = loadMCPConfig();
     // Store original stderr.write
@@ -209,14 +410,7 @@ export async function initializeMCPServers() {
         }
     });
     try {
-        for (const serverConfig of config.servers) {
-            try {
-                await manager.addServer(serverConfig);
-            }
-            catch (error) {
-                logger.warn(`Failed to initialize MCP server ${serverConfig.name}: ${error instanceof Error ? error.message : String(error)}`);
-            }
-        }
+        await manager.ensureServersInitialized(config);
     }
     finally {
         // Restore original stderr.write
@@ -243,30 +437,10 @@ export function convertMCPToolToCodeBuddyTool(mcpTool) {
  *  so for moderate tool counts it's better to keep full schemas and let RAG
  *  tool-selection pick the relevant ~15. Override with CODEBUDDY_MCP_DEFER_THRESHOLD. */
 const DEFERRED_SCHEMA_THRESHOLD = Number(process.env.CODEBUDDY_MCP_DEFER_THRESHOLD) || 30;
-/** Full MCP tool schemas stored for deferred retrieval */
-let _deferredMCPSchemas = null;
-/**
- * Get the deferred MCP schemas map (for tool_search to resolve full schemas).
- */
-export function getDeferredMCPSchemas() {
-    return _deferredMCPSchemas ?? new Map();
-}
-/**
- * Check if deferred MCP schema loading is active.
- */
-export function isDeferredSchemaMode() {
-    return _deferredMCPSchemas !== null && _deferredMCPSchemas.size > 0;
-}
-/**
- * Resolve full schemas for MCP tools by name (called by tool_search).
- */
-export function resolveDeferredSchemas(toolNames) {
-    if (!_deferredMCPSchemas)
-        return [];
-    return toolNames
-        .map(name => _deferredMCPSchemas.get(name))
-        .filter((t) => t !== undefined);
-}
+// The deferred-schema STATE lives in tools/deferred-schema-state.ts so that
+// tool_search reads it without importing this module (cycle break). These are
+// re-exported for the existing importers of tools.ts.
+export { getDeferredMCPSchemas, isDeferredSchemaMode, resolveDeferredSchemas, } from '../tools/deferred-schema-state.js';
 export function addMCPToolsToCodeBuddyTools(baseTools) {
     if (!mcpManager) {
         return baseTools;
@@ -274,17 +448,17 @@ export function addMCPToolsToCodeBuddyTools(baseTools) {
     const mcpTools = mcpManager.getTools();
     // If below threshold, include full schemas as before
     if (mcpTools.length <= DEFERRED_SCHEMA_THRESHOLD) {
-        _deferredMCPSchemas = null;
+        setDeferredMCPSchemas(null);
         const codebuddyMCPTools = mcpTools.map(convertMCPToolToCodeBuddyTool);
         return [...baseTools, ...codebuddyMCPTools];
     }
     // Deferred mode: store full schemas, only send stubs to LLM
     logger.debug(`Deferred MCP schema loading active: ${mcpTools.length} tools exceed threshold ${DEFERRED_SCHEMA_THRESHOLD}`);
-    _deferredMCPSchemas = new Map();
+    const deferred = new Map();
     const stubs = [];
     for (const mcpTool of mcpTools) {
         const full = convertMCPToolToCodeBuddyTool(mcpTool);
-        _deferredMCPSchemas.set(full.function.name, full);
+        deferred.set(full.function.name, full);
         // Stub: name + description only, no parameters (forces tool_search)
         stubs.push({
             type: 'function',
@@ -299,6 +473,7 @@ export function addMCPToolsToCodeBuddyTools(baseTools) {
             },
         });
     }
+    setDeferredMCPSchemas(deferred);
     return [...baseTools, ...stubs];
 }
 /**
@@ -391,14 +566,19 @@ export async function getAllCodeBuddyTools() {
     }
     // Apply CLI tool filter (--enabled-tools, --disabled-tools, --allowed-tools)
     allTools = applyToolFilter(allTools);
+    // An explicitly focused profile removes optional product faculties before
+    // both RAG selection and the tool_search index are built. With no profile,
+    // this returns the original array unchanged.
+    allTools = filterToolsForSurface(allTools);
     // When Code Explorer (code-explorer) is connected, make the built-in graph tools
     // defer to it at the decision point — its graph is broader / more complete.
     // Conditional & non-mutating: returns fresh objects only for code_graph /
     // codebase_map, and only when a code-explorer tool is present (no change otherwise).
-    if (allTools.some((t) => t.function.name.startsWith('mcp__code-explorer__'))) {
-        const DEFER = ' NOTE: Code Explorer (code-explorer) is available — for code-relationship, blast-radius/impact, ' +
-            'dead-code and cycle questions PREFER its MCP tools (`mcp__code-explorer__impact` / `context` / ' +
-            '`query` / `find_cycles`); use this built-in only as a fallback if a code-explorer tool errors.';
+    const cexPrefix = codeExplorerToolPrefix(); // 'mcp__code-explorer__' | 'mcp__gitnexus__' | null
+    if (cexPrefix) {
+        const DEFER = ` NOTE: Code Explorer is available — for code-relationship, blast-radius/impact, ` +
+            `dead-code and cycle questions PREFER its MCP tools (\`${cexPrefix}impact\` / \`${cexPrefix}context\` / ` +
+            `\`${cexPrefix}query\` / \`${cexPrefix}find_cycles\`); use this built-in only as a fallback if it errors.`;
         allTools = allTools.map((t) => t.function.name === 'code_graph' || t.function.name === 'codebase_map'
             ? { ...t, function: { ...t.function, description: (t.function.description ?? '') + DEFER } }
             : t);
@@ -526,7 +706,7 @@ export function getSkillAugmentedTools(currentTools, skill) {
     // Skill requirements must not bypass CLI/custom-agent/Fleet profile
     // filters. Re-apply the active schema filter after augmentation so a
     // disabled tool cannot reappear in the model-facing tool schema.
-    return applyToolFilter([...currentTools, ...missingTools]);
+    return applyToolFilter(filterToolsForSurface([...currentTools, ...missingTools]));
 }
 // Initialize registry on module load
 initializeToolRegistry();

package/dist/cognition/budget-reservations.d.ts

@@ -0,0 +1,27 @@
+export interface CognitiveBudgetLimits {
+    maxActivationsPerHour: number;
+    maxUsdPerHour: number;
+}
+export interface CognitiveBudgetSnapshot {
+    activations: number;
+    committedUsd: number;
+    reservedUsd: number;
+    rejected: number;
+}
+export interface CognitiveBudgetReservation {
+    id: string;
+    commit(actualUsd: number): void;
+    release(): void;
+}
+/** Atomic in-process admission budget. Free calls still consume activation quota. */
+export declare class CognitiveBudgetLedger {
+    private readonly limits;
+    private readonly now;
+    private readonly entries;
+    private readonly rejected;
+    private sequence;
+    constructor(limits: CognitiveBudgetLimits, now?: () => number);
+    reserve(specialistId: string, estimatedUsd: number): CognitiveBudgetReservation | null;
+    snapshot(specialistId: string): CognitiveBudgetSnapshot;
+    private prune;
+}

package/dist/cognition/budget-reservations.js

@@ -0,0 +1,70 @@
+/** Atomic in-process admission budget. Free calls still consume activation quota. */
+export class CognitiveBudgetLedger {
+    limits;
+    now;
+    entries = new Map();
+    rejected = new Map();
+    sequence = 0;
+    constructor(limits, now = Date.now) {
+        this.limits = limits;
+        this.now = now;
+    }
+    reserve(specialistId, estimatedUsd) {
+        const now = this.now();
+        this.prune(now);
+        const estimate = Math.max(0, Number.isFinite(estimatedUsd) ? estimatedUsd : 0);
+        const current = [...this.entries.values()].filter((entry) => entry.specialistId === specialistId);
+        const usd = current.reduce((sum, entry) => sum + (entry.status === 'committed' ? entry.actualUsd ?? 0 : entry.estimatedUsd), 0);
+        if (current.length >= Math.max(0, this.limits.maxActivationsPerHour) ||
+            usd + estimate > Math.max(0, this.limits.maxUsdPerHour)) {
+            this.rejected.set(specialistId, (this.rejected.get(specialistId) ?? 0) + 1);
+            return null;
+        }
+        const id = `cognitive_budget_${now}_${++this.sequence}`;
+        this.entries.set(id, {
+            id,
+            specialistId,
+            createdAt: now,
+            estimatedUsd: estimate,
+            status: 'reserved',
+        });
+        let settled = false;
+        return {
+            id,
+            commit: (actualUsd) => {
+                if (settled)
+                    return;
+                settled = true;
+                const entry = this.entries.get(id);
+                if (!entry)
+                    return;
+                entry.status = 'committed';
+                entry.actualUsd = Math.max(0, Number.isFinite(actualUsd) ? actualUsd : estimate);
+            },
+            release: () => {
+                if (settled)
+                    return;
+                settled = true;
+                this.entries.delete(id);
+            },
+        };
+    }
+    snapshot(specialistId) {
+        this.prune(this.now());
+        const current = [...this.entries.values()].filter((entry) => entry.specialistId === specialistId);
+        return {
+            activations: current.length,
+            committedUsd: current.reduce((sum, entry) => sum + (entry.actualUsd ?? 0), 0),
+            reservedUsd: current.reduce((sum, entry) => sum + (entry.status === 'reserved' ? entry.estimatedUsd : 0), 0),
+            rejected: this.rejected.get(specialistId) ?? 0,
+        };
+    }
+    prune(now) {
+        const cutoff = now - 60 * 60_000;
+        for (const [id, entry] of this.entries) {
+            if (entry.createdAt < cutoff)
+                this.entries.delete(id);
+        }
+    }
+}
+//# sourceMappingURL=budget-reservations.js.map

package/dist/cognition/cognitive-bus-client.d.ts

@@ -0,0 +1,94 @@
+import { EventEmitter } from 'node:events';
+import type { CognitivePublishAck, CognitiveSubscriptionEvent } from './cognitive-hub.js';
+import { type CognitiveContextAcquireRequest, type CognitiveDraft } from './cognitive-wire-contract.js';
+import type { WorkspaceKind } from './types.js';
+export interface CognitiveBusClientOptions {
+    /** Gateway endpoint, for example ws://127.0.0.1:3000/ws. */
+    wsUrl: string;
+    /** Defaults to the HTTP origin beside wsUrl plus /api/cognition. */
+    httpBaseUrl?: string;
+    apiKey?: string;
+    jwt?: string;
+    kinds?: readonly WorkspaceKind[];
+    requestTimeoutMs?: number;
+    snapshotPageSize?: number;
+    liveBufferCapacity?: number;
+    dedupeCapacity?: number;
+    autoReconnect?: boolean;
+    reconnectInitialMs?: number;
+    reconnectMaxMs?: number;
+    fetch?: typeof globalThis.fetch;
+}
+export interface CognitiveContextHandle {
+    readonly leaseId: string | null;
+    readonly turnContext: string;
+    readonly evidence: string;
+    readonly itemIds: readonly string[];
+    commit(): Promise<void>;
+    release(): Promise<void>;
+}
+export type CognitiveEventListener = (event: CognitiveSubscriptionEvent) => void;
+export declare class CognitiveBusClientError extends Error {
+    readonly code: string;
+    readonly cause?: unknown | undefined;
+    constructor(code: string, message: string, cause?: unknown | undefined);
+}
+/**
+ * Resumable cross-process cognitive bus client.
+ *
+ * It subscribes before taking an HTTP snapshot, buffers live events during
+ * recovery, and only then drains the buffer. This closes the otherwise subtle
+ * subscribe/snapshot race without pretending WebSocket delivery is durable.
+ */
+export declare class CognitiveBusClient extends EventEmitter {
+    private readonly options;
+    private readonly wsUrl;
+    private readonly httpBaseUrl;
+    private readonly requestTimeoutMs;
+    private readonly snapshotPageSize;
+    private readonly liveBufferCapacity;
+    private readonly dedupeCapacity;
+    private readonly fetchImpl;
+    private readonly kinds?;
+    private ws;
+    private pending;
+    private seen;
+    private liveBuffer;
+    private cursor;
+    private serverEpoch;
+    private desiredConnected;
+    private ready;
+    private recovering;
+    private recoveryRequested;
+    private connecting;
+    private reconnectTimer;
+    private reconnectAttempt;
+    private generation;
+    private hasEverBeenReady;
+    constructor(options: CognitiveBusClientOptions);
+    get isReady(): boolean;
+    get currentRevision(): number;
+    get currentServerEpoch(): string | null;
+    connect(): Promise<void>;
+    disconnect(): Promise<void>;
+    subscribe(listener: CognitiveEventListener): () => void;
+    publish(draft: CognitiveDraft, clientEventId?: `${string}-${string}-${string}-${string}-${string}`): Promise<CognitivePublishAck>;
+    cancel(correlationId: string): Promise<boolean>;
+    acquireContext(options?: Omit<CognitiveContextAcquireRequest, 'version'>): Promise<CognitiveContextHandle>;
+    private openConnection;
+    private initializeSession;
+    private handleFrame;
+    private handleLiveEvent;
+    private recoverUntilStable;
+    private recoverSnapshot;
+    private fetchSnapshot;
+    private drainLiveBuffer;
+    private deliver;
+    private resetForEpoch;
+    private request;
+    private handleSocketClosed;
+    private scheduleReconnect;
+    private clearReconnectTimer;
+    private rejectPending;
+    private asClientError;
+}