@basein/runner 0.2.11 → 0.3.0

package/dist/replay/tool-error.d.ts

@@ -13,13 +13,27 @@
  * reports failures as ordinary text with `isError: false`, `postgres-mcp` among
  * them, is taken at its word on both sides: its `Error: relation does not exist`
  * is a successful call here, as it was when it was recorded. A built-in's
- * hook-shaped response is never judged.
+ * hook-shaped response is never judged here: the host says whether a built-in
+ * failed (`PostToolUseFailure`), and the control server hands that verdict to
+ * `ReplayController.postTool` itself.
  */
 /**
  * The error a serialized `CallToolResult` reports, or undefined when it does
  * not. `serialized` is the proxy's own serialization — the whole result, as JSON.
  */
 export declare function toolResultError(serialized: string): string | undefined;
+/**
+ * Whether a serialized result is no result at all.
+ *
+ * A proxy that reports a call its upstream abandoned — the server died
+ * mid-call (`proxy/intercept.ts`, `onAbandoned`) — sends `isError` and no
+ * result, and the control server threads `serializeCapped(redact(undefined))`,
+ * which is `null`. A real `CallToolResult` is always an object, so this can
+ * only mean the call never produced one: it was sent, and may or may not have
+ * done its work. Read as a success, the next step was pinned and auto-approved
+ * on top of a call nobody saw finish.
+ */
+export declare function isNoResult(serialized: string | undefined): boolean;
 /**
  * What a server says when a tool no longer exists — the one failure a grace
  * period cannot cure (plan-services.md D8, kind 2).

package/dist/replay/tool-error.js

@@ -13,7 +13,9 @@
  * reports failures as ordinary text with `isError: false`, `postgres-mcp` among
  * them, is taken at its word on both sides: its `Error: relation does not exist`
  * is a successful call here, as it was when it was recorded. A built-in's
- * hook-shaped response is never judged.
+ * hook-shaped response is never judged here: the host says whether a built-in
+ * failed (`PostToolUseFailure`), and the control server hands that verdict to
+ * `ReplayController.postTool` itself.
  */
 const MAX_ERROR_CHARS = 500;
 /**
@@ -31,10 +33,40 @@ export function toolResultError(serialized) {
     if (!parsed || typeof parsed !== "object")
         return undefined;
     const result = parsed;
+    // A protocol-level failure. When a `tools/call` is answered with a JSON-RPC
+    // `error` instead of a result, the proxy's step report carries that error
+    // object as the "result" (`proxy/intercept.ts`): `{ code, message }`, with no
+    // `content` and no `isError`. Read as a success, a steered step the upstream
+    // refused (bad arguments, a crashed handler) threaded as if it had worked, and
+    // the next step was pinned and auto-approved on top of it. A real
+    // `CallToolResult` always carries `content`, so the shape cannot be mistaken
+    // for one.
+    if (result.content === undefined &&
+        typeof result.code === "number" &&
+        typeof result.message === "string") {
+        return clip(`${result.code}: ${result.message}`);
+    }
     if (result.isError !== true)
         return undefined;
     return clip(firstText(result.content) ?? "the tool reported an error");
 }
+/**
+ * Whether a serialized result is no result at all.
+ *
+ * A proxy that reports a call its upstream abandoned — the server died
+ * mid-call (`proxy/intercept.ts`, `onAbandoned`) — sends `isError` and no
+ * result, and the control server threads `serializeCapped(redact(undefined))`,
+ * which is `null`. A real `CallToolResult` is always an object, so this can
+ * only mean the call never produced one: it was sent, and may or may not have
+ * done its work. Read as a success, the next step was pinned and auto-approved
+ * on top of a call nobody saw finish.
+ */
+export function isNoResult(serialized) {
+    if (serialized === undefined)
+        return true;
+    const trimmed = serialized.trim();
+    return trimmed === "" || trimmed === "null" || trimmed === "undefined";
+}
 /**
  * What a server says when a tool no longer exists — the one failure a grace
  * period cannot cure (plan-services.md D8, kind 2).

package/dist/replay/types.d.ts

@@ -211,10 +211,13 @@ export declare const OUTCOME_RANK: Record<ExecutionOutcome, number>;
  * What became of one step of a replay.
  *
  *   `ok`       — its tool ran here and its output threaded.
- *   `recorded` — its tool could not run here, so its recorded output stood in.
- *                A pass, with an asterisk: the values are from the source run.
- *   `skipped`  — its tool could not run and there was no recorded output. The
- *                step did not happen at all; later steps read nothing from it.
+ *   `recorded` — its tool could not be sent from here, so its recorded output
+ *                stood in (only with `BIR_REPLAY_RECORDED_OUTPUTS=1`, and `bir
+ *                replay`). A pass, with an asterisk: the values are from the
+ *                source run.
+ *   `skipped`  — its call produced no result here: it could not be sent, or it
+ *                was sent and never answered (its error says which). The run
+ *                stops at it; nothing after it ran.
  *   `failed`   — the *scenario's own logic* threw, or its tool ran and reported
  *                an error (stage `tool_call`). Either way the step's work did
  *                not happen, and a plan cannot claim success past it.

package/dist/upstream/client.d.ts

@@ -12,9 +12,9 @@
  * The primitive here is therefore message-level: {@link send} takes any
  * `JsonRpcMessage` verbatim and {@link onMessage} hands back any message the
  * upstream originates, in either role. `request`/`notify` remain, implemented on
- * top, for the few places that genuinely want a call (`bir doctor`, tests) — and
- * they allocate ids in the reserved `bir:` space so they can never collide with a
- * host id passing through (Phase 1.3).
+ * top, for the few places that genuinely want a call (`bir doctor`, tests, the
+ * replay work loop) — and they allocate ids in the reserved `bir:` space so they
+ * can never collide with a host id passing through (Phase 1.3).
  */
 import type { JsonRpcMessage } from "../jsonrpc/types.js";
 /** Why the upstream connection ended. */
