nexus-prime 6.3.0 → 6.4.0

package/dist/agents/adapters/mcp/async-gate.d.ts

@@ -0,0 +1,96 @@
+/**
+ * AsyncGate — lightweight async MCP handler wrapper.
+ *
+ * Long-running MCP tool calls timeout in Claude Code (~60s). This module lets
+ * any handler opt into an async contract: if work exceeds maxSyncMs, return
+ * {queued:true, runId} immediately and finish in the background. Callers poll
+ * nexus_run_status(runId) for completion.
+ *
+ * Design:
+ *   - In-memory ring buffer (cap 200 jobs). No SQLite dep — keep hot path fast.
+ *   - withAsyncGate wraps a handler fn; uses Promise.race against a deadline.
+ *   - getAsyncGate() returns the process-singleton instance.
+ */
+export type AsyncJobStatus = 'pending' | 'running' | 'completed' | 'failed';
+export interface AsyncJob {
+    runId: string;
+    tool: string;
+    status: AsyncJobStatus;
+    stage: string;
+    progress: number;
+    queuedAt: number;
+    startedAt?: number;
+    completedAt?: number;
+    result?: {
+        content: Array<{
+            type: string;
+            text: string;
+        }>;
+    };
+    error?: string;
+    etaMs?: number;
+}
+export interface AsyncGateOpts {
+    /** Tool name — for job metadata */
+    tool: string;
+    /** If handler resolves within this window, return inline. Default: 2000ms */
+    maxSyncMs?: number;
+    /** Human-readable hint for estimated duration */
+    etaMs?: number;
+}
+type HandlerFn = () => Promise<{
+    content: Array<{
+        type: string;
+        text: string;
+    }>;
+}>;
+declare class AsyncGate {
+    private jobs;
+    private insertOrder;
+    /** Run handler; if it takes >maxSyncMs, queue it and return runId immediately. */
+    run(fn: HandlerFn, opts: AsyncGateOpts): Promise<{
+        content: Array<{
+            type: string;
+            text: string;
+        }>;
+    } | {
+        queued: true;
+        runId: string;
+        etaMs?: number;
+    }>;
+    getJob(runId: string): AsyncJob | undefined;
+    /** Format job status as MCP text response */
+    formatStatus(runId: string): {
+        content: Array<{
+            type: string;
+            text: string;
+        }>;
+    };
+    updateStage(runId: string, stage: string, progress: number): void;
+    /** Return jobs that have been running longer than their stale threshold. */
+    getStaleJobs(now: number, defaultStaleMs: number, etaMultiplier: number): AsyncJob[];
+    /** Mark a running job as failed (watchdog reap). */
+    markFailed(runId: string, reason: string): void;
+    private enqueueJob;
+}
+export declare function getAsyncGate(): AsyncGate;
+/**
+ * Wrap an MCP handler function in the async gate.
+ *
+ * Usage:
+ *   return withAsyncGate(() => doSlowWork(), { tool: 'nexus_orchestrate', maxSyncMs: 2000, etaMs: 30_000 });
+ *
+ * If work finishes within maxSyncMs → inline result (transparent).
+ * If not → { queued: true, runId } immediately; work continues in bg.
+ */
+export declare function withAsyncGate(fn: HandlerFn, opts: AsyncGateOpts): Promise<{
+    content: Array<{
+        type: string;
+        text: string;
+    }>;
+} | {
+    queued: true;
+    runId: string;
+    etaMs?: number;
+}>;
+export {};

package/dist/agents/adapters/mcp/async-gate.js

