@basein/runner 0.2.3 → 0.2.5

package/dist/replay/executor.js

@@ -18,6 +18,36 @@
  * A proxy that never polls (an old build, or one started without `BIR_REPLAY`)
  * is not an error: `call` rejects with `no_proxy`, and the caller falls back to
  * the step's recorded output.
+ *
+ * WHICH PROXY. Several proxies can poll for the same server at once — one per
+ * Claude Code session in the project, and a session's proxy outlives a
+ * `bir-hooks` restart by simply re-polling. They are NOT interchangeable: each
+ * holds its own upstream, and another session's upstream may be in any state (a
+ * database connection a benchmark reset killed, a browser on another page).
+ * Handing a step to "whoever is parked first" therefore ran it on the oldest
+ * proxy in the project, which is precisely the one most likely to be stale. So
+ * every proxy polls under its own id, and a step goes to, in order:
+ *
+ *   1. a proxy bound to the step's session — learned from a correlated step the
+ *      proxy reported, or from an earlier step of this session it ran;
+ *   2. otherwise the newest unbound proxy (latest process start) — a session's
+ *      proxies are spawned when it starts, so the newest is the best guess for
+ *      a session that has not called the server yet;
+ *   3. otherwise NOBODY. A proxy bound to another session is never used for
+ *      this one: the step resolves as a tool error, so the plan stops and hands
+ *      over to the agent, who calls the tool on its own upstream. It does not
+ *      reject — a rejection lets a recorded output stand in, or skips the step
+ *      and runs the rest of the plan past it.
+ *
+ * A session's bindings are released when it ends (a `/clear` starts a new
+ * session on the same proxies). Legacy proxies, which send no id, share one
+ * record per server and are never bound: they stay a pool anyone may use.
+ *
+ * `bir replay` has no session, and takes the newest proxy, bound or not.
+ *
+ * The choice is made against proxies that are *present*, parked or not, and the
+ * work is then held for that proxy if it is mid-round-trip — never handed to a
+ * different one that happens to be parked.
  */
 import { randomUUID } from "node:crypto";
 import { logDetail } from "../util/log.js";
@@ -32,44 +62,70 @@ export const NO_PROXY = "no_proxy";
  * plan lose every step after the first.
  */
 const PRESENT_MS = 60_000;
