knodin 0.7.5 → 0.8.2

package/dist/src/mcp-graph-worker.js

@@ -0,0 +1,69 @@
+import readline from "node:readline";
+import { DatabaseSync } from "node:sqlite";
+import { resolveDbPath } from "./engine/state-paths.js";
+import { attachMcpRequestSignal, handleKnodinTool } from "./tools/knodin-tools.js";
+const IPC_VERSION = 1;
+const active = new Map();
+function send(value) {
+    process.stdout.write(`${JSON.stringify(value)}\n`);
+}
+async function receive(message) {
+    if (message.version !== IPC_VERSION)
+        return;
+    if (message.type === "cancel") {
+        active.get(message.id)?.abort("gateway-cancelled");
+        return;
+    }
+    const controller = new AbortController();
+    active.set(message.id, controller);
+    send({ version: IPC_VERSION, type: "progress", id: message.id, sequence: 1, phase: "dispatch" });
+    try {
+        const fault = message.args?.__c89Fault;
+        if (process.env.KNODIN_MCP_FAULT_FIXTURES === "1") {
+            if (fault === "crash")
+                process.exit(91);
+            if (fault === "hang")
+                await new Promise(() => undefined);
+            if (fault === "lock") {
+                const repo = message.args.repoPath ?? process.cwd();
+                const database = new DatabaseSync(resolveDbPath(repo));
+                database.exec("INSERT INTO c89_lock_fixture(value) VALUES ('worker')");
+                database.close();
+            }
+        }
+        attachMcpRequestSignal(message.args, controller.signal);
+        const result = await handleKnodinTool(message.args);
+        send({ version: IPC_VERSION, type: "result", id: message.id, result });
+    }
+    catch (error) {
+        send({
+            version: IPC_VERSION,
+            type: "error",
+            id: message.id,
+            error: {
+                name: error instanceof Error ? error.name : "Error",
+                message: error instanceof Error ? error.message : String(error),
+                code: typeof error?.code === "string"
+                    ? error.code
+                    : null,
+            },
+        });
+    }
+    finally {
+        active.delete(message.id);
+    }
+}
+const lines = readline.createInterface({
+    input: process.stdin,
+    crlfDelay: Number.POSITIVE_INFINITY,
+});
+lines.on("line", (line) => {
+    try {
+        void receive(JSON.parse(line));
+    }
+    catch {
+        send({ version: IPC_VERSION, type: "protocol-error" });
+    }
+});
+lines.on("close", () => process.exit(0));
+send({ version: IPC_VERSION, type: "ready", pid: process.pid });

package/dist/src/mcp-reliability.js