@@ -0,0 +1,193 @@
+/**
+ * AsyncGate — lightweight async MCP handler wrapper.
+ *
+ * Long-running MCP tool calls timeout in Claude Code (~60s). This module lets
+ * any handler opt into an async contract: if work exceeds maxSyncMs, return
+ * {queued:true, runId} immediately and finish in the background. Callers poll
+ * nexus_run_status(runId) for completion.
+ *
+ * Design:
+ *   - In-memory ring buffer (cap 200 jobs). No SQLite dep — keep hot path fast.
+ *   - withAsyncGate wraps a handler fn; uses Promise.race against a deadline.
+ *   - getAsyncGate() returns the process-singleton instance.
+ */
+import { randomUUID } from 'crypto';
+import { nexusEventBus } from '../../../engines/event-bus.js';
+// ─── Ring buffer ──────────────────────────────────────────────────────────────
+const RING_CAP = 200;
+class AsyncGate {
+    jobs = new Map();
+    insertOrder = [];
+    /** Run handler; if it takes >maxSyncMs, queue it and return runId immediately. */
+    async run(fn, opts) {
+        const maxSyncMs = opts.maxSyncMs ?? 2000;
+        const runId = randomUUID();
+        const job = {
+            runId,
+            tool: opts.tool,
+            status: 'pending',
+            stage: 'queued',
+            progress: 0,
+            queuedAt: Date.now(),
+            etaMs: opts.etaMs,
+        };
+        this.enqueueJob(job);
+        // Race: handler vs deadline
+        let syncResolved = false;
+        const deadline = new Promise((resolve) => setTimeout(() => resolve(null), maxSyncMs));
+        const work = (async () => {
+            job.status = 'running';
+            job.stage = 'executing';
+            job.startedAt = Date.now();
+            try {
+                const result = await fn();
+                job.status = 'completed';
+                job.stage = 'done';
+                job.progress = 100;
+                job.result = result;
+                job.completedAt = Date.now();
+                nexusEventBus.emit('async_gate.completed', { runId, tool: opts.tool });
+                return result;
+            }
+            catch (err) {
+                job.status = 'failed';
+                job.stage = 'error';
+                job.error = err instanceof Error ? err.message : String(err);
+                job.completedAt = Date.now();
+                nexusEventBus.emit('async_gate.failed', { runId, tool: opts.tool, error: job.error });
+                // Do not rethrow — if deadline already won there is no downstream catcher;
+                // job state is updated so polls return the error correctly.
+            }
+        })();
+        // Suppress unhandled rejection: deadline may win while work is still in flight.
+        work.catch(() => { });
+        const winner = await Promise.race([
+            work.then((r) => { syncResolved = true; return r; }),
+            deadline,
+        ]);
+        if (syncResolved && winner !== null) {
+            // Completed within deadline — return inline
+            return winner;
+        }
+        // Still running — return async receipt
+        return { queued: true, runId, etaMs: opts.etaMs };
+    }
+    getJob(runId) {
+        return this.jobs.get(runId);
+    }
+    /** Format job status as MCP text response */
+    formatStatus(runId) {
+        const job = this.jobs.get(runId);
+        if (!job) {
+            return { content: [{ type: 'text', text: `❌ Async run not found: ${runId}` }] };
+        }
+        if (job.status === 'completed' && job.result) {
+            return job.result;
+        }
+        if (job.status === 'failed') {
+            return {
+                content: [{
+                        type: 'text',
+                        text: `❌ Run ${runId} failed\nTool: ${job.tool}\nError: ${job.error ?? 'unknown'}`,
+                    }],
+            };
+        }
+        const elapsed = Date.now() - job.queuedAt;
+        const etaLine = job.etaMs ? `  ETA: ~${Math.ceil((job.etaMs - elapsed) / 1000)}s remaining` : '';
+        return {
+            content: [{
+                    type: 'text',
+                    text: [
+                        `⏳ Run ${runId}`,
+                        `  Tool:     ${job.tool}`,
+                        `  Status:   ${job.status}`,
+                        `  Stage:    ${job.stage}`,
+                        `  Progress: ${job.progress}%`,
+                        `  Elapsed:  ${Math.round(elapsed / 100) / 10}s`,
+                        etaLine,
+                        '',
+                        'Poll again with nexus_run_status(runId) in a few seconds.',
+                    ].filter(l => l !== undefined).join('\n'),
+                }],
+        };
+    }
+    updateStage(runId, stage, progress) {
+        const job = this.jobs.get(runId);
+        if (job && job.status === 'running') {
+            job.stage = stage;
+            job.progress = Math.min(99, progress);
+        }
+    }
+    /** Return jobs that have been running longer than their stale threshold. */
+    getStaleJobs(now, defaultStaleMs, etaMultiplier) {
+        const stale = [];
+        for (const job of this.jobs.values()) {
+            if (job.status !== 'running')
+                continue;
+            const startedAt = job.startedAt ?? job.queuedAt;
+            const threshold = job.etaMs != null
+                ? job.etaMs * etaMultiplier
+                : defaultStaleMs;
+            if (now - startedAt > threshold)
+                stale.push(job);
+        }
+        return stale;
+    }
+    /** Mark a running job as failed (watchdog reap). */
+    markFailed(runId, reason) {
+        const job = this.jobs.get(runId);
+        if (job && (job.status === 'running' || job.status === 'pending')) {
+            job.status = 'failed';
+            job.stage = 'error';
+            job.error = reason;
+            job.completedAt = Date.now();
+        }
+    }
+    enqueueJob(job) {
+        if (this.insertOrder.length >= RING_CAP) {
+            // Skip eviction if oldest job is still running — losing it would make polls fail.
+            const oldestId = this.insertOrder[0];
+            const oldest = oldestId ? this.jobs.get(oldestId) : undefined;
+            if (oldest && (oldest.status === 'running' || oldest.status === 'pending')) {
+                // Buffer full with live jobs — evict second-oldest completed/failed instead
+                const evictIdx = this.insertOrder.findIndex(id => {
+                    const j = this.jobs.get(id);
+                    return j && j.status !== 'running' && j.status !== 'pending';
+                });
+                if (evictIdx !== -1) {
+                    const evictId = this.insertOrder.splice(evictIdx, 1)[0];
+                    if (evictId)
+                        this.jobs.delete(evictId);
+                }
+                // If all live, just append without eviction (buffer temporarily oversized).
+            }
+            else {
+                this.insertOrder.shift();
+                if (oldestId)
+                    this.jobs.delete(oldestId);
+            }
+        }
+        this.jobs.set(job.runId, job);
+        this.insertOrder.push(job.runId);
+    }
+}
+// ─── Singleton ────────────────────────────────────────────────────────────────
+let _instance = null;
+export function getAsyncGate() {
+    if (!_instance)
+        _instance = new AsyncGate();
+    return _instance;
+}
+// ─── withAsyncGate helper ─────────────────────────────────────────────────────
+/**
+ * Wrap an MCP handler function in the async gate.
+ *
+ * Usage:
+ *   return withAsyncGate(() => doSlowWork(), { tool: 'nexus_orchestrate', maxSyncMs: 2000, etaMs: 30_000 });
+ *
+ * If work finishes within maxSyncMs → inline result (transparent).
+ * If not → { queued: true, runId } immediately; work continues in bg.
+ */
+export function withAsyncGate(fn, opts) {
+    return getAsyncGate().run(fn, opts);
+}

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