@@ -23,6 +23,25 @@ export interface UpstreamCloseInfo {
     signal?: NodeJS.Signals | null;
     error?: Error;
 }
+/**
+ * An answer the upstream produced but the transport could not deliver — today,
+ * a response line over the framing cap. `id` is what could be recovered from
+ * the line's ends; the relay uses it to answer the host's request instead of
+ * leaving it waiting forever.
+ */
+export interface UndeliverableInfo {
+    id?: string | number;
+    /**
+     * The line was recognisably an answer (its first bytes say `result` or
+     * `error`), and no proxy-originated request was out when it arrived. Only
+     * then may an answer without a recoverable id be matched to the single host
+     * call in flight; anything less is a guess that can hand the wrong call an
+     * error and then its real answer as well.
+     */
+    response?: boolean;
+    bytes: number;
+    reason: string;
+}
 export interface UpstreamClient {
     /** Resolves when the transport is usable; rejects if the upstream is unusable. */
     readonly ready: Promise<void>;
@@ -34,11 +53,28 @@ export interface UpstreamClient {
     onMessage(handler: (msg: JsonRpcMessage) => void): void;
     /** Called once when the upstream connection ends, for any reason. */
     onClose(handler: (info: UpstreamCloseInfo) => void): void;
+    /**
+     * An upstream answer that could not be delivered (see {@link UndeliverableInfo}).
+     * Optional: a transport that can never drop an answer need not offer it.
+     */
+    onUndeliverable?(handler: (info: UndeliverableInfo) => void): void;
+    /**
+     * The upstream died and is being restarted (`--restart`). Nothing that was in
+     * flight will ever be answered by the new process, so the relay answers it.
+     */
+    onRestart?(handler: (info: UpstreamCloseInfo) => void): void;
     /** Convenience call in the reserved `bir:` id space. Never used by the relay. */
     request(method: string, params?: unknown, signal?: AbortSignal): Promise<unknown>;
     /** Fire-and-forget notification toward the upstream. */
     notify(method: string, params?: unknown): void;
     close(): void;
+    /**
+     * Close politely and wait, bounded by `graceMs` plus a short kill window:
+     * the upstream is given the chance to exit on its own before it (and, on
+     * Windows, everything it started) is killed. Optional; `close()` is the
+     * fallback.
+     */
+    shutdown?(graceMs?: number): Promise<void>;
 }
 /**
  * The id prefix reserved for requests the proxy itself originates. Host ids pass
@@ -57,14 +93,20 @@ export declare abstract class BaseUpstreamClient implements UpstreamClient {
     abstract readonly ready: Promise<void>;
     private readonly messageHandlers;
     private readonly closeHandlers;
+    private readonly undeliverableHandlers;
+    private readonly restartHandlers;
     private readonly pending;
     private nextId;
     private isDead;
     get dead(): boolean;
+    /** Proxy-originated (`bir:`) requests still waiting for their answer. */
+    protected get ownRequestsInFlight(): number;
     abstract send(msg: JsonRpcMessage): void;
     abstract close(): void;
     onMessage(handler: (msg: JsonRpcMessage) => void): void;
     onClose(handler: (info: UpstreamCloseInfo) => void): void;
+    onUndeliverable(handler: (info: UndeliverableInfo) => void): void;
+    onRestart(handler: (info: UpstreamCloseInfo) => void): void;
     request(method: string, params?: unknown, signal?: AbortSignal): Promise<unknown>;
     notify(method: string, params?: unknown): void;
     /**
@@ -72,6 +114,17 @@ export declare abstract class BaseUpstreamClient implements UpstreamClient {
      * consumed here and never reach the relay; everything else fans out verbatim.
      */
     protected accept(msg: JsonRpcMessage): void;
+    /**
+     * Report an answer that could not be delivered. A `bir:` id is ours and is
+     * failed here; anything else goes to the relay, which owns host requests.
+     */
+    protected undeliverable(info: UndeliverableInfo): void;
+    /**
+     * The process behind this client died and a new one is being started. Every
+     * in-flight `request()` fails (the new process never saw it), and the relay
+     * is told so it can answer the host's in-flight requests likewise.
+     */
+    protected restarting(info: UpstreamCloseInfo): void;
     /** Mark the connection over. Idempotent; fails every in-flight `request()`. */
     protected closed(info: UpstreamCloseInfo): void;
 }

