@descryy/mcp 0.1.0

package/dist/render.js

@@ -0,0 +1,333 @@
+/**
+ * The one way an engine answer becomes an MCP tool result.
+ *
+ * ## Why this file exists rather than each tool formatting its own reply
+ *
+ * `QueryResult` carries three things a caller would rather not think about: a
+ * staleness stamp (§27.3), a `truncated` flag, and `notes` — the plain-words
+ * disclosures that populate the five result states' `refused`/`empty`/`failed`/
+ * `timed_out` cases. The engine computes all three correctly today. Every one of
+ * them is one careless `return result.data` away from never reaching a user.
+ *
+ * So the tool handler's return type is `QueryResult`, not content. A handler
+ * *cannot* build a reply; it can only produce an answer, and this module is the
+ * only thing that turns an answer into frames. Rule 7 — honest degradation, no
+ * silent doing-less — becomes a property of the type system rather than of
+ * whoever writes the next tool.
+ *
+ * ## `ai-tool-contract.md` §2 — the frozen envelope
+ *
+ * This module used to ship a two-value `status: "ok" | "not_analysable"`. The
+ * contract froze five: `ok` / `empty` / `refused` / `failed` / `timed_out`
+ * (§1), plus `class`, `toolVersion`, `budget` and a structured `truncated`
+ * object (§2). `AnswerStatus`/`renderAnswer`'s old two-state shape is gone
+ * rather than kept alongside the new one — two envelope shapes on the wire is
+ * the thing DEC-277's "one process mints" reasoning exists to avoid one layer
+ * up, applied here to a type rather than a decision number.
+ *
+ * ## Four invariants, asserted rather than documented (§2.1)
+ *
+ * `render.ts` already enforced the first two; the other two are new.
+ *
+ * 1. `truncated != null` with empty `disclosures` → throw.
+ * 2. `state` in `{refused, failed, timed_out}` with empty `disclosures` → throw.
+ * 3. `state == "refused"` with no verbatim reason in `disclosures` → throw (§4).
+ * 4. `class == "action"` returning anything other than a handshake envelope on
+ *    the first call → throw (§7) — enforced in `action-handshake.ts` and
+ *    `server.ts`, not here: this module never sees a mint, only a redeemed run.
+ */
+import { reliabilityCap, reliabilityNote, reportCategory as deriveReportCategory, } from "@descryy/ir";
+/**
+ * MK-5 — which of the sixteen tools states a conclusion about the user's code
+ * versus which reports a fact about the graph.
+ *
+ * Lives here rather than in `@descryy/ir`: `tool-surface.ts`'s own header
+ * scopes that file to exactly `ResultState` and `ToolClass` ("and nothing
+ * else"), because those two cross into the pipeline and the desktop surface.
+ * This distinction is agent-mode-only (`plugin-and-mcp-surface.md` §3 PL-1),
+ * so a third shared union there would be scope creep the file's own doc
+ * disclaims. `kit.ts` imports it from here rather than the reverse, because
+ * `kit.ts` already depends on this module for `ToolAnswer`/`TruncationDetail`
+ * — defining it in `kit.ts` instead would make this module import back from
+ * `kit.ts` and cycle.
+ *
+ * - `conclusion` — the output is a statement about the user's code
+ *   (`validate`, `contracts`, `cross_pr`). Never raw candidates: an
+ *   already-adjudicated result carrying the category and the disclosure
+ *   sentence as one payload.
+ * - `evidence` — the output is a fact the graph computed, already carrying
+ *   its own resolution and qualification. The other thirteen.
+ */
+export const TOOL_TIERS = ["conclusion", "evidence"];
+const PROVENANCE = {
+    surface: "mcp",
+    adjudicatedBy: "descry",
+    presentedBy: "host-agent",
+    governancePipeline: false,
+};
+export class DisclosureError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = "DisclosureError";
+    }
+}
+/**
+ * MK-8's derivation, shared by every envelope-producing function below so the
+ * rule lives in one place rather than four.
+ */
+function deriveEnvelopeCategory(tier, state, resolutionFloor, nameLevel) {
+    if (tier === "conclusion")
+        return null;
+    if (state === "failed" || state === "timed_out")
+        return null;
+    if (state === "refused")
+        return "not analysable";
+    return deriveReportCategory({
+        hasRuntimeEvidence: false,
+        directMechanismEvidence: false,
+        independentSignalTypes: 0,
+        // `renderAnswer`'s own `state`/`disclosures` invariants guarantee a real
+        // graph was consulted whenever state is ok/empty, so this is never the
+        // null-graph sentinel — cast is safe, not asserted blind.
+        resolution: (resolutionFloor ?? 0),
+        nameLevel,
+        humanAsserted: false,
+    }).category;
+}
+/**
+ * A refusal's reason must be the specific, verbatim thing that blocked it —
+ * never just the state name. This is a heuristic proxy for that rule (§4):
+ * `disclosures` must contain something a template did not produce, which we
+ * cannot verify from here, but we CAN verify the weaker, structurally
+ * checkable half — that at least one disclosure exists and it is not empty
+ * text — the same shape invariant 2 already asserts. The stronger claim (the
+ * reason is *this* refusal's actual cause, not a generic string) is a
+ * per-tool authoring discipline this function cannot see into; it is checked
+ * by `tool-contract-gate.mjs`'s exemplar reading instead.
+ */
+export function renderAnswer(tool, answer, options) {
+    const { result, nameLevel } = answer;
+    const state = answer.state ?? "ok";
+    if (result.truncated && result.notes.length === 0) {
+        throw new DisclosureError(`${tool} returned a truncated answer with no disclosure. A partial result that does not ` +
+            "say it is partial reads as a complete one, which is the failure rule 7 exists to " +
+            "prevent. Fix the query, not this check.");
+    }
+    if ((state === "refused" || state === "failed" || state === "timed_out") && result.notes.length === 0) {
+        throw new DisclosureError(`${tool} reported "${state}" without saying why. The five result states exist to distinguish ` +
+            '"we found nothing" from "we could not look" from "something broke"; with no reason attached ' +
+            "this reply says none of them.");
+    }
+    const resolutionFloor = result.stamp.resolutionFloor;
+    const cap = reliabilityCap(resolutionFloor, nameLevel);
+    const disclosures = [...result.notes, reliabilityNote(resolutionFloor, nameLevel)];
+    const envelope = {
+        tool,
+        toolVersion: options.toolVersion,
+        state,
+        class: options.toolClass,
+        headline: answer.headline,
+        data: result.data,
+        graph: {
+            commitSha: result.stamp.commitSha,
+            builtAt: result.stamp.graphBuiltAt === null
+                ? null
+                : new Date(result.stamp.graphBuiltAt).toISOString(),
+            irSchemaVersion: result.stamp.irSchemaVersion,
+            resolutionFloor,
+            reliabilityCap: cap,
+        },
+        truncated: !result.truncated
+            ? null
+            : (answer.truncatedDetail ?? { shown: -1, total: -1, more: null }),
+        refusals: answer.refusalSummary ?? null,
+        budget: { elapsedMs: options.elapsedMs, limitMs: options.limitMs },
+        disclosures,
+        reportCategory: deriveEnvelopeCategory(options.toolTier, state, resolutionFloor, nameLevel),
+        provenance: PROVENANCE,
+    };
+    return {
+        content: [{ type: "text", text: narrate(envelope) }],
+        structuredContent: envelope,
+    };
+}
+/**
+ * The text an agent actually reads.
+ *
+ * Ordered so that the disclosures are **last**, because that is what a model
+ * summarising the reply keeps. A caveat buried above the data is a caveat that
+ * gets dropped in the summary the developer sees.
+ */
+function narrate(envelope) {
+    const lines = [envelope.headline];
+    if (envelope.state !== "ok" && envelope.state !== "empty") {
+        lines.push("", `**${envelope.state}.** ` +
+            (envelope.state === "refused"
+                ? "This is not a result — see below for why Descry could not look."
+                : envelope.state === "failed"
+                    ? "Something broke while answering this call — see below."
+                    : "The call ran out of its declared time budget — see below."));
+    }
+    else if (envelope.state === "empty") {
+        lines.push("", "**Empty.** Descry looked completely and there was nothing to find — see below.");
+    }
+    const stale = envelope.graph.commitSha === null
+        ? "The graph is empty — nothing has been analysed into it yet."
+        : `Graph at ${envelope.graph.commitSha.slice(0, 12)}` +
+            (envelope.graph.builtAt === null ? "" : `, built ${envelope.graph.builtAt}`) +
+            `. Weakest evidence R${envelope.graph.resolutionFloor ?? "n/a"}; findings here cap at ` +
+            `reliability class ${envelope.graph.reliabilityCap}.`;
+    lines.push("", stale);
+    if (envelope.disclosures.length > 0) {
+        lines.push("", "What this answer does not cover:");
+        for (const note of envelope.disclosures)
+            lines.push(`- ${note}`);
+    }
+    return lines.join("\n");
+}
+/**
+ * A failure that is the caller's to fix — a bad argument, a missing graph.
+ *
+ * Returned as a tool result with `isError`, not as a JSON-RPC error, which is
+ * what the MCP spec asks for: protocol errors are for malformed protocol, tool
+ * errors are for tools, and an agent can act on the second only if it arrives as
+ * content it can read.
+ *
+ * Deliberately outside the five-state envelope: a bad argument is not a
+ * statement about what Descry found or could not find, it is "fix your call
+ * and retry" — a different kind of thing than `refused`/`failed`.
+ */
+export function renderToolError(tool, message) {
+    return {
+        content: [{ type: "text", text: `${tool}: ${message}` }],
+        structuredContent: { tool, status: "error", message },
+        isError: true,
+    };
+}
+/**
+ * `state: "failed"` — §1.1: "promoted from a transport error to a result."
+ *
+ * An unexpected/internal error, not a bad argument (`renderToolError` still
+ * handles those). `data` is always `null` here (§2.2): the tool does not know
+ * what happened, and anything it returned would be a guess about its own
+ * fault. `isError` stays `true` so a generic MCP client that only reads the
+ * transport-level signal still treats this as a failure; an AI-layer-aware
+ * caller additionally gets `state: "failed"` in `structuredContent` to reason
+ * about rather than a bare `{tool, status, message}` shape.
+ */
+export function renderFailed(tool, message, options) {
+    const envelope = {
+        tool,
+        toolVersion: options.toolVersion,
+        state: "failed",
+        class: options.toolClass,
+        headline: `${tool} failed.`,
+        data: null,
+        graph: {
+            commitSha: null,
+            builtAt: null,
+            irSchemaVersion: 0,
+            resolutionFloor: null,
+            reliabilityCap: "C",
+        },
+        truncated: null,
+        refusals: null,
+        budget: { elapsedMs: options.elapsedMs, limitMs: options.limitMs },
+        disclosures: [message],
+        // A fault is not a claim about the code either way (§20) — no category applies.
+        reportCategory: null,
+        provenance: PROVENANCE,
+    };
+    return {
+        content: [{ type: "text", text: narrate(envelope) }],
+        structuredContent: envelope,
+        isError: true,
+    };
+}
+/**
+ * The one legitimate producer of a pending-handshake payload — §7's mint call.
+ *
+ * `class == "action"` returning anything other than this shape on an
+ * unconfirmed first call is invariant 4 (§2.1): "throw." This function is
+ * where that shape is produced, so the throw lives at the one call site that
+ * builds anything else for an action tool's first call — `server.ts`'s
+ * dispatch loop calls this and only this when `resolveActionDispatch` returns
+ * `{kind: "handshake"}`, never `tool.run`.
+ *
+ * `state: "ok"` deliberately: a mint is not a refusal, a failure or an empty
+ * result — it is a successful "here is what I would do", and the *pending*
+ * flag inside `data` is what tells a caller nothing was performed yet.
+ */
+export function renderHandshake(tool, token, willDo, options) {
+    const envelope = {
+        tool,
+        toolVersion: options.toolVersion,
+        state: "ok",
+        class: options.toolClass,
+        headline: `Confirmation required: ${willDo}`,
+        data: { pending: true, token, willDo },
+        graph: {
+            commitSha: null,
+            builtAt: null,
+            irSchemaVersion: 0,
+            resolutionFloor: null,
+            reliabilityCap: "C",
+        },
+        truncated: null,
+        refusals: null,
+        budget: { elapsedMs: options.elapsedMs, limitMs: options.limitMs },
+        disclosures: [
+            `Nothing was performed. Call ${tool} again with { "confirmToken": "${token}" } to actually do this — ` +
+                "the token expires in five minutes and is single-use.",
+        ],
+        // Nothing was analysed yet — a confirmation prompt makes no claim to categorize.
+        reportCategory: null,
+        provenance: PROVENANCE,
+    };
+    return {
+        content: [{ type: "text", text: narrate(envelope) }],
+        structuredContent: envelope,
+    };
+}
+/**
+ * `state: "timed_out"` — the call ran out of its declared budget.
+ *
+ * §6: "not a silent truncation and never a `failed`". `data` is `null` here
+ * because none of the registered tools currently produce genuine partial
+ * results mid-run (none checks `ctx.signal` internally yet — a disclosed gap,
+ * not a silent one, named in the returned disclosure); the envelope shape
+ * supports a populated partial `data` the day a tool does.
+ */
+export function renderTimedOut(tool, options) {
+    const envelope = {
+        tool,
+        toolVersion: options.toolVersion,
+        state: "timed_out",
+        class: options.toolClass,
+        headline: `${tool} timed out.`,
+        data: null,
+        graph: {
+            commitSha: null,
+            builtAt: null,
+            irSchemaVersion: 0,
+            resolutionFloor: null,
+            reliabilityCap: "C",
+        },
+        truncated: null,
+        refusals: null,
+        budget: { elapsedMs: options.elapsedMs, limitMs: options.limitMs },
+        disclosures: [
+            `${tool} did not finish within its ${options.limitMs}ms budget. This is a partial answer, not ` +
+                "a finding of failure or of absence — retry, or narrow the request.",
+        ],
+        // A partial run in progress makes no claim to categorize yet.
+        reportCategory: null,
+        provenance: PROVENANCE,
+    };
+    return {
+        content: [{ type: "text", text: narrate(envelope) }],
+        structuredContent: envelope,
+        isError: true,
+    };
+}
+//# sourceMappingURL=render.js.map