@@ -0,0 +1,154 @@
+import crypto from "node:crypto";
+import fs from "node:fs";
+import path from "node:path";
+import v8 from "node:v8";
+import { repositoryBoundWrite } from "./diagnostics.js";
+const LOG_PATH = ".knodin/mcp-reliability.jsonl";
+const MAX_LOG_BYTES = 256 * 1024;
+const MAX_LOG_AGE_MS = 7 * 24 * 60 * 60 * 1000;
+const MAX_PROGRESS_EVENTS = 64;
+const DEADLINES = {
+    status: 15_000,
+    docs: 15_000,
+    context: 45_000,
+    explain: 60_000,
+    query: 60_000,
+    search: 90_000,
+    review: 90_000,
+    map: 120_000,
+    repair: 300_000,
+    index: 300_000,
+};
+export function operationDeadlineMs(operation) {
+    const override = Number.parseInt(process.env.KNODIN_MCP_DEADLINE_MS ?? "", 10);
+    if (Number.isSafeInteger(override) && override > 0)
+        return Math.min(override, 300_000);
+    return DEADLINES[operation] ?? 60_000;
+}
+/** Refuse new work when the local heap is already at a bounded pressure sentinel. */
+export function assertMcpMemoryHeadroom() {
+    const configured = Number.parseInt(process.env.KNODIN_MCP_MEMORY_SENTINEL_BYTES ?? "", 10);
+    const limit = Number.isSafeInteger(configured) && configured > 0
+        ? configured
+        : Math.floor(v8.getHeapStatistics().heap_size_limit * 0.9);
+    if (process.memoryUsage().heapUsed >= limit)
+        throw reliabilityError("KNODIN_MEMORY_PRESSURE", "MCP request refused by the local memory-pressure sentinel; retry after memory is released");
+}
+export function createMcpRequestContext(requestId, operation, repoPath) {
+    return {
+        requestId,
+        traceId: crypto.randomBytes(12).toString("hex"),
+        operation,
+        repoPath,
+        deadlineMs: operationDeadlineMs(operation),
+    };
+}
+function reliabilityError(code, message) {
+    return Object.assign(new Error(message), { code });
+}
+export async function superviseMcpRequest(context, signal, run, options = {}) {
+    if (signal.aborted)
+        throw reliabilityError("KNODIN_REQUEST_CANCELLED", "MCP request cancelled before dispatch");
+    let timer;
+    let onAbort;
+    const operation = new AbortController();
+    const task = run(operation.signal);
+    if (options.cooperativeCancellation !== true)
+        return await task;
+    let terminalError;
+    const deadline = new Promise((_resolve, reject) => {
+        timer = setTimeout(() => {
+            operation.abort("deadline");
+            terminalError = reliabilityError("KNODIN_DEADLINE_EXCEEDED", `${context.operation} exceeded its ${context.deadlineMs}ms deadline`);
+            reject(terminalError);
+        }, context.deadlineMs);
+    });
+    const cancelled = new Promise((_resolve, reject) => {
+        onAbort = () => {
+            operation.abort(signal.reason);
+            terminalError = reliabilityError("KNODIN_REQUEST_CANCELLED", "MCP request cancelled by client");
+            reject(terminalError);
+        };
+        signal.addEventListener("abort", onAbort, { once: true });
+    });
+    try {
+        return await Promise.race([task, deadline, cancelled]);
+    }
+    catch (error) {
+        if (terminalError) {
+            try {
+                await task;
+            }
+            catch {
+                // The classified cancellation/deadline remains the public failure.
+            }
+            throw terminalError;
+        }
+        throw error;
+    }
+    finally {
+        if (timer)
+            clearTimeout(timer);
+        if (onAbort)
+            signal.removeEventListener("abort", onAbort);
+    }
+}
+export function classifyMcpFailure(error) {
+    const code = typeof error?.code === "string" ? error.code : "";
+    const message = error instanceof Error ? error.message : String(error);
+    if (code === "KNODIN_REQUEST_CANCELLED")
+        return { kind: "cancelled", code };
+    if (code === "KNODIN_CLIENT_DISCONNECTED" ||
+        /transport closed|broken pipe|client disconnect/i.test(message))
+        return { kind: "client-disconnected", code: "KNODIN_CLIENT_DISCONNECTED" };
+    if (code === "KNODIN_DEADLINE_EXCEEDED")
+        return { kind: "deadline-exceeded", code };
+    if (code === "SQLITE_BUSY" ||
+        code === "SQLITE_LOCKED" ||
+        /database is locked|graph lock/i.test(message))
+        return { kind: "graph-locked", code: "KNODIN_GRAPH_LOCKED" };
+    if (code === "KNODIN_MEMORY_PRESSURE" ||
+        code === "ERR_WORKER_OUT_OF_MEMORY" ||
+        /heap out of memory|memory pressure/i.test(message))
+        return { kind: "memory-pressure", code: "KNODIN_MEMORY_PRESSURE" };
+    if (code === "ERR_WORKER_NOT_RUNNING" || /worker (?:exited|crashed|terminated)/i.test(message))
+        return { kind: "worker-crashed", code: "KNODIN_WORKER_CRASHED" };
+    return { kind: "operation-failed", code: "KNODIN_OPERATION_FAILED" };
+}
+function safeRepo(repoPath) {
+    try {
+        return fs.realpathSync(repoPath);
+    }
+    catch {
+        return null;
+    }
+}
+/** Synchronous, metadata-only journal: each complete line survives abrupt process exit. */
+export function recordMcpLifecycle(context, event, detail = {}) {
+    const repo = safeRepo(context.repoPath);
+    if (!repo || (detail.sequence ?? 0) > MAX_PROGRESS_EVENTS)
+        return;
+    try {
+        const target = path.join(repo, LOG_PATH);
+        const record = {
+            schemaVersion: 1,
+            at: new Date().toISOString(),
+            event,
+            requestId: context.requestId,
+            traceId: context.traceId,
+            operation: context.operation,
+            deadlineMs: context.deadlineMs,
+            ...detail,
+        };
+        const line = `${JSON.stringify(record)}\n`;
+        repositoryBoundWrite(repo, target, line, "append", MAX_LOG_BYTES, MAX_LOG_AGE_MS);
+    }
+    catch {
+        // Reliability logging must never break the request path.
+    }
+}
+export const mcpReliabilityBounds = {
+    maxLogBytes: MAX_LOG_BYTES,
+    maxLogAgeMs: MAX_LOG_AGE_MS,
+    maxProgressEvents: MAX_PROGRESS_EVENTS,
+};