@@ -0,0 +1,40 @@
+/**
+ * Circuit breaker + backpressure for MCP tool calls.
+ *
+ * Circuit breaker: track p99 latency over a rolling window per tool.
+ * If p99 exceeds CIRCUIT_TRIP_MS, tool is force-gated (async even for fast calls).
+ * Resets automatically after RESET_WINDOW_MS of clean calls.
+ *
+ * Backpressure: global in-flight counter. If above QUEUE_CAPACITY,
+ * return {busy: true, retryAfterMs} instead of queuing more work.
+ */
+export type CircuitState = 'closed' | 'open' | 'half-open';
+export interface CircuitStats {
+    tool: string;
+    state: CircuitState;
+    p99Ms: number;
+    sampleCount: number;
+    trippedAt?: number;
+}
+declare class CircuitManager {
+    private circuits;
+    private inFlight;
+    private getCircuit;
+    /** Check backpressure BEFORE enqueuing. Returns retryAfterMs or 0 if OK. */
+    checkCapacity(): number;
+    /** True if circuit is open (tool force-gated to async). */
+    isForceAsync(tool: string): boolean;
+    /** Record a completed call. Pass durationMs for p99 tracking. */
+    recordComplete(tool: string, durationMs: number, success: boolean): void;
+    /** Call when work starts (increments in-flight). */
+    recordStart(tool: string): void;
+    getStats(tool: string): CircuitStats;
+    getAllStats(): CircuitStats[];
+    getInFlight(): number;
+}
+export declare function getCircuitManager(): CircuitManager;
+export declare function checkBackpressure(): {
+    ok: boolean;
+    retryAfterMs?: number;
+};
+export {};

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

