@ybotok/loam 0.1.0-beta.3 → 0.2.0-alpha.13

package/dist/core/mcp/framing.js

@@ -0,0 +1,46 @@
+/**
+ * MCP stdio framing — the ONE module that knows how protocol messages are
+ * delimited on the wire.
+ *
+ * Assumed spec revision: 2025-06-18 (unchanged on this point since
+ * 2024-11-05): the MCP stdio transport is newline-delimited JSON-RPC — one
+ * UTF-8 encoded message per line, and messages MUST NOT contain embedded
+ * newlines. It is NOT LSP's Content-Length header framing, which this facade
+ * was once at risk of assuming because both protocols are JSON-RPC over
+ * stdio. If a framing correction is ever needed, it is a change to this
+ * module alone: the serve loop consumes `splitFrames`/`frame` and never
+ * touches delimiter bytes itself.
+ */
+/**
+ * Split buffered input into complete frames plus the unterminated tail.
+ * Stateless on purpose: the caller owns `rest` as a local, so no state can
+ * leak between serve sessions the way module-level buffering would.
+ */
+export function splitFrames(buffered) {
+    const parts = buffered.split("\n");
+    // split() never returns an empty array, so pop() always yields a string —
+    // the text after the final "\n", which is "" when the chunk ended on one.
+    const rest = parts.pop() ?? "";
+    return { lines: parts.map(bareFrame), rest };
+}
+/**
+ * One frame stripped of transport debris: a trailing CR (Windows clients end
+ * lines with \r\n, and the frame is the JSON text, not the carriage return)
+ * and a leading U+FEFF. The BOM case was observed, not imagined: PowerShell's
+ * pipeline encoder prepends one when it feeds a native process, so a Windows
+ * client's very first `initialize` died with -32700 while every later frame
+ * worked. A BOM can never begin valid JSON, so stripping it drops no message.
+ */
+function bareFrame(line) {
+    const noBom = line.startsWith("") ? line.slice(1) : line;
+    return noBom.endsWith("\r") ? noBom.slice(0, -1) : noBom;
+}
+/**
+ * One outbound frame. JSON.stringify escapes every newline inside string
+ * values, so the serialized form of a message object can never contain the
+ * delimiter — which is the invariant the transport rests on.
+ */
+export function frame(message) {
+    return JSON.stringify(message) + "\n";
+}
+//# sourceMappingURL=framing.js.map

package/dist/core/mcp/framing.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"framing.js","sourceRoot":"","sources":["../../../src/core/mcp/framing.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AASH;;;;GAIG;AACH,MAAM,UAAU,WAAW,CAAC,QAAgB;IAC1C,MAAM,KAAK,GAAG,QAAQ,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC;IACnC,0EAA0E;IAC1E,0EAA0E;IAC1E,MAAM,IAAI,GAAG,KAAK,CAAC,GAAG,EAAE,IAAI,EAAE,CAAC;IAC/B,OAAO,EAAE,KAAK,EAAE,KAAK,CAAC,GAAG,CAAC,SAAS,CAAC,EAAE,IAAI,EAAE,CAAC;AAC/C,CAAC;AAED;;;;;;;GAOG;AACH,SAAS,SAAS,CAAC,IAAY;IAC7B,MAAM,KAAK,GAAG,IAAI,CAAC,UAAU,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC;IAC1D,OAAO,KAAK,CAAC,QAAQ,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,KAAK,CAAC,KAAK,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,KAAK,CAAC;AAC3D,CAAC;AAED;;;;GAIG;AACH,MAAM,UAAU,KAAK,CAAC,OAAgC;IACpD,OAAO,IAAI,CAAC,SAAS,CAAC,OAAO,CAAC,GAAG,IAAI,CAAC;AACxC,CAAC","sourcesContent":["/**\n * MCP stdio framing — the ONE module that knows how protocol messages are\n * delimited on the wire.\n *\n * Assumed spec revision: 2025-06-18 (unchanged on this point since\n * 2024-11-05): the MCP stdio transport is newline-delimited JSON-RPC — one\n * UTF-8 encoded message per line, and messages MUST NOT contain embedded\n * newlines. It is NOT LSP's Content-Length header framing, which this facade\n * was once at risk of assuming because both protocols are JSON-RPC over\n * stdio. If a framing correction is ever needed, it is a change to this\n * module alone: the serve loop consumes `splitFrames`/`frame` and never\n * touches delimiter bytes itself.\n */\n\nexport interface FrameSplit {\n  /** Complete frames, in arrival order, each with its delimiter (and any trailing CR) removed. */\n  readonly lines: readonly string[];\n  /** The bytes after the last delimiter — a frame still arriving. Feed it back in front of the next chunk. */\n  readonly rest: string;\n}\n\n/**\n * Split buffered input into complete frames plus the unterminated tail.\n * Stateless on purpose: the caller owns `rest` as a local, so no state can\n * leak between serve sessions the way module-level buffering would.\n */\nexport function splitFrames(buffered: string): FrameSplit {\n  const parts = buffered.split(\"\\n\");\n  // split() never returns an empty array, so pop() always yields a string —\n  // the text after the final \"\\n\", which is \"\" when the chunk ended on one.\n  const rest = parts.pop() ?? \"\";\n  return { lines: parts.map(bareFrame), rest };\n}\n\n/**\n * One frame stripped of transport debris: a trailing CR (Windows clients end\n * lines with \\r\\n, and the frame is the JSON text, not the carriage return)\n * and a leading U+FEFF. The BOM case was observed, not imagined: PowerShell's\n * pipeline encoder prepends one when it feeds a native process, so a Windows\n * client's very first `initialize` died with -32700 while every later frame\n * worked. A BOM can never begin valid JSON, so stripping it drops no message.\n */\nfunction bareFrame(line: string): string {\n  const noBom = line.startsWith(\"\") ? line.slice(1) : line;\n  return noBom.endsWith(\"\\r\") ? noBom.slice(0, -1) : noBom;\n}\n\n/**\n * One outbound frame. JSON.stringify escapes every newline inside string\n * values, so the serialized form of a message object can never contain the\n * delimiter — which is the invariant the transport rests on.\n */\nexport function frame(message: Record<string, unknown>): string {\n  return JSON.stringify(message) + \"\\n\";\n}\n"]}

