bantamkit-mcp 0.35.8 → 0.35.9

package/dist/mcp/server.js

@@ -3,7 +3,7 @@
  *
  * A port of `runtime-py/src/bantamkit/mcpserver.py`'s `build_server`, across two unrelated
  * SDK lineages — Python runs `mcp` 2.0.0 (`from mcp.server import MCPServer`), this runs
- * `@modelcontextprotocol/sdk` 1.30.0. Where the two SDKs make a difference unavoidable it is
+ * `@modelcontextprotocol/sdk` 1.31.0. Where the two SDKs make a difference unavoidable it is
  * a `ruling` case in `tools/conformance/suites/wire.mjs`, carrying its reason and required to
  * KEEP differing — a ruling whose case quietly started matching fails the suite too. Where
  * they do not, this file takes the reference's answer even when the SDK offers an easier one.
@@ -27,10 +27,10 @@
  * part of the wire and no asset carries it.
  */
 import { existsSync, readFileSync, realpathSync, statSync } from 'node:fs';
-import { dirname, join } from 'node:path';
+import { dirname, join, sep } from 'node:path';
 import { fileURLToPath } from 'node:url';
 import { Server } from '@modelcontextprotocol/sdk/server/index.js';
-import { CallToolRequestSchema, ErrorCode, GetPromptRequestSchema, ListPromptsRequestSchema, ListResourceTemplatesRequestSchema, ListResourcesRequestSchema, ListToolsRequestSchema, ReadResourceRequestSchema, } from '@modelcontextprotocol/sdk/types.js';
+import { CallToolRequestSchema, ErrorCode, GetPromptRequestSchema, InitializeRequestSchema, ListPromptsRequestSchema, ListResourceTemplatesRequestSchema, ListResourcesRequestSchema, ListToolsRequestSchema, PingRequestSchema, ReadResourceRequestSchema, } from '@modelcontextprotocol/sdk/types.js';
 import { AssetNotFound, assetsRoot, loadSkill, loadToolAsset } from '../assets.js';
 import { BantamError } from '../errors.js';
 import { bantamkitReadUnknownPart, documentError, documentManifest, documentOffsetPastEnd, documentPage, schemaError, toolFailed, } from '../contract.js';
@@ -471,6 +471,22 @@ function runTool(name, memory, args, version, log, documents) {
         out.set('bantamkit_degraded', { t: 'str', v: line });
         return { t: 'dict', v: out };
     };
+    /**
+     * A reply that is ONE JSON DOCUMENT rendered as text (`skill_audit`, `token_ledger`), plus
+     * the footer if there is one, as a `bantamkit_degraded` key LAST in that document (#124).
+     *
+     * `noted` would append a sentence after the closing brace and the reply would stop parsing.
+     * The key is spliced into the text rather than the document being re-parsed, so every byte
+     * of a degraded reply before the key is the healthy reply's: `asJson` is
+     * `JSON.stringify(dict, null, 2)` of a non-empty object, so it always ends `\n}`, and the key
+     * goes in at that two-space indent, exactly where `json.dumps(indent=2)` would put it.
+     */
+    const notedJson = (document) => {
+        const line = notice();
+        if (line === '')
+            return document;
+        return `${document.slice(0, -2)},\n  "bantamkit_degraded": ${JSON.stringify(line)}\n}`;
+    };
     switch (name) {
         case 'memory_save': {
             const links = args.get('links');
@@ -802,7 +818,7 @@ function runTool(name, memory, args, version, log, documents) {
                     findings: result.findings.length,
                     omissions: result.omissions.length,
                 });
-                return { value: { t: 'str', v: noted(result.asJson()) }, wrapped: true };
+                return { value: { t: 'str', v: notedJson(result.asJson()) }, wrapped: true };
             });
         }
         case 'repo_map': {
@@ -921,7 +937,7 @@ function runTool(name, memory, args, version, log, documents) {
                     requests: result.requests,
                     sessions: result.sessions.length,
                 });
-                return { value: { t: 'str', v: noted(tokenledger.asJson(result)) }, wrapped: true };
+                return { value: { t: 'str', v: notedJson(tokenledger.asJson(result)) }, wrapped: true };
             });
         }
         case 'work_plan':
