nexus-prime 4.5.0 → 4.6.1

package/README.md

@@ -654,6 +654,28 @@ Inventory Snapshot: 109 skills · 64 workflows · 9 hooks · 5 automations · 7
 ## 📜 Release History
 
 <details open>
+<summary><b>v4.6.1</b> · 2026-03-29 · Release corridor stabilization — audited publish path and npm release recovery</summary>
+
+- **Publish path repaired**: Patched the vulnerable `path-to-regexp` dependency edges through targeted overrides so `CI & Publish` can clear `npm run audit:prod` and proceed to npm publication.
+- **Lockfile normalized for release**: Refreshed the production lockfile so GitHub Actions, local installs, and release packaging all resolve the same audited dependency graph.
+- **No feature drift from v4.6.0**: This is a release-stability patch on top of Context Ascension, not a new product surface or protocol change.
+
+Full notes: [releases/v4.6.1.md](./releases/v4.6.1.md) · Full history: [CHANGELOG.md](./CHANGELOG.md)
+</details>
+
+<details>
+<summary><b>v4.6.0</b> · 2026-03-29 · Context Ascension — always-on compression, native search, and operator telemetry</summary>
+
+- **Always-on token optimization**: Bootstrap now auto-applies token optimization whenever candidate files are available, and bootstrap/orchestrate responses surface token and USD savings directly instead of hiding the win in diagnostics.
+- **Project-scoped session summaries**: Session close and `nexus_session_dna` now persist reusable project summaries, and the next bootstrap surfaces whether prior context was recovered before any broad file reading begins.
+- **Dynamic context discovery**: MCP `ListTools` now keeps core lifecycle tools expanded while summarizing non-core tools by default, with `nexus_describe_tool` available for on-demand full contracts.
+- **Native search and skill bridge**: Added sparse n-gram backed `nexus_search` plus Nexus-native bridging for installed gstack skills so external workflows appear inside the normal tool surface.
+- **Opt-in telemetry and dashboard signals**: Remote telemetry remains disabled until consent, clears queued events when turned off, and the dashboard now shows savings, search activity, and telemetry status in the main operator banner.
+
+Full notes: [releases/v4.6.0.md](./releases/v4.6.0.md) · Full history: [CHANGELOG.md](./CHANGELOG.md)
+</details>
+
+<details>
 <summary><b>v4.5.0</b> · 2026-03-27 · Neural Ascension — Auto-optimization, memory injection, and sci-fi command center</summary>
 
 - **Auto token optimization**: Bootstrap auto-applies token planning when 5+ candidate files detected. Quality floor (0.7) ensures task-referenced and recently modified files never get skipped. Zero manual `nexus_optimize_tokens` calls needed.

package/dist/agents/adapters/mcp.d.ts