@@ -0,0 +1,135 @@
+/**
+ * Circuit breaker + backpressure for MCP tool calls.
+ *
+ * Circuit breaker: track p99 latency over a rolling window per tool.
+ * If p99 exceeds CIRCUIT_TRIP_MS, tool is force-gated (async even for fast calls).
+ * Resets automatically after RESET_WINDOW_MS of clean calls.
+ *
+ * Backpressure: global in-flight counter. If above QUEUE_CAPACITY,
+ * return {busy: true, retryAfterMs} instead of queuing more work.
+ */
+import { nexusEventBus } from '../../../engines/event-bus.js';
+// ─── Config ───────────────────────────────────────────────────────────────────
+const WINDOW_SIZE = 50; // rolling sample count per tool
+const CIRCUIT_TRIP_MS = 20_000; // p99 > 20s → trip circuit
+const RESET_WINDOW_MS = 60_000; // stay tripped for 60s before retry
+const QUEUE_CAPACITY = 100; // max concurrent in-flight tool calls
+// ─── CircuitBreaker ───────────────────────────────────────────────────────────
+class ToolCircuit {
+    samples = [];
+    state = 'closed';
+    trippedAt = 0;
+    record(durationMs) {
+        this.samples.push(durationMs);
+        if (this.samples.length > WINDOW_SIZE)
+            this.samples.shift();
+        this.evaluate();
+    }
+    /** Returns true if this tool should be force-gated (async even for fast calls). */
+    isOpen() {
+        if (this.state === 'closed')
+            return false;
+        if (this.state === 'open') {
+            if (Date.now() - this.trippedAt >= RESET_WINDOW_MS) {
+                this.state = 'half-open';
+                return false;
+            }
+            return true;
+        }
+        // half-open: allow one attempt
+        return false;
+    }
+    onSuccess() {
+        if (this.state === 'half-open') {
+            this.state = 'closed';
+            this.samples = [];
+        }
+    }
+    onFailure() {
+        if (this.state === 'half-open') {
+            this.trip();
+        }
+    }
+    p99() {
+        if (this.samples.length === 0)
+            return 0;
+        const sorted = [...this.samples].sort((a, b) => a - b);
+        const idx = Math.floor(sorted.length * 0.99);
+        return sorted[Math.min(idx, sorted.length - 1)];
+    }
+    evaluate() {
+        if (this.state !== 'closed')
+            return;
+        if (this.samples.length >= 10 && this.p99() > CIRCUIT_TRIP_MS) {
+            this.trip();
+        }
+    }
+    trip() {
+        this.state = 'open';
+        this.trippedAt = Date.now();
+    }
+}
+// ─── Singleton manager ────────────────────────────────────────────────────────
+class CircuitManager {
+    circuits = new Map();
+    inFlight = 0;
+    getCircuit(tool) {
+        if (!this.circuits.has(tool))
+            this.circuits.set(tool, new ToolCircuit());
+        return this.circuits.get(tool);
+    }
+    /** Check backpressure BEFORE enqueuing. Returns retryAfterMs or 0 if OK. */
+    checkCapacity() {
+        return this.inFlight >= QUEUE_CAPACITY ? 5_000 : 0;
+    }
+    /** True if circuit is open (tool force-gated to async). */
+    isForceAsync(tool) {
+        return this.getCircuit(tool).isOpen();
+    }
+    /** Record a completed call. Pass durationMs for p99 tracking. */
+    recordComplete(tool, durationMs, success) {
+        const c = this.getCircuit(tool);
+        c.record(durationMs);
+        if (success)
+            c.onSuccess();
+        else
+            c.onFailure();
+        this.inFlight = Math.max(0, this.inFlight - 1);
+        if (c.state === 'open') {
+            nexusEventBus.emit('nexus.circuit-open', { tool, p99Ms: c.p99() });
+        }
+    }
+    /** Call when work starts (increments in-flight). */
+    recordStart(tool) {
+        this.inFlight++;
+        if (this.inFlight >= QUEUE_CAPACITY) {
+            nexusEventBus.emit('nexus.circuit-tripped', { tool, reason: 'backpressure', queueDepth: this.inFlight });
+        }
+    }
+    getStats(tool) {
+        const c = this.getCircuit(tool);
+        return {
+            tool,
+            state: c.state,
+            p99Ms: c.p99(),
+            sampleCount: c.samples?.length ?? 0,
+            trippedAt: c.state !== 'closed' ? c.trippedAt : undefined,
+        };
+    }
+    getAllStats() {
+        return Array.from(this.circuits.keys()).map(t => this.getStats(t));
+    }
+    getInFlight() {
+        return this.inFlight;
+    }
+}
+let _manager = null;
+export function getCircuitManager() {
+    if (!_manager)
+        _manager = new CircuitManager();
+    return _manager;
+}
+export function checkBackpressure() {
+    const retryAfterMs = getCircuitManager().checkCapacity();
+    return retryAfterMs > 0 ? { ok: false, retryAfterMs } : { ok: true };
+}

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

