@basein/runner 0.2.11 → 0.3.0

package/dist/proxy/intercept.js

@@ -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,14 +19,85 @@
  * 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, extractCallId, qualifyToolName, relaxToolsListResult, } from "../control/correlation.js";
+import { BIR_CALL_ID, extractCallId, fingerprint, qualifyToolName, } from "../control/correlation.js";
 import { redact } from "../record/redact.js";
-import { truncateStrings, DEFAULT_MAX_STRING_BYTES } from "../record/truncate.js";
+import { truncateStrings, serializeCapped, DEFAULT_MAX_STRING_BYTES, DEFAULT_MAX_PAYLOAD_BYTES, } from "../record/truncate.js";
 import { paramsObject } from "../jsonrpc/types.js";
-import { logDetail } from "../util/log.js";
+import { logDetail, logLine, errText } from "../util/log.js";
+/**
+ * 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 function tolerateCallId(schema) {
+    if (!schema || typeof schema !== "object" || Array.isArray(schema))
+        return schema;
+    const base = schema;
+    const props = base.properties;
+    if (props !== undefined && (!props || typeof props !== "object" || Array.isArray(props)))
+        return schema;
+    return {
+        ...base,
+        properties: {
+            ...(props ?? {}),
+            [BIR_CALL_ID]: { type: "string", description: "Reserved. Leave unset." },
+        },
+    };
+}
+/** Apply {@link tolerateCallId} to every tool of a `tools/list` result. */
+export function tolerateCallIdInToolsList(result) {
+    if (!result || typeof result !== "object" || Array.isArray(result))
+        return result;
+    const r = result;
+    if (!Array.isArray(r.tools))
+        return result;
+    return {
+        ...r,
+        tools: r.tools.map((tool) => {
+            if (!tool || typeof tool !== "object" || Array.isArray(tool))
+                return tool;
+            const t = tool;
+            return { ...t, inputSchema: tolerateCallId(t.inputSchema) };
+        }),
+    };
+}
+/**
+ * Keep a recorded payload inside the per-payload cap *before* it is queued.
+ * An oversized value becomes exactly the marker `serializeCapped` would have
+ * written for it at record time, so what is finally recorded is unchanged —
+ * but the queue, and the loopback POST to the control server (which serves
+ * every hook on the same event loop), no longer carry megabytes to get there.
+ */
+function capForReport(value) {
+    let json;
+    try {
+        json = JSON.stringify(value);
+    }
+    catch {
+        return { truncated: true, reason: "unserializable" };
+    }
+    if (json === undefined)
+        return value;
+    if (json.length <= DEFAULT_MAX_PAYLOAD_BYTES / 3 || Buffer.byteLength(json, "utf8") <= DEFAULT_MAX_PAYLOAD_BYTES) {
+        return value;
+    }
+    try {
+        return JSON.parse(serializeCapped(value));
+    }
+    catch {
+        return { truncated: true, originalBytes: Buffer.byteLength(json, "utf8") };
+    }
+}
 export class RecordingInterceptor {
     serverName;
     session;
@@ -46,12 +117,19 @@ export class RecordingInterceptor {
         const params = paramsObject(msg.params);
         const toolName = String(params.name ?? "");
         const { callId, cleaned } = extractCallId(params.arguments);
-        this.calls.set(id, { callId, toolName, args: cleaned, startedAt: Date.now() });
-        if (callId === undefined)
+        // Nothing to record when the session records nothing (the project never
+        // opted in, or the runner is off): no call is tracked, so nothing is held.
+        if (this.session.recording) {
+            this.calls.set(id, { callId, toolName, args: cleaned, startedAt: Date.now() });
+        }
+        // `extractCallId` hands back the very same object when the key is absent.
+        if (cleaned === params.arguments)
             return { action: "forward" };
         // The upstream must never see a key its schema does not declare, so the
-        // correlation id is stripped here rather than being relayed and ignored.
-        logDetail("call.correlated", { server: this.serverName, tool: toolName, callId });
+        // correlation id is stripped here — in every tier, whatever its value —
+        // rather than being relayed and ignored.
+        if (callId !== undefined)
+            logDetail("call.correlated", { server: this.serverName, tool: toolName, callId });
         return {
             action: "forward",
             message: {
@@ -62,12 +140,13 @@ export class RecordingInterceptor {
     }
     onUpstreamResponse(pending, response) {
         if (pending.method === "tools/list") {
-            // The only rewrite in the whole proxy, and only when Tier 1 correlation is
-            // actually active: relaxation is visible to the model on every call, so it
-            // is never paid for unless it is buying a merged step (Phase 6).
-            if (!this.session.correlationActive || response.error)
+            // The only rewrite in the whole proxy, and only when a control server may
+            // inject call ids into this server's calls (Phase 6). Decided by the
+            // session so it does not depend on whether registration happened to beat
+            // this answer.
+            if (!this.session.declaresCallId || response.error)
                 return;
-            return { ...response, result: relaxToolsListResult(response.result) };
+            return { ...response, result: tolerateCallIdInToolsList(response.result) };
         }
         if (pending.method !== "tools/call")
             return;
@@ -75,9 +154,9 @@ export class RecordingInterceptor {
         this.calls.delete(pending.id);
         if (!call)
             return;
-        // Report *after* returning: the relay writes what we return here, and the
-        // queue push below runs on this same tick but does no I/O of its own.
-        this.report(call, response);
+        // Report on a later tick: the relay writes the answer as soon as this
+        // returns, and the copy's redaction and clipping cost nothing it waits on.
+        setImmediate(() => this.report(call, response));
         return; // the upstream's result, verbatim
     }
     onAbandoned(pending, reason) {
@@ -85,61 +164,111 @@ export class RecordingInterceptor {
         if (!call)
             return;
         this.calls.delete(pending.id);
-        this.session.reportStep({
-            callId: call.callId,
-            serverName: this.serverName,
-            toolName: call.toolName,
-            qualifiedName: qualifyToolName(this.serverName, call.toolName),
-            args: this.scrub(call.args),
-            isError: true,
-            errorMessage: reason,
-            startedAt: call.startedAt,
-            durationMs: Date.now() - call.startedAt,
+        const durationMs = Date.now() - call.startedAt;
+        setImmediate(() => {
+            try {
+                const step = {
+                    callId: call.callId,
+                    serverName: this.serverName,
+                    toolName: call.toolName,
+                    qualifiedName: qualifyToolName(this.serverName, call.toolName),
+                    args: capForReport(this.scrub(call.args)),
+                    argsFingerprint: fingerprint(this.serverName, call.toolName, call.args),
+                    isError: true,
+                    errorMessage: reason,
+                    startedAt: call.startedAt,
+                    durationMs,
+                };
+                this.session.reportStep(step);
+            }
+            catch (err) {
+                logLine("proxy.report_failed", { server: this.serverName, error: errText(err) });
+            }
         });
     }
     /** Build the step report from a completed call. Redaction happens on the copy. */
     report(call, response) {
-        const durationMs = Date.now() - call.startedAt;
-        const result = response.result;
-        let isError = false;
-        let errorMessage;
-        if (response.error) {
-            // A protocol-level failure: the call never produced a tool result.
-            isError = true;
-            errorMessage = `${response.error.code}: ${response.error.message}`;
+        try {
+            const durationMs = Date.now() - call.startedAt;
+            const result = response.result;
+            let isError = false;
+            let errorMessage;
+            if (response.error) {
+                // A protocol-level failure: the call never produced a tool result.
+                isError = true;
+                errorMessage = `${response.error.code}: ${response.error.message}`;
+            }
+            else if (result && typeof result === "object" && result.isError === true) {
+                isError = true;
+            }
+            const step = {
+                callId: call.callId,
+                serverName: this.serverName,
+                toolName: call.toolName,
+                qualifiedName: qualifyToolName(this.serverName, call.toolName),
+                args: capForReport(this.scrub(call.args)),
+                argsFingerprint: fingerprint(this.serverName, call.toolName, call.args),
+                result: capForReport(response.error ? this.scrub(response.error) : this.scrub(response.result)),
+                isError,
+                errorMessage,
+                startedAt: call.startedAt,
+                durationMs,
+            };
+            this.session.reportStep(step);
+            logDetail("call.done", {
+                server: this.serverName,
+                tool: call.toolName,
+                ms: durationMs,
+                isError,
+            });
         }
-        else if (result && typeof result === "object" && result.isError === true) {
-            isError = true;
+        catch (err) {
+            // Recording is best-effort; nothing here may become an uncaught exception.
+            logLine("proxy.report_failed", { server: this.serverName, error: errText(err) });
         }
-        const step = {
-            callId: call.callId,
-            serverName: this.serverName,
-            toolName: call.toolName,
-            qualifiedName: qualifyToolName(this.serverName, call.toolName),
-            args: this.scrub(call.args),
-            result: response.error ? this.scrub(response.error) : this.scrub(response.result),
-            isError,
-            errorMessage,
-            startedAt: call.startedAt,
-            durationMs,
-        };
-        this.session.reportStep(step);
-        logDetail("call.done", {
-            server: this.serverName,
-            tool: call.toolName,
-            ms: durationMs,
-            isError,
-        });
     }
     /**
-     * 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
      * full, possibly for the length of the run.
      */
     scrub(value) {
-        return truncateStrings(redact(value), DEFAULT_MAX_STRING_BYTES);
+        return truncateStrings(redact(truncateStrings(value, DEFAULT_MAX_STRING_BYTES * 2)), DEFAULT_MAX_STRING_BYTES);
+    }
+}
+/**
+ * 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 class StripCallIdInterceptor {
+    onHostMessage(msg) {
+        if (msg.method !== "tools/call")
+            return { action: "forward" };
+        const params = paramsObject(msg.params);
+        const { cleaned } = extractCallId(params.arguments);
+        if (cleaned === params.arguments)
+            return { action: "forward" };
+        return {
+            action: "forward",
+            message: {
+                ...msg,
+                params: { ...params, arguments: cleaned },
+            },
+        };
     }
 }
 /** Re-exported so callers wiring a proxy need one import for the correlation key. */

package/dist/proxy/relay.d.ts

@@ -92,6 +92,22 @@ export declare class Relay {
      * where a JSON-RPC error just breaks the client's tool plumbing (§10).
      */
     private deadUpstreamAnswer;
+    /** An `isError` tool result for `tools/call`, a JSON-RPC error for anything else. */
+    private failureAnswer;
+    /**
+     * The upstream answered, but the answer could not be delivered (a line over
+     * the framing cap). Answer the request it was for, so the host's call ends
+     * with an error the model can react to instead of spinning until Esc.
+     *
+     * The id comes from the line's ends and may be missing. Without it, the
+     * request is identifiable only when the line was recognisably an answer
+     * (`info.response`) and exactly one host call — a `tools/call`, the request
+     * whose answers are the big ones — is in flight. Anything looser is a guess:
+     * an oversized notification used to be "matched" to the one call in flight,
+     * which got a false error and then its real answer too. With several in
+     * flight nothing is answered, and each keeps waiting for its own reply.
+     */
+    private onUndeliverable;
     private abandonAll;
 }
 //# sourceMappingURL=relay.d.ts.map

package/dist/proxy/relay.js

@@ -66,6 +66,9 @@ export class Relay {
             writeFrame(hostOut, msg, (err) => logLine("relay.write_failed", { label, error: errText(err) }));
         });
         upstream.onClose(() => this.abandonAll("upstream closed"));
+        // `--restart`: nothing in flight will be answered by the new process.
+        upstream.onRestart?.(() => this.abandonAll("upstream restarted"));
+        upstream.onUndeliverable?.((info) => this.onUndeliverable(info));
         this.detach = readFrames(hostIn, {
             onMessage: (msg) => this.onHostMessage(msg),
             onParseError: (detail) => {
@@ -110,14 +113,32 @@ export class Relay {
                 const p = this.pending.get(requestId);
                 if (p) {
                     this.pending.delete(requestId);
-                    interceptor?.onAbandoned?.(p, "cancelled by host");
+                    try {
+                        interceptor?.onAbandoned?.(p, "cancelled by host");
+                    }
+                    catch (err) {
+                        logLine("relay.intercept_failed", { label, error: errText(err) });
+                    }
                 }
             }
         }
         if (isRequest(outgoing)) {
             if (upstream.dead) {
-                // §10: the host must get an answer, or it waits forever.
-                writeFrame(hostOut, this.deadUpstreamAnswer(outgoing.id, outgoing.method));
+                // §10: the host must get an answer, or it waits forever. The
+                // interceptor has already opened a call for it; close that too, or it
+                // is held (arguments and all) for the life of the process.
+                try {
+                    interceptor?.onAbandoned?.({
+                        id: outgoing.id,
+                        method: outgoing.method,
+                        params: outgoing.params,
+                        startedAt: Date.now(),
+                    }, "upstream unavailable");
+                }
+                catch (err) {
+                    logLine("relay.intercept_failed", { label, error: errText(err) });
+                }
+                writeFrame(hostOut, this.deadUpstreamAnswer(outgoing.id, outgoing.method), (err) => logLine("relay.write_failed", { label, error: errText(err) }));
                 return;
             }
             this.pending.set(outgoing.id, {
@@ -141,7 +162,12 @@ export class Relay {
      * where a JSON-RPC error just breaks the client's tool plumbing (§10).
      */
     deadUpstreamAnswer(id, method) {
-        const message = `upstream MCP server "${this.opts.label ?? "unknown"}" is not available`;
+        // Phrased as the host would phrase it unwrapped — about the server, not
+        // about a proxy the user never needs to know is there.
+        return this.failureAnswer(id, method, `MCP server "${this.opts.label ?? "unknown"}" is not available`);
+    }
+    /** An `isError` tool result for `tools/call`, a JSON-RPC error for anything else. */
+    failureAnswer(id, method, message) {
         if (method === "tools/call") {
             return {
                 jsonrpc: "2.0",
@@ -151,6 +177,44 @@ export class Relay {
         }
         return errorResponse(id, JsonRpcErrorCode.UpstreamUnavailable, message);
     }
+    /**
+     * The upstream answered, but the answer could not be delivered (a line over
+     * the framing cap). Answer the request it was for, so the host's call ends
+     * with an error the model can react to instead of spinning until Esc.
+     *
+     * The id comes from the line's ends and may be missing. Without it, the
+     * request is identifiable only when the line was recognisably an answer
+     * (`info.response`) and exactly one host call — a `tools/call`, the request
+     * whose answers are the big ones — is in flight. Anything looser is a guess:
+     * an oversized notification used to be "matched" to the one call in flight,
+     * which got a false error and then its real answer too. With several in
+     * flight nothing is answered, and each keeps waiting for its own reply.
+     */
+    onUndeliverable(info) {
+        const { hostOut, interceptor, label } = this.opts;
+        let target;
+        if (info.id !== undefined) {
+            target = this.pending.get(info.id);
+        }
+        else if (info.response && this.pending.size === 1) {
+            const only = [...this.pending.values()][0];
+            if (only.method === "tools/call")
+                target = only;
+        }
+        if (!target) {
+            logLine("relay.undeliverable_unmatched", { label, bytes: info.bytes, id: info.id, inFlight: this.pending.size });
+            return;
+        }
+        this.pending.delete(target.id);
+        logLine("relay.undeliverable", { label, method: target.method, id: target.id, bytes: info.bytes });
+        try {
+            interceptor?.onAbandoned?.(target, info.reason);
+        }
+        catch (err) {
+            logLine("relay.intercept_failed", { label, error: errText(err) });
+        }
+        writeFrame(hostOut, this.failureAnswer(target.id, target.method, capitalise(info.reason)), (err) => logLine("relay.write_failed", { label, error: errText(err) }));
+    }
     abandonAll(reason) {
         if (this.pending.size === 0)
             return;
@@ -158,9 +222,17 @@ export class Relay {
         logLine("relay.abandoning", { label, requests: this.pending.size, reason });
         for (const [id, p] of [...this.pending]) {
             this.pending.delete(id);
-            interceptor?.onAbandoned?.(p, reason);
+            try {
+                interceptor?.onAbandoned?.(p, reason);
+            }
+            catch (err) {
+                logLine("relay.intercept_failed", { label, error: errText(err) });
+            }
             writeFrame(hostOut, this.deadUpstreamAnswer(p.id, p.method), (err) => logLine("relay.write_failed", { label, error: errText(err) }));
         }
     }
 }
+function capitalise(text) {
+    return text ? text[0].toUpperCase() + text.slice(1) : text;
+}
 //# sourceMappingURL=relay.js.map

package/dist/proxy/revive.d.ts

@@ -0,0 +1,122 @@
+/**
+ * revive — a bound proxy brings back the recorder that died under it.
+ *
+ * Every Claude Code hook but SessionStart is an HTTP post to the project's
+ * recorder. When that process dies mid-session (killed by an antivirus or the
+ * OOM killer, or a restart from another window that did not come back), every
+ * later prompt and tool call shows the user a hook error, and only a new
+ * session, `/clear` or a compaction — the next SessionStart — started it again.
+ * A bound proxy is the one long-lived process of the session that notices, so
+ * it asks for a new one: it launches `bir-hooks revive --cwd <project>`,
+ * detached, which starts the recorder under the same start lock the
+ * SessionStart hook uses, so any number of proxies (and bir-scenario) asking
+ * at once start one recorder.
+ *
+ * ONLY WHEN IT IS DEAD, NOT SLOW. All of these, checked in this order, cheapest
+ * first:
+ *
+ *   - the project's discovery file is still there and names a pid that is no
+ *     longer running. A recorder that stopped cleanly — `bir down`, a restart —
+ *     removed its file, so a recorder the user stopped on purpose is never
+ *     brought back from here; a pid that is alive (busy, or recycled by an
+ *     unrelated process) is never second-guessed either;
+ *   - the recorder's address refuses a TCP connection. Anything that accepts
+ *     one — a recorder coming up, whatever else took the port — or does not
+ *     answer within a couple of seconds is left alone;
+ *   - `bir install` set this directory up (the sidecar has its project record).
+ *
+ * NEVER IN ANYONE'S WAY. {@link RecorderReviver.nudge} is synchronous and
+ * constant-time: it only arms a timer. The checks run on that timer, after a
+ * random 0-5 s (so the proxies of one session do not all launch in the same
+ * instant), and the launch is a detached, unref'd process with no stdio: the
+ * proxy neither waits for it nor learns how it went. At most one launch per
+ * {@link REVIVE_MIN_INTERVAL_MS} per process, backing off to
+ * {@link REVIVE_MAX_INTERVAL_MS} while launches keep not taking (a recorder
+ * that dies on start). Each launch is one audit line.
+ *
+ * Not for an explicit control channel (`BIR_CONTROL_URL` + `BIR_CONTROL_TOKEN`,
+ * the Agent SDK's): that control server is its owner's to run.
+ */
+/** At most one launch per process in this long. */
+export declare const REVIVE_MIN_INTERVAL_MS = 30000;
+/** ...doubling per launch that did not take, up to this. */
+export declare const REVIVE_MAX_INTERVAL_MS: number;
+/** A launch is delayed by a random 0 to this, so sibling proxies spread out. */
+export declare const REVIVE_MAX_JITTER_MS = 5000;
+/** The recorder a discovery file still names although its process is gone. */
+export interface DeadRecorder {
+    pid: number;
+    url: string;
+}
+/**
+ * The project's discovery file as it is on disk, when the pid it names is no
+ * longer running. `readDiscovery` hides exactly these files — correctly, for
+ * binding — and they are the evidence here: a recorder that stopped cleanly
+ * removed its own.
+ */
+export declare function deadRecorder(cwd: string): Promise<DeadRecorder | undefined>;
+/** Whether the install sidecar has a project record for `cwd`. Unreadable → no. */
+export declare function projectRecordedHere(cwd: string): Promise<boolean>;
+/**
+ * True only when a loopback `url`'s port actively refuses a TCP connection.
+ * Accepted, timed out, any other error, or not a loopback address: false.
+ */
+export declare function refusesConnections(url: string, timeoutMs?: number): Promise<boolean>;
+/**
+ * Launch `bir-hooks revive --cwd <cwd>` detached, and forget it. Never throws.
+ *
+ * On Windows the revive always starts the recorder through PowerShell's
+ * `Start-Process`, whatever `BIR_WINDOWS_LAUNCH` says: a process started from
+ * here inherits this proxy's handles — its stdout is the host's JSON-RPC pipe
+ * — and a recorder launched directly from it would hold that pipe for days
+ * (see HOW IT IS LAUNCHED in control/daemon.ts). The revive itself lives for
+ * seconds.
+ */
+export declare function launchRevive(cwd: string, opts?: {
+    script?: string;
+    env?: NodeJS.ProcessEnv;
+}): Promise<boolean>;
+export interface ReviverOptions {
+    /** The project directory: the proxy's cwd. */
+    cwd: string;
+    /** The wrapped server, for the audit line. */
+    server: string;
+    /**
+     * The environment the revive (and so the recorder it starts) is given:
+     * the one this process was started with. Default `process.env`.
+     */
+    env?: NodeJS.ProcessEnv;
+    /** Launch the revive. Default {@link launchRevive}; tests inject one. */
+    launch?: (cwd: string) => Promise<boolean> | boolean;
+    minIntervalMs?: number;
+    maxIntervalMs?: number;
+    maxJitterMs?: number;
+    checkIntervalMs?: number;
+}
+/** One per bound proxy: decides whether, and when, to launch a revive. */
+export declare class RecorderReviver {
+    private readonly opts;
+    private readonly minIntervalMs;
+    private readonly maxIntervalMs;
+    private readonly maxJitterMs;
+    private readonly checkIntervalMs;
+    private interval;
+    private timer?;
+    private pending;
+    private stopped;
+    private nextLaunchAt;
+    private nextCheckAt;
+    private lastLaunchAt;
+    /** How many revives this process launched. */
+    launches: number;
+    constructor(opts: ReviverOptions);
+    /**
+     * The recorder did not answer. Arms the check, unless one is pending or
+     * the rate limit says not yet. Synchronous, constant-time, never throws.
+     */
+    nudge(why: string): void;
+    /** No more launches: the proxy is closing. */
+    stop(): void;
+    private attempt;
+}
+//# sourceMappingURL=revive.d.ts.map