@basein/runner 0.2.11 → 0.3.0

package/dist/upstream/sse.d.ts

@@ -0,0 +1,78 @@
+/**
+ * sse — a Server-Sent Events parser for the remote upstream (http-client.ts).
+ *
+ * WHY NOT THE OBVIOUS TEN LINES. The first version appended each chunk to one
+ * string and re-ran a blank-line regex over the whole buffer on every chunk.
+ * That is quadratic in the size of one event: a 24 MB tool result (a
+ * screenshot, a file) took 2.6 s to parse as SSE against 0.18 s as JSON, all of
+ * it added to the user's tool call. It also computed the separator length by
+ * guessing (`\r\n\n` ate the next event's first byte), never recognised a lone
+ * CR — which the SSE spec allows — so a CR-only server's answers never arrived,
+ * and it had no size bound at all.
+ *
+ * So this one is line-oriented and linear:
+ *
+ *   - each chunk is scanned once, from where the last one stopped; a partial
+ *     line is kept as a list of pieces and joined once, when its terminator
+ *     arrives (a V8 `+=` rope would be flattened by every search);
+ *   - CRLF, LF and lone CR all end a line, including a CRLF split across two
+ *     chunks;
+ *   - the fields are the spec's (`data`, `event`, `id`, `retry`, `:` comments),
+ *     so a stream's last event id and retry hint are available to reconnects;
+ *   - one event's data is capped (the framing layer's 32 MiB by default). Past
+ *     it `push` returns false and the caller abandons the stream and answers the
+ *     request it was carrying, rather than allocating until the process dies.
+ */
+import type { Readable } from "node:stream";
+export interface SseEvent {
+    /** The `event:` field; `"message"` when the event named none. */
+    event: string;
+    /** The `data:` lines joined with `\n`. */
+    data: string;
+    /** The stream's last event id at dispatch time, when it has one. */
+    id?: string;
+}
+/** Raised by {@link readSseStream} when one event outgrows the cap. */
+export declare class SseTooLargeError extends Error {
+    constructor(limit: number);
+}
+export declare class SseParser {
+    /** The last `id:` seen. Per the spec it persists across events. */
+    lastEventId: string;
+    /** The server's `retry:` hint in ms, when it sent one. */
+    retryMs?: number;
+    private readonly onEvent;
+    private readonly maxEventChars;
+    /** The unterminated tail of the current line, in pieces (see the header). */
+    private partial;
+    private partialChars;
+    private dataLines;
+    private dataChars;
+    private eventType;
+    /** The previous chunk ended in CR: a leading LF on the next one is its pair. */
+    private pendingCr;
+    private overflowed;
+    /** Per instance: a shared global regex would share `lastIndex`. */
+    private readonly lineBreak;
+    constructor(onEvent: (event: SseEvent) => void, maxEventChars?: number);
+    /** True once an event outgrew the cap; the parser ignores input from then on. */
+    get tooLarge(): boolean;
+    /** Feed decoded text. Returns false once one event has outgrown the cap. */
+    push(text: string): boolean;
+    private overflow;
+    private line;
+    private dispatch;
+}
+/**
+ * Read an SSE body to its end, calling `onEvent` per complete event. Resolves
+ * when the stream ends cleanly; rejects when it errors (a reset, an abort) or
+ * with {@link SseTooLargeError} when one event outgrows the cap — the body is
+ * destroyed then, so the socket is released. An event handler that throws is
+ * isolated: one bad event must not end the stream carrying every other answer.
+ */
+export declare function readSseStream(body: Readable, onEvent: (event: SseEvent) => void, opts?: {
+    maxEventBytes?: number;
+    parser?: (parser: SseParser) => void;
+    onHandlerError?: (err: unknown) => void;
+}): Promise<void>;
+//# sourceMappingURL=sse.d.ts.map

package/dist/upstream/sse.js

