syncstaff-mcp 0.2.3

package/dist/mcp/daemon-client.js

@@ -0,0 +1,156 @@
+/**
+ * Thin client for the optional local-graph daemon (daemon.ts).
+ *
+ * Every function here is fail-soft by construction: a daemon that is not
+ * running, not reachable, on a mismatched protocol version, or that errors
+ * mid-request never throws out of this module. The caller (index.ts) always
+ * gets either a real result or `null`, and on `null` falls back to building
+ * its own local graph exactly as it did before this module existed. Nothing
+ * here may become a new way for `sync_impact` / `sync_context_card` /
+ * `sync_retrieve` to fail that didn't already exist without a daemon.
+ */
+import { spawn } from "node:child_process";
+import { existsSync, readFileSync } from "node:fs";
+import { connect } from "node:net";
+import { fileURLToPath } from "node:url";
+import { DAEMON_PROTOCOL_VERSION, socketPathFor, tcpPortFileFor, } from "./daemon-protocol.js";
+function envSeconds(name, fallback) {
+    const value = Number(process.env[name]);
+    return Number.isFinite(value) && value >= 0 ? value : fallback;
+}
+/** 0 disables the daemon path entirely — every call falls back to local computation, same as before this module existed. */
+const REQUEST_TIMEOUT_MS = envSeconds("KEEL_MCP_DAEMON_TIMEOUT_SECONDS", 20) * 1000;
+const CONNECT_TIMEOUT_MS = 500;
+/** Opt-in: off by default, so existing behavior is unchanged unless a caller sets this. */
+export function daemonEnabled() {
+    const v = process.env.KEEL_MCP_DAEMON?.trim().toLowerCase();
+    return v === "1" || v === "true" || v === "on";
+}
+function connectTo(target) {
+    return new Promise((resolve, reject) => {
+        const socket = "path" in target ? connect(target.path) : connect(target.port, "127.0.0.1");
+        const timer = setTimeout(() => {
+            socket.destroy();
+            reject(new Error("connect timeout"));
+        }, CONNECT_TIMEOUT_MS);
+        socket.once("connect", () => {
+            clearTimeout(timer);
+            resolve(socket);
+        });
+        socket.once("error", (err) => {
+            clearTimeout(timer);
+            reject(err);
+        });
+    });
+}
+async function connectToDaemon(root) {
+    const socketPath = socketPathFor(root);
+    if (existsSync(socketPath)) {
+        try {
+            return await connectTo({ path: socketPath });
+        }
+        catch {
+            /* stale socket file, or a daemon mid-shutdown; fall through to the TCP fallback check below */
+        }
+    }
+    const portFile = tcpPortFileFor(root);
+    if (existsSync(portFile)) {
+        const port = Number(readFileSync(portFile, "utf8").trim());
+        if (Number.isInteger(port) && port > 0) {
+            try {
+                return await connectTo({ port });
+            }
+            catch {
+                /* stale port file */
+            }
+        }
+    }
+    return null;
+}
+function sendRequest(socket, req) {
+    return new Promise((resolve, reject) => {
+        let buffer = "";
+        const timer = setTimeout(() => {
+            socket.destroy();
+            reject(new Error("daemon request timed out"));
+        }, REQUEST_TIMEOUT_MS);
+        socket.setEncoding("utf8");
+        socket.on("data", (chunk) => {
+            buffer += chunk;
+            const newline = buffer.indexOf("\n");
+            if (newline === -1)
+                return;
+            clearTimeout(timer);
+            const line = buffer.slice(0, newline);
+            socket.end();
+            try {
+                resolve(JSON.parse(line));
+            }
+            catch (e) {
+                reject(e);
+            }
+        });
+        socket.once("error", (err) => {
+            clearTimeout(timer);
+            reject(err);
+        });
+        socket.write(`${JSON.stringify(req)}\n`);
+    });
+}
+/**
+ * Try answering `op` from the daemon; `null` means "no usable daemon right
+ * now", never a thrown error — see the module comment for why that is load
+ * bearing rather than incidental.
+ */
+export async function tryDaemon(root, op, args) {
+    if (!daemonEnabled())
+        return null;
+    let socket = null;
+    try {
+        socket = await connectToDaemon(root);
+        if (!socket)
+            return null;
+        const res = await sendRequest(socket, { v: DAEMON_PROTOCOL_VERSION, op, root, args });
+        if (!res.ok)
+            return null; // version mismatch, bad request, or a build failure — fall back silently
+        return res.result;
+    }
+    catch {
+        return null;
+    }
+    finally {
+        socket?.destroy();
+    }
+}
+let spawnAttempted = false;
+/**
+ * Fire-and-forget: start the daemon in the background for NEXT call. Never
+ * awaited by a tool call — the point is that today's call still completes
+ * at today's speed via the local fallback, and only a later call (this
+ * agent's or another's) benefits once the daemon is warm.
+ */
+export function ensureDaemonSpawned(root) {
+    // Once per process, not once per root: a second attempt for a root whose
+    // first daemon failed to start would just fail the same way again, and
+    // daemon.ts's own EADDRINUSE handling already makes a redundant spawn for
+    // a root that DOES have one running cheap and safe (see "a second daemon
+    // spawned for the same root exits quietly" in mcp-daemon.test.ts) — so
+    // there is no correctness reason to gate on `existsSync(pidFileFor(root))`
+    // first, and a real cost to doing so: a stale pidfile left by a daemon
+    // that crashed before cleaning up would make that check true forever,
+    // permanently skipping every future spawn attempt for this root.
+    if (!daemonEnabled() || spawnAttempted)
+        return;
+    spawnAttempted = true;
+    try {
+        const daemonScript = fileURLToPath(new URL("./daemon.js", import.meta.url));
+        const child = spawn(process.execPath, [daemonScript, root], {
+            detached: true,
+            stdio: "ignore",
+        });
+        child.unref();
+    }
+    catch {
+        /* best-effort — the in-process fallback covers this call and every call after it if spawning never works here */
+    }
+}

