pennyrouter 0.2.9 → 0.2.11

package/src/mcp-register.test.js

@@ -0,0 +1,171 @@
+import assert from "node:assert/strict";
+
+import {
+  SERVER_NAME,
+  applyClaudeRegistry,
+  isManagedEntry,
+  removeManagedCodexMcp,
+  renderCodexMcp,
+  serverEntry,
+} from "./mcp-register.js";
+
+// -- what gets written ----------------------------------------------------
+// Unpinned on purpose: an absolute path breaks on a node/nvm switch and the server then stops
+// appearing silently, and a pinned version would freeze the session writers — wrong for a
+// feature whose risk is that the harnesses change their undocumented formats.
+{
+  const entry = serverEntry();
+  assert.equal(entry.command, "npx");
+  assert.deepEqual(entry.args, ["-y", "pennyrouter", "mcp"]);
+  assert.ok(!JSON.stringify(entry).includes("/"), "no absolute paths");
+  assert.ok(!/pennyrouter@/.test(JSON.stringify(entry)), "not version-pinned");
+}
+
+// -- Claude Code registry -------------------------------------------------
+{
+  // Registering into an empty config.
+  const fresh = applyClaudeRegistry({});
+  assert.deepEqual(fresh.mcpServers[SERVER_NAME], serverEntry());
+
+  // Existing unrelated servers are preserved.
+  const withOthers = applyClaudeRegistry({
+    mcpServers: { railway: { command: "railway" } },
+    projects: { "/x": {} },
+  });
+  assert.ok(withOthers.mcpServers.railway, "other servers survive");
+  assert.ok(withOthers.projects, "unrelated top-level keys survive");
+
+  // Re-installing updates in place rather than duplicating.
+  const twice = applyClaudeRegistry(applyClaudeRegistry({}));
+  assert.equal(Object.keys(twice.mcpServers).length, 1);
+
+  // A same-named server we did not write is a hard stop, not a silent overwrite.
+  assert.throws(
+    () => applyClaudeRegistry({ mcpServers: { [SERVER_NAME]: { command: "/my/own/build" } } }),
+    /did not write/,
+  );
+
+  // Removal takes ours and leaves everything else.
+  const removed = applyClaudeRegistry(
+    { mcpServers: { railway: { command: "railway" }, [SERVER_NAME]: serverEntry() } },
+    { remove: true },
+  );
+  assert.ok(!removed.mcpServers[SERVER_NAME]);
+  assert.ok(removed.mcpServers.railway);
+
+  // A user who re-pointed the name at their own build keeps it through an uninstall.
+  const custom = { mcpServers: { [SERVER_NAME]: { command: "/my/own/build" } } };
+  assert.deepEqual(applyClaudeRegistry(custom, { remove: true }), custom);
+
+  // Removing the last server drops the key entirely rather than leaving `{}`.
+  const emptied = applyClaudeRegistry(
+    { mcpServers: { [SERVER_NAME]: serverEntry() } },
+    { remove: true },
+  );
+  assert.ok(!("mcpServers" in emptied));
+}
+
+// -- managed-entry detection ----------------------------------------------
+assert.equal(isManagedEntry(serverEntry()), true);
+assert.equal(isManagedEntry({ command: "npx", args: ["-y", "pennyrouter@1.2.3", "mcp"] }), true);
+assert.equal(isManagedEntry({ command: "/my/own/build" }), false);
+assert.equal(isManagedEntry(null), false);
+assert.equal(isManagedEntry({}), false);
+
+// -- Codex TOML -----------------------------------------------------------
+{
+  const existing = [
+    'model_provider = "pennyrouter"',
+    "",
+    "[mcp_servers.node_repl]",
+    'command = "/Applications/Codex.app/node_repl"',
+  ].join("\n");
+
+  const written = renderCodexMcp(existing);
+  assert.ok(written.includes(`[mcp_servers.${SERVER_NAME}]`));
+  assert.ok(written.includes('command = "npx"'));
+  assert.ok(written.includes('args = ["-y", "pennyrouter", "mcp"]'));
+  assert.ok(written.includes("[mcp_servers.node_repl]"), "existing servers survive");
+
+  // A TOML table header captures every key after it, so our block must be appended — splicing
+  // it above an existing table would reparent that table's keys into ours.
+  const ourIndex = written.indexOf(`[mcp_servers.${SERVER_NAME}]`);
+  assert.ok(ourIndex > written.indexOf("[mcp_servers.node_repl]"), "appended, not spliced");
+  assert.ok(
+    written.indexOf('model_provider = "pennyrouter"') < written.indexOf("[mcp_servers."),
+    "root keys stay above every table",
+  );
+
+  // Re-installing is idempotent: the managed block is replaced, not stacked.
+  const again = renderCodexMcp(written);
+  assert.equal(again.match(new RegExp(`\\[mcp_servers\\.${SERVER_NAME}\\]`, "g")).length, 1);
+
+  // Removal restores the original.
+  assert.equal(renderCodexMcp(written, { remove: true }).trim(), existing.trim());
+  assert.equal(removeManagedCodexMcp(written).trim(), existing.trim());
+
+  // An unmanaged server of the same name is a hard stop.
+  assert.throws(
+    () => renderCodexMcp(`[mcp_servers.${SERVER_NAME}]\ncommand = "mine"`),
+    /outside PennyRouter's managed block/,
+  );
+
+  // Empty config in, valid config out.
+  assert.ok(renderCodexMcp("").includes(`[mcp_servers.${SERVER_NAME}]`));
+  assert.equal(renderCodexMcp("", { remove: true }), "");
+}
+
+// -- status reporting -----------------------------------------------------
+// `mcp status` is how someone finds out they are in the state install cannot reach: opted out
+// with --no-mcp, or blocked by a name conflict. Both must be distinguishable from "not set up".
+{
+  const { mkdtempSync, writeFileSync, mkdirSync } = await import("node:fs");
+  const { tmpdir } = await import("node:os");
+  const { join } = await import("node:path");
+  const { mcpStatus } = await import("./mcp-register.js");
+
+  const home = mkdtempSync(join(tmpdir(), "pr-mcp-status-"));
+  const originalHome = process.env.HOME;
+  process.env.HOME = home;
+  try {
+    // No configs at all: reported as absent, not as "not registered".
+    let rows = await mcpStatus(["claude-code", "codex"]);
+    assert.deepEqual(rows.map((r) => r.configFound), [false, false]);
+
+    // Present but not registered — the --no-mcp state.
+    writeFileSync(join(home, ".claude.json"), JSON.stringify({ mcpServers: {} }));
+    mkdirSync(join(home, ".codex"), { recursive: true });
+    writeFileSync(join(home, ".codex", "config.toml"), 'model = "gpt-5"\n');
+    rows = await mcpStatus(["claude-code", "codex"]);
+    assert.deepEqual(rows.map((r) => r.registered), [false, false]);
+    assert.deepEqual(rows.map((r) => r.conflict), [false, false]);
+    assert.deepEqual(rows.map((r) => r.configFound), [true, true]);
+
+    // Someone else's server under our name.
+    writeFileSync(
+      join(home, ".claude.json"),
+      JSON.stringify({ mcpServers: { [SERVER_NAME]: { command: "/my/own/build" } } }),
+    );
+    writeFileSync(
+      join(home, ".codex", "config.toml"),
+      `[mcp_servers.${SERVER_NAME}]\ncommand = "mine"\n`,
+    );
+    rows = await mcpStatus(["claude-code", "codex"]);
+    assert.deepEqual(rows.map((r) => r.conflict), [true, true]);
+    assert.deepEqual(rows.map((r) => r.registered), [false, false]);
+
+    // Ours.
+    writeFileSync(
+      join(home, ".claude.json"),
+      JSON.stringify(applyClaudeRegistry({})),
+    );
+    writeFileSync(join(home, ".codex", "config.toml"), renderCodexMcp(""));
+    rows = await mcpStatus(["claude-code", "codex"]);
+    assert.deepEqual(rows.map((r) => r.registered), [true, true]);
+    assert.deepEqual(rows.map((r) => r.conflict), [false, false]);
+  } finally {
+    process.env.HOME = originalHome;
+  }
+}
+
+console.log("mcp-register tests passed");