package/dist/render.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"render.js","sourceRoot":"","sources":["../src/render.ts"],"names":[],"mappings":"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"}

package/dist/server.d.ts

@@ -0,0 +1,42 @@
+/**
+ * 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 type { Session } from "./session.ts";
+import type { Transport } from "./transport.ts";
+export interface McpServerOptions {
+    readonly session: Session;
+    readonly name?: string;
+    readonly version?: string;
+}
+export interface McpServer {
+    /** Handle one newline-delimited frame. Never throws; every failure becomes a frame. */
+    dispatch(line: string, transport: Transport): Promise<void>;
+    /** True once the client has completed the handshake. */
+    readonly initialized: boolean;
+}
+export declare function createMcpServer(options: McpServerOptions): McpServer;
+//# sourceMappingURL=server.d.ts.map

package/dist/server.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"server.d.ts","sourceRoot":"","sources":["../src/server.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AAwBH,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,cAAc,CAAC;AAE5C,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,gBAAgB,CAAC;AAYhD,MAAM,WAAW,gBAAgB;IAC/B,QAAQ,CAAC,OAAO,EAAE,OAAO,CAAC;IAC1B,QAAQ,CAAC,IAAI,CAAC,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,OAAO,CAAC,EAAE,MAAM,CAAC;CAC3B;AAED,MAAM,WAAW,SAAS;IACxB,uFAAuF;IACvF,QAAQ,CAAC,IAAI,EAAE,MAAM,EAAE,SAAS,EAAE,SAAS,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAC5D,wDAAwD;IACxD,QAAQ,CAAC,WAAW,EAAE,OAAO,CAAC;CAC/B;AAyDD,wBAAgB,eAAe,CAAC,OAAO,EAAE,gBAAgB,GAAG,SAAS,CA2MpE"}