package/dist/mcp/daemon-protocol.js

@@ -0,0 +1,100 @@
+/**
+ * Wire contract between the MCP adapter and its optional local graph daemon.
+ *
+ * Deliberately tiny and framing-free beyond newline-delimited JSON: one
+ * request per line in, one response per line out, over a long-lived
+ * connection. Anything richer (length-prefixing, multiplexed request ids)
+ * is complexity this doesn't need yet — today's local graph tools are one
+ * request awaiting one response, never concurrent on one connection.
+ *
+ * Both `daemon.ts` (the server) and `daemon-client.ts` (the caller) import
+ * this rather than each defining their own copy, because two independently
+ * maintained copies of a socket path formula are how a client silently stops
+ * finding a daemon that is, in fact, running.
+ */
+import { createHash } from "node:crypto";
+import { realpathSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+/**
+ * NOT `os.tmpdir()` on POSIX, deliberately.
+ *
+ * `os.tmpdir()` reads `TMPDIR`, and the MCP SDK's `getDefaultEnvironment()`
+ * — what a host CLI hands a spawned stdio adapter when it does not pass its
+ * own full environment — inherits `HOME`/`LOGNAME`/`PATH`/`SHELL`/`TERM`/
+ * `USER` and nothing else; `TMPDIR` is not on that list. Two adapter
+ * processes for the same repo, launched by two different host CLIs (or the
+ * same CLI with and without a custom env), can then disagree on where
+ * `os.tmpdir()` even points — one at `/var/folders/.../T` from an inherited
+ * `TMPDIR`, the other falling back to `/tmp` because it never saw one. Two
+ * clients that cannot agree on a path can never find the same daemon, which
+ * defeats the one thing this module exists for. Found the hard way: a daemon
+ * spawned from inside an adapter process bound and ran correctly, just at a
+ * path the test (and every other real client) never thought to look.
+ *
+ * `/tmp` itself needs no environment variable on POSIX and is standard
+ * across macOS and Linux. Windows keeps `os.tmpdir()`, because `TEMP` (and
+ * `TMP`) ARE in `getDefaultEnvironment()`'s Windows list — this is a POSIX-
+ * specific gap, not a general one.
+ */
+function baseDir() {
+    return process.platform === "win32" ? tmpdir() : "/tmp";
+}
+/**
+ * Bumped whenever the request/response shape changes in a way an older peer
+ * cannot safely parse. A version mismatch is handled by the CLIENT refusing
+ * to use the daemon for that call (falling back to local computation) rather
+ * than the daemon attempting a live self-restart — see daemon.ts's module
+ * comment for why an in-place upgrade is out of scope for now.
+ */
+export const DAEMON_PROTOCOL_VERSION = 1;
+/**
+ * A stable, filesystem-safe name for this repo root's daemon socket (or, on
+ * the TCP fallback, the file that records which port it bound).
+ *
+ * Hashed rather than a sanitized path: two repos differing only in
+ * characters `net.createServer().listen(path)` treats specially, or a path
+ * long enough to exceed a Unix socket's ~104-byte limit, would otherwise
+ * collide or fail to bind for reasons that have nothing to do with two
+ * repos actually being the same one.
+ *
+ * Resolved through `realpathSync` before hashing, because "the same root"
+ * is not always spelled the same way by every caller. `repoRoot()`
+ * (agent-state.ts) shells out to `git rev-parse --show-toplevel`, which
+ * resolves symlinks — on macOS that turns `/var/folders/...` (what
+ * `os.tmpdir()` returns) into `/private/var/folders/...`. Two processes
+ * that agree on the actual directory but disagree on which of those two
+ * spellings names it would hash to two different sockets and never find
+ * each other — found via exactly that mismatch between a test's own
+ * `tmpdir()`-built fixture path and the real adapter's `repoRoot()`. A
+ * root that does not exist yet (or a transient FS error) falls back to
+ * hashing what was given rather than failing the caller over it.
+ */
+export function daemonInstanceId(root) {
+    let canonical = root;
+    try {
+        canonical = realpathSync(root);
+    }
+    catch {
+        /* root not on disk from this vantage point yet, or unreadable — hash the literal string rather than throw */
+    }
+    return createHash("sha256").update(canonical).digest("hex").slice(0, 16);
+}
+/**
+ * Unix domain socket path for this root. Not `/tmp/sync.sock` (a name
+ * shared across every repo and every user on the box) — one fixed path
+ * would make a second project's daemon either refuse to start or, worse,
+ * silently answer questions about the wrong checkout the moment the first
+ * daemon's socket happened to still exist.
+ */
+export function socketPathFor(root) {
+    return join(baseDir(), `keel-daemon-${daemonInstanceId(root)}.sock`);
+}
+/** Where the TCP fallback (used when the socket path can't be bound — see daemon.ts) records its port. */
+export function tcpPortFileFor(root) {
+    return join(baseDir(), `keel-daemon-${daemonInstanceId(root)}.port`);
+}
+/** The pidfile a running daemon maintains so a stale one can be told apart from a live one before connecting. */
+export function pidFileFor(root) {
+    return join(baseDir(), `keel-daemon-${daemonInstanceId(root)}.pid`);
+}

package/dist/mcp/escalation-waiter.js

@@ -0,0 +1,183 @@
+/**
+ * Keep an MCP tool call alive until a durable human escalation is resolved.
+ *
+ * SSE is the fast path. The coordinator's event stream is replayable, but a
+ * client still needs to reconnect when a proxy or server restarts. A small
+ * polling loop runs alongside it as a safety net: an approval must never be
+ * lost merely because the stream was unavailable at the instant it arrived.
+ */
+/** Parse complete SSE frames. The caller may retain an incomplete final frame. */
+export function parseSseFrames(input) {
+    const frames = [];
+    for (const block of input.replace(/\r\n/g, "\n").split("\n\n")) {
+        if (!block.trim() || block.trimStart().startsWith(":"))
+            continue;
+        let id;
+        let event;
+        const data = [];
+        for (const line of block.split("\n")) {
+            if (!line || line.startsWith(":"))
+                continue;
+            const separator = line.indexOf(":");
+            const field = separator < 0 ? line : line.slice(0, separator);
+            const value = separator < 0 ? "" : line.slice(separator + 1).replace(/^ /, "");
+            if (field === "id")
+                id = value;
+            else if (field === "event")
+                event = value;
+            else if (field === "data")
+                data.push(value);
+        }
+        if (data.length > 0 || event || id)
+            frames.push({ id, event, data: data.join("\n") });
+    }
+    return frames;
+}
+function resolved(record) {
+    return Boolean(record?.resolved_at && record.resolution);
+}
+function result(escalationId, record, status) {
+    const resolution = record?.resolution ?? null;
+    const applied = resolution?.applied ?? null;
+    return {
+        status,
+        escalation_id: escalationId,
+        record,
+        resolution,
+        chosen_option: resolution?.chosen_option ?? null,
+        effect: applied?.effect ?? null,
+        changes: applied?.changes ?? [],
+        resolved_by: record?.resolved_by ?? null,
+    };
+}
+function sleep(ms, signal) {
+    return new Promise((resolve) => {
+        if (signal.aborted)
+            return resolve();
+        const timer = setTimeout(resolve, ms);
+        signal.addEventListener("abort", () => {
+            clearTimeout(timer);
+            resolve();
+        }, { once: true });
+    });
+}
+async function listenToSse(options, signal) {
+    const fetchImpl = options.fetchImpl ?? fetch;
+    const url = `${options.server.replace(/\/+$/, "")}/events?project_id=${encodeURIComponent(options.projectId)}`;
+    const response = await fetchImpl(url, { headers: options.headers, signal });
+    if (!response.ok || !response.body)
+        throw new Error(`SSE connection failed: ${response.status}`);
+    const reader = response.body.getReader();
+    const decoder = new TextDecoder();
+    let pending = "";
+    try {
+        while (!signal.aborted) {
+            const read = await reader.read();
+            if (read.done)
+                break;
+            pending += decoder.decode(read.value, { stream: true });
+            const boundary = pending.lastIndexOf("\n\n");
+            if (boundary < 0)
+                continue;
+            const complete = pending.slice(0, boundary + 2);
+            pending = pending.slice(boundary + 2);
+            for (const frame of parseSseFrames(complete)) {
+                if (frame.event === "escalation.resolved") {
+                    try {
+                        const payload = JSON.parse(frame.data);
+                        if (payload.escalation_id === options.escalationId)
+                            return frame;
+                    }
+                    catch {
+                        // A malformed unrelated event must not kill the wait loop.
+                    }
+                }
+            }
+        }
+    }
+    finally {
+        reader.releaseLock();
+    }
+    return null;
+}
+async function streamLoop(options, signal, deadline) {
+    while (!signal.aborted && Date.now() < deadline) {
+        const attempt = new AbortController();
+        const relay = () => attempt.abort();
+        signal.addEventListener("abort", relay, { once: true });
+        const timer = setTimeout(() => attempt.abort(), Math.min(options.streamAttemptMs ?? 15_000, Math.max(1, deadline - Date.now())));
+        try {
+            const frame = await (options.connectSse
+                ? options.connectSse(attempt.signal)
+                : listenToSse(options, attempt.signal));
+            if (frame) {
+                const payload = JSON.parse(frame.data);
+                // The event is a wake-up, not the durable decision record. Some
+                // resolvers intentionally publish only id/resolver/effect/reason; if
+                // we synthesize a record from that abbreviated event, callers see a
+                // resolved escalation with a null chosen option and no applied
+                // changes even though the database contains both. Re-read after the
+                // event so the fast SSE path and the polling path return one shape.
+                const durable = (await options.fetchEscalations()).find((row) => row.id === options.escalationId);
+                if (resolved(durable))
+                    return durable;
+                // Retain compatibility with complete event producers. An abbreviated
+                // event falls through and reconnects/polls until the durable row is
+                // visible instead of claiming an incomplete resolution.
+                if (payload.chosen_option == null || payload.applied == null)
+                    continue;
+                return {
+                    id: payload.escalation_id,
+                    resolved_at: new Date().toISOString(),
+                    resolved_by: payload.resolved_by ?? null,
+                    resolution: {
+                        chosen_option: payload.chosen_option ?? null,
+                        applied: payload.applied ?? null,
+                    },
+                };
+            }
+        }
+        catch {
+            // Reconnect below. Polling remains active throughout this loop.
+        }
+        finally {
+            clearTimeout(timer);
+            signal.removeEventListener("abort", relay);
+        }
+        await sleep(Math.min(250, Math.max(1, deadline - Date.now())), signal);
+    }
+    return null;
+}
+async function pollLoop(options, signal, deadline) {
+    const interval = Math.max(100, options.pollIntervalMs ?? 5_000);
+    while (!signal.aborted && Date.now() < deadline) {
+        await sleep(Math.min(interval, Math.max(1, deadline - Date.now())), signal);
+        if (signal.aborted || Date.now() >= deadline)
+            break;
+        try {
+            const record = (await options.fetchEscalations()).find((row) => row.id === options.escalationId);
+            if (resolved(record))
+                return record ?? null;
+        }
+        catch {
+            // A transient coordinator error is why the deadline is bounded.
+        }
+    }
+    return null;
+}
+export async function waitForEscalation(options) {
+    const initial = (await options.fetchEscalations()).find((row) => row.id === options.escalationId);
+    if (resolved(initial))
+        return result(options.escalationId, initial, "resolved");
+    const deadline = Date.now() + Math.max(0, options.timeoutMs);
+    if (options.timeoutMs <= 0)
+        return result(options.escalationId, initial ?? null, "timeout");
+    const controller = new AbortController();
+    const winner = await Promise.race([
+        streamLoop(options, controller.signal, deadline),
+        pollLoop(options, controller.signal, deadline),
+    ]);
+    controller.abort();
+    const record = winner;
+    return record ? result(options.escalationId, record, "resolved") : result(options.escalationId, null, "timeout");
+}

package/dist/mcp/graph-ops.js

@@ -0,0 +1,169 @@
+/**
+ * Local graph tools' shared implementation: build the index once, then answer
+ * `sync_impact` / `sync_context_card` / `sync_retrieve` from it.
+ *
+ * Split out of `index.ts` so the exact same code runs two ways: in-process
+ * (today's behavior, one build per adapter process) and inside the optional
+ * daemon (`daemon.ts`, one build per repo root shared across every connected
+ * adapter). Neither path may diverge from the other — a daemon that answered
+ * `sync_impact` differently than the in-process fallback would be a silent
+ * correctness bug that only shows up when the daemon happens to be running.
+ * Keeping one implementation is what rules that out by construction.
+ *
+ * `buildLocalGraph` remains genuinely expensive (a full parse of the repo);
+ * the `run*` functions below are the cheap, per-call queries against its
+ * result and carry no I/O of their own beyond the optional skeleton read.
+ */
+import { readFileSync, mkdirSync } from "node:fs";
+import { join } from "node:path";
+import { retrievalModeFromEnv } from "../lib/index/pipeline.js";
+function envFlag(name, fallback) {
+    const value = process.env[name]?.trim().toLowerCase();
+    if (value === undefined)
+        return fallback;
+    return !["0", "false", "off", "no"].includes(value);
+}
+/** One index per (root), rebuilding per call would be absurd. Caller owns caching. */
+export async function buildLocalGraph(root) {
+    const [registryMod, parserMod, indexMod, graphMod, symbolsMod, incrementalMod, persistenceMod, vectorCacheMod, gitHistoryMod] = await Promise.all([
+        import("../lib/index/registry.js"),
+        import("../lib/index/typescript-parser.js"),
+        import("../lib/index/file-index.js"),
+        import("../lib/index/graph.js"),
+        import("../lib/index/symbols.js"),
+        import("../lib/index/incremental.js"),
+        import("../lib/index/persistence.js"),
+        import("../lib/index/vector-cache.js"),
+        import("../lib/index/git-history.js"),
+    ]);
+    const parser = await parserMod.loadTypeScriptParser();
+    if (!parser) {
+        throw new Error("local graph unavailable: no parser backend is installed. Add typescript to this " +
+            "checkout, or use blast_radius_preview, which falls back to textual matching.");
+    }
+    const registry = new registryMod.LanguageRegistry().register(parser);
+    let archive = null;
+    let vectorCache = null;
+    let keepArchiveOpen = false;
+    let indexed;
+    try {
+        mkdirSync(join(root, ".keel"), { recursive: true });
+        archive = new persistenceMod.IndexSnapshotArchive(join(root, ".keel", "index.sqlite"));
+        vectorCache = new vectorCacheMod.VectorCache(archive);
+        indexed = incrementalMod.loadOrUpdateFileIndex(root, registry, {
+            archive,
+            exclude: ["node_modules", "dist", "build", ".next", "coverage", "out"],
+        });
+    }
+    catch {
+        indexed = {
+            index: indexMod.buildFileIndex(root, registry, {
+                exclude: ["node_modules", "dist", "build", ".next", "coverage", "out"],
+            }),
+            freshness: {
+                indexed_commit: null,
+                index_age: null,
+                staleness_warning: "Persistent local index unavailable; used a fresh in-memory build.",
+            },
+        };
+    }
+    try {
+        const { index, freshness } = indexed;
+        const graph = graphMod.buildDependencyGraph(index);
+        const calls = symbolsMod.resolveCallEdges(index, symbolsMod.buildSymbolTable(index));
+        const coverageMod = await import("../lib/index/coverage.js");
+        const coverage = coverageMod.buildCoverageFacts(index, graph, calls);
+        try {
+            archive?.putCoverage(index.fingerprint, coverage);
+        }
+        catch {
+            /* cache unavailable; the facts are still correct in memory */
+        }
+        const retrievalMode = retrievalModeFromEnv();
+        let coChangeIndex;
+        if (retrievalMode !== "stable") {
+            try {
+                coChangeIndex = gitHistoryMod.buildCoChangeIndex(root, new Set(index.files.map((file) => file.path)), { before: "HEAD" });
+            }
+            catch {
+                coChangeIndex = undefined;
+            }
+        }
+        keepArchiveOpen = vectorCache !== null;
+        return { root, index, graph, calls, coverage, freshness, vectorCache, coChangeIndex, retrievalMode };
+    }
+    finally {
+        if (!keepArchiveOpen) {
+            vectorCache?.dispose();
+            archive?.shutdown();
+        }
+    }
+}
+export async function runImpact(local, args) {
+    const { graph, calls, index, coverage, freshness } = local;
+    const impactMod = await import("../lib/index/impact.js");
+    const impact = impactMod.computeImpact(graph, calls, args.paths, {
+        maxDistance: args.max_distance,
+        coverage,
+    });
+    return {
+        declared: args.paths,
+        affected: impact.added,
+        reasons: impactMod.explainImpact(impact),
+        complete: impact.complete,
+        caveats: impact.caveats,
+        coverage: index.coverage,
+        blind_spots: impact.coverage,
+        ...freshness,
+    };
+}
+export async function runContextCard(local, args) {
+    const { index, graph, calls, freshness, root } = local;
+    const cardMod = await import("../lib/index/context-card.js");
+    const card = cardMod.buildContextCard(index, graph, calls, args.path, {
+        maxCallers: args.max_callers,
+        ...(args.include_skeleton
+            ? { readFile: (p) => readFileSync(join(root, p), "utf8") }
+            : {}),
+    });
+    if (!card) {
+        return {
+            error: `${args.path} is not in the local index`,
+            hint: "Check the path is repo-root-relative and that the file is tracked by git.",
+            ...freshness,
+        };
+    }
+    const { localOnly: _localOnly, ...transportable } = card;
+    return { ...transportable, ...freshness };
+}
+export async function runRetrieve(local, args) {
+    const { root, index, freshness, vectorCache, coChangeIndex, retrievalMode } = local;
+    const { retrieve } = await import("../lib/index/pipeline.js");
+    const { generatePages } = await import("../lib/index/pages.js");
+    const { vocabularyWeightFromEnv } = await import("../lib/index/lexical.js");
+    const query = [args.question, args.refinement].filter(Boolean).join("\n\n");
+    const answer = await retrieve(generatePages(index), query, {
+        limit: args.limit,
+        offset: args.offset,
+        excludePaths: new Set(args.exclude_paths ?? []),
+        symbolIndex: index,
+        leasedPaths: new Set(args.leasedPaths ?? []),
+        vectorCache: vectorCache ?? undefined,
+        retrievalMode,
+        lexicalVocabularyWeight: vocabularyWeightFromEnv(),
+        queryRouting: retrievalMode !== "stable" && envFlag("KEEL_RETRIEVAL_ROUTING", false),
+        coChangeIndex,
+        ...(retrievalMode !== "stable" && envFlag("KEEL_RETRIEVAL_VERIFY", false) ? { verify: { root } } : {}),
+    });
+    return {
+        ...answer,
+        retrieval_mode: retrievalMode,
+        ...freshness,
+        results: answer.results.map(({ page, ...result }) => ({
+            path: page.target_path,
+            page_type: page.page_type,
+            quote: page.content,
+            ...result,
+        })),
+    };
+}