mirror-mind 0.0.1 → 0.33.0

package/ts/src/mcp/guards.ts

@@ -0,0 +1,244 @@
+// Wallet guards for the MCP surface (CV22.DS9.TS1).
+//
+// This module has no oracle. Nothing here exists in Python: US1, US2, and TS2 were ports
+// graded by byte equality, and this is deliberate divergence, argued from the DS9 threat
+// model (item 3, denial of wallet) and sized from measured spend.
+//
+// What it guards, and why that shape:
+//
+//   * The risk is RATE, not dollars. Measured on the author's ledger, an embedding costs
+//     ~$0.000002 and the whole account spent $0.0001 on embeddings in seven days -- one
+//     dollar is ~500,000 calls. A USD ceiling that bites would have to be set at cents.
+//     What a runaway agent loop actually does is exhaust the provider's rate limit (whose
+//     429s then land on the user's OTHER work), stall at ~2s per call, and fill its own
+//     context. So the rate guard is the control and the ceiling is an opt-in backstop.
+//
+//   * State lives in the `llm_calls` ledger, not in this process. A user runs several MCP
+//     clients at once; a per-process counter is a belief, not a ceiling.
+//
+//   * The count is attributed. Extraction embeds every memory it creates, so a session
+//     close writes dozens of embedding rows in a minute. Counting all of them would refuse
+//     the agent because the USER ended a conversation -- so only rows marked as this
+//     surface's are counted.
+//
+//   * The decision is pure and the ledger read is at the edge, so the policy is testable
+//     against synthetic states and the refusal text is under test rather than in a comment.
+
+import type { Database } from "#db/database.ts";
+
+/**
+ * The `llm_calls.session_id` value marking a call made by the MCP surface.
+ *
+ * One fact in one column (D2). The first draft encoded the tool too
+ * (`mcp:search_memories`), to honour the AI-19 rider's "per-tool" phrasing; measured, that
+ * granularity buys nothing -- both paid tools cost one embedding per call and a global cap
+ * bounds the harm identically -- so it was rejected as two facts in one column. If per-tool
+ * attribution is ever needed it is a real column with a real migration, not a delimiter.
+ *
+ * `session_id` is the right column: free text, semantically "the session that made the
+ * call", and null on every one of the 225 embedding rows that existed when this was
+ * written, so the marker collides with nothing. It also makes MCP spend filterable in
+ * `inspect llm-calls --session mcp`, which is the operator's view of this surface.
+ */
+export const MCP_LEDGER_SESSION = "mcp";
+
+/** The tools whose calls cross an embedding provider, and are therefore counted. */
+export const PAID_TOOLS: readonly string[] = ["search_memories", "mirror_context"];
+
+export interface SpendPolicy {
+  /** Max attributed embedding calls inside the window. */
+  rateLimit: number;
+  /** Sliding window, in minutes. */
+  windowMinutes: number;
+  /** Trailing-24h USD ceiling, or null for none (the default). */
+  dailyUsdCeiling: number | null;
+}
+
+/** What the ledger says about this surface right now. */
+export interface SpendState {
+  /** Attributed embedding calls inside the window. */
+  callsInWindow: number;
+  /** Attributed spend over the trailing 24h. Unpriced rows contribute 0. */
+  usdLast24h: number;
+}
+
+export type SpendDecision =
+  | { allow: true }
+  | { allow: false; reason: "rate_limit" | "daily_ceiling"; text: string };
+
+export const DEFAULT_SPEND_POLICY: SpendPolicy = {
+  // A human-driven session rarely sustains three searches a minute; a loop at the measured
+  // ~2s per search reaches thirty inside one minute. The gap between the two is where this
+  // number lives.
+  rateLimit: 30,
+  windowMinutes: 10,
+  dailyUsdCeiling: null,
+};
+
+/**
+ * The unmetered way to use each paid tool, named in its own refusal.
+ *
+ * Per tool, because the advice has to be advice the refused tool can actually take:
+ * `mirror_context` has no layer or type filter, and telling an agent to use one is how it
+ * learns that refusal text is noise.
+ */
+const UNMETERED_ALTERNATIVE: Record<string, string> = {
+  search_memories:
+    "Filtered calls — journey, layer, or type, with no query — are not metered and still work.",
+  mirror_context: "Calling it without a query is not metered and still returns the context.",
+};
+
+function alternativeFor(tool: string): string {
+  return UNMETERED_ALTERNATIVE[tool] ?? "Calls that do not carry a query are not metered.";
+}
+
+/**
+ * Decide whether one paid call may proceed. Pure: no clock, no database.
+ *
+ * The refusal TEXT is produced here rather than at the call site because it is the control,
+ * not decoration. Keeping it here keeps it under test -- and the E2E is what tests the part
+ * a unit test cannot: whether a real model obeys it.
+ *
+ * Shape (prompt-engineer lens): lead with the fact, name the unmetered alternative, name
+ * the human who can lift the bound, instruction LAST because what comes last is what a
+ * model follows in the moment. Never a timed invitation: an agent told when to come back
+ * plans to come back, and the return is the loop.
+ *
+ * Two corrections came from the first E2E (2026-09-19), and both are the loop working:
+ *
+ *   * "Use a filter instead" was read by the model as "the error message suggests a way
+ *     around the limit", and it then admitted it did not know whether filtered calls
+ *     counted. A refusal that reads as a loophole hint teaches bypass in the server's own
+ *     voice. Saying plainly that filters are NOT METERED is the truth, grants nothing the
+ *     tool schema did not already expose, and removes the evasion framing.
+ *
+ *   * "Do not retry this tool" was read as "this call will not succeed": the agent moved
+ *     to the next topic and was refused four more times. The stop is now scoped to the
+ *     paid mode (another QUERY) and gated on the human rather than on nothing.
+ */
+export function decideSpend(tool: string, state: SpendState, policy: SpendPolicy): SpendDecision {
+  const stop = `Do not send another query to this tool until the user replies.`;
+  if (policy.dailyUsdCeiling !== null && state.usdLast24h >= policy.dailyUsdCeiling) {
+    return {
+      allow: false,
+      reason: "daily_ceiling",
+      text:
+        `${tool} is over the MCP spend ceiling the user set for today. ` +
+        `${alternativeFor(tool)} Ask the user before continuing. ${stop}`,
+    };
+  }
+  if (state.callsInWindow >= policy.rateLimit) {
+    return {
+      allow: false,
+      reason: "rate_limit",
+      text:
+        `${tool} is rate-limited (${policy.rateLimit} query searches in ${policy.windowMinutes} minutes). ` +
+        `${alternativeFor(tool)} Ask the user to raise MIRROR_MCP_EMBED_RATE_LIMIT if you ` +
+        `need more. ${stop}`,
+    };
+  }
+  return { allow: true };
+}
+
+/** The env slice the tunables read. `process.env` satisfies it. */
+export interface SpendPolicyEnv {
+  MIRROR_MCP_EMBED_RATE_LIMIT?: string;
+  MIRROR_MCP_EMBED_RATE_WINDOW_MINUTES?: string;
+  MIRROR_MCP_DAILY_USD_CEILING?: string;
+}
+
+function positiveNumber(name: string, raw: string, integer: boolean): number {
+  const value = Number(raw);
+  const valid = Number.isFinite(value) && value > 0 && (!integer || Number.isInteger(value));
+  if (!valid) {
+    throw new Error(
+      `${name} must be a positive ${integer ? "integer" : "number"}; got ${JSON.stringify(raw)}`,
+    );
+  }
+  return value;
+}
+
+/**
+ * Whether the wallet guards run: on unless `MIRROR_TS_MCP_GUARDS=0` (CV22.DS9.TS1).
+ *
+ * NOT one of the revert gates CV22.DS10.TS5 deleted. Those chose an ENGINE and left with
+ * the Python one; this switches a TypeScript behavior, and `=0` restores exactly what TS2
+ * shipped. Only an exact `"0"` turns the guards off, so an unrelated value cannot silently
+ * unguard the surface. (It was the routing module's generic `gateWithDefault` until that
+ * module stopped having gates; this is its only reader.)
+ */
+export function guardsEnabled(value: string | undefined): boolean {
+  return value !== "0";
+}
+
+/**
+ * Read the tunables, failing loudly on anything malformed.
+ *
+ * A typo in `.env` takes the MCP surface down with a named reason in the client's log
+ * rather than silently reverting to a default -- the DS8 rule. Silently unguarded while the
+ * user believes otherwise is the worse of the two failures.
+ */
+export function policyFromEnv(env: SpendPolicyEnv): SpendPolicy {
+  const rateLimitRaw = env.MIRROR_MCP_EMBED_RATE_LIMIT;
+  const windowRaw = env.MIRROR_MCP_EMBED_RATE_WINDOW_MINUTES;
+  const ceilingRaw = env.MIRROR_MCP_DAILY_USD_CEILING;
+  return {
+    rateLimit:
+      rateLimitRaw === undefined
+        ? DEFAULT_SPEND_POLICY.rateLimit
+        : positiveNumber("MIRROR_MCP_EMBED_RATE_LIMIT", rateLimitRaw, true),
+    windowMinutes:
+      windowRaw === undefined
+        ? DEFAULT_SPEND_POLICY.windowMinutes
+        : positiveNumber("MIRROR_MCP_EMBED_RATE_WINDOW_MINUTES", windowRaw, true),
+    dailyUsdCeiling:
+      ceilingRaw === undefined
+        ? DEFAULT_SPEND_POLICY.dailyUsdCeiling
+        : positiveNumber("MIRROR_MCP_DAILY_USD_CEILING", ceilingRaw, false),
+  };
+}
+
+/**
+ * Read what the ledger says about this surface: attributed calls inside the window and
+ * attributed spend over the trailing 24 hours.
+ *
+ * Cross-process by construction -- the state is rows, not memory, so a second MCP client
+ * shares the count rather than getting its own budget. One indexed-enough `SELECT` per paid
+ * call on a read-only WAL handle, which blocks nothing (measured at 552 rows: sub-
+ * millisecond; revisit if the table passes ~100k).
+ *
+ * `SUM(cost_usd)` skips NULLs, so a failed attempt contributes zero to the ceiling while
+ * still counting against the rate -- which is the right way round: a failing loop still
+ * hammers the provider, but it did not demonstrably spend.
+ */
+export function readSpendState(
+  db: Database,
+  policy: SpendPolicy,
+  now: Date = new Date(),
+): SpendState {
+  const windowStart = isoFrom(now, policy.windowMinutes);
+  const dayStart = isoFrom(now, 24 * 60);
+  const row = db
+    .prepare(
+      `SELECT
+         COUNT(CASE WHEN called_at >= ? THEN 1 END) AS calls_in_window,
+         COALESCE(SUM(CASE WHEN called_at >= ? THEN cost_usd END), 0) AS usd_last_24h
+       FROM llm_calls
+       WHERE session_id = ? AND role = 'embedding' AND called_at >= ?`,
+    )
+    .get(windowStart, dayStart, MCP_LEDGER_SESSION, dayStart);
+  return {
+    callsInWindow: Number(row?.calls_in_window ?? 0),
+    usdLast24h: Number(row?.usd_last_24h ?? 0),
+  };
+}
+
+/**
+ * `called_at` is microsecond ISO UTC on both engines (`nowIso` -> `toMicrosecondIso`), and
+ * this bound is compared lexically against it. A millisecond `toISOString()` sorts
+ * correctly against microsecond values because the prefix is identical up to the
+ * fractional digits and the comparison is `>=` on a lower bound.
+ */
+function isoFrom(now: Date, minutesAgo: number): string {
+  return new Date(now.getTime() - minutesAgo * 60_000).toISOString();
+}