package/dist/upstream/client.js

@@ -12,9 +12,9 @@
  * The primitive here is therefore message-level: {@link send} takes any
  * `JsonRpcMessage` verbatim and {@link onMessage} hands back any message the
  * upstream originates, in either role. `request`/`notify` remain, implemented on
- * top, for the few places that genuinely want a call (`bir doctor`, tests) — and
- * they allocate ids in the reserved `bir:` space so they can never collide with a
- * host id passing through (Phase 1.3).
+ * top, for the few places that genuinely want a call (`bir doctor`, tests, the
+ * replay work loop) — and they allocate ids in the reserved `bir:` space so they
+ * can never collide with a host id passing through (Phase 1.3).
  */
 /**
  * The id prefix reserved for requests the proxy itself originates. Host ids pass
@@ -34,12 +34,18 @@ export function isBirId(id) {
 export class BaseUpstreamClient {
     messageHandlers = [];
     closeHandlers = [];
+    undeliverableHandlers = [];
+    restartHandlers = [];
     pending = new Map();
     nextId = 1;
     isDead = false;
     get dead() {
         return this.isDead;
     }
+    /** Proxy-originated (`bir:`) requests still waiting for their answer. */
+    get ownRequestsInFlight() {
+        return this.pending.size;
+    }
     onMessage(handler) {
         this.messageHandlers.push(handler);
     }
@@ -50,14 +56,33 @@ export class BaseUpstreamClient {
         }
         this.closeHandlers.push(handler);
     }
