@basein/runner 0.2.11 → 0.3.0

package/dist/jsonrpc/framing.d.ts

@@ -1,16 +1,23 @@
 /**
  * framing — line-delimited JSON-RPC over a byte stream (Phase 1.1).
  *
- * MCP's stdio transport is one JSON value per line. Three things break naive
- * implementations, and all three are handled here:
+ * MCP's stdio transport is one JSON value per line. Four things break naive
+ * implementations, and all four are handled here:
  *
  *   1. **Partial reads.** A chunk boundary lands mid-message. Bytes are buffered
  *      until a newline arrives.
- *   2. **Oversized lines.** A runaway upstream can otherwise grow the buffer
+ *   2. **Large lines.** A 20 MB screenshot arrives as ~300 pipe reads. The
+ *      reader keeps the pieces in a list and searches only the *new* chunk for
+ *      the newline, then joins the pieces once per complete line — linear in
+ *      the line's size. (It used to re-concatenate and re-scan the whole
+ *      pending buffer on every chunk: 0.8 s of pure copying at 20 MB, 1.7 s at
+ *      30 MB, all of it added to the user's tool call.)
+ *   3. **Oversized lines.** A runaway upstream can otherwise grow the buffer
  *      without bound. Past `maxLineBytes` the reader drops bytes until the next
- *      newline and reports one error, rather than allocating until the process
- *      dies.
- *   3. **Invalid JSON.** Reported to the caller (which answers `-32700` toward a
+ *      newline and reports one error *when the line ends*, with its first and
+ *      last bytes, so a caller can still find the request id in it and answer
+ *      the request instead of leaving it hanging (see stdio-client.ts).
+ *   4. **Invalid JSON.** Reported to the caller (which answers `-32700` toward a
  *      host, or logs and drops toward an upstream). It never throws.
  *
  * Buffering is done on `Buffer`, not on a decoded string: a multi-byte UTF-8
@@ -19,16 +26,33 @@
  */
 import type { Readable, Writable } from "node:stream";
 import type { JsonRpcMessage } from "./types.js";
-/** 32 MiB. Large enough for a base64 screenshot, small enough to be a bound. */
+/**
+ * 128 MiB. Large enough for any realistic tool result (a full-page screenshot
+ * at high DPI is tens of MB once base64-encoded), small enough to be a bound:
+ * one line costs roughly three to four times its size while it is joined,
+ * decoded and parsed, and V8 caps a single string at ~512 MB.
+ */
 export declare const DEFAULT_MAX_LINE_BYTES: number;
+/** How many bytes of each end of an oversized line are kept for the report. */
+export declare const OVERSIZE_SAMPLE_BYTES = 256;
+export interface ParseErrorDetail {
+    reason: string;
+    bytes: number;
+    /** The first bytes of the offending line, decoded (lossy at the cut). */
+    sample: string;
+    /** Set only for a line over `maxLineBytes`. */
+    oversized?: boolean;
+    /**
+     * The last bytes of an oversized line, decoded. The TypeScript MCP SDK
+     * serialises `id` *last* (`{ result, jsonrpc, id }`), so this is where a
+     * response's id usually is; Python/pydantic puts it first, in `sample`.
+     */
+    tail?: string;
+}
 export interface FrameHandlers {
     onMessage: (msg: JsonRpcMessage) => void;
     /** A line that was not valid JSON, or that exceeded `maxLineBytes`. */
-    onParseError?: (detail: {
-        reason: string;
-        bytes: number;
-        sample: string;
-    }) => void;
+    onParseError?: (detail: ParseErrorDetail) => void;
     /** The input stream ended or errored. Called at most once. */
     onEnd?: (err?: Error) => void;
 }