@@ -1050,6 +1050,108 @@ export function buildMcpToolDefinitions() {
         },
         ...synapseToolDefinitions,
         ...architectsToolDefinitions,
+        // ── Workforce (unified worker+job layer) ──────────────────────────
+        {
+            name: 'nexus_work_enqueue',
+            description: 'Enqueue a new job into the workforce queue. Jobs with dependsOn start in backlog; others start ready.',
+            inputSchema: {
+                type: 'object',
+                properties: {
+                    title: { type: 'string' },
+                    tier: { type: 'string', enum: ['strategy', 'tactical'] },
+                    priority: { type: 'number' },
+                    parentId: { type: 'string' },
+                    dependsOn: { type: 'array', items: { type: 'string' } },
+                    budgetCapUsd: { type: 'number' },
+                    payload: { type: 'object' },
+                    client: { type: 'string' },
+                },
+                required: ['title'],
+            },
+        },
+        {
+            name: 'nexus_work_claim',
+            description: 'Atomically claim a specific job (by jobId) or the next highest-priority ready job.',
+            inputSchema: {
+                type: 'object',
+                properties: {
+                    workerId: { type: 'string' },
+                    jobId: { type: 'string' },
+                    leaseMs: { type: 'number' },
+                },
+                required: ['workerId'],
+            },
+        },
+        {
+            name: 'nexus_work_progress',
+            description: 'Advance a claimed job (claimed→wip or wip→review) and record token usage.',
+            inputSchema: {
+                type: 'object',
+                properties: {
+                    jobId: { type: 'string' },
+                    workerId: { type: 'string' },
+                    stage: { type: 'string', enum: ['wip', 'review'] },
+                    tokens: { type: 'number' },
+                },
+                required: ['jobId', 'workerId'],
+            },
+        },
+        {
+            name: 'nexus_work_complete',
+            description: 'Mark a job as done, failed, or blocked. Triggers DAG promotion.',
+            inputSchema: {
+                type: 'object',
+                properties: {
+                    jobId: { type: 'string' },
+                    workerId: { type: 'string' },
+                    outcome: { type: 'string', enum: ['done', 'failed', 'blocked'] },
+                },
+                required: ['jobId', 'workerId', 'outcome'],
+            },
+        },
+        {
+            name: 'nexus_work_block',
+            description: 'Mark a job as blocked.',
+            inputSchema: {
+                type: 'object',
+                properties: {
+                    jobId: { type: 'string' },
+                    workerId: { type: 'string' },
+                },
+                required: ['jobId', 'workerId'],
+            },
+        },
+        {
+            name: 'nexus_work_kanban',
+            description: 'Kanban board showing jobs grouped by status lane.',
+            inputSchema: {
+                type: 'object',
+                properties: { client: { type: 'string' } },
+            },
+        },
+        {
+            name: 'nexus_work_workers',
+            description: 'List registered workers with status, load, and budget.',
+            inputSchema: {
+                type: 'object',
+                properties: {
+                    status: { type: 'string', enum: ['idle', 'active', 'stale', 'retired'] },
+                },
+            },
+        },
+        {
+            name: 'nexus_work_hire',
+            description: 'Register a new worker (agent) into the workforce pool.',
+            inputSchema: {
+                type: 'object',
+                properties: {
+                    name: { type: 'string' },
+                    role: { type: 'string' },
+                    client: { type: 'string' },
+                    budgetCapUsd: { type: 'number' },
+                },
+            },
+        },
         // ── Embedded capabilities (auto-detected from installed skills) ──
         ...getGstackBridge().getToolDefinitions(),
     ];