package/dist/server.js

@@ -0,0 +1,263 @@
+/**
+ * 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 { resolveActionDispatch } from "./action-handshake.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, renderTimedOut, renderToolError, } from "./render.js";
+import { TOOLS, TOOLS_BY_NAME, ToolInputError } from "./tools/index.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"));
+}
+const SERVER_INSTRUCTIONS = "Descry reads the repository's source into a code graph and answers questions about it.\n\n" +
+    "Call `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" +
+    "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 `verification_status` with 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. `refusal_fetch` " +
+    "gives the graph's full ledger of things an adapter could not resolve — call it with no " +
+    "arguments 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 three that already state a verdict about your " +
+    "code (`validate`, `contracts`, `cross_pr` — quote their `headline` verbatim rather than " +
+    "rephrasing it) or `evidence` for the other thirteen, which return 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) and, on an `evidence`-tier reply, `unconfirmed` at best: this " +
+    "server has no runtime evidence to offer, so `confirmed` never appears here — that word is " +
+    "reserved for the full Descry app, and its absence is honest, not a bug. `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";
+    let initialized = false;
+    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,
+                    })),
+                }));
+                return;
+            }
+            case "tools/call": {
+                transport.send(ok(id, await callTool(id, params, transport)));
+                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');
+        }
+        const tool = TOOLS_BY_NAME.get(name);
+        if (tool === undefined) {
+            return renderToolError(name, `no such tool. Available: ${TOOLS.map((t) => t.name).join(", ")}.`);
+        }
+        const rawArgs = params["arguments"];
+        if (rawArgs !== undefined && (typeof rawArgs !== "object" || rawArgs === null || Array.isArray(rawArgs))) {
+            return renderToolError(name, '"arguments" must be an object');
+        }
+        const args = (rawArgs ?? {});
+        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,
+                    },
+                });
+            }
+            : () => { };
+        const ctx = {
+            session,
+            progress,
+            signal: AbortSignal.timeout(CALL_BUDGET_MS),
+        };
+        const started = Date.now();
+        const renderOptions = () => ({
+            toolVersion: tool.version,
+            toolClass: tool.class,
+            toolTier: tool.tier,
+            elapsedMs: Date.now() - started,
+            limitMs: CALL_BUDGET_MS,
+        });
+        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") {
+                return renderHandshake(name, dispatch.token, dispatch.willDo, renderOptions());
+            }
+            const outcome = await tool.run(dispatch.args, ctx);
+            return renderAnswer(name, outcome, renderOptions());
+        }
+        catch (error) {
+            if (error instanceof ToolInputError)
+                return renderToolError(name, error.message);
+            if (isAbort(error) || ctx.signal.aborted)
+                return renderTimedOut(name, renderOptions());
+            // 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.
+            return renderFailed(name, `${error instanceof Error ? error.message : String(error)}`, renderOptions());
+        }
+    }
+    // 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;
+                // Every other notification — cancellation, roots changed — is accepted
+                // and ignored. A notification must never be answered, so silence here is
+                // the protocol, not a gap.
+                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