package/ts/src/mcp/main.ts

@@ -0,0 +1,121 @@
+// Mirror MCP server entry point (CV22.DS9.US1 + US2).
+//
+// Launched by an MCP client over stdio. Unreferenced by any route until
+// CV22.DS9.TS2 flips the plugin manifest to it; it ships now so the parity
+// harness can spawn the real process the way a client would.
+//
+// Warning suppression is load-bearing, not cosmetic. `node:sqlite` emits an
+// ExperimentalWarning on import under the Node 24 floor this package declares,
+// and the Mirror skills silence it with `NODE_OPTIONS=--no-warnings` -- an
+// environment variable NO MCP CLIENT WILL SET. stderr is the client's log for
+// this server, and the parity harness asserts it stays empty, so the
+// suppression has to live in-process and run before anything reaches for the
+// database. (RS005: what lands in that log is read by the host.)
+
+process.removeAllListeners("warning");
+process.on("warning", (warning) => {
+  if (warning.name === "ExperimentalWarning") return;
+  process.stderr.write(`${warning.name}: ${warning.message}\n`);
+});
+
+const { resolveDbPath } = await import("#frontDoor/dbPath.ts");
+const { resolveSearchEmbeddingProvider } = await import("#frontDoor/searchRoute.ts");
+const { openDatabaseForLedgerAppend, openDatabaseReadOnly } = await import("#db/database.ts");
+const { ensureDatabaseReady } = await import("#db/readyOnOpen.ts");
+const { embeddingLedgerHook } = await import("#observability/ledgerHooks.ts");
+const { guardsEnabled, MCP_LEDGER_SESSION, policyFromEnv } = await import("./guards.ts");
+const { guardedRegistry } = await import("./boundary.ts");
+const { basename } = await import("node:path");
+const { wiredRegistry } = await import("./registry.ts");
+const { serve } = await import("./serve.ts");
+
+// READ-ONLY, by Navigator decision (CV22.DS9.US2, option (d)).
+//
+// The alternatives were a full pre-write backup on every launch -- measured at
+// 399 ms and a 49.3 MB snapshot on the owner's database, paid each time a
+// client spawns this process -- or opening writable without that gate, which
+// would narrow the DS4 write discipline inside a wiring story. Read-only is the
+// strongest posture and matches the DS9 threat model, which calls this server a
+// read oracle over private memory: it now cannot write even if a tool tried.
+//
+// The cost is named rather than hidden: the embedding-ledger row that a query
+// search would record (AI-09/D-003) is NOT written, so agent-initiated searches
+// go uncounted as spend. CV22.DS9.TS1's wallet guard reads that ledger, so TS2
+// must settle how this server opens its database before TS1 can guard what it
+// cannot see. Recorded in the DS9 package.
+//
+// Opened eagerly, as Python does: `serve()` constructs its MemoryClient before
+// reading the first line, so an unconfigured install fails at startup rather
+// than answering `initialize` and then failing all seven tools.
+const databasePath = resolveDbPath([]);
+
+// Activate before opening, also as Python does: `get_connection` bootstraps a
+// missing file and runs migrations under the bootstrap lock before handing back
+// a connection, so every Python entry point -- this server included -- gets a
+// current schema. US2 opened read-only and skipped it, which meant a pending
+// TS-authored migration would surface as a tool error on the first read that
+// touched the new shape, where Python would simply have applied it.
+const migration = ensureDatabaseReady(databasePath);
+if (migration.migrated) {
+  // The one thing this server writes to stderr in normal operation. A migration
+  // is an operator-visible event and stderr is the client's log for this
+  // process; the front door records the same fact, redacted the same way, in
+  // the front-door log. Ids and a backup file name only -- never content.
+  process.stderr.write(
+    `migrate_on_open applied=${migration.appliedIds.join(",")} backup=${
+      migration.backupPath ? basename(migration.backupPath) : "none"
+    }\n`,
+  );
+}
+
+const db = openDatabaseReadOnly(databasePath);
+
+// The single sanctioned write (TS2 D1), on its own connection, opened lazily so
+// a session that never searches never opens it. The handle can prepare nothing
+// but the `llm_calls` append, and it never reaches a tool: the registry gets
+// the SINK below, not this connection.
+// Attributed to this surface (TS1 D2): extraction embeds every memory it creates, so a
+// session close writes dozens of embedding rows in a minute. A wallet guard counting all
+// of them would refuse the agent because the USER ended a conversation. The marker is what
+// makes the count name the actor it guards -- and it never leaves this file, so no tool can
+// write a row claiming to be someone else.
+let ledgerDb: ReturnType<typeof openDatabaseForLedgerAppend> | null = null;
+const embeddingLedger = (info: Parameters<ReturnType<typeof embeddingLedgerHook>>[0]): void => {
+  ledgerDb ??= openDatabaseForLedgerAppend(databasePath);
+  embeddingLedgerHook(ledgerDb, { sessionId: MCP_LEDGER_SESSION })(info);
+};
+
+// The live provider resolves its config lazily, so a missing key degrades the
+// search to lexical-only instead of failing the server -- the same posture the
+// `memories --search` route takes.
+const embeddingProvider = await resolveSearchEmbeddingProvider();
+
+const registry = wiredRegistry({
+  db,
+  runtime: {
+    embeddingProvider,
+    embeddingLedger,
+    databasePath,
+    ...(process.env.MIRROR_HOME ? { mirrorHome: process.env.MIRROR_HOME } : {}),
+    ...(process.env.MIRROR_USER ? { user: process.env.MIRROR_USER } : {}),
+  },
+});
+
+// Guards on by default (CV22.DS9.TS1); `MIRROR_TS_MCP_GUARDS=0` restores exactly what TS2
+// shipped. The tunables are resolved here,
+// at startup, so a typo in `.env` fails the launch with a named reason in the client's log
+// rather than leaving the surface silently unguarded (the DS8 rule).
+//
+// The gate reverts REFUSALS only. The ledger row and its marker stay on either way: they
+// are observability, and turning off a guard is not a reason to stop recording what the
+// agent spends.
+const guarded = guardsEnabled(process.env.MIRROR_TS_MCP_GUARDS)
+  ? guardedRegistry(registry, { db, policy: policyFromEnv(process.env) })
+  : registry;
+
+await serve({ registry: guarded });
+
+// Input ended and every response has drained (`serve` does not resolve before
+// that). Exiting explicitly keeps the process from lingering on an open stdin
+// handle in clients that leave the pipe half-open.
+process.exit(0);