@@ -0,0 +1,189 @@
+/**
+ * sse — a Server-Sent Events parser for the remote upstream (http-client.ts).
+ *
+ * WHY NOT THE OBVIOUS TEN LINES. The first version appended each chunk to one
+ * string and re-ran a blank-line regex over the whole buffer on every chunk.
+ * That is quadratic in the size of one event: a 24 MB tool result (a
+ * screenshot, a file) took 2.6 s to parse as SSE against 0.18 s as JSON, all of
+ * it added to the user's tool call. It also computed the separator length by
+ * guessing (`\r\n\n` ate the next event's first byte), never recognised a lone
+ * CR — which the SSE spec allows — so a CR-only server's answers never arrived,
+ * and it had no size bound at all.
+ *
+ * So this one is line-oriented and linear:
+ *
+ *   - each chunk is scanned once, from where the last one stopped; a partial
+ *     line is kept as a list of pieces and joined once, when its terminator
+ *     arrives (a V8 `+=` rope would be flattened by every search);
+ *   - CRLF, LF and lone CR all end a line, including a CRLF split across two
+ *     chunks;
+ *   - the fields are the spec's (`data`, `event`, `id`, `retry`, `:` comments),
+ *     so a stream's last event id and retry hint are available to reconnects;
+ *   - one event's data is capped (the framing layer's 32 MiB by default). Past
+ *     it `push` returns false and the caller abandons the stream and answers the
+ *     request it was carrying, rather than allocating until the process dies.
+ */
+import { DEFAULT_MAX_LINE_BYTES } from "../jsonrpc/framing.js";
+/** Raised by {@link readSseStream} when one event outgrows the cap. */
+export class SseTooLargeError extends Error {
+    constructor(limit) {
+        super(`an event stream message exceeded ${limit} bytes`);
+        this.name = "SseTooLargeError";
+    }
+}
+export class SseParser {
+    /** The last `id:` seen. Per the spec it persists across events. */
+    lastEventId = "";
+    /** The server's `retry:` hint in ms, when it sent one. */
+    retryMs;
+    onEvent;
+    maxEventChars;
+    /** The unterminated tail of the current line, in pieces (see the header). */
+    partial = [];
+    partialChars = 0;
+    dataLines = [];
+    dataChars = 0;
+    eventType = "";
+    /** The previous chunk ended in CR: a leading LF on the next one is its pair. */
+    pendingCr = false;
+    overflowed = false;
+    /** Per instance: a shared global regex would share `lastIndex`. */
+    lineBreak = /\r\n|\r|\n/g;
+    constructor(onEvent, maxEventChars = DEFAULT_MAX_LINE_BYTES) {
+        this.onEvent = onEvent;
+        this.maxEventChars = maxEventChars;
+    }
+    /** True once an event outgrew the cap; the parser ignores input from then on. */
+    get tooLarge() {
+        return this.overflowed;
+    }
+    /** Feed decoded text. Returns false once one event has outgrown the cap. */
+    push(text) {
+        if (this.overflowed)
+            return false;
+        if (text.length === 0)
+            return true; // keep a pending CR for the next chunk
+        let start = 0;
+        if (this.pendingCr && text.charCodeAt(0) === 10)
+            start = 1;
+        this.pendingCr = false;
+        const lineBreak = this.lineBreak;
+        lineBreak.lastIndex = start;
+        let match;
+        while ((match = lineBreak.exec(text)) !== null) {
+            let line = text.slice(start, match.index);
+            if (this.partial.length > 0) {
+                this.partial.push(line);
+                line = this.partial.join("");
+                this.partial = [];
+                this.partialChars = 0;
+            }
+            start = match.index + match[0].length;
+            // A CR as the very last character may be the first half of a CRLF.
+            if (match[0] === "\r" && start === text.length)
+                this.pendingCr = true;
+            this.line(line);
+            if (this.overflowed)
+                return false;
+        }
+        if (start < text.length) {
+            const rest = text.slice(start);
+            this.partial.push(rest);
+            this.partialChars += rest.length;
+        }
+        if (this.dataChars + this.partialChars > this.maxEventChars) {
+            this.overflow();
+            return false;
+        }
+        return true;
+    }
+    overflow() {
+        this.overflowed = true;
+        this.partial = [];
+        this.dataLines = [];
+    }
+    line(line) {
+        if (line.length === 0) {
+            this.dispatch();
+            return;
+        }
+        if (line.charCodeAt(0) === 58 /* ":" */)
+            return; // a comment / keep-alive
+        const colon = line.indexOf(":");
+        let field;
+        let value;
+        if (colon === -1) {
+            field = line;
+            value = "";
+        }
+        else {
+            field = line.slice(0, colon);
+            value = line.slice(colon + 1);
+            if (value.charCodeAt(0) === 32 /* " " */)
+                value = value.slice(1);
+        }
+        switch (field) {
+            case "data":
+                this.dataLines.push(value);
+                this.dataChars += value.length + 1;
+                if (this.dataChars > this.maxEventChars)
+                    this.overflow();
+                break;
+            case "event":
+                this.eventType = value;
+                break;
+            case "id":
+                if (!value.includes("\0"))
+                    this.lastEventId = value;
+                break;
+            case "retry":
+                if (/^\d+$/.test(value))
+                    this.retryMs = Number(value);
+                break;
+            default:
+                // Unknown fields are ignored, per the spec.
+                break;
+        }
+    }
+    dispatch() {
+        const event = this.eventType || "message";
+        this.eventType = "";
+        if (this.dataLines.length === 0)
+            return; // the spec: no data, no event
+        const data = this.dataLines.join("\n");
+        this.dataLines = [];
+        this.dataChars = 0;
+        this.onEvent(this.lastEventId ? { event, data, id: this.lastEventId } : { event, data });
+    }
+}
+/**
+ * Read an SSE body to its end, calling `onEvent` per complete event. Resolves
+ * when the stream ends cleanly; rejects when it errors (a reset, an abort) or
+ * with {@link SseTooLargeError} when one event outgrows the cap — the body is
+ * destroyed then, so the socket is released. An event handler that throws is
+ * isolated: one bad event must not end the stream carrying every other answer.
+ */
+export async function readSseStream(body, onEvent, opts = {}) {
+    const limit = opts.maxEventBytes ?? DEFAULT_MAX_LINE_BYTES;
+    const parser = new SseParser((event) => {
+        try {
+            onEvent(event);
+        }
+        catch (err) {
+            opts.onHandlerError?.(err);
+        }
+    }, limit);
+    opts.parser?.(parser);
+    // Decoding with `stream: true` keeps a multi-byte character split across two
+    // chunks intact; the parser only ever sees whole characters.
+    const decoder = new TextDecoder("utf-8");
+    for await (const chunk of body) {
+        const text = typeof chunk === "string" ? chunk : decoder.decode(chunk, { stream: true });
+        if (!parser.push(text)) {
+            body.destroy();
+            throw new SseTooLargeError(limit);
+        }
+    }
+    parser.push(decoder.decode());
+}
+//# sourceMappingURL=sse.js.map