+    onUndeliverable(handler) {
+        this.undeliverableHandlers.push(handler);
+    }
+    onRestart(handler) {
+        this.restartHandlers.push(handler);
+    }
     request(method, params, signal) {
         if (this.isDead)
             return Promise.reject(new Error("upstream is not available"));
+        if (signal?.aborted)
+            return Promise.reject(new Error(`${method} aborted`));
         const id = `${BIR_ID_PREFIX}${this.nextId++}`;
         return new Promise((resolve, reject) => {
             const onAbort = () => {
-                this.pending.delete(id);
+                if (!this.pending.delete(id))
+                    return;
                 reject(new Error(`${method} aborted`));
+                // The caller has stopped waiting, but the upstream has not stopped
+                // working: a replay step that timed out would otherwise still run to
+                // completion — after the control server may already have substituted
+                // a recorded output for it, doubling a side effect nobody can see.
+                // A late answer to this id is dropped by `accept`, which finds no
+                // waiter left for it.
+                const reason = signal?.reason?.name === "TimeoutError"
+                    ? "timeout"
+                    : "aborted";
+                this.notify("notifications/cancelled", { requestId: id, reason });
             };
             signal?.addEventListener("abort", onAbort, { once: true });
             this.pending.set(id, {
@@ -95,6 +120,38 @@ export class BaseUpstreamClient {
         for (const handler of this.messageHandlers)
             handler(msg);
     }
+    /**
+     * Report an answer that could not be delivered. A `bir:` id is ours and is
+     * failed here; anything else goes to the relay, which owns host requests.
+     */
+    undeliverable(info) {
+        if (isBirId(info.id)) {
+            const waiter = this.pending.get(info.id);
+            if (waiter) {
+                this.pending.delete(info.id);
+                waiter.cleanup();
+                waiter.reject(new Error(info.reason));
+            }
+            return;
+        }
+        for (const handler of this.undeliverableHandlers)
+            handler(info);
+    }
+    /**
+     * The process behind this client died and a new one is being started. Every
+     * in-flight `request()` fails (the new process never saw it), and the relay
+     * is told so it can answer the host's in-flight requests likewise.
+     */
+    restarting(info) {
+        const err = info.error ?? new Error("upstream restarted");
+        for (const [, waiter] of this.pending) {
+            waiter.cleanup();
+            waiter.reject(err);
+        }
+        this.pending.clear();
+        for (const handler of this.restartHandlers)
+            handler(info);
+    }
     /** Mark the connection over. Idempotent; fails every in-flight `request()`. */
     closed(info) {
         if (this.isDead)

package/dist/upstream/headers.d.ts

@@ -0,0 +1,43 @@
+/**
+ * headers — the credentials a remote upstream is reached with.
+ *
+ * WHERE THEY COME FROM. A wrapped remote server is a stdio entry that runs
+ * `bir-proxy --url …`, so its headers reach the proxy at spawn time. Two ways,
+ * both kept:
+ *
+ *   - `BIR_UPSTREAM_HEADERS`, a JSON object of header name → string value, in
+ *     the entry's `env` — where an install puts them now, because an entry's
+ *     `args` show up in process listings and its `env` does not;
+ *   - `--header 'Name: value'` arguments, repeatable — what older entries and
+ *     hand-written `bir wrap` lines carry. On a clash the argument wins.
+ *
+ * THE VALUES ARE SECRETS. Nothing here logs one, or the raw variable: a
+ * problem is described by its shape ("not JSON", "2 entries skipped") and, at
+ * most, a count. The variable is removed from the proxy's environment as soon
+ * as it is read (bir-proxy.ts), so no process the proxy starts inherits it.
+ */
+/** The environment variable a wrapped remote entry carries its headers in. */
+export declare const UPSTREAM_HEADERS_ENV = "BIR_UPSTREAM_HEADERS";
+export interface ParsedHeaders {
+    headers: Record<string, string>;
+    /** Why some or all of the input was not used. Never contains a value. */
+    problem?: string;
+}
+/**
+ * Keep only the headers Node can send. A bad name or value would otherwise
+ * make *every* request to the upstream fail at the socket, as "unreachable".
+ */
+export declare function sendableHeaders(input: Record<string, string>): ParsedHeaders;
+/**
+ * Parse `BIR_UPSTREAM_HEADERS`. Absent or empty → no headers and no problem.
+ * Not JSON, or not an object of strings → whatever is usable, and a problem
+ * that says what was wrong without repeating any of it.
+ */
+export declare function parseUpstreamHeaders(raw: string | undefined): ParsedHeaders;
+/**
+ * `base` overlaid with `override`, header names compared case-insensitively
+ * (HTTP's rule): `authorization` in one and `Authorization` in the other is
+ * one header, and `override`'s spelling and value are the ones kept.
+ */
+export declare function mergeHeaders(base: Record<string, string>, override: Record<string, string>): Record<string, string>;
+//# sourceMappingURL=headers.d.ts.map

package/dist/upstream/headers.js

@@ -0,0 +1,90 @@
+/**
+ * headers — the credentials a remote upstream is reached with.
+ *
+ * WHERE THEY COME FROM. A wrapped remote server is a stdio entry that runs
+ * `bir-proxy --url …`, so its headers reach the proxy at spawn time. Two ways,
+ * both kept:
+ *
+ *   - `BIR_UPSTREAM_HEADERS`, a JSON object of header name → string value, in
+ *     the entry's `env` — where an install puts them now, because an entry's
+ *     `args` show up in process listings and its `env` does not;
+ *   - `--header 'Name: value'` arguments, repeatable — what older entries and
+ *     hand-written `bir wrap` lines carry. On a clash the argument wins.
+ *
+ * THE VALUES ARE SECRETS. Nothing here logs one, or the raw variable: a
+ * problem is described by its shape ("not JSON", "2 entries skipped") and, at
+ * most, a count. The variable is removed from the proxy's environment as soon
+ * as it is read (bir-proxy.ts), so no process the proxy starts inherits it.
+ */
+/** The environment variable a wrapped remote entry carries its headers in. */
+export const UPSTREAM_HEADERS_ENV = "BIR_UPSTREAM_HEADERS";
+/** An HTTP header name: RFC 9110's `token`. Node refuses anything else at send time. */
+const HEADER_NAME = /^[!#$%&'*+.^_`|~0-9A-Za-z-]+$/;
+/** A header value Node will send: no CR, LF, NUL or other control bytes, nothing past Latin-1. */
+const HEADER_VALUE = /^[\t\x20-\x7e\x80-\xff]*$/;
+/**
+ * Keep only the headers Node can send. A bad name or value would otherwise
+ * make *every* request to the upstream fail at the socket, as "unreachable".
+ */
+export function sendableHeaders(input) {
+    const headers = {};
+    let skipped = 0;
+    for (const [name, value] of Object.entries(input)) {
+        if (!HEADER_NAME.test(name) || typeof value !== "string" || !HEADER_VALUE.test(value)) {
+            skipped += 1;
+            continue;
+        }
+        headers[name] = value;
+    }
+    return skipped ? { headers, problem: `${skipped} header(s) skipped: not a valid HTTP header name or value` } : { headers };
+}
+/**
+ * Parse `BIR_UPSTREAM_HEADERS`. Absent or empty → no headers and no problem.
+ * Not JSON, or not an object of strings → whatever is usable, and a problem
+ * that says what was wrong without repeating any of it.
+ */
+export function parseUpstreamHeaders(raw) {
+    if (raw === undefined || raw.trim() === "")
+        return { headers: {} };
+    let parsed;
+    try {
+        parsed = JSON.parse(raw);
+    }
+    catch {
+        return { headers: {}, problem: "not valid JSON; ignored" };
+    }
+    if (!parsed || typeof parsed !== "object" || Array.isArray(parsed)) {
+        return { headers: {}, problem: "not a JSON object of header name to value; ignored" };
+    }
+    const strings = {};
+    let nonString = 0;
+    for (const [name, value] of Object.entries(parsed)) {
+        if (typeof value === "string")
+            strings[name] = value;
+        else
+            nonString += 1;
+    }
+    const sendable = sendableHeaders(strings);
+    const problems = [
+        nonString ? `${nonString} header(s) skipped: the value is not a string` : undefined,
+        sendable.problem,
+    ].filter((p) => p !== undefined);
+    return problems.length ? { headers: sendable.headers, problem: problems.join("; ") } : { headers: sendable.headers };
+}
+/**
+ * `base` overlaid with `override`, header names compared case-insensitively
+ * (HTTP's rule): `authorization` in one and `Authorization` in the other is
+ * one header, and `override`'s spelling and value are the ones kept.
+ */
+export function mergeHeaders(base, override) {
+    const out = { ...base };
+    for (const [name, value] of Object.entries(override)) {
+        const lower = name.toLowerCase();
+        for (const key of Object.keys(out))
+            if (key !== name && key.toLowerCase() === lower)
+                delete out[key];
+        out[name] = value;
+    }
+    return out;
+}
+//# sourceMappingURL=headers.js.map