package/dist/core/mcp/protocol.js

@@ -0,0 +1,280 @@
+/**
+ * Pure JSON-RPC 2.0 + MCP routing for `loam mcp` — parse one inbound frame,
+ * decide the reply. Computes and returns only: the stream loop, the stdout
+ * writes and the dispatcher live in `src/commands/mcp/`, so every decision
+ * here is unit-testable without a stream in sight.
+ *
+ * Spec revision assumed: MCP 2025-06-18 (framing note in `./framing.ts`).
+ * The lifecycle is deliberately NOT policed: this server is a stateless
+ * facade over a stateless CLI, its capabilities never vary, and refusing a
+ * tools/call that arrives before `initialize` would protect nothing — so
+ * every request is answered on its own terms, whatever came first. What IS
+ * refused: JSON-RPC batch arrays (removed in 2025-06-18; the older revisions
+ * this server also negotiates allowed them, and that gap is deliberate — a
+ * clear -32600 with the reason beats a half-implemented batch path no real
+ * MCP client exercises).
+ */
+import { isRecord } from "../kernel/records.js";
+import { LOAM_VERSION } from "../envelope/version.js";
+import { toArgv, toInputSchema } from "./argv.js";
+import { MCP_TOOLS, READ_ONLY_ANNOTATIONS, toolByName, } from "./tools.js";
+import { AGENTS_MD } from "../agent/agents-md.js";
+import { PROTOCOLS } from "../agent/protocol.js";
+import { withoutFixTables } from "../explain/fix-tables.js";
+/** JSON-RPC 2.0 error codes this server emits. */
+export const PARSE_ERROR = -32700;
+export const INVALID_REQUEST = -32600;
+export const METHOD_NOT_FOUND = -32601;
+export const INVALID_PARAMS = -32602;
+export const INTERNAL_ERROR = -32603;
+/**
+ * Newest first. `initialize` echoes the client's requested version when it is
+ * one of these, else answers the newest — the negotiation rule the 2025-06-18
+ * lifecycle spec states for servers. All three revisions are identical in
+ * everything this facade implements (stdio framing, tools/list, tools/call
+ * with text content) except batching, refused above.
+ */
+export const SUPPORTED_PROTOCOL_VERSIONS = ["2025-06-18", "2025-03-26", "2024-11-05"];
+export const LATEST_PROTOCOL_VERSION = SUPPORTED_PROTOCOL_VERSIONS[0];
+const TOOL_OUTPUT_SCHEMA = {
+    type: "object",
+    required: ["contractVersion", "version", "ok"],
+    properties: {
+        contractVersion: { const: "1.0" },
+        version: { type: "string" },
+        ok: { type: "boolean" },
+        error: {
+            type: "object",
+            properties: { code: { type: "string" }, message: { type: "string" } },
+            required: ["code", "message"],
+            additionalProperties: true,
+        },
+    },
+    additionalProperties: true,
+};
+const RESOURCE_TEXT = {
+    "loam://orientation": AGENTS_MD,
+    ...Object.fromEntries(Object.entries(PROTOCOLS).map(([name, body]) => [`loam://instructions/${name}`, body])),
+    "loam://instructions/loam-check/compact": withoutFixTables(PROTOCOLS["loam-check"]),
+};
+export function resultResponse(id, result) {
+    return { jsonrpc: "2.0", id, result };
+}
+/**
+ * `rpcCode`, not `code`: the stable-code drift collector
+ * (test/helpers/stable-codes.ts) treats every function with a parameter named
+ * `code` as an emitter of loam's stable code STRINGS and demands a literal at
+ * each call site. A JSON-RPC numeric code is a different vocabulary — naming
+ * the parameter into that scan would make the guard demand string literals
+ * where the protocol requires numbers.
+ */
+export function errorResponse(id, rpcCode, message) {
+    return { jsonrpc: "2.0", id, error: { code: rpcCode, message } };
+}
+const reply = (response) => ({ kind: "reply", response });
+/** One line off the wire → what to do about it. Total: every input maps to an outcome, nothing throws. */
+export function routeLine(line, tools = MCP_TOOLS) {
+    if (line.trim() === "")
+        return { kind: "ignore" };
+    let message;
+    try {
+        message = JSON.parse(line);
+    }
+    catch (err) {
+        const detail = err instanceof Error ? err.message : String(err);
+        return reply(errorResponse(null, PARSE_ERROR, `Parse error: ${detail}`));
+    }
+    if (Array.isArray(message)) {
+        // JSON-RPC batching was removed in MCP 2025-06-18; see the module comment
+        // for why the older negotiated revisions refuse it too instead of half-supporting it.
+        return reply(errorResponse(null, INVALID_REQUEST, "Invalid Request: JSON-RPC batch arrays are not supported"));
+    }
+    if (!isRecord(message)) {
+        return reply(errorResponse(null, INVALID_REQUEST, "Invalid Request: a message must be a JSON object"));
+    }
+    const rawId = message["id"];
+    // Three id states, kept apart because they demand opposite answers. ABSENT
+    // (or an explicit null, reserved for unanswerable errors) is a notification.
+    // A PRESENT id that is not a string or a finite number — an object, a bool,
+    // an array, a JSON `1e999` that parsed to Infinity — is a malformed REQUEST:
+    // the client is waiting on a reply, and folding it into the notification
+    // branch answers with silence, which for a request is a hang, not an error.
+    const validId = typeof rawId === "string" || (typeof rawId === "number" && Number.isFinite(rawId)) ? rawId : null;
+    if (message["jsonrpc"] !== "2.0") {
+        return reply(errorResponse(validId, INVALID_REQUEST, "Invalid Request: jsonrpc must be the string \"2.0\""));
+    }
+    const method = message["method"];
+    if (typeof method !== "string") {
+        return reply(errorResponse(validId, INVALID_REQUEST, "Invalid Request: method must be a string"));
+    }
+    if (!("id" in message) || rawId === null)
+        return { kind: "ignore" };
+    if (validId === null) {
+        // id null in the response: the request's own id is unusable, and null is
+        // exactly the id JSON-RPC reserves for that answer.
+        return reply(errorResponse(null, INVALID_REQUEST, "Invalid Request: id must be a string or a finite number"));
+    }
+    return routeRequest(validId, method, message["params"], tools);
+}
+function routeRequest(id, method, params, tools) {
+    switch (method) {
+        case "initialize":
+            return reply(resultResponse(id, initializeResult(params)));
+        case "ping":
+            return reply(resultResponse(id, {}));
+        case "tools/list":
+            // No pagination: the whole tool table fits in one page, so `nextCursor`
+            // is omitted rather than emitted empty — the spec reads an absent
+            // cursor as "done".
+            return reply(resultResponse(id, {
+                tools: tools.map((tool) => ({
+                    name: tool.name,
+                    description: tool.description,
+                    inputSchema: toInputSchema(tool),
+                    outputSchema: TOOL_OUTPUT_SCHEMA,
+                    // Base tools share the read-only default; opt-in authoring tools
+                    // carry their own mutation annotations in author-tools.ts.
+                    annotations: tool.annotations ?? READ_ONLY_ANNOTATIONS,
+                })),
+            }));
+        case "resources/list":
+            return reply(resultResponse(id, {
+                resources: Object.keys(RESOURCE_TEXT).map((uri) => ({
+                    uri,
+                    name: uri === "loam://orientation" ? "loam orientation" : uri.slice("loam://instructions/".length),
+                    description: uri === "loam://orientation"
+                        ? "Small always-loaded map of a loam repository"
+                        : "Version-matched loam workflow, support protocol or reference page",
+                    mimeType: "text/markdown",
+                })),
+            }));
+        case "resources/read":
+            return routeResourceRead(id, params);
+        case "tools/call":
+            return routeToolCall(id, params, tools);
+        default:
+            // Everything else — including a literal `shutdown`, which is LSP's
+            // lifecycle and not MCP's (the MCP stdio lifecycle ends at stdin EOF).
+            return reply(errorResponse(id, METHOD_NOT_FOUND, `Method not found: ${method}`));
+    }
+}
+function routeResourceRead(id, params) {
+    if (!isRecord(params) || typeof params["uri"] !== "string") {
+        return reply(errorResponse(id, INVALID_PARAMS, "resources/read requires params.uri"));
+    }
+    const uri = params["uri"];
+    const text = RESOURCE_TEXT[uri];
+    if (text === undefined) {
+        return reply(errorResponse(id, INVALID_PARAMS, `Unknown resource '${uri}'`));
+    }
+    return reply(resultResponse(id, { contents: [{ uri, mimeType: "text/markdown", text }] }));
+}
+function routeToolCall(id, params, tools) {
+    if (!isRecord(params) || typeof params["name"] !== "string") {
+        return reply(errorResponse(id, INVALID_PARAMS, "tools/call requires params.name naming a tool"));
+    }
+    const tool = toolByName(params["name"], tools);
+    if (tool === undefined) {
+        const names = tools.map((t) => t.name).join(", ");
+        return reply(errorResponse(id, INVALID_PARAMS, `Unknown tool '${params["name"]}' — this server offers: ${names}`));
+    }
+    const rawArgs = params["arguments"] ?? {};
+    if (!isRecord(rawArgs)) {
+        return reply(errorResponse(id, INVALID_PARAMS, "tools/call params.arguments must be an object when present"));
+    }
+    const built = toArgv(tool, rawArgs);
+    if (!built.ok)
+        return reply(errorResponse(id, INVALID_PARAMS, built.problem));
+    return { kind: "call", id, toolName: tool.name, argv: built.argv };
+}
+/**
+ * The `initialize` result. The version rule: echo the requested revision when
+ * this server supports it, otherwise answer the newest it does — the client
+ * then decides whether it can live with that (2025-06-18 lifecycle,
+ * "Version Negotiation").
+ */
+export function initializeResult(params) {
+    const requested = isRecord(params) ? params["protocolVersion"] : undefined;
+    const negotiated = typeof requested === "string" && SUPPORTED_PROTOCOL_VERSIONS.includes(requested)
+        ? requested
+        : LATEST_PROTOCOL_VERSION;
+    return {
+        protocolVersion: negotiated,
+        capabilities: {
+            // The sets never change while the server lives, so no
+            // listChanged notification is declared — announcing one and never
+            // sending it would be a promise, not a capability.
+            tools: {},
+            resources: {},
+        },
+        serverInfo: { name: "loam", version: LOAM_VERSION },
+        instructions: "Every tool result is a loam --json envelope (contractVersion 1.0): branch on ok, " +
+            "and on error.code when ok is false — the same machine contract the CLI prints.",
+    };
+}
+/**
+ * One tool run wrapped as an MCP tool result. The envelope rides VERBATIM in
+ * content[0].text — one machine contract, not two — and again parsed as
+ * structuredContent for clients that read that field.
+ *
+ * `isError` follows the ENVELOPE's `ok`, and the exit code only when no
+ * envelope could be parsed. The two disagree on purpose for half the tool
+ * set: validate, doctor, gate, context and delta all have graded answers
+ * that exit 1 while reporting `ok: true` — an invalid fleet, a blocked
+ * doctor, a `verdict: "fail"` deploy gate. Those exits are CI levers, not
+ * call failures, and an MCP host renders `isError: true` as "the call
+ * failed" and may discard structuredContent — which for loam_gate would
+ * discard the exact verdict the caller asked for. `ok: false` is the one
+ * signal that means "loam refused to answer", so it is the one isError
+ * mirrors; the exit-code fallback exists only for stdout that parsed as no
+ * envelope at all.
+ *
+ * An EMPTY stdout is a protocol error, not a quiet result: with `--json` on
+ * every argv, a command that printed no envelope is a command whose answer
+ * was lost, and "nobody could look" must stay distinguishable from any
+ * genuine envelope — even a refusing one.
+ */
+export function toolReply(run) {
+    if (run.stdout.trim() === "") {
+        const hint = run.stderr.trim() === "" ? "" : ` stderr: ${run.stderr.trim()}`;
+        return {
+            kind: "error",
+            code: INTERNAL_ERROR,
+            message: `the command exited ${run.code} without printing a --json envelope, so there is no result to return.${hint}`,
+        };
+    }
+    let structured;
+    try {
+        const parsed = JSON.parse(run.stdout);
+        // structuredContent must be an object; the envelope always is.
+        structured = isRecord(parsed) ? parsed : undefined;
+    }
+    catch {
+        // The fallback below handles both invalid JSON and valid non-object JSON.
+    }
+    if (structured === undefined) {
+        // Preserve the bytes in content, but keep the declared output contract:
+        // an MCP client should never have to branch on the absence of
+        // structuredContent after tools/list promised a schema.
+        structured = {
+            contractVersion: "1.0",
+            version: LOAM_VERSION,
+            ok: false,
+            error: {
+                code: "internal",
+                message: "the command did not print a JSON object envelope",
+            },
+            raw: run.stdout,
+        };
+    }
+    const envelopeOk = structured?.["ok"];
+    return {
+        kind: "result",
+        result: {
+            content: [{ type: "text", text: run.stdout }],
+            structuredContent: structured,
+            isError: typeof envelopeOk === "boolean" ? !envelopeOk : run.code !== 0,
+        },
+    };
+}
+//# sourceMappingURL=protocol.js.map

