@basein/runner 0.3.24 → 0.3.26

package/dist/upstream/http-client.js

@@ -41,12 +41,14 @@
  *      `initialize` got a 405 and the server showed as failed every session).
  *      A stream that ends — cleanly or not — is noticed, the requests riding it
  *      are answered, and it is re-established with backoff; the new session is
- *      re-initialised with the host's own `initialize` before anything else.
+ *      re-initialised with the host's own `initialize` before anything else,
+ *      and a stream whose re-initialisation fails is a reconnect that failed.
  *   4. **Session expiry is survivable.** A 404 to a request that carried a
  *      session means the server forgot us (a redeploy, an idle timeout). The
  *      spec says start a new session; the proxy does it for the host — replays
  *      the host's cached `initialize` under a `bir:` id, sends `initialized`,
- *      and retries the request once.
+ *      and retries the request once. A replay that fails is tried again when
+ *      the next request meets the same 404.
  *   5. **No timeout shorter than the host's.** The transport (http-transport.ts)
  *      bounds the connect only; how long a tool may take is Claude Code's call,
  *      and its cancellation reaches the server immediately (rule 2). What no
@@ -72,7 +74,7 @@
  * recovery, a session the server forgot, and a stream that keeps dropping as
  * soon as it opens (once an hour per server at most).
  */
-import { readFrames } from "../jsonrpc/framing.js";
+import { readFrames, receivedText, rememberText } from "../jsonrpc/framing.js";
 import { paramsObject } from "../jsonrpc/types.js";
 import { logDetail, logEvery, logLine, logOnce, errText } from "../util/log.js";
 import { BaseUpstreamClient, BIR_ID_PREFIX, isBirId } from "./client.js";