package/ts/src/mcp/payload.ts

@@ -0,0 +1,141 @@
+// Python-compatible JSON encoding for the MCP surface (CV22.DS9.US1 + US2).
+//
+// One encoder, two shapes. The JSON-RPC envelope is written compactly with
+// Python's default separators (`", "` / `": "`); tool payloads are written with
+// `indent=2`. Both come from `json.dumps` in the oracle, so both live here --
+// two modules would be the same rules maintained twice.
+//
+// Two places where `JSON.stringify` is not enough:
+//
+// 1. **Separators.** Python writes `{"a": 1, "b": 2}`; JS writes `{"a":1,"b":2}`.
+//    Semantically identical, byte-wise different, and the parity claim is about
+//    bytes (see the US1 plan).
+//
+// 2. **Whole floats.** Python writes `2.0` for a float that happens to be whole;
+//    JS writes `2`, and JavaScript has no int/float distinction to recover from
+//    (`2.0 === 2`). Measured on the real database: `detect_persona` returns
+//    scores of `1.0` and `2.0` routinely. So float-ness is carried at runtime by
+//    `PyFloat`, wrapped at the mapper for exactly the fields the oracle types as
+//    `float`. A compile-time brand cannot do this -- it is erased before the
+//    encoder ever sees the value.
+//
+// Escaping is delegated to `JSON.stringify` for every scalar and object key, so
+// string escaping, unicode (Python runs `ensure_ascii=False`, which matches JS),
+// and number formatting stay exactly what the platform does.
+
+/**
+ * A number the Python oracle types as `float`, so it renders `2.0` where an int
+ * would render `2`. A class rather than a branded type because the distinction
+ * must survive to runtime.
+ */
+export class PyFloat {
+  // An explicit field, not a parameter property: Node runs TypeScript in
+  // strip-only mode, which rejects `constructor(readonly value: number)`.
+  readonly value: number;
+
+  constructor(value: number) {
+    this.value = value;
+  }
+}
+
+/** Wrap a value the oracle types as `float`. */
+export function pyFloat(value: number): PyFloat {
+  return new PyFloat(value);
+}
+
+export interface PythonJsonOptions {
+  /** Spaces per level. Omit or pass 0 for Python's compact default. */
+  indent?: number;
+}
+
+/** Encode a value the way Python's `json.dumps` would. */
+export function pythonJson(value: unknown, options: PythonJsonOptions = {}): string {
+  const indent = options.indent ?? 0;
+  return encode(value, indent, 0);
+}
+
+/** Encode one JSON-RPC line: compact, Python separators. */
+export function encodeJsonLine(value: unknown): string {
+  return pythonJson(value);
+}
+
+/**
+ * Render a float the way Python's `repr` does.
+ *
+ * Two differences from `String(n)`, both measured against `json.dumps`:
+ * whole values keep a `.0` (`2` -> `2.0`), and exponents are written with at
+ * least two digits (`1e-7` -> `1e-07`). A value already in exponent form never
+ * gains a `.0` -- Python writes `1e+22`, not `1e+22.0`.
+ */
+function encodeFloat(value: number): string {
+  if (!Number.isFinite(value)) {
+    // Python emits bare Infinity/NaN here; no MCP payload carries them, and a
+    // silent mismatch would be worse than a loud failure.
+    throw new TypeError(`cannot encode non-finite float: ${value}`);
+  }
+  if (Object.is(value, -0)) return "-0.0";
+
+  const rendered = String(value);
+  const exponentIndex = rendered.indexOf("e");
+  if (exponentIndex === -1) {
+    return Number.isInteger(value) ? `${rendered}.0` : rendered;
+  }
+
+  const mantissa = rendered.slice(0, exponentIndex);
+  const sign = rendered[exponentIndex + 1] === "-" ? "-" : "+";
+  const digits = rendered.slice(exponentIndex + 1).replace(/^[+-]/, "");
+  return `${mantissa}e${sign}${digits.padStart(2, "0")}`;
+}
+
+function encode(value: unknown, indent: number, depth: number): string {
+  if (value instanceof PyFloat) return encodeFloat(value.value);
+  if (value === null || value === undefined) return "null";
+
+  const type = typeof value;
+  if (type === "string" || type === "boolean") return JSON.stringify(value);
+  if (type === "number") {
+    if (!Number.isFinite(value as number)) {
+      throw new TypeError(`cannot encode non-finite number: ${String(value)}`);
+    }
+    return JSON.stringify(value);
+  }
+
+  if (Array.isArray(value)) {
+    if (value.length === 0) return "[]";
+    const items = value.map((item) => encode(item, indent, depth + 1));
+    return wrap("[", items, "]", indent, depth);
+  }
+
+  if (type === "object") {
+    // Only plain objects are data. A Date, Map, or class instance would encode
+    // as `{}` through Object.entries -- silently losing content that Python
+    // would have rendered through `default=str`. Reject it instead.
+    const prototype = Object.getPrototypeOf(value);
+    if (prototype !== Object.prototype && prototype !== null) {
+      throw new TypeError(
+        `cannot encode ${(value as object).constructor?.name ?? "object"} as Python JSON`,
+      );
+    }
+    const entries = Object.entries(value as Record<string, unknown>).filter(
+      ([, entryValue]) => entryValue !== undefined,
+    );
+    if (entries.length === 0) return "{}";
+    const items = entries.map(
+      ([key, entryValue]) => `${JSON.stringify(key)}: ${encode(entryValue, indent, depth + 1)}`,
+    );
+    return wrap("{", items, "}", indent, depth);
+  }
+
+  // Python's `default=str` would stringify anything else. There is no honest
+  // port of that -- `String(obj)` is `[object Object]`, never Python's repr --
+  // and after the DS9.US2 D1 fix no tool payload contains such a value. Failing
+  // loudly puts the surprise in a test rather than in a client's context window.
+  throw new TypeError(`cannot encode value of type ${type} as Python JSON`);
+}
+
+function wrap(open: string, items: string[], close: string, indent: number, depth: number): string {
+  if (indent <= 0) return `${open}${items.join(", ")}${close}`;
+  const inner = " ".repeat(indent * (depth + 1));
+  const outer = " ".repeat(indent * depth);
+  return `${open}\n${inner}${items.join(`,\n${inner}`)}\n${outer}${close}`;
+}