@@ -46,4 +70,44 @@ export declare function readFrames(input: Readable, handlers: FrameHandlers, opt
  * session down with it, which rule 4 of §1 forbids.
  */
 export declare function writeFrame(output: Writable, msg: unknown, onError?: (err: Error) => void): void;
+/**
+ * What an oversized line was, as far as its two ends tell:
+ *
+ *   - `request` — a request or notification from the upstream (a huge log
+ *     line, a sampling request carrying an image). Nobody on the host side is
+ *     waiting for it by id; `id`, when there is one, is in the *upstream's*
+ *     id space and must never be matched against a host's request.
+ *   - `response` — recognisably an answer, `id` when either end carries it.
+ *   - `unknown` — neither end says; `id` is what the tail's usual position
+ *     held, if anything, and is only good for an exact match.
+ */
+export type OversizedLineKind = {
+    kind: "request";
+    id?: string | number;
+} | {
+    kind: "response";
+    id?: string | number;
+} | {
+    kind: "unknown";
+    id?: string | number;
+};
+/**
+ * Classify an oversized line from its first and last bytes.
+ *
+ * Only a top-level `"id"` is wanted, and a nested one (inside `result`) could
+ * sit near either end, so each end is tried only in the position a serialiser
+ * puts the top-level key: last, right before the final brace (`…,"id":7}`,
+ * the TypeScript SDK), or first (`{"jsonrpc":"2.0","id":7,…`, Python/pydantic).
+ * A nested `"id"` is followed by more than one closing bracket, so it does not
+ * match the first form, and cannot be at the start, so it does not match the
+ * second.
+ */
+export declare function classifyOversizedLine(sample: string, tail?: string): OversizedLineKind;
+/**
+ * Best-effort recovery of the `id` of an oversized JSON-RPC **response** from
+ * its first and last bytes. `undefined` when neither end carries a
+ * recognisable one, or when the line looks like a request (whose id lives in
+ * the upstream's own id space and must never be mistaken for a host's).
+ */
+export declare function recoverResponseId(sample: string, tail?: string): string | number | undefined;
 //# sourceMappingURL=framing.d.ts.map

package/dist/jsonrpc/framing.js

@@ -1,107 +1,196 @@
 /**
  * framing — line-delimited JSON-RPC over a byte stream (Phase 1.1).
  *
- * MCP's stdio transport is one JSON value per line. Three things break naive
- * implementations, and all three are handled here:
+ * MCP's stdio transport is one JSON value per line. Four things break naive
+ * implementations, and all four are handled here:
  *
  *   1. **Partial reads.** A chunk boundary lands mid-message. Bytes are buffered
  *      until a newline arrives.
- *   2. **Oversized lines.** A runaway upstream can otherwise grow the buffer
+ *   2. **Large lines.** A 20 MB screenshot arrives as ~300 pipe reads. The
+ *      reader keeps the pieces in a list and searches only the *new* chunk for
+ *      the newline, then joins the pieces once per complete line — linear in
+ *      the line's size. (It used to re-concatenate and re-scan the whole
+ *      pending buffer on every chunk: 0.8 s of pure copying at 20 MB, 1.7 s at
+ *      30 MB, all of it added to the user's tool call.)
+ *   3. **Oversized lines.** A runaway upstream can otherwise grow the buffer
  *      without bound. Past `maxLineBytes` the reader drops bytes until the next
- *      newline and reports one error, rather than allocating until the process
- *      dies.
- *   3. **Invalid JSON.** Reported to the caller (which answers `-32700` toward a
+ *      newline and reports one error *when the line ends*, with its first and
+ *      last bytes, so a caller can still find the request id in it and answer
+ *      the request instead of leaving it hanging (see stdio-client.ts).
+ *   4. **Invalid JSON.** Reported to the caller (which answers `-32700` toward a
  *      host, or logs and drops toward an upstream). It never throws.
  *
  * Buffering is done on `Buffer`, not on a decoded string: a multi-byte UTF-8
  * character split across two chunks decodes to replacement characters if you
  * concatenate strings, which silently corrupts payloads containing non-ASCII.
  */
-/** 32 MiB. Large enough for a base64 screenshot, small enough to be a bound. */
-export const DEFAULT_MAX_LINE_BYTES = 32 * 1024 * 1024;
+/**
+ * 128 MiB. Large enough for any realistic tool result (a full-page screenshot
+ * at high DPI is tens of MB once base64-encoded), small enough to be a bound:
+ * one line costs roughly three to four times its size while it is joined,
+ * decoded and parsed, and V8 caps a single string at ~512 MB.
+ */
+export const DEFAULT_MAX_LINE_BYTES = 128 * 1024 * 1024;
+/** How many bytes of each end of an oversized line are kept for the report. */
+export const OVERSIZE_SAMPLE_BYTES = 256;
 const NEWLINE = 0x0a;
+const EMPTY = Buffer.alloc(0);
+/** The last `n` bytes of `a` followed by `b`, as a fresh buffer. */
+function lastBytes(a, b, n) {
+    if (b.length >= n)
+        return Buffer.from(b.subarray(b.length - n));
+    const joined = Buffer.concat([a, b]);
+    return joined.length > n ? Buffer.from(joined.subarray(joined.length - n)) : joined;
+}
+/** The first `n` bytes across `parts`, as a fresh buffer. */
+function firstBytes(parts, n) {
+    const out = [];
+    let have = 0;
+    for (const p of parts) {
+        if (have >= n)
+            break;
+        const take = p.subarray(0, n - have);
+        out.push(take);
+        have += take.length;
+    }
+    return Buffer.concat(out, have);
+}
+/** The last `n` bytes across `parts`, as a fresh buffer. */
+function lastBytesOf(parts, n) {
+    const out = [];
+    let have = 0;
+    for (let i = parts.length - 1; i >= 0 && have < n; i -= 1) {
+        const p = parts[i];
+        const take = p.subarray(Math.max(0, p.length - (n - have)));
+        out.unshift(take);
+        have += take.length;
+    }
+    return Buffer.concat(out, have);
+}
 /**
  * Read newline-delimited JSON messages off `input`.
  * Returns a detach function that stops the reader (it does not close `input`).
  */
 export function readFrames(input, handlers, opts = {}) {
     const maxLineBytes = opts.maxLineBytes ?? DEFAULT_MAX_LINE_BYTES;
-    let buf = Buffer.alloc(0);
+    /** The current line's bytes so far, in arrival order. Joined once, at its newline. */
+    let parts = [];
+    let pendingBytes = 0;
     /** Set after an oversized line: drop bytes until the next newline resynchronises us. */
     let discarding = false;
     let discarded = 0;
+    let head = EMPTY;
+    let tail = EMPTY;
     let ended = false;
+    const reportOversized = () => {
+        handlers.onParseError?.({
+            reason: `line exceeded ${maxLineBytes} bytes`,
+            bytes: discarded,
+            sample: head.toString("utf8"),
+            oversized: true,
+            tail: tail.toString("utf8"),
+        });
+    };
+    const enterDiscard = () => {
+        head = firstBytes(parts, OVERSIZE_SAMPLE_BYTES);
+        tail = lastBytesOf(parts, OVERSIZE_SAMPLE_BYTES);
+        discarding = true;
+        discarded = pendingBytes;
+        parts = [];
+        pendingBytes = 0;
+    };
     const finish = (err) => {
         if (ended)
             return;
         ended = true;
+        if (discarding) {
+            // The stream ended inside an oversized line: still say so, once.
+            discarding = false;
+            reportOversized();
+        }
         handlers.onEnd?.(err);
     };
+    const handleLine = (line) => {
+        if (line.length === 0)
+            return; // keep-alive blank lines are legal noise
+        if (line.length > maxLineBytes) {
+            head = Buffer.from(line.subarray(0, OVERSIZE_SAMPLE_BYTES));
+            tail = Buffer.from(line.subarray(Math.max(0, line.length - OVERSIZE_SAMPLE_BYTES)));
+            discarded = line.length;
+            reportOversized();
+            return;
+        }
+        const text = line.toString("utf8");
+        let msg;
+        try {
+            msg = JSON.parse(text);
+        }
+        catch (err) {
+            handlers.onParseError?.({
+                reason: err instanceof Error ? err.message : String(err),
+                bytes: line.length,
+                sample: text.slice(0, 120),
+            });
+            return;
+        }
+        if (!msg || typeof msg !== "object" || Array.isArray(msg)) {
+            // A bare scalar or a JSON-RPC batch. Neither appears in MCP; both would
+            // desynchronise a 1:1 relay, so they are reported rather than forwarded.
+            handlers.onParseError?.({
+                reason: "message was not a JSON object",
+                bytes: line.length,
+                sample: text.slice(0, 120),
+            });
+            return;
+        }
+        handlers.onMessage(msg);
+    };
     const onData = (chunk) => {
-        buf = Buffer.concat([buf, typeof chunk === "string" ? Buffer.from(chunk, "utf8") : chunk]);
-        for (;;) {
-            const nl = buf.indexOf(NEWLINE);
+        const buf = typeof chunk === "string" ? Buffer.from(chunk, "utf8") : chunk;
+        let start = 0;
+        while (start < buf.length) {
+            // Only the new bytes are searched: everything already in `parts` is known
+            // to contain no newline.
+            const nl = buf.indexOf(NEWLINE, start);
             if (nl === -1) {
+                const rest = buf.subarray(start);
                 if (discarding) {
-                    discarded += buf.length;
-                    buf = Buffer.alloc(0);
+                    discarded += rest.length;
+                    tail = lastBytes(tail, rest, OVERSIZE_SAMPLE_BYTES);
                 }
-                else if (buf.length > maxLineBytes) {
-                    // Enter discard mode; report once for the whole oversized line.
-                    handlers.onParseError?.({
-                        reason: `line exceeded ${maxLineBytes} bytes`,
-                        bytes: buf.length,
-                        sample: buf.subarray(0, 120).toString("utf8"),
-                    });
-                    discarding = true;
-                    discarded = buf.length;
-                    buf = Buffer.alloc(0);
+                else {
+                    parts.push(rest);
+                    pendingBytes += rest.length;
+                    // Enter discard mode; the one report goes out when the line ends.
+                    if (pendingBytes > maxLineBytes)
+                        enterDiscard();
                 }
                 return;
             }
-            const line = buf.subarray(0, nl);
-            buf = buf.subarray(nl + 1);
+            const piece = buf.subarray(start, nl);
+            start = nl + 1;
             if (discarding) {
                 // The tail of an oversized line. Resynchronised — resume normal reading.
-                discarded += line.length;
+                discarded += piece.length;
+                tail = lastBytes(tail, piece, OVERSIZE_SAMPLE_BYTES);
                 discarding = false;
+                reportOversized();
                 discarded = 0;
+                head = EMPTY;
+                tail = EMPTY;
                 continue;
             }
-            if (line.length === 0)
-                continue; // keep-alive blank lines are legal noise
-            if (line.length > maxLineBytes) {
-                handlers.onParseError?.({
-                    reason: `line exceeded ${maxLineBytes} bytes`,
-                    bytes: line.length,
-                    sample: line.subarray(0, 120).toString("utf8"),
-                });
-                continue;
+            let line;
+            if (pendingBytes === 0) {
+                line = piece;
             }
-            const text = line.toString("utf8");
-            let msg;
-            try {
-                msg = JSON.parse(text);
+            else {
+                parts.push(piece);
+                line = Buffer.concat(parts, pendingBytes + piece.length);
+                parts = [];
+                pendingBytes = 0;
             }
-            catch (err) {
-                handlers.onParseError?.({
-                    reason: err instanceof Error ? err.message : String(err),
-                    bytes: line.length,
-                    sample: text.slice(0, 120),
-                });
-                continue;
-            }
-            if (!msg || typeof msg !== "object" || Array.isArray(msg)) {
-                // A bare scalar or a JSON-RPC batch. Neither appears in MCP; both would
-                // desynchronise a 1:1 relay, so they are reported rather than forwarded.
-                handlers.onParseError?.({
-                    reason: "message was not a JSON object",
-                    bytes: line.length,
-                    sample: text.slice(0, 120),
-                });
-                continue;
-            }
-            handlers.onMessage(msg);
+            handleLine(line);
         }
     };
     const onError = (err) => finish(err);
@@ -140,4 +229,72 @@ export function writeFrame(output, msg, onError) {
         onError?.(err instanceof Error ? err : new Error(String(err)));
     }
 }
+const ID_VALUE = String.raw `("(?:[^"\\]|\\.)*"|-?\d+)`;
+/** An optional leading `"jsonrpc":"2.0",` — where Python/pydantic, Go and Rust put it. */
+const OPT_JSONRPC = String.raw `(?:"jsonrpc"\s*:\s*"2\.0"\s*,\s*)?`;
+/**
+ * `{"method":…` (TypeScript SDK) or `{"jsonrpc":"2.0","method":…` (Python) —
+ * a request or notification, not an answer.
+ */
+const LEADS_WITH_METHOD = new RegExp(String.raw `^\s*\{\s*${OPT_JSONRPC}"method"\s*:`);
+/** `{"result":…` / `{"error":…` (TypeScript SDK), with or without `jsonrpc` first. */
+const LEADS_WITH_OUTCOME = new RegExp(String.raw `^\s*\{\s*${OPT_JSONRPC}"(?:result|error)"\s*:`);
+/**
+ * `{"jsonrpc":"2.0","id":7,<next key>` / `{"id":7,<next key>` (Python and most
+ * other serialisers). The key after the id says which kind of message it is.
+ */
+const LEADING_ID = new RegExp(String.raw `^\s*\{\s*${OPT_JSONRPC}"id"\s*:\s*${ID_VALUE}\s*(?:,\s*"(method|result|error)"\s*:)?`);
+/** `…,"id":7}` at the very end (TypeScript SDK key order). */
+const TRAILING_ID = new RegExp(String.raw `"id"\s*:\s*${ID_VALUE}\s*\}\s*$`);
+/**
+ * Classify an oversized line from its first and last bytes.
+ *
+ * Only a top-level `"id"` is wanted, and a nested one (inside `result`) could
+ * sit near either end, so each end is tried only in the position a serialiser
+ * puts the top-level key: last, right before the final brace (`…,"id":7}`,
+ * the TypeScript SDK), or first (`{"jsonrpc":"2.0","id":7,…`, Python/pydantic).
+ * A nested `"id"` is followed by more than one closing bracket, so it does not
+ * match the first form, and cannot be at the start, so it does not match the
+ * second.
+ */
+export function classifyOversizedLine(sample, tail) {
+    const parse = (raw) => {
+        try {
+            const v = JSON.parse(raw);
+            return typeof v === "string" || typeof v === "number" ? v : undefined;
+        }
+        catch {
+            return undefined;
+        }
+    };
+    const trailing = () => {
+        const m = tail ? TRAILING_ID.exec(tail) : null;
+        return m ? parse(m[1]) : undefined;
+    };
+    // TypeScript SDK requests end in their id; Python ones lead with it.
+    if (LEADS_WITH_METHOD.test(sample))
+        return { kind: "request", id: trailing() };
+    const lead = LEADING_ID.exec(sample);
+    if (lead) {
+        const id = parse(lead[1]);
+        if (lead[2] === "method")
+            return { kind: "request", id };
+        if (lead[2] === "result" || lead[2] === "error")
+            return { kind: "response", id };
+        return { kind: "unknown", id };
+    }
+    if (LEADS_WITH_OUTCOME.test(sample))
+        return { kind: "response", id: trailing() };
+    return { kind: "unknown", id: trailing() };
+}
+/**
+ * Best-effort recovery of the `id` of an oversized JSON-RPC **response** from
+ * its first and last bytes. `undefined` when neither end carries a
+ * recognisable one, or when the line looks like a request (whose id lives in
+ * the upstream's own id space and must never be mistaken for a host's).
+ */
+export function recoverResponseId(sample, tail) {
+    const shape = classifyOversizedLine(sample, tail);
+    return shape.kind === "request" ? undefined : shape.id;
+}
 //# sourceMappingURL=framing.js.map

package/dist/proxy/intercept.d.ts

@@ -4,7 +4,7 @@
  * | Method       | Direction      | Action                                        |
  * |--------------|----------------|-----------------------------------------------|
  * | `initialize` | host → upstream| Relay, and rewrite as little as possible.      |
- * | `tools/list` | host → upstream| Relay; relax schemas only when Tier 1 needs it.|
+ * | `tools/list` | host → upstream| Relay; declare the call-id key when Tier 1 may inject it.|
  * | `tools/call` | host → upstream| Strip the call id, time it, relay, report it.  |
  *
  * `initialize` DESERVES ITS OWN PARAGRAPH, because getting it wrong is what makes
@@ -19,10 +19,13 @@
  * TWO RULES THAT ARE EASY TO GET WRONG, and are enforced here:
  *   - **Never rewrite a `tools/call` result.** The upstream object is returned
  *     as-is, `_meta` and `structuredContent` included. A *copy* is recorded.
- *   - **Never let recording block the response.** The step is queued after the
- *     result is already on its way to the host.
+ *   - **Never let recording block the response.** Only bookkeeping happens on
+ *     the response's own tick; the copy is redacted, clipped and queued on a
+ *     later one (`setImmediate`), after the relay has written the answer. A
+ *     20 MB result used to be redacted and deep-copied twice *in front of* its
+ *     own delivery.
  */
-import { BIR_CALL_ID } from "../control/correlation.js";
+import { BIR_CALL_ID, type ProxyStepReport } from "../control/correlation.js";
 import { type JsonRpcMessage, type JsonRpcResponse } from "../jsonrpc/types.js";
 import type { Interceptor, PendingRequest } from "./relay.js";
 import type { ProxySession } from "./session.js";
@@ -30,6 +33,28 @@ export interface RecordingInterceptorOptions {
     serverName: string;
     session: ProxySession;
 }
+/**
+ * A step report as this proxy sends it. `argsFingerprint` is the fingerprint
+ * join key computed on the *raw* arguments: the `args` a report carries are
+ * redacted and clipped, so a fingerprint the control server computed from them
+ * would miss its hook-side twin whenever redaction or clipping changed
+ * anything. Extra, so an older control server just ignores it.
+ */
+export type ProxyStepWireReport = ProxyStepReport & {
+    argsFingerprint?: string;
+};
+/**
+ * Declare the call-id key on one tool's input schema so a host that validates
+ * `updatedInput` against it accepts an injected id.
+ *
+ * Deliberately minimal — the model reads these schemas on every request: no
+ * text naming the runner, and `additionalProperties` stays whatever the upstream
+ * declared (declaring the key is already enough; forcing `true` advertised a
+ * strict server as accepting anything, inviting arguments it then rejects).
+ */
+export declare function tolerateCallId(schema: unknown): unknown;
+/** Apply {@link tolerateCallId} to every tool of a `tools/list` result. */
+export declare function tolerateCallIdInToolsList(result: unknown): unknown;
 export declare class RecordingInterceptor implements Interceptor {
     private readonly serverName;
     private readonly session;
@@ -42,7 +67,12 @@ export declare class RecordingInterceptor implements Interceptor {
     /** Build the step report from a completed call. Redaction happens on the copy. */
     private report;
     /**
-     * Redact, then clip long strings, on the recording copy only.
+     * Clip, redact, clip — on the recording copy only.
+     *
+     * Clipping first keeps redaction's regexes off megabytes that are about to be
+     * thrown away. It clips to *twice* the cap first, so a secret straddling the
+     * final cut is still whole — and still recognisable — when redaction runs;
+     * clipping straight to the cap could leave a token prefix no pattern matches.
      *
      * Clipping happens here rather than only at serialization time because a
      * browser MCP's base64 screenshot would otherwise sit in the step queue in
@@ -50,6 +80,20 @@ export declare class RecordingInterceptor implements Interceptor {
      */
     private scrub;
 }
+/**
+ * The interceptor of a proxy that records nothing — started while the runner
+ * was off (`bir off`, `BIR_OFF=1`) with a remote upstream, where there is no
+ * process to hand stdio to and the relay must stay in the path.
+ *
+ * It does one thing: strip the call id. The runner can be switched back on
+ * mid-session, and a control server may then inject an id into a call routed
+ * here (a replay-pinned step, `bypassPermissions`, an explicit opt-in). A
+ * strict upstream would reject the unknown key, and the user would see a
+ * tool error the runner caused. No tracking, no reporting, no schema change.
+ */
+export declare class StripCallIdInterceptor implements Interceptor {
+    onHostMessage(msg: JsonRpcMessage): ReturnType<NonNullable<Interceptor["onHostMessage"]>>;
+}
 /** Re-exported so callers wiring a proxy need one import for the correlation key. */
 export { BIR_CALL_ID };
 //# sourceMappingURL=intercept.d.ts.map