package/dist/upstream/stdio-client.d.ts

@@ -14,8 +14,15 @@
  *     mangles JSON), {@link resolveCommand} resolves the real file on PATH and,
  *     for a batch file, invokes `cmd.exe /d /s /c` with `windowsVerbatimArguments`
  *     and its own quoting.
+ *
+ * AND ONE THING THAT BREAKS THE USER'S MACHINE: a server the proxy started must
+ * not outlive it. On Windows a batch-file upstream is `cmd.exe` → `node` (or
+ * `python`, or Chrome), and killing `cmd.exe` leaves the rest running — holding
+ * a browser profile or a database lock the next session then cannot open. So
+ * {@link StdioUpstreamClient.shutdown} closes stdin first (the MCP-spec way to
+ * ask a server to exit), waits briefly, and only then kills the whole tree.
  */
-import type { JsonRpcMessage } from "../jsonrpc/types.js";
+import { type JsonRpcMessage } from "../jsonrpc/types.js";
 import { BaseUpstreamClient } from "./client.js";
 export interface StdioUpstreamOptions {
     command: string;
@@ -26,6 +33,8 @@ export interface StdioUpstreamOptions {
     label?: string;
     /** Restart once with this backoff if the upstream dies unexpectedly. 0 disables. */
     restartDelayMs?: number;
+    /** Largest upstream line parsed. Defaults to the framing default; tests lower it. */
+    maxLineBytes?: number;
 }
 /** What `spawn` should actually be given for `command` on this platform. */
 export interface ResolvedCommand {
@@ -33,6 +42,37 @@ export interface ResolvedCommand {
     args: string[];
     windowsVerbatimArguments?: boolean;
 }
+/** Default time a closing upstream gets to exit on stdin EOF before it is killed. */
+export declare const DEFAULT_SHUTDOWN_GRACE_MS = 1500;
+/**
+ * Quote one argument for `cmd.exe /c` and, behind it, the C runtime's argv
+ * parser in whatever the batch file launches.
+ *
+ * Three rules, each for a case that used to arrive mangled:
+ *   - An embedded `"` becomes `""`, which cmd reads as leaving and re-entering
+ *     a quoted run (so its metacharacters stay quoted) and the C runtime reads
+ *     as one literal quote.
+ *   - Backslashes before a quote — an embedded one or our closing one — are
+ *     doubled, because the C runtime reads `\"` as an escaped quote.
+ *     `C:\projects\` used to swallow the next argument whole.
+ *   - `%` is taken *out* of the quotes and caret-escaped: cmd expands `%NAME%`
+ *     even inside quotes, and a caret is literal there. Outside them, `^%`
+ *     survives expansion (the text between the two percents is no longer a
+ *     variable name, because it contains a quote) and the caret is removed
+ *     afterwards, leaving `%`. The C runtime then joins the pieces:
+ *     `"a"%"B"%"c"` is the single argument `a%B%c`.
+ */
+export declare function quoteForCmd(arg: string): string;
+/**
+ * Read an environment variable the way Windows does — case-insensitively.
+ *
+ * `process.env` is case-insensitive on Windows, but a *copy* of it (`{ ...process.env }`,
+ * which is what spawning with extra variables needs) is a plain object, and a
+ * normal Windows process spells the key `Path`. Reading `.PATH` off the copy
+ * found nothing, `npx` stayed unresolved, and every npx-launched server failed
+ * with `spawn npx ENOENT` whenever a host passed its environment through.
+ */
+export declare function envValue(env: NodeJS.ProcessEnv, key: string): string | undefined;
 /** Find `command` on PATH, trying PATHEXT extensions. Returns undefined if absent. */
 export declare function whichSync(command: string, env?: NodeJS.ProcessEnv): string | undefined;
 /**
@@ -48,10 +88,30 @@ export declare class StdioUpstreamClient extends BaseUpstreamClient {
     private readonly opts;
     private restartsLeft;
     private closing;
+    /**
+     * Set while a `--restart` is in progress: host messages wait here for the
+     * new process to be spawned and re-initialised, instead of being written
+     * into a dead pipe and lost.
+     */
+    private restartBuffer?;
+    /** True while our replayed `initialize` is the one message allowed through. */
+    private handshaking;
+    /** The host's `initialize` params, replayed to a restarted upstream. */
+    private hostInitParams?;
+    private hostInitialized;
     constructor(opts: StdioUpstreamOptions);
     private start;
     private onChildGone;
+    /** Start a new process, replay the host's handshake to it, then release held messages. */
+    private restart;
     send(msg: JsonRpcMessage): void;
+    private write;
     close(): void;
+    /**
+     * Close the way the MCP spec asks a client to: end stdin, give the server
+     * `graceMs` to exit on its own, then kill it — with its whole process tree on
+     * Windows. A server that exits on EOF (nearly all do) costs no wait at all.
+     */
+    shutdown(graceMs?: number): Promise<void>;
 }
 //# sourceMappingURL=stdio-client.d.ts.map