@descryy/mcp 0.11.5 → 0.11.6

package/dist/server.js

@@ -0,0 +1,642 @@
+/**
+ * The MCP server: handshake, tool listing, tool calls, streaming narration.
+ *
+ * ## The layering that makes this testable without a pipe
+ *
+ * `dispatch` takes a line of text and a `send`, and that is the whole surface.
+ * The stdio transport is a loop around it; a test is a call to it. So the
+ * handshake, the error frames and the progress notifications are all covered by
+ * ordinary unit tests rather than by spawning a process and hoping.
+ *
+ * ## Streaming narration — §22.2's primary UX, at the protocol level
+ *
+ * A developer asking a question in their editor and watching the work happen is
+ * the most-used delivery path in the architecture. MCP's mechanism is
+ * `notifications/progress`, sent only when the request carried a
+ * `_meta.progressToken`. Tools call `ctx.progress(...)` unconditionally and this
+ * layer decides whether anyone is listening — the alternative, tools checking
+ * first, is how narration ends up in some code paths and not others.
+ *
+ * ## Every tool failure is a *tool* result, not a protocol error
+ *
+ * The spec is explicit and the reason is practical: a JSON-RPC error is for a
+ * malformed request, and an agent that receives one has nothing to reason about.
+ * A bad argument, a missing graph, an unreadable repository — those come back as
+ * content with `isError`, which the model can read and act on. Only genuinely
+ * broken protocol produces an error frame.
+ */
+import { randomUUID } from "node:crypto";
+import { resolveActionDispatch } from "./action-handshake.js";
+import { TOOL_ALIASES } from "./tools/aliases.js";
+import { fail, isRequest, negotiateVersion, ok, parseMessage, ProtocolError, RPC_INTERNAL_ERROR, RPC_INVALID_PARAMS, RPC_METHOD_NOT_FOUND, } from "./protocol.js";
+import { renderAnswer, renderFailed, renderHandshake, renderRefusedInput, renderTimedOut, renderToolError, TOOL_OUTPUT_SCHEMA, } from "./render.js";
+import { createDisclosureLedger } from "./disclosure-ledger.js";
+import { AUTO_REFRESH_BUDGET_MS, checkConfigDrift, checkFreshness, ConfigError } from "./session.js";
+import { TOOLS, TOOLS_BY_NAME, ToolInputError, } from "./tools/index.js";
+import { analyzeTool } from "./tools/analyze.js";
+/** Every call's declared budget (§6). Fixed today; per-trigger budgets are P26/P28 work. */
+const CALL_BUDGET_MS = 15 * 60 * 1000;
+function isAbort(error) {
+    return ((error instanceof Error && error.name === "AbortError") ||
+        (typeof DOMException !== "undefined" && error instanceof DOMException && error.name === "TimeoutError"));
+}
+/**
+ * The stored graph's stamp, for a caller that has no `result` to read it from
+ * — a refusal, a failure, a timeout, or a handshake mint (F3, UAT Phase 5).
+ *
+ * Read defensively, never folded into `renderOptions()` unconditionally: a
+ * graph in a state `baseStamp()` cannot read (a stale schema version, MK-4)
+ * must not turn a graceful refusal into a thrown error. `try`/`catch` to
+ * `undefined` here, exactly as `renderHandshake`'s call site already did
+ * before this helper existed, so `renderRefusedInput`/`renderFailed`/
+ * `renderTimedOut` can stop hardcoding "no graph" regardless of what is
+ * actually stored, without reopening that already-reverted failure mode.
+ */
+function readGraphStampSafely(session) {
+    try {
+        return session.provider().baseStamp();
+    }
+    catch {
+        return undefined;
+    }
+}
+const NO_FRESHNESS_OUTCOME = { freshness: undefined, autoNotes: [] };
+function elapsedSeconds(startedAt) {
+    return ((Date.now() - startedAt) / 1000).toFixed(1);
+}
+/**
+ * Lane "map-freshness" items 1-3, run once per call, ahead of `tool.run` —
+ * the one shared place this happens, rather than 29 separate tools each
+ * growing their own copy (the lane's own instruction). Builds the graph when
+ * it is empty, refreshes it (within a budget) when it is `behind`, and
+ * either way reads the freshness this call should report.
+ *
+ * Skipped entirely for `workspace`: its `analyze`/`index` verbs already are
+ * the build/refresh mechanism (so running this ahead of them would be a
+ * second, redundant build) and `link` only declares repositories. The retired
+ * `analyze`/`analyze_workspace` names are aliases that resolve to `workspace`
+ * before this runs, so they are covered by the same check. `analyzeTool` is
+ * imported directly: it is not registered in `TOOLS_BY_NAME` under its own
+ * name any more, so a by-name lookup finds nothing.
+ *
+ * Never throws: an auto-build/refresh that fails (a `ConfigError` needing
+ * input this call can't default, an aborted refresh, anything else) is
+ * caught and treated as "did not run" — the real tool call proceeds exactly
+ * as it would have if this had never been attempted, per the lane's own
+ * "keep today's named refusal" instruction. An empty graph that stays empty
+ * after a failed auto-build still reports `freshness: null` (never `unknown`
+ * or a fabricated `current`) via `freshnessField` in `render.ts`, from the
+ * real `commitSha` this function reads again after the attempt.
+ */
+async function ensureFreshGraph(session, tool, ctx) {
+    if (tool.name === "workspace")
+        return NO_FRESHNESS_OUTCOME;
+    let stamp;
+    try {
+        stamp = session.provider().baseStamp();
+    }
+    catch {
+        return NO_FRESHNESS_OUTCOME;
+    }
+    // Item 2: an empty graph is built with defaults before this call answers.
+    // `analyzeTool.run` already calls `ctx.progress(...)` as it works, so
+    // reusing this call's real `ctx` (rather than a stand-in) is what "sends
+    // progress notifications" means here — nothing extra to wire.
+    if (stamp.commitSha === null) {
+        const startedAt = Date.now();
+        try {
+            await analyzeTool.run({}, ctx);
+        }
+        catch {
+            // Needs input `analyze`'s own defaults can't supply (not a git
+            // repository, for instance) — leave the graph empty and let the real
+            // tool call's own "graph is empty" refusal stand, unchanged.
+        }
+        const rebuilt = readGraphStampSafely(session);
+        if (rebuilt === undefined || rebuilt.commitSha === null)
+            return NO_FRESHNESS_OUTCOME;
+        return {
+            freshness: await checkFreshness(session),
+            autoNotes: [`Code map built automatically for this answer (took ${elapsedSeconds(startedAt)}s).`],
+        };
+    }
+    const freshness = await checkFreshness(session);
+    if (freshness === undefined || freshness.status !== "behind")
+        return { freshness, autoNotes: [] };
+    // Item 3: refresh within a budget. `AbortSignal.any` combines the caller's
+    // signal with a timeout for this attempt, and `analyze` hands it to every
+    // source's `prepare()`. That is the whole reach of the budget: a source
+    // that checks the signal abandons the refresh, one that does not (git
+    // history does not) runs to completion, so the budget bounds a slow
+    // adapter, not the refresh as a whole. It is not raced against a timer:
+    // an abandoned refresh left running would write the graph while the real
+    // tool reads it. A budget of 0 or less skips the refresh outright.
+    const budgetMs = session.autoRefreshBudgetMs ?? AUTO_REFRESH_BUDGET_MS;
+    if (budgetMs <= 0)
+        return { freshness, autoNotes: [] };
+    const refreshCtx = { ...ctx, signal: AbortSignal.any([ctx.signal, AbortSignal.timeout(budgetMs)]) };
+    const startedAt = Date.now();
+    try {
+        await analyzeTool.run({}, refreshCtx);
+    }
+    catch {
+        // Timed out, or failed outright — answer from the graph as it stood
+        // before this attempt. `freshness` (still `behind`) already carries its
+        // own disclosure downstream (`freshnessDisclosure` in `render.ts`), so
+        // the caller learns the map is stale even though the refresh did not run.
+        return { freshness, autoNotes: [] };
+    }
+    return {
+        freshness: await checkFreshness(session),
+        autoNotes: [`Code map refreshed automatically for this answer (took ${elapsedSeconds(startedAt)}s).`],
+    };
+}
+/** A schema's own declared top-level argument names — empty when it has none, or when the
+ *  schema isn't the `{ properties: {...} }` shape every tool's `inputSchema` actually is. */
+function declaredTopLevelProperties(schema) {
+    const props = schema["properties"];
+    return typeof props === "object" && props !== null ? Object.keys(props) : [];
+}
+/** UAT phase 5, F12: which top-level keys in `args` this schema does not declare. Only meaningful
+ *  when the schema opts into `additionalProperties: false` — the promise every tool's `SCHEMA`
+ *  already makes (asserted across the registry by `tool-input-schema-gate.test.ts`) and that
+ *  nothing enforced before this check existed. Shape only: whether a key exists, never what it
+ *  means — a tool's own `requiredString`/`optionalEnum`/etc. still reads and validates the value. */
+function unknownArgumentKeys(schema, args) {
+    if (schema["additionalProperties"] !== false)
+        return [];
+    const known = new Set(declaredTopLevelProperties(schema));
+    return Object.keys(args).filter((key) => !known.has(key));
+}
+/**
+ * Does this frame have to jump the transport's ordering queue?
+ *
+ * True for `notifications/cancelled` and nothing else. Exported because the
+ * stdio runner needs the answer and the knowledge of what MCP methods mean
+ * belongs here, not in a module that otherwise only knows about bytes. Never
+ * throws — a line that will not parse is the dispatcher's to reject, with the
+ * error frame it already knows how to build.
+ */
+export function isOutOfBand(line) {
+    try {
+        const message = JSON.parse(line);
+        if (typeof message !== "object" || message === null || Array.isArray(message))
+            return false;
+        const frame = message;
+        // A *request* named `notifications/cancelled` is malformed, not a
+        // cancellation. Letting it jump the queue would answer it out of order,
+        // which is the exact hazard the ordering exists to prevent.
+        return frame["method"] === "notifications/cancelled" && frame["id"] === undefined;
+    }
+    catch {
+        return false;
+    }
+}
+const SERVER_INSTRUCTIONS = "Descry reads the repository's source into a code graph and answers questions about it. A " +
+    "graph-reading tool builds the graph itself the first time it finds one empty, and refreshes " +
+    "it when it is behind the code — both disclosed in the reply. Call `workspace` yourself only " +
+    "to control timing directly (`{verb: \"analyze\"}` to force a rebuild now, `{verb: \"link\"}` " +
+    "to declare a shared workspace).\n\n" +
+    "Every reply has a `state`, one of five, and they are different claims: `ok` (found " +
+    "something), `empty` (looked completely, found nothing — a fact about your code), `refused` " +
+    "(could not look — a fact about Descry, never about your code), `failed` (something broke) " +
+    "and `timed_out` (ran out of its time budget, partial answer). Never read `refused` as " +
+    "\"clean\" or `empty` as \"broken\".\n\n" +
+    "One case is not an answer at all and has its own shape: a call naming no tool this server " +
+    "has comes back with `isError: true` and `{ tool, status: \"error\", message }`, carrying no " +
+    "`state`. A *resolved* tool given bad input instead comes back as a real `state: \"refused\"` " +
+    "reply, with `disclosures` naming what was wrong. Branch on `isError` before reading " +
+    "`state`.\n\n" +
+    "Every reply also carries a `disclosures` list, a `resolutionFloor` and a `reliabilityCap` " +
+    "(A, B or C) inside `graph`. `resolutionFloor` is the weakest resolution behind the answer, " +
+    "R0 through R4: R0 is syntax only; R1 adds module/import resolution; R2 adds cross-file " +
+    "reference resolution (which symbol a name refers to, no type checker); R3 adds a type " +
+    "checker, so claims about shapes are provable; R4 means the fact was observed at runtime " +
+    "rather than inferred. `reliabilityCap` is what that floor permits: C means the claim is an " +
+    "unconfirmed behavioural prediction. B means the claim rests on structural or reference " +
+    "resolution — a name, an import, a call target — real evidence, not yet confirmed behaviour. " +
+    "A means the claim is as strong as this graph can make it: a name-level fact at R2 or better, " +
+    "a shape-level fact backed by a type checker (R3), or anything witnessed at runtime (R4). " +
+    "Read the disclosures before summarising — they say what the answer does not cover.\n\n" +
+    "Coverage is separate from confidence: call `disclosure` with `{verb: \"coverage\", refs: " +
+    "[...]}` and node ids or file paths from an earlier reply to learn which of them the graph " +
+    "actually reached, rather than assuming silence means untested. `disclosure`'s " +
+    "`{verb: \"unresolved\"}` gives the graph's full ledger of things an adapter could not " +
+    "resolve — call with no `handle` for a one-line summary and a handle, then again with that " +
+    "handle to page through every row.\n\n" +
+    "`class` on each tool (`read`, `stateful-read` or `action`) says whether it is safe to retry. " +
+    "Some `action`-class tools gate a write behind a two-call handshake: the first call performs " +
+    "nothing and returns a `confirmToken` describing what it would do; a second call presenting " +
+    "that exact token performs the write, with the arguments frozen at the first call — a changed " +
+    "argument on the second call is discarded and disclosed.\n\n" +
+    "`tier` on each tool is `conclusion` for the tools that already state a verdict about your " +
+    "code (`validate`, `contracts`, `cross_pr` — quote their `headline` verbatim rather than " +
+    "rephrasing it) or `evidence` for every other tool, which returns graph facts for you to " +
+    "reason over yourself. Every reply also carries `reportCategory` — one of `confirmed`, " +
+    "`strongly supported`, `unconfirmed`, `not analysable`, `unsupported`, or `null` where no " +
+    "claim applies. It is `null` on every `conclusion`-tier reply (the `headline` already states " +
+    "the verdict). On an `evidence`-tier reply it follows that reply's own `resolutionFloor`: " +
+    "`unconfirmed` below R4, and `strongly supported` at R4, where every hop behind the answer " +
+    "was witnessed in a real run — `observe`'s `runtime`/`tests` verbs and the browser tools are " +
+    "what write those edges. `confirmed` never appears here — that word is reserved for results " +
+    "that passed the full governance pipeline, and its absence is honest, not a bug.\n\n" +
+    "Beside it, `existenceCategory` answers a different question. `reportCategory` says how " +
+    "strongly the cause may be stated, capped by how well the code resolved; `existenceCategory` " +
+    "says how strongly the evidence shows the failure is real, never reading the resolution at " +
+    "all. A reply that witnessed a failure on several channels but resolved no code path reports " +
+    "`unconfirmed` for the cause and `strongly supported` for the failure — read that as " +
+    "*something is wrong and we could not tell you where*, not as *nothing is wrong*. It is " +
+    "`null` wherever no evidence reading was taken: conclusion-tier replies, faults, and " +
+    "refusals. `provenance` names this surface explicitly (`adjudicatedBy: \"descry\"`, " +
+    "`presentedBy: \"host-agent\"`) so a reply from here is never mistaken for one the app itself " +
+    "adjudicated and presented.\n\n" +
+    "In agent mode, Descry gives you high-reliability facts about your code. It does not give " +
+    "you confirmed behaviour, because it did not run your application — at any resolution level, " +
+    "however careful the static analysis was. `confirmed` and `strongly supported` are the " +
+    "desktop app's differentiator, not this surface's; treat every reply here as a strong lead to " +
+    "verify, never as a closed case.\n\n" +
+    "Descry cannot enforce any of this once you leave this server: nothing stops you from adding " +
+    "your own claims on top of what a tool returned, and nothing stops you from investigating " +
+    "paths no tool surfaced or suggested. The fields above exist so you do not have to guess.";
+export function createMcpServer(options) {
+    const session = options.session;
+    const serverName = options.name ?? "descry";
+    const serverVersion = options.version ?? "0.0.0";
+    // One per connection, living exactly as long as this server — see
+    // `disclosure-ledger.ts` for why it is not shared across connections.
+    const disclosureLedger = createDisclosureLedger();
+    let initialized = false;
+    const tools = options.tools ?? TOOLS;
+    const toolsByName = options.tools === undefined
+        ? TOOLS_BY_NAME
+        : new Map(options.tools.map((tool) => [tool.name, tool]));
+    /**
+     * In-flight `tools/call`s, by request id, so `notifications/cancelled` has
+     * something to act on. Entries live exactly as long as the call: added
+     * before `tool.run`, removed in the `finally` that also drops the call's
+     * progress tick.
+     */
+    const pending = new Map();
+    async function handleRequest(request, transport) {
+        const { id, method } = request;
+        const params = request.params ?? {};
+        switch (method) {
+            case "initialize": {
+                transport.send(ok(id, {
+                    protocolVersion: negotiateVersion(params["protocolVersion"]),
+                    // `listChanged: false` is honest: the tool set is fixed at startup,
+                    // so the server will never send a list-changed notification and
+                    // should not claim it might.
+                    capabilities: { tools: { listChanged: false } },
+                    serverInfo: { name: serverName, version: serverVersion },
+                    instructions: SERVER_INSTRUCTIONS,
+                }));
+                return;
+            }
+            case "ping": {
+                transport.send(ok(id, {}));
+                return;
+            }
+            case "tools/list": {
+                transport.send(ok(id, {
+                    tools: tools.map((tool) => ({
+                        name: tool.name,
+                        title: tool.title,
+                        description: tool.description,
+                        inputSchema: tool.inputSchema,
+                        // ai-tool-contract.md §8: every endpoint declares a class, and an
+                        // external client has no other way to read it — §6's retry table
+                        // (read=retryable, stateful-read=idempotent-retryable,
+                        // action=no-retry+handshake-required) is meaningless without this
+                        // on the wire.
+                        class: tool.class,
+                        // MK-5: whether this tool's output is a conclusion about the
+                        // user's code or a fact about the graph — same "no other way to
+                        // read it" reasoning as `class`, one line up.
+                        tier: tool.tier,
+                        toolVersion: tool.version,
+                        // Every reply this server sends carries a `structuredContent`
+                        // envelope, and without this a host has no way to validate one.
+                        // Shared across all tools because the envelope is: see
+                        // `TOOL_OUTPUT_SCHEMA`, including why `data` is left open.
+                        outputSchema: TOOL_OUTPUT_SCHEMA,
+                    })),
+                }));
+                return;
+            }
+            case "tools/call": {
+                const result = await callTool(id, params, transport);
+                // `null` means the call was cancelled while it ran. MCP forbids a
+                // response to a cancelled request, so the only correct frame here is
+                // no frame at all.
+                if (result !== null)
+                    transport.send(ok(id, result));
+                return;
+            }
+            default:
+                transport.send(fail(id, RPC_METHOD_NOT_FOUND, `unknown method: ${method}`));
+        }
+    }
+    async function callTool(id, params, transport) {
+        const name = params["name"];
+        if (typeof name !== "string") {
+            return renderToolError("tools/call", '"name" must be a string');
+        }
+        // A retired name is resolved here and nowhere else: `tools/list` never
+        // offered it (see `tools/aliases.ts`), so only a caller holding an old
+        // name in a config or a script can arrive with one. `aliasedTo` is
+        // threaded into `renderOptions` so the reply says which name answered.
+        const direct = toolsByName.get(name);
+        const alias = direct === undefined ? TOOL_ALIASES.get(name) : undefined;
+        const tool = direct ?? (alias === undefined ? undefined : toolsByName.get(alias.to));
+        if (tool === undefined) {
+            return renderToolError(name, `no such tool. Available: ${tools.map((t) => t.name).join(", ")}.`);
+        }
+        // `tool` is resolved from here on, so any input failure below has a real
+        // `ToolDefinition` to render a `state: "refused"` envelope from
+        // (`renderRefusedInput`) rather than `renderToolError`'s bare shape —
+        // minted here, ahead of the args check, so both that check and a
+        // `ToolInputError` thrown later out of `tool.run` share the one
+        // `renderOptions()`. Same precedent as B10's `callId`: a call that never
+        // reaches `tool.run` still gets one minted (`renderFailed`/`renderTimedOut`
+        // already do this for every call but `verify_claim`), and is never passed
+        // to `session.recordCallWithId` below, so no gap opens in what a citation
+        // can resolve.
+        const started = Date.now();
+        const callId = name === "verify_claim" ? randomUUID() : session.allocateCallId();
+        // 13.3.16 (N2) steps 2-3: checked once per call, ahead of dispatch, so every
+        // reply this call produces — ok, refused, failed or timed out — carries the
+        // same disclosure and the same `configStale` flag, not only `analyze`'s.
+        const configDrift = await checkConfigDrift(session);
+        // Lane "map-freshness": set for real just before `tool.run` (once `ctx`
+        // exists), by `ensureFreshGraph`. Declared here, ahead of every early
+        // `renderOptions()` call below (an `"arguments"`-shape refusal, an
+        // unknown-argument refusal), so those calls see the same
+        // `NO_FRESHNESS_OUTCOME` default `configDrift` above already reads —
+        // never a "used before declaration" on a call site that runs before
+        // `ctx` does.
+        let freshnessOutcome = NO_FRESHNESS_OUTCOME;
+        const renderOptions = () => ({
+            toolVersion: tool.version,
+            toolClass: tool.class,
+            toolTier: tool.tier,
+            elapsedMs: Date.now() - started,
+            limitMs: CALL_BUDGET_MS,
+            disclosureLedger,
+            callId,
+            configDrift,
+            ...(freshnessOutcome.freshness === undefined ? {} : { freshness: freshnessOutcome.freshness }),
+            ...(freshnessOutcome.autoNotes.length === 0 ? {} : { autoNotes: freshnessOutcome.autoNotes }),
+            ...(alias === undefined ? {} : { aliasedFrom: name, aliasedTo: tool.name }),
+        });
+        const rawArgs = params["arguments"];
+        if (rawArgs !== undefined && (typeof rawArgs !== "object" || rawArgs === null || Array.isArray(rawArgs))) {
+            const graphStamp = readGraphStampSafely(session);
+            return renderRefusedInput(name, '"arguments" must be an object', {
+                ...renderOptions(),
+                ...(graphStamp === undefined ? {} : { graphStamp }),
+            });
+        }
+        const rewritten = (rawArgs ?? {});
+        // The old call shape becomes the new one before any gate reads it, so the
+        // schema check below is run against the tool that will actually answer.
+        const args = alias?.args === undefined ? rewritten : alias.args(rewritten);
+        // UAT phase 5, F12: `inputSchema` is advertised in `tools/list` and never read
+        // again — every tool hand-reads the keys it knows, so an unknown argument was
+        // silently ignored rather than refused (`contracts({ symbol: ... })` returning
+        // the whole-repo report; `browser_start_session({ profile: ... })` issuing the
+        // wrong consent because the tool reads `environment`). Checked here, once, for
+        // every tool that declares `additionalProperties: false` — which is all of
+        // them (asserted by tool-input-schema-gate.test.ts) — before dispatch, so a
+        // typo'd or misremembered key refuses loudly instead of vanishing. This is
+        // shape only: which keys exist, not what they mean — each tool's own
+        // `requiredString`/`optionalEnum`/etc. still checks that.
+        const unknownArgs = unknownArgumentKeys(tool.inputSchema, args);
+        if (unknownArgs.length > 0) {
+            const known = declaredTopLevelProperties(tool.inputSchema);
+            return renderRefusedInput(name, `unknown argument(s): ${unknownArgs.map((k) => `"${k}"`).join(", ")}. ` +
+                (known.length > 0 ? `${name} accepts: ${known.join(", ")}.` : `${name} takes no arguments.`), renderOptions());
+        }
+        const meta = params["_meta"];
+        const token = typeof meta === "object" && meta !== null
+            ? meta["progressToken"]
+            : undefined;
+        const progress = typeof token === "string" || typeof token === "number"
+            ? (message, current, total) => {
+                transport.send({
+                    jsonrpc: "2.0",
+                    method: "notifications/progress",
+                    params: {
+                        progressToken: token,
+                        // `progress` is required by the spec and must increase. When a
+                        // tool narrates without a count, the message is the payload and
+                        // the number is a monotonic tick rather than a fake percentage.
+                        progress: current ?? nextTick(id),
+                        ...(total === undefined ? {} : { total }),
+                        message,
+                    },
+                });
+            }
+            : () => { };
+        // Two ways a call ends early, composed into the one signal the tool sees:
+        // its own budget running out, and the client asking for it to stop.
+        //
+        // **What this does and does not buy.** Aborting here stops the *server*
+        // waiting and suppresses the response the client is no longer listening
+        // for, which is the protocol's requirement and is met. It stops the actual
+        // work only in a tool that reads the signal it is handed, and today that is
+        // exactly one of thirty-three — `analyze`, which passes `ctx.signal` down. The
+        // other thirty-two, `browser_run_scenario` and `observe_runtime` among
+        // them, take the signal and never look at it, so a cancelled call there
+        // leaves a real browser or a real application process running until it
+        // finishes on its own. That is a disclosed gap, filed as
+        // `DEC-NEXT-cancellation-reaches-one-tool-in-thirty.md`, not something this
+        // layer can fix from here — threading the signal is each tool's own work.
+        const controller = new AbortController();
+        pending.set(id, controller);
+        const ctx = {
+            session,
+            progress,
+            signal: AbortSignal.any([controller.signal, AbortSignal.timeout(CALL_BUDGET_MS)]),
+        };
+        // B10: `started`/`callId`/`renderOptions` are minted above, ahead of the
+        // `arguments` shape check, so every envelope this call can produce
+        // (refused, handshake, failed, timed-out, or a real answer) carries the
+        // exact id `recordCallWithId` will file the record under below — a
+        // caller reading `callId` off the reply and citing it in `verify_claim`
+        // is citing the id that call is actually recorded as.
+        //
+        // `verify_claim` itself is the one exception, on the same reasoning as
+        // its exclusion from recording just below: it produces no fact for a
+        // later claim to cite, so its own `callId` is not drawn from the
+        // session's call-id sequence at all — `session.allocateCallId()` is
+        // reserved for calls that will actually be recorded under the id it
+        // returns. Reusing it here would consume a real id `verify_claim` never
+        // gets recorded under, opening a gap in the sequence a caller relies on
+        // corresponding exactly to recorded calls.
+        try {
+            // §7's two-call handshake. Decided before any real work starts — a mint
+            // has no I/O to time out on — so this sits outside the try/catch's
+            // failure/timeout handling below, which is for `tool.run` alone.
+            const dispatch = await resolveActionDispatch(tool, args, ctx);
+            if (dispatch.kind === "handshake") {
+                // A handshake mint has done no I/O yet, so falling back to "no stamp
+                // known" on a read failure is exactly `renderHandshake`'s original,
+                // already-correct behaviour, not a new silent failure — see
+                // `readGraphStampSafely`'s own doc for why this is never folded into
+                // `renderOptions()` unconditionally.
+                const graphStamp = readGraphStampSafely(session);
+                return renderHandshake(name, dispatch.token, dispatch.willDo, {
+                    ...renderOptions(),
+                    ...(graphStamp === undefined ? {} : { graphStamp }),
+                });
+            }
+            // Lane "map-freshness" items 1-3: build an empty graph, refresh a
+            // `behind` one within budget, and read the freshness this call should
+            // report — once, here, ahead of the real work, not inside `tool.run`
+            // itself. After the handshake check (a mint does no I/O, so nothing to
+            // ensure yet) and before `tool.run` (which is what needs a fresh graph
+            // to answer from).
+            freshnessOutcome = await ensureFreshGraph(session, tool, ctx);
+            const outcome = await tool.run(dispatch.args, ctx);
+            // Cancelled while it was running, and it finished anyway — the client
+            // stopped listening for this id, so the answer is dropped rather than
+            // sent late. Not recorded on the session either: a fact the caller never
+            // received must not become one a later `verify_claim` can cite.
+            if (controller.signal.aborted)
+                return null;
+            // Re-checked here, not reused from the `configDrift` captured before
+            // dispatch: `tool.run` is the one place `session.reloadConfig()` can be
+            // called (§0 gap 2's `analyze({ reload: true })`), and a call that just
+            // reloaded must not still report itself as stale — the drift it would
+            // be reporting no longer exists by the time this line runs.
+            const rendered = renderAnswer(name, outcome, {
+                ...renderOptions(),
+                configDrift: await checkConfigDrift(session),
+                // Rule 7 on the redemption path: the handshake decided which arguments ran, so it is the
+                // only thing that knows which of the caller's were dropped. Omitted entirely when nothing
+                // was, so a correct two-call redemption reads exactly as it did before.
+                ...(dispatch.discardedArgs === undefined ? {} : { discardedArgs: dispatch.discardedArgs }),
+            });
+            // MK-12: recorded after rendering, from the exact structuredContent the
+            // host receives — not the pre-render outcome, which the host never
+            // sees. `verify_claim` itself is excluded: it produces no fact for a
+            // later claim to cite, only a verdict about other calls' facts.
+            //
+            // Recorded under `callId` — the same id `rendered.structuredContent`
+            // already carries as `callId` — rather than a freshly minted one
+            // (B10): the two must be the same value for a citation read off this
+            // reply to resolve.
+            if (name !== "verify_claim") {
+                // B1: a tool that can be handed a credential says how it wants to be
+                // remembered (`ToolDefinition.redactArgs`). Every other tool is
+                // recorded exactly as it was called, as before.
+                session.recordCallWithId(callId, name, tool.redactArgs === undefined ? args : tool.redactArgs(args), rendered.structuredContent);
+            }
+            return rendered;
+        }
+        catch (error) {
+            // Cancellation is checked before anything else, including
+            // `ToolInputError`: whatever the tool threw on its way out, the client
+            // has told us it is not listening, and the spec is explicit that a
+            // cancelled request gets no response at all.
+            if (controller.signal.aborted)
+                return null;
+            const graphStamp = readGraphStampSafely(session);
+            const optionsWithStamp = () => ({
+                ...renderOptions(),
+                ...(graphStamp === undefined ? {} : { graphStamp }),
+            });
+            if (error instanceof ToolInputError)
+                return renderRefusedInput(name, error.message, optionsWithStamp());
+            if (isAbort(error) || ctx.signal.aborted)
+                return renderTimedOut(name, optionsWithStamp());
+            // Anything else is a bug or an environment failure. It still comes back as
+            // a tool result: an agent can retry or tell the user, whereas a protocol
+            // error just ends the call with nothing it can use.
+            const failureMessage = error instanceof Error ? error.message : String(error);
+            // 13.3.5 Half A: a `ConfigError` is thrown with a full written reason
+            // specifically so a caller can read it — giving it the generic
+            // "X failed." headline and burying that reason in `disclosures` says
+            // less than the error already said. An unexplained fault keeps the
+            // opaque default `renderFailed` falls back to.
+            return renderFailed(name, failureMessage, optionsWithStamp(), error instanceof ConfigError ? `${name} could not run: ${failureMessage}` : undefined);
+        }
+        finally {
+            pending.delete(id);
+        }
+    }
+    /**
+     * Act on `notifications/cancelled`: abort the named call if it is still ours
+     * and still running.
+     *
+     * Silence in every other case is deliberate and is what the spec asks for. A
+     * cancellation racing a call that has already returned is ordinary client
+     * behaviour, not an error — the client sent it before our response reached
+     * it — and a notification cannot be answered anyway, so there is nowhere to
+     * report a bad `requestId` even if one were worth reporting.
+     */
+    function cancel(params) {
+        const requestId = params["requestId"];
+        if (typeof requestId !== "string" && typeof requestId !== "number")
+            return;
+        const controller = pending.get(requestId);
+        if (controller === undefined)
+            return;
+        const reason = params["reason"];
+        controller.abort(new Error(typeof reason === "string" && reason !== ""
+            ? `cancelled by client: ${reason}`
+            : "cancelled by client"));
+    }
+    // Monotonic per-request tick for narration with no natural count.
+    const ticks = new Map();
+    function nextTick(id) {
+        const next = (ticks.get(id) ?? 0) + 1;
+        ticks.set(id, next);
+        return next;
+    }
+    return {
+        get initialized() {
+            return initialized;
+        },
+        async dispatch(line, transport) {
+            let message;
+            try {
+                message = parseMessage(line);
+            }
+            catch (error) {
+                if (error instanceof ProtocolError) {
+                    // No usable id means no response is possible: JSON-RPC has nowhere to
+                    // put the answer, and inventing an id would put a frame on the wire
+                    // the client cannot correlate to anything it sent.
+                    if (error.id !== null)
+                        transport.send(fail(error.id, error.code, error.message));
+                    return;
+                }
+                throw error;
+            }
+            if (!isRequest(message)) {
+                if (message.method === "notifications/initialized")
+                    initialized = true;
+                else if (message.method === "notifications/cancelled")
+                    cancel(message.params ?? {});
+                // Anything else — roots changed, and every notification a future spec
+                // adds — is accepted and ignored. A notification must never be
+                // answered, so silence on the wire is the protocol; silence *in
+                // response* is what cancellation could not afford, which is why it is
+                // the one handled above.
+                return;
+            }
+            try {
+                await handleRequest(message, transport);
+            }
+            catch (error) {
+                transport.send(fail(message.id, error instanceof ToolInputError ? RPC_INVALID_PARAMS : RPC_INTERNAL_ERROR, error instanceof Error ? error.message : String(error)));
+            }
+            finally {
+                ticks.delete(message.id);
+            }
+        },
+    };
+}
+//# sourceMappingURL=server.js.map