@@ -1063,7 +1079,8 @@ export function buildServer(memory, wire, version, log = EventLog.fromEnv(memory
     }));
     server.setRequestHandler(ReadResourceRequestSchema, (request) => {
         const uri = request.params.uri;
-        const skill = /^bantamkit:\/\/skills\/([^/]*)$/.exec(uri);
+        const skillName = templateName(uri, 'bantamkit://skills/');
+        const skill = skillName === null ? null : [uri, skillName];
         if (skill) {
             // A skill that pairs with a tool is served on that tool's surfaces and no other. The
             // pairing is the one the reference's `filegraph.py` spells — `load_tool("file_graph")`
@@ -1094,9 +1111,14 @@ export function buildServer(memory, wire, version, log = EventLog.fromEnv(memory
             }
             return { contents: [{ mimeType: 'text/plain', text, uri }] };
         }
-        const rubric = /^bantamkit:\/\/rubrics\/([^/]*)$/.exec(uri);
+        const rubricName = templateName(uri, 'bantamkit://rubrics/');
+        const rubric = rubricName === null ? null : [uri, rubricName];
         if (rubric) {
-            const path = join(assetsRoot(), 'rubrics', `${rubric[1]}.yaml`);
+            // Joined as TEXT, not with `path.join`: `join` folds `x/../y` lexically, and the
+            // reference's `Path / f"{name}.yaml"` does not, so `x%2F..%2Fcode-quality` (no
+            // traversal ABOVE the start, so the security check passes it) would read
+            // `code-quality.yaml` here and nothing there. The kernel resolves `x/..` on both.
+            const path = `${join(assetsRoot(), 'rubrics')}${sep}${rubric[1]}.yaml`;
             let text;
             try {
                 text = pyReadText(path);
@@ -1106,11 +1128,8 @@ export function buildServer(memory, wire, version, log = EventLog.fromEnv(memory
             }
             return { contents: [{ mimeType: 'text/plain', text, uri }] };
         }
-        // The template variable matches ONE segment and MAY BE EMPTY — measured: the reference
-        // answers `bantamkit://skills/` with -32603 `unknown skill asset: `, not with "unknown
-        // resource", so `[^/]*` and not `[^/]+`. A traversal is still not a match at all,
-        // because `bantamkit://skills/../../etc/passwd` has separators in it, and the reference
-        // answers that one -32602.
+        // No template took the URI (`templateName` says how the reference decides), so the
+        // reference's `ResourceNotFoundError`: -32602 `Unknown resource: <uri>` (#180).
         throw rpcError(ErrorCode.InvalidParams, `Unknown resource: ${uri}`, { uri });
     });
     server.setRequestHandler(CallToolRequestSchema, (request, extra) => {
@@ -1158,14 +1177,140 @@ export function buildServer(memory, wire, version, log = EventLog.fromEnv(memory
             ...(structuredValue === null ? {} : { structuredContent: toJs(structuredValue) }),
         };
     });
+    guardRequests(server, wire);
     return server;
 }
+/**
+ * The reference's ONE answer to a request it will not hand to a handler, byte for byte:
+ * `mcp` 2.0.0's `ServerRunner._on_request` raises `MCPError(INVALID_PARAMS, "Invalid request
+ * parameters", data="")` both for params its pydantic model refuses and for a served method
+ * asked before `initialize` was accepted ("pinned compat: the same error shape the union
+ * validation produced"). No pydantic or zod text reaches the wire.
+ */
+const invalidParams = () => rpcError(ErrorCode.InvalidParams, 'Invalid request parameters', '');
+/** The request schema of every method this server answers; `guardRequests` refuses a gap. */
+const REQUEST_SCHEMAS = new Map([
+    InitializeRequestSchema,
+    PingRequestSchema,
+    ListToolsRequestSchema,
+    CallToolRequestSchema,
+    ListResourcesRequestSchema,
+    ListResourceTemplatesRequestSchema,
+    ReadResourceRequestSchema,
+    ListPromptsRequestSchema,
+    GetPromptRequestSchema,
+].map((schema) => [schema.shape.method.value, schema]));
+/** Only `ping` may be asked before `initialize` (`runner._INIT_EXEMPT`). */
+const INIT_EXEMPT = new Set(['ping']);
+/**
+ * #147 AND #178: the two refusals the reference makes before a handler runs, put in front of
+ * every handler the SDK holds.
+ *
+ * #147. The TS SDK parses a request's params INSIDE the handler it registered, so a refusal
+ * left as a thrown zod error: -32603 Internal error with the issue list pretty-printed as the
+ * message (`tools/call` with `params: {}`, `arguments: "notadict"`, `resources/read` with no
+ * `uri`, ...). The reference answers all of them -32602 with a short message. The schema is
+ * the SDK's own, checked here first, so what is refused does not change — only how.
+ *
+ * #178. The TS SDK has no initialization gate: a `tools/call` with no `initialize` before it
+ * was served. The reference refuses every method it serves, except `ping`, until an
+ * `initialize` has been ACCEPTED (its answer, not `notifications/initialized`), with the same
+ * -32602; a method it does not serve is -32601 either way, which the SDK already says because
+ * an unserved method never reaches this table. The gate opens SYNCHRONOUSLY when a valid
+ * `initialize` reaches its handler: the reference parks its read loop while `initialize` runs,
+ * so a request written in the same chunk behind it is served, and here the next handler call
+ * is a later microtask in arrival order. `_oninitialize` cannot refuse a valid request (it
+ * negotiates down to its own latest version), so opening before it returns is not optimism.
+ *
+ * THE SEAM IS THE SDK'S HANDLER TABLE, `Protocol._requestHandlers`: TypeScript-private, and
+ * the only place that sees `initialize` and `ping`, which the SDK registers itself. Pinned to
+ * the capped SDK, and checked here: a table that is not a Map, or a handler with no schema
+ * in `REQUEST_SCHEMAS`, stops the server at startup rather than serving it unguarded.
+ */
+function guardRequests(server, wire) {
+    const table = server._requestHandlers;
+    if (!(table instanceof Map)) {
+        throw new Error('the MCP SDK keeps no _requestHandlers map: the #147/#178 request guard has no seam');
+    }
+    const handlers = table;
+    let accepted = false;
+    for (const [method, handler] of [...handlers]) {
+        const schema = REQUEST_SCHEMAS.get(method);
+        if (schema === undefined)
+            throw new Error(`no request schema for served method ${method}: the #147 guard would skip it`);
+        handlers.set(method, (request, extra) => {
+            // pydantic's optional fields (`cursor`, `arguments`, `_meta`, ...) are `X | None =
+            // None`, so `null` is the same as absent there; zod's `.optional()` refuses it. A
+            // REQUIRED field (`name`, `uri`) is still refused once its `null` is set aside.
+            const params = request.params;
+            if (params !== null && typeof params === 'object' && !Array.isArray(params)) {
+                for (const [key, value] of Object.entries(params))
+                    if (value === null)
+                        delete params[key];
+            }
+            // `?.`: the in-memory test harnesses hand `buildServer` a two-method stub for `wire`.
+            if (wire.paramsRefused?.(extra.requestId) === true || !schema.safeParse(request).success)
+                throw invalidParams();
+            if (method === 'initialize')
+                accepted = true;
+            else if (!accepted && !INIT_EXEMPT.has(method))
+                throw invalidParams();
+            return handler(request, extra);
+        });
+    }
+}
+/**
+ * `mcp` 2.0.0's `ResourceTemplate.matches` for a template `<prefix>{name}`: the decoded
+ * name, or `null` when the reference's resource manager would answer `Unknown resource`
+ * (#180). Three steps, each measured against the running reference:
+ *
+ * - `UriTemplate.match`: a URI past 65 536 code points is no match; the literal prefix must
+ *   be there; a simple `{name}` stops at `/ ? # & ,`, so a tail holding any of them is no
+ *   match (`memory?x=1`, `memory#frag`, `a/b`). The empty tail matches (`bantamkit://skills/`
+ *   is -32603 `unknown skill asset: ` on both sides).
+ * - `urllib.parse.unquote`: `%XX` runs decoded as UTF-8 with replacement, so `%6Demory` IS
+ *   `memory` and `..%2F..%2Fpackage` is `../../package`.
+ * - `ResourceSecurity`'s default policy on the decoded value: a NUL, a `..` that climbs
+ *   above the start (`/` and `\` both separators), or an absolute path (`/x`, `\x`, `C:`)
+ *   raises `ResourceSecurityError`, which the manager turns into `Unknown resource`.
+ *
+ * Before this the port matched `[^/]*` on the RAW text and answered -32603 `unknown skill
+ * asset: ..` for all three of the issue's URIs; neither side ever read outside the pack.
+ */
+function templateName(uri, prefix) {
+    if ([...uri].length > 65_536 || !uri.startsWith(prefix))
+        return null;
+    const raw = uri.slice(prefix.length);
+    if (/[/?#&,]/.test(raw))
+        return null;
+    const name = raw.replace(/(?:%[0-9A-Fa-f]{2})+/g, (run) => new TextDecoder('utf-8').decode(Uint8Array.from(run.split('%').slice(1), (h) => parseInt(h, 16))));
+    if (name.includes('\0') || climbs(name) || isAbsolutePath(name))
+        return null;
+    return name;
+}
+/** `mcp.shared.path_security.contains_path_traversal`: does a `..` climb above the start? */
+function climbs(value) {
+    let depth = 0;
+    for (const part of value.replace(/\\/g, '/').split('/')) {
+        if (part === '..') {
+            depth -= 1;
+            if (depth < 0)
+                return true;
+        }
+        else if (part !== '' && part !== '.')
+            depth += 1;
+    }
+    return false;
+}
+/** `mcp.shared.path_security.is_absolute_path`: POSIX, UNC/root-relative, or a drive letter. */
+const isAbsolutePath = (value) => value !== '' && (value[0] === '/' || value[0] === '\\' || /^[A-Za-z]:/.test(value));
 /** `params.arguments` out of the raw request line, with every number literal intact. */
 function argumentsFrom(line) {
     try {
         const params = asDict(parseJson(line)).get('params');
         const args = params === undefined ? undefined : asDict(params).get('arguments');
-        return args ?? { t: 'dict', v: new Map() };
+        // `arguments: null` is no arguments (pydantic's `dict | None = None`, #147).
+        return args === undefined || args.t === 'null' ? { t: 'dict', v: new Map() } : args;
     }
     catch {
         // Unreachable over a line the SDK already parsed; a re-parse failure must not be the

package/dist/mcp/transport.d.ts

@@ -10,13 +10,13 @@
  *    The SDK exposes no hook for this — `ReadBuffer.readMessage` parses inside the buffer and
  *    the buffer is private — so the buffering is done here instead. It is thirty lines
  *    (`indexOf('\n')`, strip a trailing `\r`) and it keeps the LINE next to the parsed
- *    message, keyed by JSON-RPC id. A handler then re-reads its own arguments with
+ *    message, keyed PER MESSAGE (see 3). A handler then re-reads its own arguments with
  *    `pyjson.parseJson`, which tags `5.0` as a float and keeps an integer past 2^53 exact.
  *
  * 2. THE OUTGOING NUMBER LITERALS AND THE ENVELOPE ORDER. `serializeMessage` is
  *    `JSON.stringify(message) + '\n'`, which un-does the work above on the way out: the same
  *    `5.0` in a `structuredContent` leaves as `5`. So a tool handler registers the EXACT text
- *    of its result here, keyed by request id, and `send` splices it in. Everything else still
+ *    of its result here, keyed per message, and `send` splices it in. Everything else still
  *    goes through `JSON.stringify`, which is byte-for-byte what pydantic-core writes for
  *    strings, bools, nulls and safe integers.
  *
@@ -25,6 +25,30 @@
  *    order is not observable to a conforming client, but it costs nothing here and it removes
  *    a difference from the list rather than adding a ruling to it.
  *
+ * 3. ONE ENTRY PER MESSAGE, NOT PER ID (#146, #148). The side table used to be keyed by the
+ *    client's id, so two requests in flight under ONE id (JSON-RPC forbids it; a client can
+ *    still do it) shared one slot: the second line overwrote the first and both answers were
+ *    computed from the second request's arguments. And the SDK's schema refuses an integer id
+ *    past 2^53 (`JSON.parse` has already rounded it), so such a request got no answer at all.
+ *    Both are fixed the same way: every request is handed to the SDK under a TOKEN of this
+ *    file's own (`bantamkit-<n>`, unique per message), and the client's id is kept as the
+ *    exact TEXT it arrived as, read losslessly with `pyjson.parseJson`; `send` writes that
+ *    text back. The reference answers each request from its own arguments and echoes a big
+ *    id exactly, so this is the port catching up, not a choice. A `notifications/cancelled`
+ *    naming a client id is pointed at the newest token carrying it.
+ *
+ * 4. A FRAME THE SDK WOULD DROP IS ANSWERED (#148). A line that is not JSON is answered
+ *    `-32700 Parse error`, and JSON that is not a JSON-RPC message (a batch array, a bare
+ *    number, a message with no `jsonrpc`) `-32600 Invalid Request`, both with `id: null`
+ *    as JSON-RPC 2.0 section 5.1 requires, and both in the bytes `mcpstdio.py` writes. Before,
+ *    both went to `onerror` and the client waited forever. A blank line is still skipped.
+ *
+ * 5. A HOST THAT CLOSED ITS READ END ENDS THE SESSION QUIETLY (#181). `process.stdout` had no
+ *    `error` listener, so an EPIPE mid-answer was an unhandled `error` event: exit 1 and a
+ *    stack. It is now what stdin EOF already was, the host going away: the transport closes,
+ *    stdin is released, and the process exits 0 with nothing on stderr. Any OTHER write error
+ *    is rethrown and still crashes, because it is not that.
+ *
  * NOTHING IN THIS FILE WRITES TO STDOUT EXCEPT `send`. That is the invariant the whole
  * package is under, and it is checked by `test/server.test.mjs`, which asserts that every
  * line a real session produced parses as a frame and that stdout never ends mid-line.
@@ -33,6 +57,12 @@ import type { Transport } from '@modelcontextprotocol/sdk/shared/transport.js';
 import type { JSONRPCMessage } from '@modelcontextprotocol/sdk/types.js';
 type Readable = NodeJS.ReadableStream;
 type Writable = NodeJS.WritableStream;
+/**
+ * The two frames JSON-RPC 2.0 section 5.1 prescribes for a message no id can be read from,
+ * byte for byte what `mcpstdio.py` writes (`JSONRPCError(id=None, ...)` dumped by the SDK).
+ */
+export declare const PARSE_ERROR_FRAME = "{\"jsonrpc\":\"2.0\",\"id\":null,\"error\":{\"code\":-32700,\"message\":\"Parse error\"}}";
+export declare const INVALID_REQUEST_FRAME = "{\"jsonrpc\":\"2.0\",\"id\":null,\"error\":{\"code\":-32600,\"message\":\"Invalid Request\"}}";
 export declare class RawStdioTransport implements Transport {
     private readonly input;
     private readonly output;
@@ -42,18 +72,31 @@ export declare class RawStdioTransport implements Transport {
     sessionId?: string;
     private buffer;
     private started;
-    private readonly rawLines;
-    private readonly exactResults;
+    private outputGone;
+    private sequence;
+    /** Token (the id the SDK sees) -> the request it stands for. One entry per MESSAGE. */
+    private readonly inFlight;
+    /** Client id text -> the newest token carrying it, for `notifications/cancelled`. */
+    private readonly newest;
     private readonly ondata;
     private readonly onstreamerror;
+    private readonly onoutputerror;
     constructor(input?: Readable, output?: Writable);
-    /** The verbatim request line that carried this id, or `undefined` if it is gone. */
+    /** The verbatim request line this message token stands for, or `undefined` if it is gone. */
     rawLineFor(id: unknown): string | undefined;
-    /** Register the exact JSON text to send as this request's `result`. */
+    /**
+     * #147: whether the reference would refuse this request's params on its `_meta` alone, a
+     * member the TS SDK checks in its ENVELOPE schema and the reference only per method.
+     */
+    paramsRefused(id: unknown): boolean;
+    /** Register the exact JSON text to send as this message's `result`. */
     setExactResult(id: unknown, json: string): void;
     start(): Promise<void>;
     close(): Promise<void>;
     send(message: JSONRPCMessage): Promise<void>;
+    private write;
+    /** Answer a line no id could be read from, in order with every other frame. */
+    private refuse;
     /**
      * One frame, in the reference's key order, with an exact `result` when one was registered.
      *
@@ -64,5 +107,7 @@ export declare class RawStdioTransport implements Transport {
      */
     private frame;
     private consume;
+    /** Point a `notifications/cancelled` at the token now standing for the id it names. */
+    private retarget;
 }
 export {};

package/dist/mcp/transport.js

@@ -1,7 +1,37 @@
 import { JSONRPCMessageSchema } from '@modelcontextprotocol/sdk/types.js';
 import { PY_LINESEP } from '../memory/pyfs.js';
-/** A JSON-RPC id is a string or a number; the map key is its JSON text, which is total. */
-const idKey = (id) => JSON.stringify(id ?? null);
+import { parseJson } from '../pyjson.js';
+/**
+ * The two frames JSON-RPC 2.0 section 5.1 prescribes for a message no id can be read from,
+ * byte for byte what `mcpstdio.py` writes (`JSONRPCError(id=None, ...)` dumped by the SDK).
+ */
+export const PARSE_ERROR_FRAME = '{"jsonrpc":"2.0","id":null,"error":{"code":-32700,"message":"Parse error"}}';
+export const INVALID_REQUEST_FRAME = '{"jsonrpc":"2.0","id":null,"error":{"code":-32600,"message":"Invalid Request"}}';
+/** The write errors that mean the reader of stdout is gone, on POSIX and on Windows (libuv EOF). */
+const HOST_GONE = new Set(['EPIPE', 'ECONNRESET', 'EOF', 'ERR_STREAM_DESTROYED']);
+/**
+ * The client's id as the exact JSON text to echo, or `undefined` when it is not one a
+ * JSON-RPC id may be. A string is re-serialised (`JSON.stringify` is pydantic-core's string
+ * spelling); a number is read again LOSSLESSLY, because `JSON.parse` has already rounded an
+ * integer past 2^53 and cannot tell `1.0` from `1`. The reference's `RequestId` is a STRICT
+ * int or a str, so a float literal is no id at all there either.
+ */
+function clientIdText(line, id) {
+    if (typeof id === 'string')
+        return JSON.stringify(id);
+    if (typeof id !== 'number')
+        return undefined;
+    try {
+        const frame = parseJson(line);
+        const value = frame.t === 'dict' ? frame.v.get('id') : undefined;
+        return value?.t === 'int' ? value.v.toString() : undefined;
+    }
+    catch {
+        return Number.isSafeInteger(id) ? String(id) : undefined;
+    }
+}
+/** The JSON text of an id named INSIDE a message (a cancellation's `requestId`). */
+const namedIdText = (id) => typeof id === 'string' ? JSON.stringify(id) : Number.isSafeInteger(id) ? String(id) : undefined;
 export class RawStdioTransport {
     input;
     output;
@@ -11,21 +41,45 @@ export class RawStdioTransport {
     sessionId;
     buffer = Buffer.alloc(0);
     started = false;
-    rawLines = new Map();
-    exactResults = new Map();
+    outputGone = false;
+    sequence = 0;
+    /** Token (the id the SDK sees) -> the request it stands for. One entry per MESSAGE. */
+    inFlight = new Map();
+    /** Client id text -> the newest token carrying it, for `notifications/cancelled`. */
+    newest = new Map();
     ondata = (chunk) => this.consume(chunk);
     onstreamerror = (error) => this.onerror?.(error);
+    onoutputerror = (error) => {
+        if (!HOST_GONE.has(error.code ?? ''))
+            throw error;
+        if (this.outputGone)
+            return;
+        this.outputGone = true;
+        // The host is gone, so nothing will ever read another answer: stop reading too, or a
+        // stdin the host left open would keep the process alive with nowhere to write.
+        this.input.destroy?.();
+        void this.close();
+    };
     constructor(input = process.stdin, output = process.stdout) {
         this.input = input;
         this.output = output;
     }
-    /** The verbatim request line that carried this id, or `undefined` if it is gone. */
+    /** The verbatim request line this message token stands for, or `undefined` if it is gone. */
     rawLineFor(id) {
-        return this.rawLines.get(idKey(id));
+        return typeof id === 'string' ? this.inFlight.get(id)?.line : undefined;
+    }
+    /**
+     * #147: whether the reference would refuse this request's params on its `_meta` alone, a
+     * member the TS SDK checks in its ENVELOPE schema and the reference only per method.
+     */
+    paramsRefused(id) {
+        return typeof id === 'string' && this.inFlight.get(id)?.paramsRefused === true;
     }
-    /** Register the exact JSON text to send as this request's `result`. */
+    /** Register the exact JSON text to send as this message's `result`. */
     setExactResult(id, json) {
-        this.exactResults.set(idKey(id), json);
+        const entry = typeof id === 'string' ? this.inFlight.get(id) : undefined;
+        if (entry !== undefined)
+            entry.exact = json;
     }
     async start() {
         if (this.started)
@@ -33,6 +87,7 @@ export class RawStdioTransport {
         this.started = true;
         this.input.on('data', this.ondata);
         this.input.on('error', this.onstreamerror);
+        this.output.on('error', this.onoutputerror);
     }
     async close() {
         this.input.off('data', this.ondata);
@@ -40,13 +95,19 @@ export class RawStdioTransport {
         if (this.input.listenerCount('data') === 0)
             this.input.pause();
         this.buffer = Buffer.alloc(0);
-        this.rawLines.clear();
-        this.exactResults.clear();
+        this.inFlight.clear();
+        this.newest.clear();
         this.onclose?.();
     }
     send(message) {
+        return this.write(this.frame(message));
+    }
+    write(text) {
         return new Promise((resolve) => {
-            const text = this.frame(message);
+            if (this.outputGone) {
+                resolve();
+                return;
+            }
             // `os.linesep`, because the reference's stdout is a TEXT stream. The Python SDK writes
             // its frames through `TextIOWrapper(sys.stdout.buffer)` with the default
             // `newline=None`, so on Windows every frame CPython emits ends `\r\n`. MEASURED, run
@@ -59,6 +120,10 @@ export class RawStdioTransport {
                 this.output.once('drain', () => resolve());
         });
     }
+    /** Answer a line no id could be read from, in order with every other frame. */
+    refuse(frame) {
+        void this.write(frame);
+    }
     /**
      * One frame, in the reference's key order, with an exact `result` when one was registered.
      *
@@ -69,17 +134,18 @@ export class RawStdioTransport {
      */
     frame(message) {
         const framed = message;
-        if (framed.id === undefined)
+        if (framed.id === undefined || 'method' in framed)
             return JSON.stringify(message);
-        const key = idKey(framed.id);
-        this.rawLines.delete(key);
-        const id = JSON.stringify(framed.id);
+        const entry = typeof framed.id === 'string' ? this.inFlight.get(framed.id) : undefined;
+        if (entry !== undefined) {
+            this.inFlight.delete(framed.id);
+            if (this.newest.get(entry.idText) === framed.id)
+                this.newest.delete(entry.idText);
+        }
+        const id = entry?.idText ?? JSON.stringify(framed.id);
         if ('result' in framed) {
-            const exact = this.exactResults.get(key);
-            this.exactResults.delete(key);
-            return `{"jsonrpc":"2.0","id":${id},"result":${exact ?? JSON.stringify(framed.result)}}`;
+            return `{"jsonrpc":"2.0","id":${id},"result":${entry?.exact ?? JSON.stringify(framed.result)}}`;
         }
-        this.exactResults.delete(key);
         if ('error' in framed)
             return `{"jsonrpc":"2.0","id":${id},"error":${JSON.stringify(framed.error)}}`;
         return JSON.stringify(message);
@@ -94,18 +160,143 @@ export class RawStdioTransport {
             this.buffer = this.buffer.subarray(at + 1);
             if (line.trim() === '')
                 continue;
-            let message;
+            let parsed;
             try {
-                message = JSONRPCMessageSchema.parse(JSON.parse(line));
+                parsed = JSON.parse(line);
+            }
+            catch {
+                this.refuse(PARSE_ERROR_FRAME);
+                continue;
             }
-            catch (error) {
-                this.onerror?.(error);
+            // A LONE SURROGATE is text `JSON.parse` keeps and pydantic's parser refuses, so the
+            // reference's SDK cannot read such a frame at all; `mcpstdio.py` answers it `-32600`
+            // (the standard library CAN read it). The one exception is job65/#160's: a `tools/call`
+            // carrying one in its arguments is refused BY NAME, which the server does here too.
+            if (LONE_ESCAPE.test(line) && holdsLoneSurrogate(parsed) && !refusedByName(line, parsed)) {
+                this.refuse(INVALID_REQUEST_FRAME);
                 continue;
             }
-            const id = message.id;
-            if (id !== undefined)
-                this.rawLines.set(idKey(id), line);
+            // The reference's adapter is pydantic, which IGNORES a member it has no field for and
+            // takes `params: null` as no params; the TS SDK's schemas are strict and refuse both.
+            // Measured on both SDKs (J66-3 note): normalised here, so a frame the reference answers
+            // is not one the port calls an Invalid Request.
+            if (isObject(parsed)) {
+                for (const key of Object.keys(parsed))
+                    if (!MESSAGE_KEYS.has(key))
+                        delete parsed[key];
+                if (parsed['params'] === null)
+                    delete parsed['params'];
+            }
+            // A REQUEST (an object with an id and a method) travels under a token of this file's
+            // own; its client id is kept as text. Anything else goes to the SDK's schema unchanged.
+            let token;
+            let idText;
+            if (isObject(parsed) && 'id' in parsed && 'method' in parsed) {
+                idText = clientIdText(line, parsed['id']);
+                if (idText === undefined) {
+                    // Not a str and not an int (`null`, `1.0`, `true`): the reference's `RequestId`
+                    // refuses it, and its union then reads the frame as a NOTIFICATION with the id
+                    // ignored, so nothing is answered. Measured; the port does the same.
+                    delete parsed['id'];
+                }
+                else {
+                    token = `bantamkit-${++this.sequence}`;
+                    parsed['id'] = token;
+                }
+            }
+            let message;
+            let paramsRefused = false;
+            try {
+                message = JSONRPCMessageSchema.parse(parsed);
+            }
+            catch {
+                // #147: the TS SDK's envelope checks a request's `params._meta`; the reference's
+                // envelope takes any object as params and checks `_meta` with the METHOD's model,
+                // so `_meta: 5` is -32602 with the client's id there (and `_meta: null` or a
+                // `progressToken: true` is served), where this used to be -32600 with id null. A
+                // request the envelope takes once `_meta` is set aside travels on without it, and
+                // `server.ts`'s guard refuses it -32602 if the reference's model would have.
+                const params = token !== undefined && isObject(parsed) ? parsed['params'] : undefined;
+                const withoutMeta = isObject(params) && '_meta' in params ? withoutKey(parsed, params) : undefined;
+                const retry = withoutMeta === undefined ? undefined : JSONRPCMessageSchema.safeParse(withoutMeta);
+                if (retry === undefined || !retry.success) {
+                    this.refuse(INVALID_REQUEST_FRAME);
+                    continue;
+                }
+                message = retry.data;
+                paramsRefused = !referenceTakesMeta(params['_meta']);
+            }
+            if (token !== undefined && idText !== undefined) {
+                this.inFlight.set(token, paramsRefused ? { idText, line, paramsRefused } : { idText, line });
+                this.newest.set(idText, token);
+            }
+            else {
+                this.retarget(message);
+            }
             this.onmessage?.(message);
         }
     }
+    /** Point a `notifications/cancelled` at the token now standing for the id it names. */
+    retarget(message) {
+        const note = message;
+        if (note.method !== 'notifications/cancelled' || note.params === undefined)
+            return;
+        const named = namedIdText(note.params.requestId);
+        const token = named === undefined ? undefined : this.newest.get(named);
+        if (token !== undefined)
+            note.params.requestId = token;
+    }
+}
+/** Only a line spelling a surrogate escape can hold a lone surrogate (`mcpstdio._ESCAPE`). */
+const LONE_ESCAPE = /\\u[dD][89a-fA-F][0-9a-fA-F]{2}/;
+const LONE = /[\uD800-\uDBFF](?![\uDC00-\uDFFF])|(?<![\uD800-\uDBFF])[\uDC00-\uDFFF]/;
+/** Whether any string in the value, member names included, holds a lone surrogate. */
+function holdsLoneSurrogate(value) {
+    if (typeof value === 'string')
+        return LONE.test(value);
+    if (Array.isArray(value))
+        return value.some(holdsLoneSurrogate);
+    if (isObject(value))
+        return Object.entries(value).some(([key, item]) => LONE.test(key) || holdsLoneSurrogate(item));
+    return false;
+}
+/**
+ * `mcpstdio.refusal_for`'s test, less the roster: a `tools/call` with a str or int id whose
+ * `arguments` object holds a lone surrogate goes on to the server, which refuses it by name
+ * (`pyargs.loneSurrogateArgument`). The reference also requires the tool to be one it
+ * serves; for an unserved name it answers `-32600` where the port answers `Unknown tool:`.
+ */
+function refusedByName(line, parsed) {
+    if (!isObject(parsed) || parsed['method'] !== 'tools/call' || !('id' in parsed))
+        return false;
+    if (clientIdText(line, parsed['id']) === undefined)
+        return false;
+    const params = parsed['params'];
+    return isObject(params) && typeof params['name'] === 'string' && isObject(params['arguments']) && holdsLoneSurrogate(params['arguments']);
+}
+/** The frame again with `params._meta` left out. */
+function withoutKey(frame, params) {
+    const { _meta: _dropped, ...rest } = params;
+    return { ...frame, params: rest };
+}
+/**
+ * Whether `mcp_types.RequestParams.meta` (`RequestParamsMeta | None`, lax) takes this
+ * `_meta`: absent or `null`, or an open object whose `progressToken`, if any, is a str or
+ * what lax `int` takes — an integral number or a bool (`NotRequired`, so not `null`).
+ * Measured on the reference: `5`, `[]`, `{"progressToken": 1.5}`, `{"progressToken": null}`
+ * and `{"progressToken": {}}` are -32602; `null`, `{"progressToken": true}` and
+ * `{"progressToken": 2.0}` are served.
+ */
+function referenceTakesMeta(meta) {
+    if (meta === undefined || meta === null)
+        return true;
+    if (!isObject(meta))
+        return false;
+    const token = meta['progressToken'];
+    return token === undefined || typeof token === 'string' || typeof token === 'boolean' || Number.isInteger(token);
+}
+/** The members a JSON-RPC 2.0 message may carry; any other is dropped as pydantic drops it. */
+const MESSAGE_KEYS = new Set(['jsonrpc', 'id', 'method', 'params', 'result', 'error']);
+function isObject(value) {
+    return value !== null && typeof value === 'object' && !Array.isArray(value);
 }