package/dist/src/mcp-worker-supervisor.js

@@ -0,0 +1,350 @@
+import { execFileSync, spawn } from "node:child_process";
+import { EventEmitter } from "node:events";
+import fs from "node:fs";
+import path from "node:path";
+import readline from "node:readline";
+import { fileURLToPath } from "node:url";
+import { gitExecutable } from "./git-executable.js";
+import { operationDeadlineMs, recordMcpLifecycle, } from "./mcp-reliability.js";
+const IPC_VERSION = 1;
+const CANCEL_GRACE_MS = 250;
+const MAX_RESTARTS = 3;
+const RESTART_WINDOW_MS = 60_000;
+function codedError(code, message) {
+    return Object.assign(new Error(message), { code });
+}
+function defaultWorkerCommand() {
+    const extension = import.meta.url.endsWith(".ts") ? "ts" : "js";
+    const entry = fileURLToPath(new URL(`../src/mcp-graph-worker.${extension}`, import.meta.url));
+    return { command: process.execPath, args: [...process.execArgv, entry] };
+}
+export class RepositoryWorker extends EventEmitter {
+    repoPath;
+    workerCommand;
+    child;
+    ready;
+    pending = new Map();
+    tail = Promise.resolve();
+    restartTimes = [];
+    lastFailureTraceId;
+    constructor(repoPath, workerCommand = defaultWorkerCommand()) {
+        super();
+        this.repoPath = repoPath;
+        this.workerCommand = workerCommand;
+    }
+    start() {
+        if (this.child && this.ready)
+            return this.ready;
+        const child = spawn(this.workerCommand.command, this.workerCommand.args, {
+            cwd: this.repoPath,
+            stdio: ["pipe", "pipe", "pipe"],
+            env: { ...process.env, KNODIN_MCP_GRAPH_WORKER: "1" },
+        });
+        this.child = child;
+        child.unref();
+        child.stdin?.unref?.();
+        child.stdout?.unref?.();
+        child.stderr?.unref?.();
+        // Drain raw diagnostics so pipe backpressure cannot stall the worker; never persist source text.
+        child.stderr?.resume();
+        this.ready = new Promise((resolve, reject) => {
+            // Deliberately fixed, not configurable. This kill is the recovery path
+            // for a wedged worker, not merely a guard against a slow one: the
+            // supervisor restarts after it fires. Raising it delays recovery by
+            // exactly the amount raised, which surfaces as the next request
+            // burning its whole deadline in startup rather than as slowness here.
+            const startup = setTimeout(() => child.kill("SIGKILL"), 10_000);
+            if (!child.stdout)
+                throw codedError("KNODIN_WORKER_CRASHED", "graph worker stdout unavailable");
+            const lines = readline.createInterface({ input: child.stdout });
+            lines.on("line", (line) => {
+                let message;
+                try {
+                    message = JSON.parse(line);
+                }
+                catch {
+                    this.failProtocol(child, "graph worker emitted malformed JSON");
+                    return;
+                }
+                if (message.version !== IPC_VERSION) {
+                    this.failProtocol(child, "graph worker IPC version mismatch");
+                    return;
+                }
+                if (message.type === "ready") {
+                    clearTimeout(startup);
+                    resolve();
+                    return;
+                }
+                this.receive(child, message);
+            });
+            child.once("error", reject);
+            child.once("exit", (code, signal) => reject(codedError("KNODIN_WORKER_CRASHED", `graph worker exited during startup (${signal ?? code ?? "unknown"})`)));
+        });
+        child.once("exit", (code, signal) => {
+            const observe = () => this.exited(child, code, signal);
+            const delay = this.workerCommand.exitObservationDelayMs ?? 0;
+            if (delay > 0)
+                setTimeout(observe, delay);
+            else
+                observe();
+        });
+        return this.ready;
+    }
+    receive(child, message) {
+        if (message.type === "protocol-error") {
+            this.failProtocol(child, "graph worker rejected the IPC request");
+            return;
+        }
+        if (!("id" in message))
+            return;
+        const pending = this.pending.get(message.id);
+        if (pending?.child !== child)
+            return;
+        if (message.type === "progress") {
+            pending.onProgress?.(message.sequence, message.phase);
+            return;
+        }
+        this.finish(message.id);
+        if (message.type === "result")
+            pending.terminalError
+                ? pending.reject(pending.terminalError)
+                : pending.resolve(message.result);
+        else if (message.type === "error")
+            pending.reject(pending.terminalError ??
+                codedError(message.error.code ?? "KNODIN_OPERATION_FAILED", message.error.message));
+    }
+    failProtocol(child, message) {
+        for (const [id, pending] of this.pending) {
+            if (pending.child !== child)
+                continue;
+            this.lastFailureTraceId = pending.context.traceId;
+            this.finish(id);
+            pending.reject(codedError("KNODIN_WORKER_PROTOCOL", message));
+        }
+        if (this.child === child) {
+            this.child = undefined;
+            this.ready = undefined;
+        }
+        child.kill("SIGKILL");
+    }
+    finish(id) {
+        const pending = this.pending.get(id);
+        if (!pending)
+            return;
+        clearTimeout(pending.timer);
+        if (pending.cancelTimer)
+            clearTimeout(pending.cancelTimer);
+        pending.signal.removeEventListener("abort", pending.cancel);
+        this.pending.delete(id);
+    }
+    exited(child, code, signal) {
+        if (this.child === child) {
+            this.child = undefined;
+            this.ready = undefined;
+        }
+        const now = Date.now();
+        this.restartTimes = this.restartTimes.filter((at) => now - at < RESTART_WINDOW_MS);
+        for (const [id, pending] of this.pending) {
+            if (pending.child !== child)
+                continue;
+            this.lastFailureTraceId = pending.context.traceId;
+            this.finish(id);
+            pending.reject(pending.terminalError ??
+                codedError("KNODIN_WORKER_CRASHED", `graph worker exited (${signal ?? code ?? "unknown"})`));
+        }
+    }
+    terminate(id, code, message) {
+        const pending = this.pending.get(id);
+        if (!pending)
+            return;
+        this.lastFailureTraceId = pending.context.traceId;
+        this.child?.stdin?.write(`${JSON.stringify({ version: IPC_VERSION, type: "cancel", id })}\n`);
+        pending.terminalError = codedError(code, message);
+        pending.cancelTimer = setTimeout(() => {
+            if (!this.pending.has(id))
+                return;
+            this.child?.kill("SIGKILL");
+        }, CANCEL_GRACE_MS);
+    }
+    async execute(context, args, signal, onProgress) {
+        const deadlineMs = operationDeadlineMs(context.operation);
+        const deadlineAt = Date.now() + deadlineMs;
+        const predecessor = this.tail;
+        let release;
+        this.tail = new Promise((resolve) => {
+            release = resolve;
+        });
+        let queueTimer;
+        let queueAbort;
+        let acquired = false;
+        try {
+            await Promise.race([
+                predecessor,
+                new Promise((_resolve, reject) => {
+                    queueTimer = setTimeout(() => reject(codedError("KNODIN_DEADLINE_EXCEEDED", `${context.operation} exceeded its ${deadlineMs}ms deadline while queued`)), deadlineMs);
+                    queueAbort = () => reject(codedError("KNODIN_CLIENT_DISCONNECTED", "MCP client disconnected while queued"));
+                    signal.addEventListener("abort", queueAbort, { once: true });
+                }),
+            ]);
+            acquired = true;
+        }
+        catch (error) {
+            void predecessor.finally(release);
+            throw error;
+        }
+        finally {
+            if (queueTimer)
+                clearTimeout(queueTimer);
+            if (queueAbort)
+                signal.removeEventListener("abort", queueAbort);
+        }
+        const { requestId, operation } = context;
+        try {
+            if (signal.aborted)
+                throw codedError("KNODIN_REQUEST_CANCELLED", "request cancelled before worker dispatch");
+            if (!this.child) {
+                if (this.restartTimes.length >= MAX_RESTARTS)
+                    throw codedError("KNODIN_RESTART_LIMIT", "graph worker restart limit reached");
+                this.restartTimes.push(Date.now());
+            }
+            const startup = this.start();
+            const remainingForStartup = Math.max(1, deadlineAt - Date.now());
+            let startupTimer;
+            let startupAbort;
+            let startupTerminalError;
+            await Promise.race([
+                startup.catch((error) => {
+                    throw startupTerminalError ?? error;
+                }),
+                new Promise((_resolve, reject) => {
+                    const terminate = (error) => {
+                        this.lastFailureTraceId = context.traceId;
+                        startupTerminalError = error;
+                        this.child?.kill("SIGKILL");
+                        startup.then(() => reject(error), () => reject(error));
+                    };
+                    startupTimer = setTimeout(() => terminate(codedError("KNODIN_DEADLINE_EXCEEDED", `${operation} exceeded its ${deadlineMs}ms deadline during worker startup`)), remainingForStartup);
+                    startupAbort = () => terminate(codedError("KNODIN_CLIENT_DISCONNECTED", "MCP client disconnected during worker startup"));
+                    signal.addEventListener("abort", startupAbort, { once: true });
+                }),
+            ]).finally(() => {
+                if (startupTimer)
+                    clearTimeout(startupTimer);
+                if (startupAbort)
+                    signal.removeEventListener("abort", startupAbort);
+            });
+            if (signal.aborted)
+                throw codedError("KNODIN_REQUEST_CANCELLED", "request cancelled during worker startup");
+            const predecessorTraceId = this.lastFailureTraceId;
+            if (predecessorTraceId)
+                recordMcpLifecycle(context, "restart", { predecessorTraceId });
+            const result = await new Promise((resolve, reject) => {
+                const remaining = Math.max(1, deadlineAt - Date.now());
+                const timer = setTimeout(() => this.terminate(requestId, "KNODIN_DEADLINE_EXCEEDED", `${operation} exceeded its ${deadlineMs}ms deadline`), remaining);
+                const cancel = () => this.terminate(requestId, "KNODIN_CLIENT_DISCONNECTED", "MCP client disconnected or cancelled");
+                const child = this.child;
+                if (!child) {
+                    clearTimeout(timer);
+                    reject(codedError("KNODIN_WORKER_CRASHED", "graph worker unavailable"));
+                    return;
+                }
+                const pendingRecord = {
+                    child,
+                    context,
+                    resolve,
+                    reject,
+                    onProgress,
+                    timer,
+                    signal,
+                    cancel,
+                };
+                this.pending.set(requestId, pendingRecord);
+                signal.addEventListener("abort", cancel, { once: true });
+                const input = child.stdin;
+                if (!input) {
+                    reject(codedError("KNODIN_WORKER_CRASHED", "graph worker stdin unavailable"));
+                    return;
+                }
+                input.write(`${JSON.stringify({ version: IPC_VERSION, type: "request", id: requestId, args })}\n`, (error) => {
+                    if (error) {
+                        pendingRecord.terminalError = codedError("KNODIN_WORKER_CRASHED", "graph worker stdin write failed");
+                        child.kill("SIGKILL");
+                    }
+                });
+            }).finally(() => this.finish(requestId));
+            if (predecessorTraceId)
+                recordMcpLifecycle(context, "recovery", { predecessorTraceId });
+            this.lastFailureTraceId = undefined;
+            return { result, ...(predecessorTraceId ? { predecessorTraceId } : {}) };
+        }
+        finally {
+            if (acquired)
+                release();
+        }
+    }
+    killForTest() {
+        this.child?.kill("SIGKILL");
+    }
+    async close() {
+        const child = this.child;
+        if (child?.exitCode !== null)
+            return;
+        await new Promise((resolve) => {
+            let escalation;
+            let bound;
+            const exited = () => {
+                if (escalation)
+                    clearTimeout(escalation);
+                if (bound)
+                    clearTimeout(bound);
+                resolve();
+            };
+            child.once("exit", exited);
+            if (child.exitCode !== null) {
+                child.off("exit", exited);
+                exited();
+                return;
+            }
+            child.kill("SIGTERM");
+            escalation = setTimeout(() => {
+                child.kill("SIGKILL");
+                bound = setTimeout(() => {
+                    child.off("exit", exited);
+                    resolve();
+                }, 500);
+            }, 500);
+        });
+    }
+}
+export class WorkerSupervisor {
+    workers = new Map();
+    exitHandler = () => void this.close();
+    constructor() {
+        process.once("exit", this.exitHandler);
+    }
+    worker(repoPath) {
+        const resolved = fs.realpathSync(path.resolve(repoPath));
+        let key = resolved;
+        try {
+            key = fs.realpathSync(execFileSync(gitExecutable(), ["rev-parse", "--show-toplevel"], {
+                cwd: resolved,
+                encoding: "utf8",
+                stdio: ["ignore", "pipe", "ignore"],
+            }).trim());
+        }
+        catch {
+            /* Non-Git fixtures retain their canonical directory identity. */
+        }
+        let worker = this.workers.get(key);
+        if (!worker) {
+            worker = new RepositoryWorker(key);
+            this.workers.set(key, worker);
+        }
+        return worker;
+    }
+    async close() {
+        await Promise.all([...this.workers.values()].map((worker) => worker.close()));
+        this.workers.clear();
+        process.off("exit", this.exitHandler);
+    }
+}