@@ -341,7 +343,11 @@ export class HttpUpstreamClient extends BaseUpstreamClient {
                 accept: "application/json, text/event-stream",
                 ...this.sessionHeaders(method === "initialize"),
                 ...this.headers,
-            }, JSON.stringify(msg), controller.signal);
+            }, 
+            // The host's own line when this is the message as the relay read it
+            // (jsonrpc/framing.ts): serialised again, an integer past 2^53 in a
+            // tool's arguments reached the server rounded.
+            receivedText(msg) ?? JSON.stringify(msg), controller.signal);
         }
         catch (err) {
             clearTimeout(abandonTimer);
@@ -516,8 +522,16 @@ export class HttpUpstreamClient extends BaseUpstreamClient {
         if (Array.isArray(parsed))
             for (const item of parsed)
                 this.deliver(item);
-        else
+        else {
+            // One message, and this is its text: the relay writes it to the host as
+            // the server wrote it rather than as JavaScript read it (framing.ts).
+            // Without the white space around it — a body often ends in a newline —
+            // and only when it is one line; a batch's members have no text of their
+            // own, and are serialised as before.
+            if (parsed && typeof parsed === "object")
+                rememberText(parsed, raw.trim());
             this.deliver(parsed);
+        }
         return true;
     }
     /** Hand one inbound JSON-RPC message to the relay (or to a `bir:` waiter). */
@@ -601,7 +615,18 @@ export class HttpUpstreamClient extends BaseUpstreamClient {
             if (this.transport === "http") {
                 this.sessionId = undefined;
                 this.resetStandingStream();
-                return this.reinitialize();
+                if (await this.reinitialize())
+                    return true;
+                // No new session: a 503 from an instance still starting, a network
+                // error, no answer in time. Left without an id, every later request
+                // went out bare, the server answered 400 or 404, and none of that
+                // read as "forgotten" any more — errors for the rest of the host's
+                // session, with the proxy up. Holding the forgotten id again makes
+                // the next request's 404 start another attempt. An id this attempt
+                // was handed is dropped with it: its handshake never completed.
+                if (!this.dead)
+                    this.sessionId = staleKey;
+                return false;
             }
             // Legacy: the session *is* the event stream. Drop it and open a new one;
             // reconnect() replays the handshake. A reconnect already under way (the
@@ -634,9 +659,10 @@ export class HttpUpstreamClient extends BaseUpstreamClient {
     /**
      * Replay the host's `initialize` (under a `bir:` id) and `initialized`.
      * `news`: say it on stderr when it worked — after a forgotten session or an
-     * outage; after a routine reconnect it is detail. A failure is always said.
+     * outage; after a routine reconnect it is detail. A failure is said, unless
+     * `failureSaid`: it is one more of an outage whose first failure was.
      */
-    async reinitialize(news = true) {
+    async reinitialize(news = true, failureSaid = false) {
         if (this.initParams === undefined || this.dead)
             return false;
         this.reinitCount += 1;
@@ -663,7 +689,10 @@ export class HttpUpstreamClient extends BaseUpstreamClient {
             return false;
         if (!reply || !("result" in reply)) {
             const error = reply ? paramsObject(reply.error).message : "no answer";
-            logLine("upstream.reinitialize_failed", { server: this.label, error: String(error ?? "error") });
+            (failureSaid ? logDetail : logLine)("upstream.reinitialize_failed", {
+                server: this.label,
+                error: String(error ?? "error"),
+            });
             return false;
         }
         this.noteProtocolVersion(reply.result);
@@ -856,15 +885,27 @@ export class HttpUpstreamClient extends BaseUpstreamClient {
                 return false;
             }
             const recovered = this.reconnectFailures > 0;
+            // A new event stream is a new, uninitialised session: replay the host's
+            // handshake before anything else is let through. Until that has worked
+            // the reconnect has not: counted as done on the stream alone, a replay
+            // the server refused (it was still starting) left every later request
+            // posted to a session nobody had initialised, and nothing ever tried
+            // again. So the stream is dropped and the attempt counts as failed —
+            // backoff, and the next request pulls a new one forward.
+            if (this.initParams !== undefined && !(await this.reinitialize(recovered || afterExpiry, recovered))) {
+                if (this.dead)
+                    return false;
+                this.reconnectFailures += 1;
+                this.onSseStreamLost(this.generation, "re-initialise failed", true);
+                this.streamAbort?.abort();
+                this.scheduleReconnect();
+                return false;
+            }
             (recovered ? logLine : logDetail)("upstream.stream_reconnected", {
                 server: this.label,
                 failedAttempts: this.reconnectFailures,
             });
             this.reconnectFailures = 0;
-            // A new event stream is a new, uninitialised session: replay the host's
-            // handshake before anything else is let through.
-            if (this.initParams !== undefined)
-                await this.reinitialize(recovered || afterExpiry);
             return true;
         })();
         this.connecting = attempt;

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

@@ -22,6 +22,7 @@
  * {@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 ChildProcessWithoutNullStreams } from "node:child_process";
 import { type JsonRpcMessage } from "../jsonrpc/types.js";
 import { BaseUpstreamClient } from "./client.js";
 export interface StdioUpstreamOptions {
@@ -80,6 +81,12 @@ export declare function whichSync(command: string, env?: NodeJS.ProcessEnv): str
  * On POSIX this is the identity. On Windows a batch file is wrapped in `cmd.exe`.
  */
 export declare function resolveCommand(command: string, args: string[], env?: NodeJS.ProcessEnv): ResolvedCommand;
+/**
+ * Kill `child` and everything it started. On Windows that takes `taskkill /T`
+ * (a plain kill terminates one process: `cmd.exe`, not the server behind it);
+ * elsewhere SIGTERM, then SIGKILL. Bounded; never throws.
+ */
+export declare function killTree(child: ChildProcessWithoutNullStreams): Promise<void>;
 export declare class StdioUpstreamClient extends BaseUpstreamClient {
     readonly ready: Promise<void>;
     private child?;

package/dist/upstream/stdio-client.js

@@ -161,7 +161,7 @@ function waitForExit(child, ms) {
  * (a plain kill terminates one process: `cmd.exe`, not the server behind it);
  * elsewhere SIGTERM, then SIGKILL. Bounded; never throws.
  */
-async function killTree(child) {
+export async function killTree(child) {
     const pid = child.pid;
     if (pid === undefined)
         return;

package/dist/util/atomic-write.d.ts

@@ -19,11 +19,19 @@
  *   - a symlinked target (dotfile managers do this to ~/.claude.json) must keep
  *     being a symlink, so the rename goes to the link's real target.
  *
- * The existing file's mode is kept; `mode` applies to a new file.
+ * The existing file's mode is kept; `mode` applies to a new file, and to an
+ * existing one too with `replaceMode`.
  */
 export interface AtomicWriteOptions {
     /** Mode for a file that does not exist yet. An existing file keeps its own. */
     mode?: number;
+    /**
+     * `mode` for an existing file as well: a file a credential goes in. Kept,
+     * the old file's mode went to the new one, and when the old file was not
+     * ours to chmod first (root's 0644, after `sudo claude`), the token went
+     * into a file that is ours and readable by every account.
+     */
+    replaceMode?: boolean;
 }
 export declare function writeFileAtomic(path: string, data: string | Uint8Array, opts?: AtomicWriteOptions): void;
 //# sourceMappingURL=atomic-write.d.ts.map

package/dist/util/atomic-write.js

@@ -19,7 +19,8 @@
  *   - a symlinked target (dotfile managers do this to ~/.claude.json) must keep
  *     being a symlink, so the rename goes to the link's real target.
  *
- * The existing file's mode is kept; `mode` applies to a new file.
+ * The existing file's mode is kept; `mode` applies to a new file, and to an
+ * existing one too with `replaceMode`.
  */
 import { chmodSync, lstatSync, realpathSync, renameSync, statSync, unlinkSync, writeFileSync, } from "node:fs";
 import { randomBytes } from "node:crypto";
@@ -42,11 +43,13 @@ function resolveTarget(path) {
 export function writeFileAtomic(path, data, opts = {}) {
     const target = resolveTarget(path);
     let mode = opts.mode;
-    try {
-        mode = statSync(target).mode & 0o777;
-    }
-    catch {
-        /* new file */
+    if (!(opts.replaceMode && mode !== undefined)) {
+        try {
+            mode = statSync(target).mode & 0o777;
+        }
+        catch {
+            /* new file */
+        }
     }
     const tmp = join(dirname(target), `.${basename(target)}.${process.pid}.${randomBytes(4).toString("hex")}.tmp`);
     try {

package/dist/util/service-health.d.ts

@@ -35,6 +35,13 @@ export declare const MAX_COOLDOWN_MS = 60000;
  * and never answers, holding a socket and a chain slot the whole time.
  */
 export declare const DEFAULT_SERVICE_TIMEOUT_MS = 10000;
+/**
+ * The longest delay a Node timer takes. Given more, `setTimeout` warns and
+ * waits 1 ms instead — so `BIR_SERVICE_TIMEOUT_MS=3000000000`, set to switch
+ * the timeout off, ended every request at once. Every delay that comes from
+ * the environment or from a caller is held to this.
+ */
+export declare const MAX_TIMER_MS = 2147483647;
 export declare function serviceTimeoutMs(): number;
 export interface HealthSnapshot {
     /** False while a cool-down is running: hot paths do not wait. */

package/dist/util/service-health.js

@@ -36,9 +36,16 @@ export const MAX_COOLDOWN_MS = 60_000;
  * and never answers, holding a socket and a chain slot the whole time.
  */
 export const DEFAULT_SERVICE_TIMEOUT_MS = 10_000;
+/**
+ * The longest delay a Node timer takes. Given more, `setTimeout` warns and
+ * waits 1 ms instead — so `BIR_SERVICE_TIMEOUT_MS=3000000000`, set to switch
+ * the timeout off, ended every request at once. Every delay that comes from
+ * the environment or from a caller is held to this.
+ */
+export const MAX_TIMER_MS = 2_147_483_647;
 export function serviceTimeoutMs() {
     const n = Number(process.env.BIR_SERVICE_TIMEOUT_MS);
-    return Number.isFinite(n) && n > 0 ? n : DEFAULT_SERVICE_TIMEOUT_MS;
+    return Number.isFinite(n) && n > 0 ? Math.min(n, MAX_TIMER_MS) : DEFAULT_SERVICE_TIMEOUT_MS;
 }
 export class ServiceHealth {
     failures = 0;
@@ -170,7 +177,7 @@ export async function awaitWithin(pending, budgetMs, what, health = serviceHealt
         const winner = await Promise.race([
             pending,
             new Promise((resolve) => {
-                timer = setTimeout(() => resolve(timedOut), budgetMs);
+                timer = setTimeout(() => resolve(timedOut), Math.min(budgetMs, MAX_TIMER_MS));
                 timer.unref?.();
             }),
         ]);
@@ -197,7 +204,7 @@ export async function awaitWithin(pending, budgetMs, what, health = serviceHealt
  */
 export function timeoutSignal(ms = serviceTimeoutMs(), parent) {
     const controller = new AbortController();
-    const timer = setTimeout(() => controller.abort(new DOMException(`timed out after ${ms} ms`, "TimeoutError")), ms);
+    const timer = setTimeout(() => controller.abort(new DOMException(`timed out after ${ms} ms`, "TimeoutError")), Math.min(ms, MAX_TIMER_MS));
     timer.unref?.();
     if (parent) {
         if (parent.aborted) {

package/docs/calculatedReplay.md

@@ -771,6 +771,38 @@ Delivery, best channel first. (A direct plan's own results go through `run_scena
    (`assembleBundle`/`truncate`, portable verbatim from `payload-executor.ts`). Works for any tool,
    and is read as adversarial — hence last.
 
+**How a bundle reads** ([`bundle.ts`](../src/replay/bundle.ts); the same in a direct run's answer,
+§6). The agent pays once to take the bundle in, as new input, and on a long plan that was most of a
+replayed task's bill — so nothing in it repeats what the model already has. Each result is shown as
+its text, not as MCP's `CallToolResult` JSON (the envelope and its second layer of escaping told the
+model nothing), with `(error)` when `isError` is set; a result with anything but text — an image, a
+resource, structured content — is shown as it came. Consecutive calls to one tool share a section,
+`--- Steps a-b: tool (n calls) ---`, with one numbered line per call, `n: input -> result`. Input
+fields with the same value in every call are said once above them (`In every call: {…}`), and so is
+an answer every call got (`Every call's result: …`). A step on its own, and a step left out, keep
+`--- Step n: tool ---`. Nothing is dropped, and each result keeps its fair share of the cap. On
+B2's length tests this made bundles 27% shorter, 33% at 50–60 steps.
+
+**A run that went well reads briefly** (`AssembleOptions.brief`, asked for by a direct run, §6). When
+every step ran live and succeeded and the agent is to answer now, its job is to see that the steps
+were right and say what was done — not to read every word of every result. So the header says every
+call succeeded; a result up to 300 characters is shown whole; a longer one that is JSON keeps every
+record and field, and only its text longer than 40 characters is cut, with "…" (`cutLongText`: the
+IDs, dates, senders and names the agent checks the steps against are short; an e-mail's body is
+not). A long result in words is shown whole — it may be the very answer. Showing only the values the
+plan took from a long result was tried first: it left the agent unable to check the plan's choices
+("I couldn't confirm these were the newest") in one reply in six on B2's length tests, and once it
+reported a correct run as wrong. The plan's summary (its response model) is said in a few words
+(short lists whole, long ones counted), in the bundle, above the footer — so `bir-scenario` gets
+`responseModel: {}` and does not append it again — and is left out when it only says it was left
+out. The footer asks for
+the answer in a few sentences: the reply is output, the dearest tokens an agent spends. Anything
+that went wrong — a step that reported an error, a run that stopped short, a recorded stand-in, a
+sub-task the agent carries on with — gets the full bundle above, because that is what the agent
+works from next. For the same reason a direct run's directive (`steeringDirective`) no longer lists
+the planned steps: the model calls none of them, and the answer names every call and says whether
+the run was whole. An operator's `bir replay` and a divergence bundle are always full.
+
 **Tier 2 — abort.** Composition itself threw (`replay.compose_failed`). Retire the plan, return
 `{}`, continue as an ordinary turn. Outcome `failed`.
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@basein/runner",
-  "version": "0.3.24",
+  "version": "0.3.26",
   "description": "A recording MCP proxy: sits between any MCP client and its MCP servers, executes each call on the client's behalf, and records the run as a reusable BaseIn scenario.",
   "type": "module",
   "license": "MIT",

package/production.md

@@ -523,7 +523,7 @@ Over 2-minute runs with one turn every 8 s (92 hooks):
 
 - **Backlog.** The backlog is bounded: 500 sends or 32 MiB, oldest steps dropped first. A queued send still facing a cool-down after 60 s is dropped unsent, not sent into the outage.
 - **Flush.** A flush waits at most 2 s (`BIR_FLUSH_TIMEOUT_MS`), and not at all while the service is cooling down.
-- **Retries.** A retry happens once, only after 429, 503, or a connection error that proves nothing reached the service. A 409 on the retry counts as "already landed". There is no retry after 502, 504 or a mid-request reset, until the service confirms it deduplicates ids (§10). What a 429 costs is in §3.3. The service's new build answers a report whose write failed with `503 report_not_booked`, so this one retry sends the report once more (built, not deployed yet).
+- **Retries.** A retry happens once, only after 429, 503, or a connection error that proves nothing reached the service. A 409 on the retry counts as "already landed". There is no retry after 502, 504 or a mid-request reset, until the service confirms it deduplicates ids (§10). What a 429 costs is in §3.3. The service's new build answers a report whose write failed with `503 report_not_booked`, so this one retry sends the report once more (built, not deployed yet). Three sends are different, because the service takes a second copy of each without harm: a run's finish and a patch (an update that keeps what it has), and an execution report that carries its ticket (a second copy answers `200 duplicate`). From 0.3.26 each of these goes back to the head of its lane when it fails with no answer or an unhealthy one (502, 504, a reset), up to 3 sends in all, and it is exempt from the 60 s give-up. Before, a run whose finish was lost never ended (never embedded, matched or calculated), and a turn whose report was lost was never booked. Any other 4xx stays final.
 
 **Size caps on uploads.**
 
@@ -1174,7 +1174,7 @@ Defaults were checked in `src/`.
 - **Two sessions in one project.** Direct replays for a session whose own proxy has not yet bound hand over instead of running.
 - **Revive gaps.** `bir-scenario` does not revive in its first 12 s; those first hooks are left to the SessionStart hook. A session with no wrapped server and no `bir` server is not revived until `/clear` or a new session. The revive window was not measured with real Claude Code.
 - **Direct-run worst case.** The worst case by budget is 120 s: 8 s of derivation, 100 s of plan, and 12 s of slack. It is reached only if every logic body hits its limit, and sits at Claude Code's 2-minute MCP auto-background. Setting `BIR_REPLAY_BUDGET_MS=120000` (the old default) makes it 140 s.
-- **Retries are conservative.** A send lost to a 502, 504 or mid-request reset is not retried until the service deduplicates ids.
+- **Retries are conservative.** A step or run create lost to a 502, 504 or mid-request reset is not retried until the service deduplicates ids. (A finish, a patch and a ticketed report are sent up to 3 times from 0.3.26: the service takes a second copy of each without harm, §6.5. The service now answers a repeated run or step id with 409.)
 - **Healthy-service prompt cost.** With an instant local service the prompt hook is about 6 ms slower than 0.2.12 (about 17 vs 11 ms median); the cause was not isolated. Under 503 or slow answers the recorder also keeps more idle keep-alive sockets. Both are small, but visible in measurements.
 - **A host other than Claude Code is not checked end to end.** What §3.2 describes ran on a bench only: a real LangChain agent against the real recorder, with a stand-in service and a fake model (`examples/langchain-proof/`). A real model, the real service and the production server have not been tried. The service's part is built and not deployed, and the Python package is not on PyPI. What that means for a LangChain application today is in `langChainGuide.md`, part 5.
 - **An interrupted or lossy Claude Code run is not marked.** Only a run of another host is finished with an `error` or with the `incomplete` mark today. A Claude Code run that was interrupted or lost steps is finished as before.

package/scripts/install.ps1

@@ -65,6 +65,11 @@ function Invoke-BirInstall {
     # child's environment only, set right before the spawn and removed after.
     $setupToken = $env:BIR_SETUP_TOKEN
     if ($setupToken) { Remove-Item -Path Env:BIR_SETUP_TOKEN -ErrorAction SilentlyContinue }
+    # The uninstall switch the same way: read once and taken out of the session,
+    # so pasting the ordinary install line later in this window installs, and
+    # does not uninstall again.
+    $uninstall = ($env:BIR_UNINSTALL -eq '1')
+    if ($null -ne $env:BIR_UNINSTALL) { Remove-Item -Path Env:BIR_UNINSTALL -ErrorAction SilentlyContinue }
 
     # Inside the function on purpose: under `irm | iex` these would otherwise
     # change the session the person keeps working in.
@@ -262,7 +267,14 @@ function Invoke-BirInstall {
                 Write-Note "node v$Version already at $exe"
                 return $exe
             }
-            # Half an extraction or a foreign file: removed, never extracted over.
+        }
+        # Half an extraction, a foreign file, or a folder whose node.exe is gone
+        # (an antivirus quarantine takes just that): removed, never extracted
+        # over. Whenever the folder is there, not only when node.exe is - a
+        # Move-Item onto a folder that exists moves the new one INSIDE it, so
+        # node.exe never appeared where it is looked for and every retry
+        # failed, 80 MB heavier. install.sh removes it the same way.
+        if (Test-Path -LiteralPath $nodeDir) {
             if ($dryRun) { Write-Would "remove the unusable $nodeDir" }
             else {
                 try { Remove-Item -LiteralPath $nodeDir -Recurse -Force }
@@ -459,7 +471,7 @@ public static extern IntPtr SendMessageTimeout(IntPtr hWnd, uint Msg, UIntPtr wP
         # before its files go. Every wrapped MCP server and every hook names a
         # file under ~\.baseinstrunner; deleting that first would break them
         # all, in every project, with no `bir` left to repair it.
-        if ($env:BIR_UNINSTALL -eq '1') {
+        if ($uninstall) {
             Write-Step 'Removing the runner from every project on this machine'
             $birCmd = Join-Path $birHome 'bin\bir.cmd'
             if (-not (Test-Path -LiteralPath $birCmd -PathType Leaf)) {