package/ts/src/mcp/protocol.ts

@@ -0,0 +1,141 @@
+// MCP JSON-RPC dispatch (CV22.DS9.US1).
+//
+// A faithful port of `handle_message` in `src/memory/mcp/server.py`. Pure over
+// the message and the registry -- no I/O, no database, no stdio -- which is what
+// makes it gradeable against a golden. `serve.ts` is the thin loop around it.
+//
+// Key-insertion order matters here. Responses are serialized with
+// `JSON.stringify`, which emits keys in insertion order, and the parity golden
+// compares the resulting bytes against Python's `json.dumps`. Every object
+// literal below is written in the oracle's field order for that reason.
+
+import type { ToolRegistry } from "./registry.ts";
+
+export const PROTOCOL_VERSION = "2025-06-18";
+export const SERVER_NAME = "mirror-mind";
+
+/** A JSON-RPC id: any JSON value, including `0`, `""`, and `null`. */
+export type JsonRpcId = unknown;
+
+export interface JsonRpcResponse {
+  jsonrpc: "2.0";
+  id: JsonRpcId;
+  result?: unknown;
+  error?: { code: number; message: string };
+}
+
+export interface HandleOptions {
+  /** Injectable so the parity test can freeze what `importlib.metadata` returns. */
+  serverVersion: string;
+}
+
+function result(id: JsonRpcId, value: Record<string, unknown>): JsonRpcResponse {
+  return { jsonrpc: "2.0", id, result: value };
+}
+
+function error(id: JsonRpcId, code: number, message: string): JsonRpcResponse {
+  return { jsonrpc: "2.0", id, error: { code, message } };
+}
+
+/**
+ * Render a value the way Python's f-string `str()` would, for the one place the
+ * oracle interpolates an arbitrary argument into a message: `Unknown tool: {name}`.
+ * A missing name is `None` in Python, not `undefined`; `True`/`False` are
+ * capitalized. Getting this wrong is invisible until a client logs the string.
+ */
+function pythonStr(value: unknown): string {
+  if (value === undefined || value === null) return "None";
+  if (value === true) return "True";
+  if (value === false) return "False";
+  if (typeof value === "string") return value;
+  return JSON.stringify(value) ?? String(value);
+}
+
+/**
+ * Python's `x or {}`: falsy values (None, {}, [], "", 0, False) become `{}`.
+ * Used for `params` and `arguments`, where the oracle relies on that coercion.
+ */
+function orEmptyObject(value: unknown): unknown {
+  if (value === undefined || value === null || value === false || value === 0 || value === "") {
+    return {};
+  }
+  if (Array.isArray(value)) return value.length === 0 ? {} : value;
+  if (typeof value === "object" && Object.keys(value as object).length === 0) return {};
+  return value;
+}
+
+/** Extract the error text the way Python's `str(exc)` would. */
+function errorText(thrown: unknown): string {
+  if (thrown instanceof Error) return thrown.message;
+  return String(thrown);
+}
+
+/**
+ * Dispatch one JSON-RPC message. Returns a response, or `null` for notifications.
+ *
+ * Request-vs-notification is decided by KEY PRESENCE (`"id" in message`), exactly
+ * as the oracle does -- so `{"id": 0}`, `{"id": ""}` and `{"id": null}` are all
+ * requests whose id must be echoed. Deciding on truthiness instead leaves those
+ * clients waiting forever for a response that is never written.
+ */
+export async function handleMessage(
+  message: Record<string, unknown>,
+  registry: ToolRegistry,
+  options: HandleOptions,
+): Promise<JsonRpcResponse | null> {
+  const method = message.method;
+  const isNotification = !("id" in message);
+  const id = message.id;
+
+  if (typeof method !== "string") {
+    return isNotification ? null : error(id, -32600, "Invalid Request");
+  }
+
+  if (method === "initialize") {
+    const params = orEmptyObject(message.params) as Record<string, unknown>;
+    const requested = params.protocolVersion;
+    return result(id, {
+      protocolVersion: typeof requested === "string" ? requested : PROTOCOL_VERSION,
+      capabilities: { tools: {} },
+      serverInfo: { name: SERVER_NAME, version: options.serverVersion },
+    });
+  }
+
+  if (method === "notifications/initialized") return null;
+
+  if (method === "ping") return result(id, {});
+
+  if (method === "tools/list") {
+    return result(id, {
+      tools: registry.list.map((tool) => ({
+        name: tool.name,
+        description: tool.description,
+        inputSchema: tool.inputSchema,
+      })),
+    });
+  }
+
+  if (method === "tools/call") {
+    const params = orEmptyObject(message.params) as Record<string, unknown>;
+    const name = params.name;
+    const args = orEmptyObject(params.arguments);
+    const tool = typeof name === "string" ? registry.byName.get(name) : undefined;
+    if (tool === undefined) return error(id, -32602, `Unknown tool: ${pythonStr(name)}`);
+    try {
+      const text = await tool.handler(args);
+      return result(id, { content: [{ type: "text", text }], isError: false });
+    } catch (thrown) {
+      // Tool errors are results, not protocol errors: the client sees a readable
+      // failure and the session continues. A protocol error here would look to
+      // the client like a broken server.
+      return result(id, {
+        content: [{ type: "text", text: `Error: ${errorText(thrown)}` }],
+        isError: true,
+      });
+    }
+  }
+
+  // Unknown notifications are ignored; unknown requests get an error. Same
+  // method string, different outcome, decided only by the presence of `id`.
+  return isNotification ? null : error(id, -32601, `Method not found: ${method}`);
+}