+/**
+ * The id a proxy that sends none polls under. One per server, so older proxies
+ * keep the old behaviour between themselves: any of them may take the work.
+ */
+function legacyId(serverName) {
+    return `legacy:${serverName}`;
+}
 export class ProxyWorkQueue {
-    /** Work dispatched while its proxy was mid-round-trip, per server. */
+    /** Work held for a proxy that was mid-round-trip when it was dispatched, per proxy id. */
     pending = new Map();
     /** Pollers currently parked, per server. */
     waiters = new Map();
     /** Work handed out and awaiting a result. */
     inFlight = new Map();
-    /** serverName → when it last polled. A proxy between polls is still present. */
-    lastSeen = new Map();
+    /** Every proxy that has polled, by id. A proxy between polls is still present. */
+    proxies = new Map();
     closed = false;
     /** Servers a proxy is currently serving — what `bir doctor` reports. */
     pollingServers() {
-        const now = Date.now();
-        return [...this.lastSeen.entries()]
-            .filter(([, at]) => now - at <= PRESENT_MS)
-            .map(([name]) => name);
+        const names = new Set();
+        for (const info of this.proxies.values()) {
+            if (this.isLive(info))
+                names.add(info.serverName);
+        }
+        return [...names];
     }
     /** True when a proxy for `serverName` is available to take work. */
     hasPoller(serverName) {
         if ((this.waiters.get(serverName)?.length ?? 0) > 0)
             return true;
-        return this.isPresent(serverName);
+        return this.present(serverName).length > 0;
     }
-    /** Parked now, or polled recently enough to be mid-round-trip. */
-    isPresent(serverName) {
-        const at = this.lastSeen.get(serverName);
-        return at !== undefined && Date.now() - at <= PRESENT_MS;
+    /**
+     * Record that `proxyId` serves `sessionId`: it reported a call whose id the
+     * session's own hook minted. Proof, so it replaces any earlier binding — a
+     * `/clear` starts a new session on the same proxies.
+     */
+    bindProxy(proxyId, sessionId) {
+        const info = this.proxies.get(proxyId);
+        if (!info)
+            return;
+        if (info.sessionId === sessionId && info.boundBy === "correlated")
+            return;
+        info.sessionId = sessionId;
+        info.boundBy = "correlated";
+        logDetail("replay.proxy_bound", {
+            server: info.serverName,
+            proxy: shortId(proxyId),
+            pid: info.pid,
+            sess: sessionId,
+            by: "correlated",
+        });
     }
     /**
      * `POST /proxy/poll`. Resolves with work, or with `undefined` at the poll
-     * deadline so the proxy re-polls. Work queued while this proxy was between
-     * polls is handed over immediately.
+     * deadline so the proxy re-polls. Work held for this proxy while it was
+     * between polls is handed over immediately.
      */
-    waitForWork(serverName, pollDeadlineMs, signal) {
+    waitForWork(serverName, pollDeadlineMs, signal, who = {}) {
         if (this.closed)
             return Promise.resolve(undefined);
-        this.lastSeen.set(serverName, Date.now());
-        const queued = this.pending.get(serverName);
+        const proxyId = who.proxyId || legacyId(serverName);
+        this.touch(proxyId, serverName, who);
+        const queued = this.pending.get(proxyId);
         if (queued && queued.length > 0) {
             return Promise.resolve(queued.shift());
         }
@@ -79,6 +135,7 @@ export class ProxyWorkQueue {
             const list = this.waiters.get(serverName) ?? [];
             const waiter = {
                 serverName,
+                proxyId,
                 resolve,
                 signal,
                 timer: setTimeout(() => {
@@ -90,6 +147,7 @@ export class ProxyWorkQueue {
                 waiter.onAbort = () => {
                     logDetail("replay.poller_gone", { server: serverName, why: "its request closed" });
                     this.removeWaiter(waiter);
+                    this.forgetIfGone(proxyId);
                     resolve(undefined);
                 };
                 signal.addEventListener("abort", waiter.onAbort, { once: true });
@@ -120,18 +178,36 @@ export class ProxyWorkQueue {
      * "could not be run here", which is exactly the condition under which the
      * caller may substitute a recorded output.
      */
-    call(serverName, toolName, args, timeoutMs) {
+    call(serverName, toolName, args, timeoutMs, route = {}) {
         if (this.closed)
             return Promise.reject(new Error(NO_PROXY));
-        const work = { workId: "birwork_" + randomUUID(), toolName, arguments: args, timeoutMs };
-        const waiter = this.takeWaiter(serverName);
-        if (!waiter && !this.isPresent(serverName)) {
+        const picked = this.pickProxy(serverName, route.sessionId);
+        if (!picked) {
             // No proxy has ever polled for this server, or one has been gone for a
             // minute. Do NOT queue: the caller is inside a turn the user is waiting on,
             // and work that sits until some proxy happens to appear would stall it past
             // every budget. Fail fast, and let the recorded-output fallback decide.
             return Promise.reject(new Error(NO_PROXY));
         }
+        if (picked === "other_sessions") {
+            const others = this.present(serverName).length;
+            logDetail("replay.no_session_proxy", {
+                server: serverName,
+                tool: toolName,
+                sess: route.sessionId,
+                others,
+                why: "only other sessions' proxies are here — the step is not run on their upstream",
+            });
+            return Promise.resolve(noSessionProxy(serverName, others));
+        }
+        const { info, why } = picked;
+        if (route.sessionId && !info.sessionId && !isLegacy(info.proxyId)) {
+            // Keep the rest of this session's plan on the same upstream.
+            info.sessionId = route.sessionId;
+            info.boundBy = "dispatched";
+        }
+        const work = { workId: "birwork_" + randomUUID(), toolName, arguments: args, timeoutMs };
+        const waiter = this.takeWaiter(serverName, info.proxyId);
         return new Promise((resolve, reject) => {
             const entry = {
                 serverName,
@@ -139,7 +215,7 @@ export class ProxyWorkQueue {
                 reject,
                 timer: setTimeout(() => {
                     this.inFlight.delete(work.workId);
-                    this.dropPending(serverName, work.workId);
+                    this.dropPending(info.proxyId, work.workId);
                     reject(new Error(`timeout after ${timeoutMs}ms`));
                 }, timeoutMs),
             };
@@ -149,23 +225,27 @@ export class ProxyWorkQueue {
                 server: serverName,
                 tool: toolName,
                 work: work.workId,
+                proxy: shortId(info.proxyId),
+                pid: info.pid,
+                pick: why,
                 queued: waiter ? undefined : true,
             });
             if (waiter) {
                 waiter.resolve(work);
                 return;
             }
-            // The proxy is mid-round-trip — POSTing the previous step's result, about
-            // to poll again. Hold the work for it; the per-call timeout above is what
-            // bounds the wait if it never comes back.
-            const list = this.pending.get(serverName) ?? [];
+            // The chosen proxy is mid-round-trip — POSTing the previous step's result,
+            // about to poll again. Hold the work for IT; another proxy that happens to
+            // be parked right now is not a substitute. The per-call timeout above is
+            // what bounds the wait if it never comes back.
+            const list = this.pending.get(info.proxyId) ?? [];
             list.push(work);
-            this.pending.set(serverName, list);
+            this.pending.set(info.proxyId, list);
         });
     }
     /** Remove queued work that timed out, so a later poll never gets stale work. */
-    dropPending(serverName, workId) {
-        const list = this.pending.get(serverName);
+    dropPending(proxyId, workId) {
+        const list = this.pending.get(proxyId);
         if (!list)
             return;
         const i = list.findIndex((w) => w.workId === workId);
@@ -184,33 +264,121 @@ export class ProxyWorkQueue {
         this.waiters.clear();
         this.pending.clear();
         // A closed queue has no proxies, whatever they were doing a moment ago.
-        this.lastSeen.clear();
+        this.proxies.clear();
         for (const [, entry] of this.inFlight) {
             clearTimeout(entry.timer);
             entry.reject(new Error("control server closed"));
         }
         this.inFlight.clear();
     }
+    /** Note a poll: create the proxy's record on first sight, refresh it after. */
+    touch(proxyId, serverName, who) {
+        const now = Date.now();
+        const info = this.proxies.get(proxyId);
+        if (info) {
+            info.lastSeen = now;
+            return;
+        }
+        const started = Number(who.startedAt);
+        this.proxies.set(proxyId, {
+            proxyId,
+            serverName,
+            startedAt: Number.isFinite(started) && started > 0 ? started : now,
+            pid: who.pid,
+            lastSeen: now,
+        });
+    }
+    /** Parked now, or polled recently enough to be mid-round-trip. */
+    isLive(info) {
+        return Date.now() - info.lastSeen <= PRESENT_MS;
+    }
+    /** Live proxies for a server, newest first. */
+    present(serverName) {
+        return [...this.proxies.values()]
+            .filter((p) => p.serverName === serverName && this.isLive(p))
+            .sort((a, b) => b.startedAt - a.startedAt);
+    }
+    /**
+     * The proxy a step for `sessionId` should run on — see the file comment.
+     * Undefined when no proxy is live at all; `other_sessions` when every live
+     * one belongs to a different session.
+     */
+    pickProxy(serverName, sessionId) {
+        const live = this.present(serverName);
+        if (live.length === 0)
+            return undefined;
+        if (!sessionId)
+            return { info: live[0], why: "newest" };
+        const mine = live.filter((p) => p.sessionId === sessionId);
+        const proven = mine.find((p) => p.boundBy === "correlated");
+        if (proven)
+            return { info: proven, why: "session" };
+        if (mine[0])
+            return { info: mine[0], why: "session" };
+        const unbound = live.find((p) => !p.sessionId);
+        if (unbound)
+            return { info: unbound, why: "newest" };
+        return "other_sessions";
+    }
     /**
-     * The oldest *live* poller. Waiters whose request has already gone are
-     * discarded rather than handed work they can never run.
+     * Free every proxy bound to `sessionId`: the session ended. After a `/clear`
+     * the same proxies serve the next session, which must be able to pick them.
      */
-    takeWaiter(serverName) {
+    releaseSession(sessionId) {
+        for (const info of this.proxies.values()) {
+            if (info.sessionId !== sessionId)
+                continue;
+            info.sessionId = undefined;
+            info.boundBy = undefined;
+            logDetail("replay.proxy_released", {
+                server: info.serverName,
+                proxy: shortId(info.proxyId),
+                pid: info.pid,
+                sess: sessionId,
+            });
+        }
+    }
+    /**
+     * A live parked poller of `proxyId`. Waiters whose request has already gone
+     * are discarded rather than handed work they can never run.
+     */
+    takeWaiter(serverName, proxyId) {
         const list = this.waiters.get(serverName);
         if (!list)
             return undefined;
-        for (;;) {
-            const waiter = list.shift();
-            if (!waiter)
-                return undefined;
-            this.detach(waiter);
+        for (let i = 0; i < list.length;) {
+            const waiter = list[i];
             if (waiter.signal?.aborted) {
                 // Its proxy is gone. Release the promise and keep looking.
+                list.splice(i, 1);
+                this.detach(waiter);
                 waiter.resolve(undefined);
                 continue;
             }
-            return waiter;
+            if (waiter.proxyId === proxyId) {
+                list.splice(i, 1);
+                this.detach(waiter);
+                return waiter;
+            }
+            i++;
         }
+        return undefined;
+    }
+    /**
+     * A proxy whose poll request closed has, almost always, exited. Forget it
+     * unless another of its polls is still parked, so it is never picked for a
+     * minute after it died. A proxy that merely lost one request re-registers on
+     * its next poll.
+     */
+    forgetIfGone(proxyId) {
+        for (const list of this.waiters.values()) {
+            if (list.some((w) => w.proxyId === proxyId && !w.signal?.aborted))
+                return;
+        }
+        if ((this.pending.get(proxyId)?.length ?? 0) > 0)
+            return;
+        this.proxies.delete(proxyId);
+        this.pending.delete(proxyId);
     }
     removeWaiter(waiter) {
         this.detach(waiter);
@@ -230,4 +398,29 @@ export class ProxyWorkQueue {
         }
     }
 }
+function isLegacy(proxyId) {
+    return proxyId.startsWith("legacy:");
+}
+/** Enough of an id to tell proxies apart in a log line. */
+function shortId(proxyId) {
+    return isLegacy(proxyId) ? proxyId : proxyId.slice(-8);
+}
+/**
+ * The step's result when only other sessions' proxies are here: an MCP tool
+ * error, so the plan stops on it and hands over (tool-error.ts), and the agent
+ * reads why.
+ */
+function noSessionProxy(serverName, others) {
+    return {
+        isError: true,
+        content: [
+            {
+                type: "text",
+                text: `Error: bir did not run this step. No ${serverName} proxy of this session is ` +
+                    `connected; the ${others} that are belong to other sessions, and a step never ` +
+                    `runs on another session's upstream. Call the tool yourself.`,
+            },
+        ],
+    };
+}
 //# sourceMappingURL=executor.js.map

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

@@ -3,16 +3,17 @@
  *
  * A step's tool call resolving is not the same as the step's work happening.
  * `executeStep` rejects only when a tool could not be run here; a tool that ran
- * and answered `Error: relation does not exist` resolves normally, with that
- * error as its response — which is right for threading (the output logic may
- * want to see it) and wrong for the verdict. Eight such steps once logged
- * `ok=true` each, the plan reported `steered_full`, and the ledger booked its
- * largest saving of the day on a replay that created nothing (docs/mcpmark.md §13).
+ * and reported a failure resolves normally, with that failure as its response —
+ * which is right for threading (the output logic may want to see it) and wrong
+ * for the verdict (docs/mcpmark.md §13).
  *
- * The signal is the MCP result itself: `isError: true` per the spec, or — for
- * servers that report failures as ordinary text, `postgres-mcp` among them — a
- * first text block that begins with the word "Error". Nothing else is read, and
- * a built-in's hook-shaped response is never judged.
+ * The signal is `isError: true` on the MCP result, per the spec, and nothing
+ * else — the same rule the recorder uses (`proxy/intercept.ts`), so a step is a
+ * success or an error in the recording and in its replay alike. A server that
+ * 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.
  */
 /**
  * The error a serialized `CallToolResult` reports, or undefined when it does

package/dist/replay/tool-error.js

@@ -3,16 +3,17 @@
  *
  * A step's tool call resolving is not the same as the step's work happening.
  * `executeStep` rejects only when a tool could not be run here; a tool that ran
- * and answered `Error: relation does not exist` resolves normally, with that
- * error as its response — which is right for threading (the output logic may
- * want to see it) and wrong for the verdict. Eight such steps once logged
- * `ok=true` each, the plan reported `steered_full`, and the ledger booked its
- * largest saving of the day on a replay that created nothing (docs/mcpmark.md §13).
+ * and reported a failure resolves normally, with that failure as its response —
+ * which is right for threading (the output logic may want to see it) and wrong
+ * for the verdict (docs/mcpmark.md §13).
  *
- * The signal is the MCP result itself: `isError: true` per the spec, or — for
- * servers that report failures as ordinary text, `postgres-mcp` among them — a
- * first text block that begins with the word "Error". Nothing else is read, and
- * a built-in's hook-shaped response is never judged.
+ * The signal is `isError: true` on the MCP result, per the spec, and nothing
+ * else — the same rule the recorder uses (`proxy/intercept.ts`), so a step is a
+ * success or an error in the recording and in its replay alike. A server that
+ * 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.
  */
 const MAX_ERROR_CHARS = 500;
 /**
@@ -27,17 +28,12 @@ export function toolResultError(serialized) {
     catch {
         return undefined;
     }
-    if (typeof parsed === "string")
-        return looksLikeError(parsed) ? clip(parsed) : undefined;
     if (!parsed || typeof parsed !== "object")
         return undefined;
     const result = parsed;
-    const text = firstText(result.content);
-    if (result.isError === true)
-        return clip(text ?? "the tool reported an error");
-    if (text !== undefined && looksLikeError(text))
-        return clip(text);
-    return undefined;
+    if (result.isError !== true)
+        return undefined;
+    return clip(firstText(result.content) ?? "the tool reported an error");
 }
 function firstText(content) {
     if (!Array.isArray(content))
@@ -49,10 +45,6 @@ function firstText(content) {
     }
     return undefined;
 }
-/** "Error: …" / "ERROR: …" / "error occurred" — not "Errors were fixed". */
-function looksLikeError(text) {
-    return /^\s*error\b/i.test(text);
-}
 function clip(text) {
     const trimmed = text.trim();
     return trimmed.length > MAX_ERROR_CHARS ? `${trimmed.slice(0, MAX_ERROR_CHARS)}…` : trimmed;