@@ -19,6 +19,7 @@ export declare class MCPAdapter implements Adapter {
     private lifecyclePolicy;
     private memoryInjectionCache;
     private lastMemoryInjectionAt;
+    private currentTask;
     private sciFiMatrixLog;
     private classifyToolCategory;
     private sciFiToolHeader;
@@ -38,6 +39,7 @@ export declare class MCPAdapter implements Adapter {
     private injectMemoryContext;
     private describeClientInstructionStatus;
     private finalizeToolDefinitions;
+    private getDecoratedToolDefinitions;
     private decorateToolDescription;
     debugListTools(profile?: McpToolProfile): McpToolDefinition[];
     private buildToolDefinitions;

package/dist/agents/adapters/mcp.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"mcp.d.ts","sourceRoot":"","sources":["../../../src/agents/adapters/mcp.ts"],"names":[],"mappings":"AAaA,OAAO,EAAE,OAAO,EAAE,cAAc,EAAE,MAAM,kBAAkB,CAAC;AAC3D,OAAO,EAAE,UAAU,EAAE,MAAM,gBAAgB,CAAC;AA0E5C,KAAK,cAAc,GAAG,YAAY,GAAG,MAAM,CAAC;AAE5C,KAAK,iBAAiB,GAAG;IACrB,IAAI,EAAE,MAAM,CAAC;IACb,WAAW,EAAE,MAAM,CAAC;IACpB,WAAW,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CACxC,CAAC;AAqTF,qBAAa,UAAW,YAAW,OAAO;IACtC,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,EAAG,KAAK,CAAU;IACtB,SAAS,UAAS;IAClB,MAAM,EAAE,MAAM,EAAE,CAAM;IAEtB,OAAO,CAAC,MAAM,CAAS;IACvB,OAAO,CAAC,QAAQ,CAAC,CAAa;IAC9B,OAAO,CAAC,SAAS,CAA4C;IAC7D,OAAO,CAAC,UAAU,CAAoB;IACtC,OAAO,CAAC,OAAO,CAAC,CAAkB;IAClC,OAAO,CAAC,eAAe,CAAyB;IAChD,OAAO,CAAC,oBAAoB,CAAgG;IAC5H,OAAO,CAAC,qBAAqB,CAAK;IAElC,OAAO,CAAC,cAAc;IA6BtB,OAAO,CAAC,oBAAoB;IAS5B,OAAO,CAAC,eAAe;IAqEvB,OAAO,CAAC,GAAG;;IAmBX,OAAO,CAAC,gBAAgB;IA4BxB,WAAW,CAAC,KAAK,EAAE,UAAU;IAI7B,OAAO,CAAC,UAAU;IAYlB,OAAO,CAAC,eAAe;IAOvB,OAAO,CAAC,cAAc;IAMtB,OAAO,CAAC,uBAAuB;IAY/B,OAAO,CAAC,4BAA4B;IAWpC,OAAO,CAAC,qBAAqB;IAiB7B,OAAO,CAAC,yBAAyB;IA2CjC,OAAO,CAAC,mBAAmB;IAO3B,OAAO,CAAC,YAAY;YAON,mBAAmB;IA0DjC,OAAO,CAAC,+BAA+B;IAMvC,OAAO,CAAC,uBAAuB;IAqB/B,OAAO,CAAC,uBAAuB;IAkC/B,cAAc,CAAC,OAAO,GAAE,cAAsC,GAAG,iBAAiB,EAAE;IAIpF,OAAO,CAAC,oBAAoB;IAkzB5B,OAAO,CAAC,iBAAiB;YA6FX,cAAc;IAk7D5B,eAAe,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,EAAE;IAItC,OAAO,CAAC,IAAI;IAmBN,OAAO,IAAI,OAAO,CAAC,IAAI,CAAC;IAOxB,UAAU,IAAI,OAAO,CAAC,IAAI,CAAC;IAoB3B,IAAI,CAAC,OAAO,EAAE,cAAc,GAAG,OAAO,CAAC,IAAI,CAAC;IAYlD,OAAO,CAAC,OAAO,EAAE,cAAc,GAAG,IAAI;CAOzC"}
+{"version":3,"file":"mcp.d.ts","sourceRoot":"","sources":["../../../src/agents/adapters/mcp.ts"],"names":[],"mappings":"AAaA,OAAO,EAAE,OAAO,EAAE,cAAc,EAAE,MAAM,kBAAkB,CAAC;AAC3D,OAAO,EAAE,UAAU,EAAE,MAAM,gBAAgB,CAAC;AAqF5C,KAAK,cAAc,GAAG,YAAY,GAAG,MAAM,CAAC;AAE5C,KAAK,iBAAiB,GAAG;IACrB,IAAI,EAAE,MAAM,CAAC;IACb,WAAW,EAAE,MAAM,CAAC;IACpB,WAAW,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CACxC,CAAC;AAuTF,qBAAa,UAAW,YAAW,OAAO;IACtC,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,EAAG,KAAK,CAAU;IACtB,SAAS,UAAS;IAClB,MAAM,EAAE,MAAM,EAAE,CAAM;IAEtB,OAAO,CAAC,MAAM,CAAS;IACvB,OAAO,CAAC,QAAQ,CAAC,CAAa;IAC9B,OAAO,CAAC,SAAS,CAA4C;IAC7D,OAAO,CAAC,UAAU,CAAoB;IACtC,OAAO,CAAC,OAAO,CAAC,CAAkB;IAClC,OAAO,CAAC,eAAe,CAAyB;IAChD,OAAO,CAAC,oBAAoB,CAAgG;IAC5H,OAAO,CAAC,qBAAqB,CAAK;IAClC,OAAO,CAAC,WAAW,CAAM;IAEzB,OAAO,CAAC,cAAc;IA6BtB,OAAO,CAAC,oBAAoB;IAS5B,OAAO,CAAC,eAAe;IAqEvB,OAAO,CAAC,GAAG;;IAmBX,OAAO,CAAC,gBAAgB;IA4BxB,WAAW,CAAC,KAAK,EAAE,UAAU;IAI7B,OAAO,CAAC,UAAU;IAYlB,OAAO,CAAC,eAAe;IAOvB,OAAO,CAAC,cAAc;IAMtB,OAAO,CAAC,uBAAuB;IAY/B,OAAO,CAAC,4BAA4B;IAWpC,OAAO,CAAC,qBAAqB;IAiB7B,OAAO,CAAC,yBAAyB;IA2CjC,OAAO,CAAC,mBAAmB;IAO3B,OAAO,CAAC,YAAY;YAON,mBAAmB;IA0DjC,OAAO,CAAC,+BAA+B;IAMvC,OAAO,CAAC,uBAAuB;IA0B/B,OAAO,CAAC,2BAA2B;IAqBnC,OAAO,CAAC,uBAAuB;IAkC/B,cAAc,CAAC,OAAO,GAAE,cAAsC,GAAG,iBAAiB,EAAE;IAIpF,OAAO,CAAC,oBAAoB;IA80B5B,OAAO,CAAC,iBAAiB;YA6FX,cAAc;IAwhE5B,eAAe,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,EAAE;IAItC,OAAO,CAAC,IAAI;IAmBN,OAAO,IAAI,OAAO,CAAC,IAAI,CAAC;IAOxB,UAAU,IAAI,OAAO,CAAC,IAAI,CAAC;IAoB3B,IAAI,CAAC,OAAO,EAAE,cAAc,GAAG,OAAO,CAAC,IAAI,CAAC;IAYlD,OAAO,CAAC,OAAO,EAAE,cAAc,GAAG,IAAI;CAOzC"}

package/dist/agents/adapters/mcp.js

@@ -24,6 +24,10 @@ import { LifecyclePolicy } from '../../engines/lifecycle-policy.js';
 import { entanglementEngine, ContinuousAttentionStream, createKVBridge, nxl, OrchestratorEngine } from '../../engines/index.js';
 import { FederationEngine } from '../../engines/federation.js';
 import { TokenAnalyticsEngine } from '../../engines/token-analytics.js';
+import { getSharedNgramIndex } from '../../engines/ngram-index.js';
+import { getSharedTelemetry } from '../../engines/telemetry-remote.js';
+import { getGstackBridge } from '../../engines/gstack-bridge.js';
+import { getSharedContextDiscovery } from '../../engines/context-discovery.js';
 import { synapseToolDefinitions, handleSynapseToolCall } from '../../synapse/index.js';
 import { architectsToolDefinitions, handleArchitectsToolCall } from '../../architects/index.js';
 const tokenEngine = new TokenSupremacyEngine();
@@ -59,6 +63,13 @@ function getHybridRetriever() {
         _hybridRetriever = new HybridRetriever(getGraphEngine());
     return _hybridRetriever;
 }
+// Lazy-initialized N-gram index for fast search
+let _ngramIndex = null;
+function getNgramIndexInstance() {
+    if (!_ngramIndex)
+        _ngramIndex = getSharedNgramIndex();
+    return _ngramIndex;
+}
 // Derive project root from this file's location (dist/agents/adapters/mcp.js → project root)
 const __filename = fileURLToPath(import.meta.url);
 const PROJECT_ROOT = path.resolve(path.dirname(__filename), '..', '..', '..');
@@ -69,6 +80,8 @@ const AUTONOMOUS_TOOL_ORDER = [
     'nexus_recall_memory',
     'nexus_memory_stats',
     'nexus_store_memory',
+    'nexus_search',
+    'nexus_describe_tool',
     'nexus_optimize_tokens',
     'nexus_mindkit_check',
     'nexus_ghost_pass',
@@ -248,7 +261,7 @@ class SessionTelemetry {
             return false;
         if (this.tokenAutoApplied)
             return false;
-        return this.fileReadIntentCount >= 3 && !this.optimizeTokensCalled;
+        return this.fileReadIntentCount >= 1 && !this.optimizeTokensCalled;
     }
     markTokenAutoApplied() {
         this.tokenAutoApplied = true;
@@ -365,6 +378,7 @@ export class MCPAdapter {
     lifecyclePolicy = new LifecyclePolicy();
     memoryInjectionCache = new Map();
     lastMemoryInjectionAt = 0;
+    currentTask = '';
     sciFiMatrixLog(title, metrics, intent) {
         const width = 76;
         console.error(`\n\x1b[36m╔═══ [ \x1b[37m\x1b[1mNEXUS PRIME · ORCHESTRATION MATRIX\x1b[0m\x1b[36m ] ${'═'.repeat(Math.max(0, width - 48))}╗\x1b[0m`);
@@ -675,6 +689,7 @@ export class MCPAdapter {
             : 'Full MCP profile active. Low-level and authoring tools are exposed.';
     }
     finalizeToolDefinitions(tools, profile = this.getToolProfile()) {
+        const taskContext = this.currentTask || this.getRuntime().getUsageSnapshot()?.orchestration?.lastPrompt || '';
         const scoped = profile === 'full'
             ? tools.slice()
             : tools.filter((tool) => AUTONOMOUS_TOOL_SET.has(tool.name));
@@ -682,6 +697,28 @@ export class MCPAdapter {
             ? [...AUTONOMOUS_TOOL_ORDER, ...scoped.map((tool) => tool.name).filter((name) => !AUTONOMOUS_TOOL_SET.has(name))]
             : [...AUTONOMOUS_TOOL_ORDER];
         const orderIndex = new Map(order.map((name, index) => [name, index]));
+        const decorated = scoped
+            .map((tool) => ({
+            ...tool,
+            description: this.decorateToolDescription(tool.name, tool.description, profile),
+        }))
+            .sort((left, right) => {
+            const leftIndex = orderIndex.get(left.name) ?? Number.MAX_SAFE_INTEGER;
+            const rightIndex = orderIndex.get(right.name) ?? Number.MAX_SAFE_INTEGER;
+            return leftIndex - rightIndex || left.name.localeCompare(right.name);
+        });
+        const discovery = getSharedContextDiscovery();
+        discovery.registerTools(decorated);
+        return discovery.applyToTools(taskContext, decorated);
+    }
+    getDecoratedToolDefinitions(profile = this.getToolProfile()) {
+        const scoped = profile === 'full'
+            ? this.buildToolDefinitions().slice()
+            : this.buildToolDefinitions().filter((tool) => AUTONOMOUS_TOOL_SET.has(tool.name));
+        const order = profile === 'full'
+            ? [...AUTONOMOUS_TOOL_ORDER, ...scoped.map((tool) => tool.name).filter((name) => !AUTONOMOUS_TOOL_SET.has(name))]
+            : [...AUTONOMOUS_TOOL_ORDER];
+        const orderIndex = new Map(order.map((name, index) => [name, index]));
         return scoped
             .map((tool) => ({
             ...tool,
@@ -704,7 +741,7 @@ export class MCPAdapter {
             return 'Optional: Inspect the execution ledger before calling nexus_orchestrate. Skip unless you need pre-run visibility into what Nexus will choose.';
         }
         if (name === 'nexus_optimize_tokens') {
-            return 'MANDATORY before reading 3+ files. Returns a token-saving reading plan. Follow it exactly and do not bulk-read the repo.';
+            return 'Always-on token optimization. Automatically generates token-saving reading plans for any file reads. Follow the plan exactly and do not bulk-read the repo.';
         }
         if (name === 'nexus_mindkit_check') {
             return 'MANDATORY before any file modification or destructive operation. Returns PASS/FAIL. Do NOT proceed if it returns FAIL.';
@@ -868,7 +905,7 @@ export class MCPAdapter {
             },
             {
                 name: 'nexus_optimize_tokens',
-                description: 'Generate a token-efficient file reading plan BEFORE reading files. MANDATORY when reading 3+ files. Returns which files to read fully, outline-only, or skip. Typically saves 50-90% tokens per session.',
+                description: 'Generate a token-efficient file reading plan. Always-on: auto-applies during bootstrap for any files. Returns which files to read fully, outline-only, or skip. Typically saves 50-90% tokens per session.',
                 inputSchema: {
                     type: 'object',
                     properties: {
@@ -880,6 +917,32 @@ export class MCPAdapter {
                     required: [],
                 },
             },
+            // ── Search ──────────────────────────────────────────────────────
+            {
+                name: 'nexus_search',
+                description: 'Fast codebase search using sparse n-gram index. Returns matching documents ranked by relevance. Much faster and cheaper than reading full files — reports token savings vs brute-force file reads.',
+                inputSchema: {
+                    type: 'object',
+                    properties: {
+                        query: { type: 'string', description: 'Search query (text or pattern)' },
+                        limit: { type: 'number', description: 'Max results to return (default 20)' },
+                        sparse: { type: 'boolean', description: 'Use sparse n-gram search for higher selectivity (default false)' },
+                    },
+                    required: ['query'],
+                },
+            },
+            // ── Context Discovery ────────────────────────────────────────────
+            {
+                name: 'nexus_describe_tool',
+                description: 'Get full description and schema for any Nexus tool on demand. Use when you need details about a specific capability without loading all tool descriptions upfront. Saves tokens via lazy loading.',
+                inputSchema: {
+                    type: 'object',
+                    properties: {
+                        tool_name: { type: 'string', description: 'Name of the Nexus tool to describe' },
+                    },
+                    required: ['tool_name'],
+                },
+            },
             // ── Mindkit ──────────────────────────────────────────────────────
             {
                 name: 'nexus_mindkit_check',
@@ -1542,6 +1605,8 @@ export class MCPAdapter {
             },
             ...synapseToolDefinitions,
             ...architectsToolDefinitions,
+            // ── Embedded capabilities (auto-detected from installed skills) ──
+            ...getGstackBridge().getToolDefinitions(),
         ];
     }
     setupToolHandlers() {
@@ -1666,9 +1731,24 @@ export class MCPAdapter {
         if (architectsResponse) {
             return architectsResponse;
         }
+        // Handle embedded gstack skill calls
+        const gstackBridge = getGstackBridge();
+        if (gstackBridge.detect() && gstackBridge.listSkills().some(s => s.toolName === toolName)) {
+            const result = await gstackBridge.execute(toolName, args);
+            getSharedTelemetry().trackFeatureUsage(toolName, { success: result.success });
+            return {
+                content: [{
+                        type: 'text',
+                        text: result.success
+                            ? result.output
+                            : `Execution failed (exit ${result.exitCode}): ${result.output.slice(0, 500)}`,
+                    }],
+            };
+        }
         switch (request.params.name) {
             case 'nexus_session_bootstrap': {
                 const bootstrapGoal = String(request.params.arguments?.goal ?? request.params.arguments?.prompt ?? '');
+                this.currentTask = bootstrapGoal;
                 const files = Array.isArray(request.params.arguments?.files)
                     ? request.params.arguments.files.map(String)
                     : undefined;
@@ -1687,6 +1767,16 @@ export class MCPAdapter {
                     tokenAutoApplied: autoTokenApplied,
                     toolProfile: this.getToolProfile(),
                 });
+                // Remote telemetry: track session start (privacy-safe, opt-in only)
+                try {
+                    const remoteTelemetry = getSharedTelemetry();
+                    remoteTelemetry.trackSessionStart();
+                    remoteTelemetry.trackFeatureUsage('session_bootstrap');
+                    if (autoTokenApplied && bootstrap.tokenOptimization?.planMetrics?.savings) {
+                        remoteTelemetry.trackTokenSavings(Number(bootstrap.tokenOptimization.planMetrics.savings));
+                    }
+                }
+                catch { /* best-effort telemetry */ }
                 // Auto-generate a project-scoped memory on bootstrap so dashboard always has something to show
                 try {
                     this.nexusRef.storeMemory(`Session bootstrap: ${bootstrapGoal || 'interactive session'}. Memory: prefrontal=${bootstrap.memoryStats?.prefrontal ?? 0}, hippocampus=${bootstrap.memoryStats?.hippocampus ?? 0}, cortex=${bootstrap.memoryStats?.cortex ?? 0}.`, 0.5, ['#session-start', '#auto', '#project']);
@@ -1709,6 +1799,7 @@ export class MCPAdapter {
                     taskGraphPreview: bootstrap.taskGraphPreview,
                     workerPlanPreview: bootstrap.workerPlanPreview,
                     knowledgeFabric: bootstrap.knowledgeFabric,
+                    sessionSummaryBootstrap: bootstrap.sessionSummaryBootstrap,
                     mcpToolProfile: this.getToolProfile(),
                 };
                 return {
@@ -1722,13 +1813,16 @@ export class MCPAdapter {
                                     `Memory stats: prefrontal ${bootstrap.memoryStats?.prefrontal ?? 0} · hippocampus ${bootstrap.memoryStats?.hippocampus ?? 0} · cortex ${bootstrap.memoryStats?.cortex ?? 0}`,
                                     `Recommended next step: ${bootstrap.recommendedNextStep || 'nexus_orchestrate'}`,
                                     `Execution mode: ${bootstrap.recommendedExecutionMode || 'autonomous'}`,
-                                    `Token optimization: ${bootstrap.tokenOptimization?.autoApplied ? 'auto-applied during bootstrap' : (bootstrap.tokenOptimization?.required ? 'required before broad reading' : 'not required yet')}`,
+                                    `Token optimization: ${bootstrap.tokenOptimization?.autoApplied ? `auto-applied — saved ${Number(bootstrap.tokenOptimization?.planMetrics?.savings ?? 0).toLocaleString()} tokens (${bootstrap.tokenOptimization?.planMetrics?.pct ?? 0}% reduction)` : (bootstrap.tokenOptimization?.required ? 'required before broad reading' : 'not required yet')}`,
                                     `Catalog health: ${bootstrap.catalogHealth?.overall || 'unknown'} · selected ${bootstrap.artifactSelectionAudit?.selected?.length || 0}`,
                                     `Shortlist: ${bootstrap.shortlist?.skills?.slice(0, 3).join(', ') || 'none'} (skills), ${bootstrap.shortlist?.specialists?.slice(0, 3).join(', ') || 'none'} (specialists)`,
                                     `Knowledge fabric: ${bootstrap.sourceMixRecommendation?.dominantSource || bootstrap.knowledgeFabric?.dominantSource || 'awaiting source mix'}`,
                                     `RAG: ${bootstrap.ragCandidateStatus?.attachedCollections || 0} attached · ${bootstrap.ragCandidateStatus?.retrievedChunks || 0} retrieved`,
                                     `Task graph: ${bootstrap.taskGraphPreview?.phases?.length || 0} phases · ${bootstrap.taskGraphPreview?.independentBranches || 0} branches`,
                                     `Worker plan: ${bootstrap.workerPlanPreview?.totalWorkers || 0} lanes planned`,
+                                    bootstrap.sessionSummaryBootstrap
+                                        ? `Session summary: reused ${Number(bootstrap.sessionSummaryBootstrap.savedTokens || 0).toLocaleString()} tokens from the previous visit`
+                                        : 'Session summary: none available yet',
                                     bootstrap.autoGhostPass?.applied
                                         ? `Auto ghost-pass: ${bootstrap.autoGhostPass.riskAreas.length} risk area(s) · ${bootstrap.autoGhostPass.workerApproaches} approach(es)`
                                         : `Auto ghost-pass: skipped`,
@@ -1745,6 +1839,7 @@ export class MCPAdapter {
             }
             case 'nexus_orchestrate': {
                 const prompt = String(request.params.arguments?.prompt ?? request.params.arguments?.goal ?? '');
+                this.currentTask = prompt;
                 const files = Array.isArray(request.params.arguments?.files)
                     ? request.params.arguments.files.map(String)
                     : undefined;
@@ -1787,11 +1882,13 @@ export class MCPAdapter {
                     const verifiedWorkers = execution.workerResults.filter((worker) => worker.verified).length;
                     const tokenPlan = execution?.knowledgeFabric?.repo?.readingPlan;
                     const canAutoApplyTokenPlan = Boolean(tokenPlan
-                        && Number(tokenPlan.savings || 0) > 5000
+                        && Number(tokenPlan.savings || 0) > 0
                         && !this.getRuntime().getUsageSnapshot()?.tokenOptimizationApplied);
                     let autoTokenApplyNote = '';
                     if (canAutoApplyTokenPlan) {
                         const savings = Number(tokenPlan.savings || 0);
+                        const totalBeforeOpt = savings + Number(tokenPlan.totalEstimatedTokens || 0);
+                        const pctSaved = totalBeforeOpt > 0 ? Math.round(savings / totalBeforeOpt * 100) : 0;
                         this.telemetry.recordTokens(savings);
                         this.getRuntime().recordClientToolCall('nexus_orchestrate', {
                             orchestrateCalled: true,
@@ -1799,7 +1896,8 @@ export class MCPAdapter {
                             tokenOptimizationApplied: true,
                             toolProfile: this.getToolProfile(),
                         });
-                        autoTokenApplyNote = `Auto-applied token optimization (${savings.toLocaleString()} estimated token savings).`;
+                        autoTokenApplyNote = `Token savings: ${savings.toLocaleString()} tokens saved (${pctSaved}% reduction).`;
+                        nexusEventBus.emit('tokens.optimized', { savings, pct: pctSaved, source: 'orchestrate' });
                     }
                     // Auto-store run summary memory so dashboard and future sessions can see what happened
                     try {
@@ -2173,6 +2271,55 @@ export class MCPAdapter {
                         }],
                 };
             }
+            case 'nexus_describe_tool': {
+                const requestedTool = String(request.params.arguments?.tool_name ?? '');
+                if (!requestedTool) {
+                    return { content: [{ type: 'text', text: 'tool_name is required.' }] };
+                }
+                const allToolDefs = this.getDecoratedToolDefinitions(this.getToolProfile());
+                const found = allToolDefs.find(t => t.name === requestedTool);
+                if (!found) {
+                    const available = allToolDefs.map(t => t.name).join(', ');
+                    return { content: [{ type: 'text', text: `Tool "${requestedTool}" not found. Available: ${available}` }] };
+                }
+                return {
+                    content: [{
+                            type: 'text',
+                            text: `## ${found.name}\n\n${found.description}\n\n**Schema:**\n\`\`\`json\n${JSON.stringify(found.inputSchema, null, 2)}\n\`\`\``,
+                        }],
+                };
+            }
+            case 'nexus_search': {
+                const query = String(request.params.arguments?.query ?? '');
+                const limit = Number(request.params.arguments?.limit ?? 20);
+                const useSparse = Boolean(request.params.arguments?.sparse);
+                if (!query.trim()) {
+                    return { content: [{ type: 'text', text: 'Search query is required.' }] };
+                }
+                const ngramIndex = getNgramIndexInstance();
+                const { results, tokensSaved, totalCandidateTokens } = ngramIndex.searchWithStats(query, limit);
+                if (results.length === 0) {
+                    return { content: [{ type: 'text', text: `No results found for "${query}".` }] };
+                }
+                const sparseResults = useSparse ? ngramIndex.searchSparse(query, limit) : null;
+                const displayResults = sparseResults ?? results;
+                const lines = displayResults.map((r, i) => `${i + 1}. ${r.docId} (score: ${r.score})`);
+                const stats = ngramIndex.getSearchStats();
+                const savingsLine = `\n📊 Token savings: ~${tokensSaved.toLocaleString()} tokens saved vs reading all ${results.length} matched files.\n` +
+                    `   Lifetime search savings: ${stats.totalTokensSaved.toLocaleString()} tokens across ${stats.totalQueries} queries.`;
+                nexusEventBus.emit('tokens.searchSaved', {
+                    query: query.slice(0, 100),
+                    resultCount: displayResults.length,
+                    tokensSaved,
+                    source: 'nexus_search',
+                });
+                return {
+                    content: [{
+                            type: 'text',
+                            text: `Search results for "${query}" (${displayResults.length} matches):\n\n${lines.join('\n')}${savingsLine}`,
+                        }],
+                };
+            }
             case 'nexus_optimize_tokens': {
                 const task = String(request.params.arguments?.goal ?? request.params.arguments?.task ?? '');
                 const rawFiles = Array.isArray(request.params.arguments?.files)
@@ -2539,6 +2686,11 @@ export class MCPAdapter {
                     });
                     const dna = this.sessionDNA.flush();
                     const formatted = SessionDNAManager.format(dna);
+                    // Trigger self-summarization at session end
+                    try {
+                        this.getOrchestrator().persistSessionSummary(telemetry.tokensOptimized || this.getRuntime().getUsageSnapshot().tokens?.grossInputTokens || 0);
+                    }
+                    catch { /* non-fatal */ }
                     return {
                         content: [{
                                 type: 'text',