package/src/mcp.js

@@ -0,0 +1,256 @@
+/* PennyRouter MCP server (stdio).
+
+   Solves the last mile: a thread you can read in the browser is not a thread you can code from.
+   These two tools let an agent take a share link and either read it or *become* it.
+
+     thread_read    fetch + parse, return the transcript to the model. For "what did we decide
+                    in this chat?" — the body lands in the caller's context, which is the point.
+     thread_resume  fetch + parse, write a resumable session for Claude Code OR Codex, return
+                    only a path and a resume command. For "let's continue coding from this chat"
+                    — the transcript never enters the caller's context, so moving a 200-turn
+                    thread costs the caller nothing. That asymmetry is the whole reason for two
+                    tools rather than one with a flag.
+
+   Because the destination is a parameter, "resume this Perplexity thread in Codex" and "…in
+   Claude Code" are the same call with a different `harness`. Each harness has its own writer:
+   the two on-disk formats share nothing structurally (see thread-session-codex.js).
+
+   ALL SCRAPING STAYS SERVER-SIDE. This process holds no adapters, no fetcher credentials and no
+   provider knowledge; it POSTs a URL to the gateway and gets a canonical thread back. What ships
+   to a user's machine is a client, not the machinery.
+
+   Hand-rolled JSON-RPC rather than @modelcontextprotocol/sdk: this package has zero dependencies
+   and is installed by `npx pennyrouter`, where every transitive dep is a supply-chain surface and
+   a slower cold start. The protocol surface actually needed here is four methods. */
+
+import { createInterface } from "node:readline";
+import { execFileSync } from "node:child_process";
+
+import { writeSession, VERIFIED_MIN, VERIFIED_MAX } from "./thread-session.js";
+import { writeSession as writeCodexSession } from "./thread-session-codex.js";
+
+const PROTOCOL_VERSION = "2024-11-05";
+
+const TOOLS = [
+  {
+    name: "thread_read",
+    description:
+      "Fetch an AI conversation from a share link (ChatGPT, Claude, Gemini, Perplexity) and " +
+      "return its transcript. Use when the user wants to discuss, summarize or ask about a " +
+      "past conversation. The transcript enters your context — for long threads that are " +
+      "meant to be continued as work, prefer thread_resume.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        url: { type: "string", description: "The share link to read." },
+      },
+      required: ["url"],
+    },
+  },
+  {
+    name: "thread_resume",
+    description:
+      "Fetch an AI conversation from a share link and write it as a resumable coding-agent " +
+      "session (Claude Code or Codex), so the user can resume into it and continue coding with " +
+      "that conversation as history. Use when the user wants to CONTINUE or BUILD FROM a past " +
+      "chat rather than talk about it. Returns a session id and path; the transcript is " +
+      "deliberately NOT returned, so importing a long thread costs you no context.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        url: { type: "string", description: "The share link to import." },
+        directory: {
+          type: "string",
+          description:
+            "Absolute path to the workspace the session should resume in. Defaults to the " +
+            "current working directory.",
+        },
+        harness: {
+          type: "string",
+          enum: ["claude-code", "codex"],
+          description:
+            "Which agent should be able to resume it. Defaults to claude-code. Use codex when " +
+            "the user asks to continue the conversation in Codex.",
+        },
+      },
+      required: ["url"],
+    },
+  },
+];
+
+/** `<tool> --version`, or null when the tool is not installed. The writers version-gate on this
+    and refuse rather than write a session file that only fails at resume time. */
+function toolVersion(binary) {
+  try {
+    return execFileSync(binary, ["--version"], { encoding: "utf8", stdio: ["ignore", "pipe", "ignore"] }).trim();
+  } catch {
+    return null;
+  }
+}
+
+async function fetchCanonical(url, { gatewayBaseUrl, apiKey }) {
+  const response = await fetch(`${gatewayBaseUrl}/v1/penny/threads/canonical`, {
+    method: "POST",
+    headers: {
+      "content-type": "application/json",
+      authorization: `Bearer ${apiKey}`,
+    },
+    body: JSON.stringify({ url }),
+  });
+
+  if (!response.ok) {
+    let detail = `HTTP ${response.status}`;
+    try {
+      const body = await response.json();
+      // The gateway's 400s carry copy written for a person; surface it rather than a status.
+      if (body?.detail) detail = body.detail;
+    } catch {
+      /* non-JSON error body; the status is all we have */
+    }
+    throw new Error(detail);
+  }
+  return response.json();
+}
+
+function transcript(thread) {
+  const lines = [`# ${thread.title || "Imported thread"}`];
+  if (thread.source_url) lines.push(`Source: ${thread.source_url}`);
+  lines.push("");
+  for (const message of thread.messages || []) {
+    const body = (message.blocks || [])
+      .map((b) => {
+        if (b.type === "text") return b.text;
+        if (b.type === "file") return ["```" + (b.language || ""), b.text, "```"].join("\n");
+        if (b.type === "thinking") return null;
+        if (b.type === "tool_use") return `[used ${b.name}]`;
+        if (b.type === "tool_result") return `[tool result] ${b.output || ""}`;
+        return null;
+      })
+      .filter((t) => t && String(t).trim())
+      .join("\n\n");
+    if (!body.trim()) continue;
+    lines.push(`## ${message.role}`, body, "");
+  }
+  return lines.join("\n").trim();
+}
+
+async function callTool(name, args, context) {
+  const url = String(args?.url || "").trim();
+  if (!url) throw new Error("a share link is required");
+
+  if (name === "thread_read") {
+    const thread = await fetchCanonical(url, context);
+    return transcript(thread);
+  }
+
+  if (name === "thread_resume") {
+    const cwd = String(args?.directory || process.cwd());
+    const harness = String(args?.harness || "claude-code").toLowerCase();
+    if (harness !== "claude-code" && harness !== "codex") {
+      throw new Error(`unknown harness "${harness}"; expected claude-code or codex`);
+    }
+
+    const codex = harness === "codex";
+    const version = codex ? toolVersion("codex") : toolVersion("claude");
+    const thread = await fetchCanonical(url, context);
+    const write = codex ? writeCodexSession : writeSession;
+    const { sessionId, path, messageCount } = write(thread, { cwd, version });
+
+    return [
+      `Imported "${thread.title}" (${thread.messages?.length || 0} messages, ` +
+        `~${thread.token_estimate || 0} tokens) from ${thread.origin_app || thread.source}.`,
+      "",
+      `Wrote a resumable ${codex ? "Codex" : "Claude Code"} session: ${messageCount} records`,
+      `  ${path}`,
+      "",
+      "Resume it with:",
+      codex
+        ? `  cd ${cwd} && codex resume ${sessionId}`
+        : `  cd ${cwd} && claude --resume ${sessionId}`,
+      "",
+      codex
+        ? "Tool calls were rendered as prose: Codex and the source harness do not share a tool " +
+          "format, so this is a readable continuation rather than a replay."
+        : "The transcript was written to disk and deliberately not returned here, so it did not " +
+          "consume this session's context.",
+    ].join("\n");
+  }
+
+  throw new Error(`unknown tool: ${name}`);
+}
+
+function send(message) {
+  process.stdout.write(JSON.stringify(message) + "\n");
+}
+
+function reply(id, result) {
+  send({ jsonrpc: "2.0", id, result });
+}
+
+/** Tool failures are reported as results with isError, not as JSON-RPC errors: the model should
+    see what went wrong and be able to tell the user, not have the call vanish into the harness. */
+function toolError(id, error) {
+  reply(id, {
+    content: [{ type: "text", text: `Failed: ${error?.message || String(error)}` }],
+    isError: true,
+  });
+}
+
+export async function runMcpServer({ gatewayBaseUrl, apiKey }) {
+  if (!apiKey) {
+    process.stderr.write(
+      "pennyrouter mcp: no API key. Run `npx pennyrouter install` first.\n",
+    );
+    process.exitCode = 1;
+    return;
+  }
+
+  const context = { gatewayBaseUrl, apiKey };
+  const rl = createInterface({ input: process.stdin });
+
+  for await (const line of rl) {
+    if (!line.trim()) continue;
+
+    let request;
+    try {
+      request = JSON.parse(line);
+    } catch {
+      continue; // a malformed frame has no id to answer to
+    }
+
+    const { id, method, params } = request;
+    try {
+      if (method === "initialize") {
+        reply(id, {
+          protocolVersion: PROTOCOL_VERSION,
+          capabilities: { tools: {} },
+          serverInfo: { name: "pennyrouter", version: "1.0.0" },
+        });
+      } else if (method === "tools/list") {
+        reply(id, { tools: TOOLS });
+      } else if (method === "tools/call") {
+        try {
+          const text = await callTool(params?.name, params?.arguments || {}, context);
+          reply(id, { content: [{ type: "text", text }] });
+        } catch (error) {
+          toolError(id, error);
+        }
+      } else if (method === "ping") {
+        reply(id, {});
+      } else if (id !== undefined) {
+        // Notifications (no id) are fire-and-forget and must never be answered.
+        send({ jsonrpc: "2.0", id, error: { code: -32601, message: `unknown method: ${method}` } });
+      }
+    } catch (error) {
+      if (id !== undefined) {
+        send({
+          jsonrpc: "2.0",
+          id,
+          error: { code: -32603, message: error?.message || String(error) },
+        });
+      }
+    }
+  }
+}
+
+export { VERIFIED_MIN, VERIFIED_MAX };