package/dist/core/mcp/protocol.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"protocol.js","sourceRoot":"","sources":["../../../src/core/mcp/protocol.ts"],"names":[],"mappings":"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","sourcesContent":["/**\n * Pure JSON-RPC 2.0 + MCP routing for `loam mcp` — parse one inbound frame,\n * decide the reply. Computes and returns only: the stream loop, the stdout\n * writes and the dispatcher live in `src/commands/mcp/`, so every decision\n * here is unit-testable without a stream in sight.\n *\n * Spec revision assumed: MCP 2025-06-18 (framing note in `./framing.ts`).\n * The lifecycle is deliberately NOT policed: this server is a stateless\n * facade over a stateless CLI, its capabilities never vary, and refusing a\n * tools/call that arrives before `initialize` would protect nothing — so\n * every request is answered on its own terms, whatever came first. What IS\n * refused: JSON-RPC batch arrays (removed in 2025-06-18; the older revisions\n * this server also negotiates allowed them, and that gap is deliberate — a\n * clear -32600 with the reason beats a half-implemented batch path no real\n * MCP client exercises).\n */\nimport { isRecord } from \"../kernel/records.js\";\nimport { LOAM_VERSION } from \"../envelope/version.js\";\nimport { toArgv, toInputSchema } from \"./argv.js\";\nimport {\n  MCP_TOOLS,\n  READ_ONLY_ANNOTATIONS,\n  toolByName,\n  type McpTool,\n} from \"./tools.js\";\nimport { AGENTS_MD } from \"../agent/agents-md.js\";\nimport { PROTOCOLS } from \"../agent/protocol.js\";\nimport { withoutFixTables } from \"../explain/fix-tables.js\";\n\n/** JSON-RPC 2.0 error codes this server emits. */\nexport const PARSE_ERROR = -32700;\nexport const INVALID_REQUEST = -32600;\nexport const METHOD_NOT_FOUND = -32601;\nexport const INVALID_PARAMS = -32602;\nexport const INTERNAL_ERROR = -32603;\n\n/**\n * Newest first. `initialize` echoes the client's requested version when it is\n * one of these, else answers the newest — the negotiation rule the 2025-06-18\n * lifecycle spec states for servers. All three revisions are identical in\n * everything this facade implements (stdio framing, tools/list, tools/call\n * with text content) except batching, refused above.\n */\nexport const SUPPORTED_PROTOCOL_VERSIONS = [\"2025-06-18\", \"2025-03-26\", \"2024-11-05\"] as const;\nexport const LATEST_PROTOCOL_VERSION = SUPPORTED_PROTOCOL_VERSIONS[0];\n\nconst TOOL_OUTPUT_SCHEMA = {\n  type: \"object\",\n  required: [\"contractVersion\", \"version\", \"ok\"],\n  properties: {\n    contractVersion: { const: \"1.0\" },\n    version: { type: \"string\" },\n    ok: { type: \"boolean\" },\n    error: {\n      type: \"object\",\n      properties: { code: { type: \"string\" }, message: { type: \"string\" } },\n      required: [\"code\", \"message\"],\n      additionalProperties: true,\n    },\n  },\n  additionalProperties: true,\n} as const;\n\nconst RESOURCE_TEXT: Readonly<Record<string, string>> = {\n  \"loam://orientation\": AGENTS_MD,\n  ...Object.fromEntries(\n    Object.entries(PROTOCOLS).map(([name, body]) => [`loam://instructions/${name}`, body]),\n  ),\n  \"loam://instructions/loam-check/compact\": withoutFixTables(PROTOCOLS[\"loam-check\"]!),\n};\n\n/** A response id: echoed from the request, or null when no id could be read (parse errors). */\nexport type JsonRpcId = string | number;\n\nexport interface JsonRpcResponse extends Record<string, unknown> {\n  readonly jsonrpc: \"2.0\";\n  readonly id: JsonRpcId | null;\n}\n\nexport function resultResponse(id: JsonRpcId | null, result: unknown): JsonRpcResponse {\n  return { jsonrpc: \"2.0\", id, result };\n}\n\n/**\n * `rpcCode`, not `code`: the stable-code drift collector\n * (test/helpers/stable-codes.ts) treats every function with a parameter named\n * `code` as an emitter of loam's stable code STRINGS and demands a literal at\n * each call site. A JSON-RPC numeric code is a different vocabulary — naming\n * the parameter into that scan would make the guard demand string literals\n * where the protocol requires numbers.\n */\nexport function errorResponse(id: JsonRpcId | null, rpcCode: number, message: string): JsonRpcResponse {\n  return { jsonrpc: \"2.0\", id, error: { code: rpcCode, message } };\n}\n\n/**\n * What one inbound frame asks of the serve loop:\n * - `ignore`: a blank line, or a notification — nothing goes back.\n * - `reply`: answered here, in pure code; write the response.\n * - `call`: a validated tools/call — run `argv` through the dispatcher and\n *   wrap what comes back. The argv is fully built here so the loop never\n *   interprets arguments.\n */\nexport type RouteOutcome =\n  | { readonly kind: \"ignore\" }\n  | { readonly kind: \"reply\"; readonly response: JsonRpcResponse }\n  | { readonly kind: \"call\"; readonly id: JsonRpcId; readonly toolName: string; readonly argv: readonly string[] };\n\nconst reply = (response: JsonRpcResponse): RouteOutcome => ({ kind: \"reply\", response });\n\n/** One line off the wire → what to do about it. Total: every input maps to an outcome, nothing throws. */\nexport function routeLine(line: string, tools: readonly McpTool[] = MCP_TOOLS): RouteOutcome {\n  if (line.trim() === \"\") return { kind: \"ignore\" };\n  let message: unknown;\n  try {\n    message = JSON.parse(line);\n  } catch (err) {\n    const detail = err instanceof Error ? err.message : String(err);\n    return reply(errorResponse(null, PARSE_ERROR, `Parse error: ${detail}`));\n  }\n  if (Array.isArray(message)) {\n    // JSON-RPC batching was removed in MCP 2025-06-18; see the module comment\n    // for why the older negotiated revisions refuse it too instead of half-supporting it.\n    return reply(errorResponse(null, INVALID_REQUEST, \"Invalid Request: JSON-RPC batch arrays are not supported\"));\n  }\n  if (!isRecord(message)) {\n    return reply(errorResponse(null, INVALID_REQUEST, \"Invalid Request: a message must be a JSON object\"));\n  }\n  const rawId = message[\"id\"];\n  // Three id states, kept apart because they demand opposite answers. ABSENT\n  // (or an explicit null, reserved for unanswerable errors) is a notification.\n  // A PRESENT id that is not a string or a finite number — an object, a bool,\n  // an array, a JSON `1e999` that parsed to Infinity — is a malformed REQUEST:\n  // the client is waiting on a reply, and folding it into the notification\n  // branch answers with silence, which for a request is a hang, not an error.\n  const validId = typeof rawId === \"string\" || (typeof rawId === \"number\" && Number.isFinite(rawId)) ? rawId : null;\n  if (message[\"jsonrpc\"] !== \"2.0\") {\n    return reply(errorResponse(validId, INVALID_REQUEST, \"Invalid Request: jsonrpc must be the string \\\"2.0\\\"\"));\n  }\n  const method = message[\"method\"];\n  if (typeof method !== \"string\") {\n    return reply(errorResponse(validId, INVALID_REQUEST, \"Invalid Request: method must be a string\"));\n  }\n  if (!(\"id\" in message) || rawId === null) return { kind: \"ignore\" };\n  if (validId === null) {\n    // id null in the response: the request's own id is unusable, and null is\n    // exactly the id JSON-RPC reserves for that answer.\n    return reply(errorResponse(null, INVALID_REQUEST, \"Invalid Request: id must be a string or a finite number\"));\n  }\n  return routeRequest(validId, method, message[\"params\"], tools);\n}\n\nfunction routeRequest(\n  id: JsonRpcId,\n  method: string,\n  params: unknown,\n  tools: readonly McpTool[],\n): RouteOutcome {\n  switch (method) {\n    case \"initialize\":\n      return reply(resultResponse(id, initializeResult(params)));\n    case \"ping\":\n      return reply(resultResponse(id, {}));\n    case \"tools/list\":\n      // No pagination: the whole tool table fits in one page, so `nextCursor`\n      // is omitted rather than emitted empty — the spec reads an absent\n      // cursor as \"done\".\n      return reply(resultResponse(id, {\n        tools: tools.map((tool) => ({\n          name: tool.name,\n          description: tool.description,\n          inputSchema: toInputSchema(tool),\n          outputSchema: TOOL_OUTPUT_SCHEMA,\n          // Base tools share the read-only default; opt-in authoring tools\n          // carry their own mutation annotations in author-tools.ts.\n          annotations: tool.annotations ?? READ_ONLY_ANNOTATIONS,\n        })),\n      }));\n    case \"resources/list\":\n      return reply(resultResponse(id, {\n        resources: Object.keys(RESOURCE_TEXT).map((uri) => ({\n          uri,\n          name: uri === \"loam://orientation\" ? \"loam orientation\" : uri.slice(\"loam://instructions/\".length),\n          description:\n            uri === \"loam://orientation\"\n              ? \"Small always-loaded map of a loam repository\"\n              : \"Version-matched loam workflow, support protocol or reference page\",\n          mimeType: \"text/markdown\",\n        })),\n      }));\n    case \"resources/read\":\n      return routeResourceRead(id, params);\n    case \"tools/call\":\n      return routeToolCall(id, params, tools);\n    default:\n      // Everything else — including a literal `shutdown`, which is LSP's\n      // lifecycle and not MCP's (the MCP stdio lifecycle ends at stdin EOF).\n      return reply(errorResponse(id, METHOD_NOT_FOUND, `Method not found: ${method}`));\n  }\n}\n\nfunction routeResourceRead(id: JsonRpcId, params: unknown): RouteOutcome {\n  if (!isRecord(params) || typeof params[\"uri\"] !== \"string\") {\n    return reply(errorResponse(id, INVALID_PARAMS, \"resources/read requires params.uri\"));\n  }\n  const uri = params[\"uri\"];\n  const text = RESOURCE_TEXT[uri];\n  if (text === undefined) {\n    return reply(errorResponse(id, INVALID_PARAMS, `Unknown resource '${uri}'`));\n  }\n  return reply(resultResponse(id, { contents: [{ uri, mimeType: \"text/markdown\", text }] }));\n}\n\nfunction routeToolCall(\n  id: JsonRpcId,\n  params: unknown,\n  tools: readonly McpTool[],\n): RouteOutcome {\n  if (!isRecord(params) || typeof params[\"name\"] !== \"string\") {\n    return reply(errorResponse(id, INVALID_PARAMS, \"tools/call requires params.name naming a tool\"));\n  }\n  const tool = toolByName(params[\"name\"], tools);\n  if (tool === undefined) {\n    const names = tools.map((t) => t.name).join(\", \");\n    return reply(errorResponse(id, INVALID_PARAMS, `Unknown tool '${params[\"name\"]}' — this server offers: ${names}`));\n  }\n  const rawArgs = params[\"arguments\"] ?? {};\n  if (!isRecord(rawArgs)) {\n    return reply(errorResponse(id, INVALID_PARAMS, \"tools/call params.arguments must be an object when present\"));\n  }\n  const built = toArgv(tool, rawArgs);\n  if (!built.ok) return reply(errorResponse(id, INVALID_PARAMS, built.problem));\n  return { kind: \"call\", id, toolName: tool.name, argv: built.argv };\n}\n\n/**\n * The `initialize` result. The version rule: echo the requested revision when\n * this server supports it, otherwise answer the newest it does — the client\n * then decides whether it can live with that (2025-06-18 lifecycle,\n * \"Version Negotiation\").\n */\nexport function initializeResult(params: unknown): Record<string, unknown> {\n  const requested = isRecord(params) ? params[\"protocolVersion\"] : undefined;\n  const negotiated =\n    typeof requested === \"string\" && (SUPPORTED_PROTOCOL_VERSIONS as readonly string[]).includes(requested)\n      ? requested\n      : LATEST_PROTOCOL_VERSION;\n  return {\n    protocolVersion: negotiated,\n    capabilities: {\n      // The sets never change while the server lives, so no\n      // listChanged notification is declared — announcing one and never\n      // sending it would be a promise, not a capability.\n      tools: {},\n      resources: {},\n    },\n    serverInfo: { name: \"loam\", version: LOAM_VERSION },\n    instructions:\n      \"Every tool result is a loam --json envelope (contractVersion 1.0): branch on ok, \" +\n      \"and on error.code when ok is false — the same machine contract the CLI prints.\",\n  };\n}\n\n/** What the dispatcher hands back from one tool call, before it becomes a protocol reply. */\nexport interface ToolRunOutcome {\n  readonly stdout: string;\n  readonly stderr: string;\n  readonly code: number;\n}\n\nexport type ToolReply =\n  | { readonly kind: \"result\"; readonly result: Record<string, unknown> }\n  | { readonly kind: \"error\"; readonly code: number; readonly message: string };\n\n/**\n * One tool run wrapped as an MCP tool result. The envelope rides VERBATIM in\n * content[0].text — one machine contract, not two — and again parsed as\n * structuredContent for clients that read that field.\n *\n * `isError` follows the ENVELOPE's `ok`, and the exit code only when no\n * envelope could be parsed. The two disagree on purpose for half the tool\n * set: validate, doctor, gate, context and delta all have graded answers\n * that exit 1 while reporting `ok: true` — an invalid fleet, a blocked\n * doctor, a `verdict: \"fail\"` deploy gate. Those exits are CI levers, not\n * call failures, and an MCP host renders `isError: true` as \"the call\n * failed\" and may discard structuredContent — which for loam_gate would\n * discard the exact verdict the caller asked for. `ok: false` is the one\n * signal that means \"loam refused to answer\", so it is the one isError\n * mirrors; the exit-code fallback exists only for stdout that parsed as no\n * envelope at all.\n *\n * An EMPTY stdout is a protocol error, not a quiet result: with `--json` on\n * every argv, a command that printed no envelope is a command whose answer\n * was lost, and \"nobody could look\" must stay distinguishable from any\n * genuine envelope — even a refusing one.\n */\nexport function toolReply(run: ToolRunOutcome): ToolReply {\n  if (run.stdout.trim() === \"\") {\n    const hint = run.stderr.trim() === \"\" ? \"\" : ` stderr: ${run.stderr.trim()}`;\n    return {\n      kind: \"error\",\n      code: INTERNAL_ERROR,\n      message: `the command exited ${run.code} without printing a --json envelope, so there is no result to return.${hint}`,\n    };\n  }\n  let structured: Record<string, unknown> | undefined;\n  try {\n    const parsed: unknown = JSON.parse(run.stdout);\n    // structuredContent must be an object; the envelope always is.\n    structured = isRecord(parsed) ? parsed : undefined;\n  } catch {\n    // The fallback below handles both invalid JSON and valid non-object JSON.\n  }\n  if (structured === undefined) {\n    // Preserve the bytes in content, but keep the declared output contract:\n    // an MCP client should never have to branch on the absence of\n    // structuredContent after tools/list promised a schema.\n    structured = {\n      contractVersion: \"1.0\",\n      version: LOAM_VERSION,\n      ok: false,\n      error: {\n        code: \"internal\",\n        message: \"the command did not print a JSON object envelope\",\n      },\n      raw: run.stdout,\n    };\n  }\n  const envelopeOk = structured?.[\"ok\"];\n  return {\n    kind: \"result\",\n    result: {\n      content: [{ type: \"text\", text: run.stdout }],\n      structuredContent: structured,\n      isError: typeof envelopeOk === \"boolean\" ? !envelopeOk : run.code !== 0,\n    },\n  };\n}\n"]}