nexus-prime 6.0.0 → 6.0.2

package/dist/agents/adapters/ide-compat.d.ts

@@ -5,6 +5,7 @@
  * Supported: VS Code (Claude Code ext), JetBrains, Cursor, Windsurf, Zed, Continue.dev, Aider, Cline, Codex
  */
 export type IDEId = 'claude-code' | 'cursor' | 'windsurf' | 'continue' | 'cline' | 'zed' | 'codex';
+export type CallerIDEId = 'claude-code' | 'cursor' | 'windsurf' | 'continue' | 'zed' | 'codex';
 export interface McpConfigOutput {
     /** Absolute path where the config should be written */
     configPath: string | null;
@@ -13,6 +14,8 @@ export interface McpConfigOutput {
     /** If true, attempt to merge into existing file rather than overwrite */
     merge: boolean;
 }
+export declare function resetDetectedCallerIDECache(): void;
+export declare function detectCallerIDE(): CallerIDEId | null;
 /** Detect which IDEs are present in the workspace or home directory. */
 export declare function detectInstalledIDEs(workspaceRoot: string): IDEId[];
 /** Get the MCP config content and target path for a given IDE. */

package/dist/agents/adapters/ide-compat.js

@@ -6,7 +6,8 @@
  */
 import { existsSync } from 'fs';
 import { homedir } from 'os';
-import { join } from 'path';
+import { dirname, join, resolve } from 'path';
+let callerIDECache;
 /** Nexus Prime MCP server entry (stdio transport). */
 function nexusMcpServerEntry(workspaceRoot) {
     return {
@@ -15,6 +16,58 @@ function nexusMcpServerEntry(workspaceRoot) {
         env: {},
     };
 }
+function hasAnyEnvPrefix(prefix) {
+    return Object.keys(process.env).some((key) => key.startsWith(prefix));
+}
+function detectCallerIDEFromEnv() {
+    if (process.env.CLAUDECODE || process.env.CLAUDE_CODE || process.env.CLAUDE_SESSION_ID || process.env.CLAUDE_PROJECT_DIR) {
+        return 'claude-code';
+    }
+    if (process.env.CURSOR_TRACE_ID || hasAnyEnvPrefix('CURSOR_')) {
+        return 'cursor';
+    }
+    if (process.env.CODEX_HOME || hasAnyEnvPrefix('CODEX_')) {
+        return 'codex';
+    }
+    if (hasAnyEnvPrefix('WINDSURF_')) {
+        return 'windsurf';
+    }
+    if (hasAnyEnvPrefix('CONTINUE_')) {
+        return 'continue';
+    }
+    if (hasAnyEnvPrefix('ZED_')) {
+        return 'zed';
+    }
+    return null;
+}
+function detectCallerIDEFromFilesystem(startDir) {
+    let current = resolve(startDir);
+    for (;;) {
+        if (existsSync(join(current, '.cursor')))
+            return 'cursor';
+        if (existsSync(join(current, '.continue')))
+            return 'continue';
+        if (existsSync(join(current, '.windsurf')))
+            return 'windsurf';
+        if (existsSync(join(current, '.zed')))
+            return 'zed';
+        const parent = dirname(current);
+        if (parent === current) {
+            return null;
+        }
+        current = parent;
+    }
+}
+export function resetDetectedCallerIDECache() {
+    callerIDECache = undefined;
+}
+export function detectCallerIDE() {
+    if (callerIDECache !== undefined) {
+        return callerIDECache;
+    }
+    callerIDECache = detectCallerIDEFromEnv() ?? detectCallerIDEFromFilesystem(process.cwd());
+    return callerIDECache;
+}
 /** Detect which IDEs are present in the workspace or home directory. */
 export function detectInstalledIDEs(workspaceRoot) {
     const detected = [];

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

@@ -0,0 +1,50 @@
+/**
+ * HandlerEnvelope — unified success/error shape for all MCP tool handlers.
+ *
+ * Lifted out of runHandler.ts so any module (middleware, handlers, tests,
+ * dashboard routes) can import the type without pulling in the full
+ * runHandler runtime.  runHandler.ts re-exports these for back-compat.
+ */
+export type HandlerErrorCode = 'timeout' | 'sqlite-busy' | 'runtime-cold' | 'input-invalid' | 'nested-dispatch-refused' | 'internal';
+export interface HandlerEnvelope<T = unknown> {
+    ok: boolean;
+    data?: T;
+    error?: {
+        code: HandlerErrorCode;
+        message: string;
+        retriable: boolean;
+        hint?: string;
+    };
+    meta: {
+        toolName: string;
+        durationMs: number;
+        attempts: number;
+        runtimeHotAt: number | null;
+    };
+}
+export interface RunHandlerOptions {
+    /** Override the per-client default timeout. */
+    timeoutMs?: number;
+    /** Max retries for transient errors (SQLite-busy, runtime-cold). Default 1. */
+    retries?: number;
+    /** Caller name for per-client timeout selection. */
+    callerName?: string;
+    /** Timestamp (ms) when the runtime became hot. Passed through into meta. */
+    runtimeHotAt?: number | null;
+}
+/**
+ * Convert a HandlerEnvelope into the MCP tool-call response shape.
+ *
+ * On success, if `envelope.data` is already a ToolResult
+ * (`{ content: Array<...> }`), it is returned directly so we never
+ * double-wrap handler output.  Any other value is JSON-stringified into a
+ * single text content block.
+ *
+ * On error, a structured JSON error block is produced.
+ */
+export declare function envelopeToMcpResponse<T>(envelope: HandlerEnvelope<T>): {
+    content: Array<{
+        type: 'text';
+        text: string;
+    }>;
+};

package/dist/agents/adapters/mcp/envelope.js

@@ -0,0 +1,45 @@
+/**
+ * HandlerEnvelope — unified success/error shape for all MCP tool handlers.
+ *
+ * Lifted out of runHandler.ts so any module (middleware, handlers, tests,
+ * dashboard routes) can import the type without pulling in the full
+ * runHandler runtime.  runHandler.ts re-exports these for back-compat.
+ */
+// ─── Serialisation helper ─────────────────────────────────────────────────────
+/**
+ * Convert a HandlerEnvelope into the MCP tool-call response shape.
+ *
+ * On success, if `envelope.data` is already a ToolResult
+ * (`{ content: Array<...> }`), it is returned directly so we never
+ * double-wrap handler output.  Any other value is JSON-stringified into a
+ * single text content block.
+ *
+ * On error, a structured JSON error block is produced.
+ */
+export function envelopeToMcpResponse(envelope) {
+    if (envelope.ok) {
+        const data = envelope.data;
+        // Pass-through: handler already returned a ToolResult-shaped object.
+        if (data !== null &&
+            data !== undefined &&
+            typeof data === 'object' &&
+            Array.isArray(data.content)) {
+            return data;
+        }
+        const text = typeof data === 'string' ? data : JSON.stringify(data, null, 2);
+        return { content: [{ type: 'text', text }] };
+    }
+    return {
+        content: [{
+                type: 'text',
+                text: JSON.stringify({
+                    status: 'error',
+                    code: envelope.error.code,
+                    message: envelope.error.message,
+                    retriable: envelope.error.retriable,
+                    hint: envelope.error.hint,
+                    meta: envelope.meta,
+                }, null, 2),
+            }],
+    };
+}

package/dist/agents/adapters/mcp/handlers/discovery.js

@@ -5,8 +5,12 @@
  */
 import { formatBullets, formatJsonDetails, collectFolderFiles, } from '../helpers.js';
 import { listExecutionPresets } from '../../../../engines/execution-presets.js';
+import { requireRuntime } from '../util/require-runtime.js';
 import * as path from 'path';
 export async function handleDiscoveryGroup(toolName, hctx, request, args, ctx) {
+    const runtimeError = requireRuntime(hctx);
+    if (runtimeError)
+        return runtimeError;
     switch (toolName) {
         case 'nexus_list_execution_presets': {
             const presets = listExecutionPresets();

package/dist/agents/adapters/mcp/handlers/governance.js

@@ -17,9 +17,15 @@ import { ensureBootstrap } from '../../../../engines/client-bootstrap.js';
 import { HybridRetriever } from '../../../../engines/hybrid-retriever.js';
 import { GraphTraversalEngine } from '../../../../engines/graph-traversal.js';
 import { fileURLToPath } from 'url';
+import { requireRuntime } from '../util/require-runtime.js';
+import { getAllPerfStats } from '../../../../engines/perf-history.js';
+import { getTTVSnapshot } from '../../../../engines/telemetry.js';
 const _gfile = fileURLToPath(import.meta.url);
 const PROJECT_ROOT = path.resolve(path.dirname(_gfile), '..', '..', '..', '..', '..');
 export async function handleGovernanceGroup(toolName, hctx, request, args, ctx) {
+    const runtimeError = requireRuntime(hctx);
+    if (runtimeError)
+        return runtimeError;
     switch (toolName) {
         case 'nexus_runtime_health': {
             const envelope = hctx.nexusRef.getRuntimeHealthEnvelope();
@@ -78,6 +84,30 @@ export async function handleGovernanceGroup(toolName, hctx, request, args, ctx)
                     : []),
             ];
             const allLive = deadSubsystems.length === 0;
+            // ── perfProfile: p50/p90/p99 per tool + TTV snapshot ─────────
+            const [perfStats, ttvSnap] = await Promise.all([
+                getAllPerfStats().catch(() => []),
+                Promise.resolve(getTTVSnapshot()),
+            ]);
+            const perfProfile = {
+                tools: perfStats.map((s) => ({
+                    tool: s.tool,
+                    count: s.count,
+                    p50ms: s.p50,
+                    p90ms: s.p90,
+                    p99ms: s.p99,
+                    budget: s.budget ?? null,
+                    slow: s.budget ? s.p99 > s.budget.fail : false,
+                })),
+                ttv: {
+                    daemonStartAt: ttvSnap.daemonStartAt,
+                    firstBootstrapMs: ttvSnap.firstBootstrapAt != null ? ttvSnap.firstBootstrapAt - ttvSnap.daemonStartAt : null,
+                    firstMemoryMs: ttvSnap.firstMemoryAt != null ? ttvSnap.firstMemoryAt - ttvSnap.daemonStartAt : null,
+                    firstInteractionMs: ttvSnap.firstInteractionAt != null ? ttvSnap.firstInteractionAt - ttvSnap.daemonStartAt : null,
+                    firstMissionMs: ttvSnap.firstMissionCompleteAt != null ? ttvSnap.firstMissionCompleteAt - ttvSnap.daemonStartAt : null,
+                },
+            };
+            const slowTools = perfProfile.tools.filter((t) => t.slow).map((t) => t.tool);
             return {
                 content: [{
                         type: 'text',
@@ -94,6 +124,7 @@ export async function handleGovernanceGroup(toolName, hctx, request, args, ctx)
                                 `Workspace: ${envelope.workspace.source}`,
                                 `Issues: ${issues.length}`,
                                 `Ngram index: ${ngramOversized ? 'oversized' : 'ok'} (${Math.round(ngramSizeBytes / 1024 / 1024)}MB)`,
+                                ...(slowTools.length > 0 ? [`\u26A0\uFE0F Slow tools (p99 > budget): ${slowTools.join(', ')}`] : []),
                             ]),
                             issues.length > 0 ? formatBullets(issues.map((issue) => `\u26A0\uFE0F ${issue}`)) : '',
                             (() => {
@@ -115,6 +146,7 @@ export async function handleGovernanceGroup(toolName, hctx, request, args, ctx)
                                     oversized: ngramOversized,
                                 },
                                 securityAudit: getSharedAuditLog().getSummary(),
+                                perfProfile,
                             }),
                         ].filter(Boolean).join('\n\n'),
                     }],

package/dist/agents/adapters/mcp/handlers/memory.js

@@ -8,7 +8,12 @@ import { formatBullets, formatJsonDetails } from '../helpers.js';
 import { nexusEventBus } from '../../../../engines/event-bus.js';
 import { getOperativeJournal } from '../../../../engines/operative-journal.js';
 import { storeToolSummary } from '../util/auto-memory.js';
+import { requireRuntime } from '../util/require-runtime.js';
+import { recordFirstMemory } from '../../../../engines/telemetry.js';
 export async function handleMemoryGroup(toolName, hctx, request, args, ctx) {
+    const runtimeError = requireRuntime(hctx);
+    if (runtimeError)
+        return runtimeError;
     switch (toolName) {
         case 'nexus_store_memory': {
             const content = String(request.params.arguments?.content ?? '');
@@ -19,6 +24,7 @@ export async function handleMemoryGroup(toolName, hctx, request, args, ctx) {
             const verbatim = Boolean(request.params.arguments?.verbatim ?? false);
             const id = hctx.nexusRef.storeMemory(content, priority, tags, undefined, undefined, { verbatim });
             hctx.telemetry.recordStore();
+            void recordFirstMemory().catch(() => { });
             hctx.sessionDNA.recordMemoryStore();
             const nudge = hctx.telemetry.planningNudge('store', { priority });
             if (ctx) {
@@ -170,7 +176,7 @@ export async function handleMemoryGroup(toolName, hctx, request, args, ctx) {
             };
         }
         case 'nexus_memory_import': {
-            const result = hctx.nexusRef.importMemoryBundle({
+            const result = await hctx.nexusRef.importMemoryBundle({
                 path: request.params.arguments?.path ? String(request.params.arguments.path) : undefined,
                 bundle: request.params.arguments?.bundle,
             });
@@ -232,7 +238,7 @@ export async function handleMemoryGroup(toolName, hctx, request, args, ctx) {
                 ]);
             }
             else if (action === 'syncFrom') {
-                const result = bridge.syncFrom(sourceDir || bridge.getBridgeDir());
+                const result = await bridge.syncFrom(sourceDir || bridge.getBridgeDir());
                 detail = formatBullets([
                     `Success: ${result.success}`,
                     `Imported: ${result.imported}`,

package/dist/agents/adapters/mcp/handlers/orchestration.js

@@ -12,12 +12,18 @@ import { formatReadingPlan } from '../../../../engines/token-supremacy.js';
 import { GhostPass, summarizeExecution } from '../../../../phantom/index.js';
 import { applyExecutionPreset, resolveExecutionPreset } from '../../../../engines/execution-presets.js';
 import { pLimit } from '../../../../engines/util/p-limit.js';
-import { promises as fsPromises, statSync } from 'fs';
+import { promises as fsPromises } from 'fs';
 import { getSharedLicenseManager } from '../../../../licensing/index.js';
 import { SessionDNAManager } from '../../../../engines/session-dna.js';
 import { getSharedTelemetry } from '../../../../engines/telemetry-remote.js';
 import { storeToolSummary } from '../util/auto-memory.js';
+import { requireRuntime } from '../util/require-runtime.js';
+import { ensureCrGraphBuilt } from '../../../../engines/code-review-graph-client.js';
+import { recordFirstBootstrap } from '../../../../engines/telemetry.js';
 export async function handleOrchestrationGroup(toolName, hctx, request, args, ctx) {
+    const runtimeError = requireRuntime(hctx);
+    if (runtimeError)
+        return runtimeError;
     // Variables computed in the original handleToolCall preamble and used by these cases
     const detailLevel = normalizeDetailLevel(args.detailLevel);
     const requestedIntent = normalizeResponseIntent(args.intent);
@@ -117,7 +123,9 @@ export async function handleOrchestrationGroup(toolName, hctx, request, args, ct
                     remoteTelemetry.trackTokenSavings(Number(bootstrap.tokenOptimization.planMetrics.savings));
                 }
             }
-            catch { /* best-effort telemetry */ }
+            catch (err) {
+                nexusEventBus.emit('mcp.handler.best-effort-failed', { toolName, stage: 'track-session-start', error: err instanceof Error ? err.message : String(err) });
+            }
             if (ctx) {
                 ctx.meta.tokenSavings = Number(bootstrap.tokenOptimization?.planMetrics?.savings ?? 0);
                 ctx.meta.projectMemoryBootstrapCount = Number(bootstrap.projectMemoryBootstrap?.count ?? 0);
@@ -133,7 +141,20 @@ export async function handleOrchestrationGroup(toolName, hctx, request, args, ct
             try {
                 storeToolSummary(hctx, 'nexus_session_bootstrap', `Session bootstrap: ${bootstrapGoal || 'interactive session'}. Memory: prefrontal=${bootstrap.memoryStats?.prefrontal ?? 0}, hippocampus=${bootstrap.memoryStats?.hippocampus ?? 0}, cortex=${bootstrap.memoryStats?.cortex ?? 0}.`);
             }
+            catch (err) {
+                nexusEventBus.emit('mcp.handler.best-effort-failed', { toolName, stage: 'persist-session-summary', error: err instanceof Error ? err.message : String(err) });
+            }
+            // Non-blocking: ensure cr-graph is fresh after bootstrap. Fires after the handler
+            // returns so the response is not delayed. Any failure is silently swallowed.
+            try {
+                const crRepoRoot = hctx.nexusRef.getWorkspaceContext().repoRoot;
+                if (crRepoRoot) {
+                    setImmediate(() => { void ensureCrGraphBuilt(crRepoRoot); });
+                }
+            }
             catch { /* best-effort */ }
+            // TTV telemetry: record first successful bootstrap (fire-and-forget).
+            void recordFirstBootstrap().catch(() => { });
             const timings = {
                 totalMs: Date.now() - callStartedAt,
             };
@@ -350,7 +371,9 @@ export async function handleOrchestrationGroup(toolName, hctx, request, args, ct
                     const modifiedFiles = execution.workerResults.flatMap((w) => w.modifiedFiles);
                     hctx.nexusRef.storeMemory(`Run ${execution.runId} ${execution.state}: ${summarizeExecution(execution)}. Workers: ${verifiedWorkers}/${execution.workerResults.length} verified. Files modified: ${modifiedFiles.slice(0, 5).join(', ') || 'none'}.`, 0.34, ['#run-summary', '#auto', '#system-hidden']);
                 }
-                catch { /* best-effort */ }
+                catch (err) {
+                    nexusEventBus.emit('mcp.handler.best-effort-failed', { toolName, stage: 'auto-memory-store', error: err instanceof Error ? err.message : String(err) });
+                }
                 execution.activeSkills.forEach((skill) => hctx.sessionDNA.recordSkill(skill.name));
                 execution.workerResults.forEach((result) => {
                     result.modifiedFiles.forEach((file) => hctx.sessionDNA.recordFileModified(file));
@@ -509,7 +532,7 @@ export async function handleOrchestrationGroup(toolName, hctx, request, args, ct
                     return { path: resolved, sizeBytes: 0 };
                 }
             })));
-            const plan = getTokenEngine().plan(task, files);
+            const plan = await getTokenEngine().plan(task, files);
             const formatted = formatReadingPlan(plan);
             // Persist the decision
             hctx.nexusRef.storeMemory(`Token plan for "${task.slice(0, 80)}": ` +
@@ -557,16 +580,16 @@ export async function handleOrchestrationGroup(toolName, hctx, request, args, ct
             const rawFiles = Array.isArray(request.params.arguments?.files)
                 ? request.params.arguments.files.map(String)
                 : [];
-            const files = rawFiles.map(p => {
+            const files = await Promise.all(rawFiles.map(async (p) => {
                 const resolved = hctx.resolveToolPath(p, request.params.arguments ?? {});
                 try {
-                    const stat = statSync(resolved);
+                    const stat = await fsPromises.stat(resolved);
                     return { path: resolved, sizeBytes: stat.size, lastModified: stat.mtimeMs };
                 }
                 catch {
                     return { path: resolved, sizeBytes: 0 };
                 }
-            });
+            }));
             const ghost = new GhostPass(hctx.getWorkspace(request.params.arguments ?? {}).repoRoot);
             const report = await ghost.analyze(goal, files);
             hctx.nexusRef.storeMemory(`Ghost pass for "${goal.slice(0, 80)}": ${report.riskAreas.length} risks identified.`, 0.6, ['#ghost-pass']);
@@ -650,7 +673,9 @@ export async function handleOrchestrationGroup(toolName, hctx, request, args, ct
             try {
                 storeToolSummary(hctx, 'nexus_spawn_workers', `Worker plan: "${goal.slice(0, 100)}" — ${workersCount} workers, ${rawFiles.length} files.`);
             }
-            catch { /* best-effort */ }
+            catch (err) {
+                nexusEventBus.emit('mcp.handler.best-effort-failed', { toolName, stage: 'worker-plan-summary', error: err instanceof Error ? err.message : String(err) });
+            }
             const execution = await hctx.getRuntime().run(applyExecutionPreset({
                 goal,
                 files: rawFiles,

package/dist/agents/adapters/mcp/handlers/runtime.js

@@ -8,7 +8,11 @@ import { formatBullets, formatJsonDetails, } from '../helpers.js';
 import { nexusEventBus } from '../../../../engines/event-bus.js';
 import { getSharedLicenseManager, snapshotPCU, formatPCUStatus } from '../../../../licensing/index.js';
 import { TokenAnalyticsEngine } from '../../../../engines/token-analytics.js';
+import { requireRuntime } from '../util/require-runtime.js';
 export async function handleRuntimeGroup(toolName, hctx, request, args, ctx) {
+    const runtimeError = requireRuntime(hctx);
+    if (runtimeError)
+        return runtimeError;
     switch (toolName) {
         case 'nexus_license_usage': {
             const fmt = String(request.params.arguments?.format ?? 'summary');
@@ -220,7 +224,7 @@ export async function handleRuntimeGroup(toolName, hctx, request, args, ctx) {
         }
         case 'nexus_run_status': {
             const runId = String(request.params.arguments?.runId ?? '');
-            const run = hctx.getRuntime().getRun(runId);
+            const run = await hctx.getRuntime().getRun(runId);
             if (!run) {
                 return { content: [{ type: 'text', text: `❌ Run not found: ${runId}` }] };
             }

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

@@ -8,34 +8,14 @@
  *
  * Per-client timeouts (AI Lead refinement):
  *   Codex 90 s · Claude Code 60 s · Cursor 30 s · default 25 s
+ *
+ * Types and `envelopeToMcpResponse` are canonical in ./envelope.ts;
+ * re-exported from here for backward compatibility.
  */
-export type HandlerErrorCode = 'timeout' | 'sqlite-busy' | 'runtime-cold' | 'input-invalid' | 'nested-dispatch-refused' | 'internal';
-export interface HandlerEnvelope<T = unknown> {
-    ok: boolean;
-    data?: T;
-    error?: {
-        code: HandlerErrorCode;
-        message: string;
-        retriable: boolean;
-        hint?: string;
-    };
-    meta: {
-        toolName: string;
-        durationMs: number;
-        attempts: number;
-        runtimeHotAt: number | null;
-    };
-}
-export interface RunHandlerOptions {
-    /** Override the per-client default timeout. */
-    timeoutMs?: number;
-    /** Max retries for transient errors (SQLite-busy, runtime-cold). Default 1. */
-    retries?: number;
-    /** Caller name for per-client timeout selection. */
-    callerName?: string;
-    /** Timestamp (ms) when the runtime became hot. Passed through into meta. */
-    runtimeHotAt?: number | null;
-}
+import type { RunHandlerOptions } from './envelope.js';
+import type { HandlerEnvelope } from './envelope.js';
+export type { HandlerErrorCode, HandlerEnvelope, RunHandlerOptions } from './envelope.js';
+export { envelopeToMcpResponse } from './envelope.js';
 /**
  * Run a handler function with timeout, retry, and structured envelope.
  *
@@ -46,10 +26,3 @@ export interface RunHandlerOptions {
  * }, { callerName: hctx.adapterName });
  */
 export declare function runHandler<T>(toolName: string, fn: () => Promise<T>, opts?: RunHandlerOptions): Promise<HandlerEnvelope<T>>;
-/** Convert a HandlerEnvelope into the MCP tool-call response shape. */
-export declare function envelopeToMcpResponse<T>(envelope: HandlerEnvelope<T>): {
-    content: Array<{
-        type: 'text';
-        text: string;
-    }>;
-};

package/dist/agents/adapters/mcp/runHandler.js

@@ -8,8 +8,13 @@
  *
  * Per-client timeouts (AI Lead refinement):
  *   Codex 90 s · Claude Code 60 s · Cursor 30 s · default 25 s
+ *
+ * Types and `envelopeToMcpResponse` are canonical in ./envelope.ts;
+ * re-exported from here for backward compatibility.
  */
 import { nexusEventBus } from '../../../engines/event-bus.js';
+import { recordPerf } from '../../../engines/perf-history.js';
+export { envelopeToMcpResponse } from './envelope.js';
 // ─── Per-client timeout map ───────────────────────────────────────────────────
 const CLIENT_TIMEOUTS = {
     'codex': 90_000,
@@ -25,12 +30,7 @@ function resolveTimeout(opts) {
     }
     return DEFAULT_TIMEOUT;
 }
-// ─── Retriable error detection ────────────────────────────────────────────────
-const RETRIABLE_RE = /SQLITE_BUSY|SQLITE_LOCKED|synapse runtime not yet|runtime not yet ready/i;
-function isRetriable(err) {
-    const msg = err instanceof Error ? err.message : String(err);
-    return RETRIABLE_RE.test(msg);
-}
+// ─── Error classification ─────────────────────────────────────────────────────
 function classifyError(err) {
     const msg = err instanceof Error ? err.message : String(err);
     if (/SQLITE_BUSY|SQLITE_LOCKED/i.test(msg))
@@ -41,6 +41,28 @@ function classifyError(err) {
         return 'input-invalid';
     return 'internal';
 }
+const RETRY_POLICIES = {
+    // SQLite lock: 3 retries with exponential backoff (100 → 300 → 900 ms).
+    'sqlite-busy': {
+        maxRetries: 3,
+        backoffMs: (attempt) => 100 * Math.pow(3, attempt - 1),
+    },
+    // Cold runtime: 1 immediate retry (the runtime may warm up in milliseconds).
+    'runtime-cold': {
+        maxRetries: 1,
+        backoffMs: () => 0,
+    },
+    // Bad input and timeouts are never retried — retrying won't fix them.
+    'input-invalid': { maxRetries: 0, backoffMs: () => 0 },
+    'timeout': { maxRetries: 0, backoffMs: () => 0 },
+};
+const DEFAULT_RETRY_POLICY = {
+    maxRetries: 1,
+    backoffMs: () => 200,
+};
+function getRetryPolicy(code) {
+    return RETRY_POLICIES[code] ?? DEFAULT_RETRY_POLICY;
+}
 // ─── Core wrapper ─────────────────────────────────────────────────────────────
 /**
  * Run a handler function with timeout, retry, and structured envelope.
@@ -53,7 +75,6 @@ function classifyError(err) {
  */
 export async function runHandler(toolName, fn, opts = {}) {
     const timeoutMs = resolveTimeout(opts);
-    const maxRetries = opts.retries ?? 1;
     const startMs = Date.now();
     let attempts = 0;
     // eslint-disable-next-line no-constant-condition -- retry loop exits via return/break
@@ -77,22 +98,34 @@ export async function runHandler(toolName, fn, opts = {}) {
                 },
             };
             nexusEventBus.emit('mcp.handler.complete', { toolName, attempts, durationMs: envelope.meta.durationMs });
+            recordPerf(toolName, envelope.meta.durationMs);
             return envelope;
         }
         catch (err) {
             clearTimeout(timeoutHandle);
-            const isTimeout = err instanceof Error && err.message === '__nexus_timeout__';
-            const canRetry = !isTimeout && attempts <= maxRetries && isRetriable(err);
+            const isTimeout = err instanceof Error && (err.message === '__nexus_timeout__' ||
+                err.message === '__nexus_pipeline_timeout__');
+            const code = isTimeout ? 'timeout' : classifyError(err);
+            const policy = getRetryPolicy(code);
+            // opts.retries overrides the policy maxRetries if provided explicitly.
+            const maxRetries = opts.retries !== undefined ? opts.retries : policy.maxRetries;
+            const canRetry = attempts <= maxRetries;
             if (canRetry) {
-                // One retry after a short backoff
-                await new Promise(r => setTimeout(r, 200));
+                const delay = policy.backoffMs(attempts);
+                nexusEventBus.emit('mcp.handler.retry', {
+                    toolName,
+                    code,
+                    attempt: attempts,
+                    delayMs: delay,
+                });
+                if (delay > 0)
+                    await new Promise(r => setTimeout(r, delay));
                 continue;
             }
-            const code = isTimeout ? 'timeout' : classifyError(err);
             const message = isTimeout
                 ? `Handler timed out after ${timeoutMs}ms`
                 : (err instanceof Error ? err.message : String(err));
-            const retriable = !isTimeout && isRetriable(err);
+            const retriable = policy.maxRetries > 0 && !isTimeout;
             const envelope = {
                 ok: false,
                 error: {
@@ -115,25 +148,3 @@ export async function runHandler(toolName, fn, opts = {}) {
         }
     }
 }
-/** Convert a HandlerEnvelope into the MCP tool-call response shape. */
-export function envelopeToMcpResponse(envelope) {
-    if (envelope.ok) {
-        const text = typeof envelope.data === 'string'
-            ? envelope.data
-            : JSON.stringify(envelope.data, null, 2);
-        return { content: [{ type: 'text', text }] };
-    }
-    return {
-        content: [{
-                type: 'text',
-                text: JSON.stringify({
-                    status: 'error',
-                    code: envelope.error.code,
-                    message: envelope.error.message,
-                    retriable: envelope.error.retriable,
-                    hint: envelope.error.hint,
-                    meta: envelope.meta,
-                }, null, 2),
-            }],
-    };
-}

package/dist/agents/adapters/mcp/util/detect-caller.d.ts

@@ -1,14 +1,22 @@
 /**
  * Detect which MCP client is invoking nexus-prime.
  *
- * Two tiers:
- *  1. detectCallerFromEnv()   — sync, instant, covers ~99% of real clients
- *  2. detectCallerAsync()     — async ps(1) fallback for edge cases (no env vars)
+ * Three tiers (highest-priority first):
+ *  1. setMcpClientName()    — from MCP initialize handshake clientInfo.name (most reliable)
+ *  2. detectCallerFromEnv() — sync env-var detection, covers ~99% of real clients
+ *  3. detectCallerAsync()   — async ps(1) fallback for edge cases (no env vars)
  *
- * The MCP adapter constructor uses tier-1 for immediate init, then calls tier-2
- * via setImmediate to optionally refine this.name before the first tool call.
+ * The MCP adapter constructor uses tier-2 for immediate init, then the Server's
+ * oninitialized callback calls setMcpClientName() (tier-1) once the handshake
+ * completes.  detectCallerAsync() falls through only when tier-1 and tier-2 miss.
  */
+/**
+ * Store the caller identity obtained from the MCP `initialize` handshake
+ * `clientInfo.name` field.  Pass an empty string to clear.
+ * Called by the MCP adapter's `oninitialized` callback.
+ */
+export declare function setMcpClientName(rawName: string): void;
 /** Instant env-variable detection. Safe to call in a constructor. */
 export declare function detectCallerFromEnv(): string;
-/** Full detection including async ps(1) fallback. Never call in a constructor. */
+/** Full detection: MCP handshake name → env vars → ps(1) fallback. */
 export declare function detectCallerAsync(): Promise<string>;