@descryy/mcp 0.11.4 → 0.11.5

package/dist/server.js

@@ -1,651 +0,0 @@
-/**
- * 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.\n\n" +
-    "Call `workspace` (`{verb: \"analyze\"}`) first — every other tool queries the graph it builds, " +
-    "and a stale graph answers about code that has changed.\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). A tool that answered `[]` for " +
-    "both \"nothing matched\" and \"I could not look\" would teach a false fact with no way to " +
-    "detect it — that is why these are distinct. 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 — `name` is not a string, or names nothing in the registry — comes back with " +
-    "`isError: true` and `{ tool, status: \"error\", message }`, carrying no `state`, no `graph` " +
-    "and no `disclosures`. There is no `state` because there is no tool to say `state` about. " +
-    "This is narrower than it once was: a *resolved* tool given bad input — a missing required " +
-    "field, a value of the wrong type — is a fact about that tool's call and comes back as a " +
-    "real `state: \"refused\"` reply instead, with `disclosures` naming what was wrong. Branch " +
-    "on `isError` before reading `state` regardless — a caller that only ever sees the second, " +
-    "unresolved-tool shape in testing will still be surprised by it in production.\n\n" +
-    "Every reply also carries a `disclosures` list, a `resolutionFloor` and a `reliabilityCap` " +
-    "(A, B or C) inside `graph`. `resolutionFloor` is how much tooling actually ran under the " +
-    "weakest evidence behind the answer, R0 through R4: R0 is syntax only, nothing resolved; R1 " +
-    "adds module/import resolution; R2 adds cross-file reference resolution (which symbol a name " +
-    "refers to, but 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 the claim to be relayed as: C means the claim is a behavioural prediction that " +
-    "has not been confirmed by running anything, and must not be relayed as fact. B means the " +
-    "claim rests on structural or reference resolution — a name, an import, a call target — real " +
-    "evidence, but not yet a confirmed behaviour. A means the claim is as strong as this graph can " +
-    "make it: a name-level fact resolved at R2 or better, a shape-level fact backed by a type " +
-    "checker (R3), or anything witnessed at runtime (R4, unconditional). Read the disclosures " +
-    "before summarising — they say what the answer does *not* cover.\n\n" +
-    "Coverage is a separate question from confidence: call `disclosure` with `{verb: \"coverage\", " +
-    "refs: [...]}` and a list of node ids or file paths from an earlier reply to learn which of " +
-    "them the graph actually reached, and at what resolution, rather than assuming silence means " +
-    "untested. `disclosure`'s `{verb: \"unresolved\"}` gives the graph's full ledger of things an " +
-    "adapter could not resolve — call it with no `handle` for a one-line summary and a handle, " +
-    "then again with that handle to page through every row; never assume the summary's one " +
-    "exemplar is the only refusal.\n\n" +
-    "`class` on each tool (`read`, `stateful-read` or `action`) says whether it is safe to retry. " +
-    "The one `action`-class tool (`questions`, when answering) takes a two-call handshake: the " +
-    "first call performs nothing and returns a confirmation token; only a second call presenting " +
-    "that exact token performs the write.\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 in plain words). On an `evidence`-tier reply it follows that reply's own " +
-    "`resolutionFloor`: `unconfirmed` below R4, where nothing was observed, and `strongly " +
-    "supported` at R4, where every hop behind the answer was witnessed in a real run — " +
-    "`observe`'s `runtime` and `tests` verbs 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, and the two are not " +
-    "interchangeable. `reportCategory` says how strongly the *cause* may be stated and is capped " +
-    "by how well the code resolved; `existenceCategory` says how strongly the evidence shows the " +
-    "failure is *real*, and never reads the resolution at all. They separate exactly where it " +
-    "matters: a reply that witnessed a failure on three 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 at all: conclusion-tier replies, faults, and " +
-    "refusals, since a refusal is a fact about Descry rather than about your code. `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 — `descry-runtime`'s live loop " +
-    "does not execute inside an MCP call, at any resolution level or 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 (the fact boundary), and nothing stops you " +
-    "from investigating paths no tool surfaced or suggested (the candidate boundary) — this text " +
-    "cannot make you not do either. 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