package/src/mcp.test.js

@@ -0,0 +1,237 @@
+import assert from "node:assert/strict";
+import { spawn } from "node:child_process";
+import { createServer } from "node:http";
+import { mkdtempSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { fileURLToPath } from "node:url";
+import { dirname, join } from "node:path";
+
+const here = dirname(fileURLToPath(import.meta.url));
+const binary = join(here, "..", "bin", "pennyrouter.js");
+
+const thread = {
+  schema_version: 1,
+  source: "perplexity_share",
+  title: "Kickplate removal",
+  origin_app: "Perplexity",
+  source_url: "https://www.perplexity.ai/search/x",
+  token_estimate: 892,
+  warnings: [],
+  messages: [
+    { key: "m0", ordinal: 0, role: "user", blocks: [{ type: "text", text: "UNIQUE-QUESTION" }] },
+    {
+      key: "m1",
+      ordinal: 1,
+      role: "assistant",
+      blocks: [{ type: "text", text: "UNIQUE-ANSWER" }],
+    },
+  ],
+};
+
+/** Stand in for the gateway so no scraping or network access is involved. */
+function stubGateway(handler) {
+  const server = createServer((req, res) => {
+    let body = "";
+    req.on("data", (c) => (body += c));
+    req.on("end", () => handler(req, body, res));
+  });
+  return new Promise((resolve) => {
+    server.listen(0, () => resolve({ server, port: server.address().port }));
+  });
+}
+
+/** Drive the server over stdio and collect the responses to `requests`. */
+function rpc(requests, { port, home }) {
+  return new Promise((resolve, reject) => {
+    const child = spawn(
+      process.execPath,
+      [binary, "mcp", "--penny-key", "pr-test", "--gateway-base-url", `http://127.0.0.1:${port}`],
+      { stdio: ["pipe", "pipe", "pipe"], env: { ...process.env, HOME: home } },
+    );
+    let out = "";
+    let err = "";
+    child.stdout.on("data", (d) => (out += d));
+    child.stderr.on("data", (d) => (err += d));
+    child.on("error", reject);
+    child.on("close", () => {
+      const messages = out
+        .trim()
+        .split("\n")
+        .filter(Boolean)
+        .map((line) => JSON.parse(line));
+      resolve({ messages, stderr: err });
+    });
+    for (const request of requests) child.stdin.write(JSON.stringify(request) + "\n");
+    setTimeout(() => child.stdin.end(), 900);
+  });
+}
+
+const home = mkdtempSync(join(tmpdir(), "pr-mcp-home-"));
+const workspace = mkdtempSync(join(tmpdir(), "pr-mcp-ws-"));
+
+// -- happy path -----------------------------------------------------------
+{
+  let requestBody = null;
+  let authHeader = null;
+  const { server, port } = await stubGateway((req, body, res) => {
+    requestBody = body;
+    authHeader = req.headers.authorization;
+    res.setHeader("content-type", "application/json");
+    res.end(JSON.stringify(thread));
+  });
+
+  const { messages } = await rpc(
+    [
+      { jsonrpc: "2.0", id: 1, method: "initialize", params: {} },
+      { jsonrpc: "2.0", id: 2, method: "tools/list" },
+      {
+        jsonrpc: "2.0",
+        id: 3,
+        method: "tools/call",
+        params: { name: "thread_read", arguments: { url: "https://www.perplexity.ai/search/x" } },
+      },
+      {
+        jsonrpc: "2.0",
+        id: 4,
+        method: "tools/call",
+        params: {
+          name: "thread_resume",
+          arguments: { url: "https://www.perplexity.ai/search/x", directory: workspace },
+        },
+      },
+    ],
+    { port, home },
+  );
+  server.close();
+
+  const byId = new Map(messages.map((m) => [m.id, m]));
+
+  assert.equal(byId.get(1).result.protocolVersion, "2024-11-05");
+  assert.equal(byId.get(1).result.serverInfo.name, "pennyrouter");
+
+  assert.deepEqual(
+    byId.get(2).result.tools.map((t) => t.name),
+    ["thread_read", "thread_resume"],
+  );
+
+  // The URL is forwarded to the gateway under the caller's key; no provider logic runs here.
+  assert.equal(JSON.parse(requestBody).url, "https://www.perplexity.ai/search/x");
+  assert.equal(authHeader, "Bearer pr-test");
+
+  // thread_read puts the conversation in the caller's context — that is its whole purpose.
+  const read = byId.get(3).result.content[0].text;
+  assert.ok(read.includes("UNIQUE-QUESTION"));
+  assert.ok(read.includes("UNIQUE-ANSWER"));
+
+  // thread_resume must NOT: the asymmetry between the two tools is the reason both exist, and
+  // a regression here silently reintroduces the token cost the tool was built to avoid.
+  const resumed = byId.get(4).result.content[0].text;
+  assert.ok(!resumed.includes("UNIQUE-QUESTION"), "thread_resume must not return the transcript");
+  assert.ok(!resumed.includes("UNIQUE-ANSWER"), "thread_resume must not return the transcript");
+  assert.ok(resumed.includes("claude --resume"), "it must tell the user how to resume");
+  assert.ok(resumed.includes("Kickplate removal"));
+  assert.equal(byId.get(4).result.isError, undefined);
+}
+
+// -- harness routing ------------------------------------------------------
+// "Resume this in Codex" is the same call with a different `harness`, so the tool must dispatch
+// to the right writer and print the right resume command. Skipped when codex is not installed:
+// the writer version-gates on `codex --version` and correctly refuses without it.
+{
+  const { server, port } = await stubGateway((req, body, res) => {
+    res.setHeader("content-type", "application/json");
+    res.end(JSON.stringify(thread));
+  });
+
+  const { messages } = await rpc(
+    [
+      { jsonrpc: "2.0", id: 1, method: "tools/list" },
+      {
+        jsonrpc: "2.0",
+        id: 2,
+        method: "tools/call",
+        params: {
+          name: "thread_resume",
+          arguments: { url: "https://x/y", directory: workspace, harness: "codex" },
+        },
+      },
+      {
+        jsonrpc: "2.0",
+        id: 3,
+        method: "tools/call",
+        params: {
+          name: "thread_resume",
+          arguments: { url: "https://x/y", directory: workspace, harness: "nonsense" },
+        },
+      },
+    ],
+    { port, home },
+  );
+  server.close();
+
+  const byId = new Map(messages.map((m) => [m.id, m]));
+
+  const schema = byId.get(1).result.tools.find((t) => t.name === "thread_resume").inputSchema;
+  assert.deepEqual(schema.properties.harness.enum, ["claude-code", "codex"]);
+
+  const codex = byId.get(2).result;
+  if (codex.isError) {
+    assert.match(codex.content[0].text, /Codex .*outside the range|ENOENT|not.*install/i);
+  } else {
+    assert.ok(codex.content[0].text.includes("codex resume"), "prints the codex resume command");
+    assert.ok(!codex.content[0].text.includes("claude --resume"));
+    assert.ok(!codex.content[0].text.includes("UNIQUE-QUESTION"), "still returns no transcript");
+  }
+
+  // An unknown harness is refused rather than silently defaulting to the wrong format.
+  assert.equal(byId.get(3).result.isError, true);
+  assert.match(byId.get(3).result.content[0].text, /unknown harness/);
+}
+
+// -- gateway failures reach the model as readable text --------------------
+{
+  const { server, port } = await stubGateway((req, body, res) => {
+    res.statusCode = 400;
+    res.setHeader("content-type", "application/json");
+    res.end(JSON.stringify({ detail: "That link returned 404. It may be private or deleted." }));
+  });
+
+  const { messages } = await rpc(
+    [
+      {
+        jsonrpc: "2.0",
+        id: 1,
+        method: "tools/call",
+        params: { name: "thread_read", arguments: { url: "https://chatgpt.com/share/gone" } },
+      },
+    ],
+    { port, home },
+  );
+  server.close();
+
+  const result = messages.find((m) => m.id === 1).result;
+  // Reported as an errored *result*, not a JSON-RPC error: the model should be able to relay
+  // what went wrong instead of the call vanishing inside the harness.
+  assert.equal(result.isError, true);
+  assert.ok(result.content[0].text.includes("may be private or deleted"));
+}
+
+// -- protocol hygiene -----------------------------------------------------
+{
+  const { server, port } = await stubGateway((req, body, res) => res.end("{}"));
+  const { messages } = await rpc(
+    [
+      { jsonrpc: "2.0", method: "notifications/initialized" }, // no id: must not be answered
+      { jsonrpc: "2.0", id: 7, method: "ping" },
+      { jsonrpc: "2.0", id: 8, method: "no/such/method" },
+    ],
+    { port, home },
+  );
+  server.close();
+
+  assert.equal(messages.length, 2, "a notification must never get a response");
+  assert.deepEqual(messages.find((m) => m.id === 7).result, {});
+  assert.equal(messages.find((m) => m.id === 8).error.code, -32601);
+}
+
+console.log("mcp tests passed");