@basein/runner 0.3.25 → 0.3.27

package/dist/jsonrpc/framing.js

@@ -35,6 +35,56 @@ export const DEFAULT_MAX_LINE_BYTES = 128 * 1024 * 1024;
 export const OVERSIZE_SAMPLE_BYTES = 256;
 const NEWLINE = 0x0a;
 const EMPTY = Buffer.alloc(0);
+/**
+ * The text each received message was parsed from, by the message object itself.
+ *
+ * WHY IT IS KEPT. A relay that parses a line and serialises the result again
+ * does not forward the message, it forwards JavaScript's reading of it:
+ * `{"big":9007199254740993,"snowflake":1234567890123456789,"f":1.0}` went out
+ * as `{"big":9007199254740992,"snowflake":1234567890123456800,"f":1}`. A
+ * JavaScript sender had lost those digits already; a Python or Rust one had
+ * not, and neither had the server it was talking to. So a message that is
+ * written as it was read goes out as the text that came in ({@link writeFrame}),
+ * which also saves serialising every message a second time.
+ *
+ * WHY BY IDENTITY. The text belongs to one object: the one the reader made.
+ * Whoever wants a different message on the wire builds a different object (the
+ * interceptor does, for the two messages it rewrites), and a different object
+ * has no entry here, so it is serialised as it always was. Nothing between a
+ * reader and a writer changes a message in place, and nothing may: the change
+ * would not be sent. Code that may — an embedder's interceptor — gets the
+ * message after {@link forgetText} (proxy/relay.ts), and so does whoever calls
+ * readFrames and writeFrame directly and changes what it read: call it first.
+ *
+ * Weak, so an entry lives exactly as long as its message does.
+ */
+const received = new WeakMap();
+/** Note that `msg` was parsed from `text`, so it can be written again as that text. */
+export function rememberText(msg, text) {
+    received.set(msg, text);
+}
+/** Forget the text `msg` was parsed from: it is serialised again when written, with any change made to it. */
+export function forgetText(msg) {
+    if (msg && typeof msg === "object")
+        received.delete(msg);
+}
+/**
+ * The text `msg` was parsed from, when it can be sent again as one line;
+ * undefined for a message nobody read off the wire, and for one whose text
+ * holds a raw line break (a pretty-printed HTTP body: inside a JSON string a
+ * line break is always escaped, so a raw one is layout, and layout cannot
+ * cross a line-delimited stream). One trailing CR is a CRLF sender's line
+ * ending, not part of the message.
+ */
+export function receivedText(msg) {
+    if (!msg || typeof msg !== "object")
+        return undefined;
+    const text = received.get(msg);
+    if (text === undefined)
+        return undefined;
+    const line = text.endsWith("\r") ? text.slice(0, -1) : text;
+    return line.includes("\n") || line.includes("\r") ? undefined : line;
+}
 /** The last `n` bytes of `a` followed by `b`, as a fresh buffer. */
 function lastBytes(a, b, n) {
     if (b.length >= n)
@@ -143,6 +193,7 @@ export function readFrames(input, handlers, opts = {}) {
             });
             return;
         }
+        rememberText(msg, text);
         handlers.onMessage(msg);
     };
     const onData = (chunk) => {
@@ -207,14 +258,16 @@ export function readFrames(input, handlers, opts = {}) {
     };
 }
 /**
- * Write one message as a single line. Serialization failure is swallowed after
- * being reported: a proxy that throws while answering the host takes the host's
- * session down with it, which rule 4 of §1 forbids.
+ * Write one message as a single line: the line it was read from when `msg` is
+ * the very object a reader produced ({@link receivedText}), its serialisation
+ * otherwise. Serialization failure is swallowed after being reported: a proxy
+ * that throws while answering the host takes the host's session down with it,
+ * which rule 4 of §1 forbids.
  */
 export function writeFrame(output, msg, onError) {
     let line;
     try {
-        line = JSON.stringify(msg);
+        line = receivedText(msg) ?? JSON.stringify(msg);
     }
     catch (err) {
         onError?.(err instanceof Error ? err : new Error(String(err)));

package/dist/proxy/intercept.d.ts

@@ -56,6 +56,8 @@ export declare function tolerateCallId(schema: unknown): unknown;
 /** Apply {@link tolerateCallId} to every tool of a `tools/list` result. */
 export declare function tolerateCallIdInToolsList(result: unknown): unknown;
 export declare class RecordingInterceptor implements Interceptor {
+    /** It builds a new message for each one it changes (relay.ts). */
+    readonly keepsMessagesWhole = true;
     private readonly serverName;
     private readonly session;
     /** Host request id → the call it opened. Only `tools/call` ids appear here. */
@@ -92,6 +94,8 @@ export declare class RecordingInterceptor implements Interceptor {
  * tool error the runner caused. No tracking, no reporting, no schema change.
  */
 export declare class StripCallIdInterceptor implements Interceptor {
+    /** It builds a new message for each one it changes (relay.ts). */
+    readonly keepsMessagesWhole = true;
     onHostMessage(msg: JsonRpcMessage): ReturnType<NonNullable<Interceptor["onHostMessage"]>>;
 }
 /** Re-exported so callers wiring a proxy need one import for the correlation key. */

package/dist/proxy/intercept.js

@@ -99,6 +99,8 @@ function capForReport(value) {
     }
 }
 export class RecordingInterceptor {
+    /** It builds a new message for each one it changes (relay.ts). */
+    keepsMessagesWhole = true;
     serverName;
     session;
     /** Host request id → the call it opened. Only `tools/call` ids appear here. */
@@ -268,6 +270,8 @@ export class RecordingInterceptor {
  * tool error the runner caused. No tracking, no reporting, no schema change.
  */
 export class StripCallIdInterceptor {
+    /** It builds a new message for each one it changes (relay.ts). */
+    keepsMessagesWhole = true;
     onHostMessage(msg) {
         if (msg.method !== "tools/call")
             return { action: "forward" };

package/dist/proxy/relay.d.ts

@@ -48,8 +48,21 @@ export type HostDecision =
  * The intercept table's interface. Every method is optional and **synchronous**:
  * recording must never sit between the upstream's answer and the host (§3,
  * Phase 3), so an interceptor queues work rather than awaiting it.
+ *
+ * AN INTERCEPTOR NEVER CHANGES THE MESSAGE IT IS HANDED. To put something else
+ * on the wire it returns another object. A message that comes back as the same
+ * object is forwarded as the text it arrived in (jsonrpc/framing.ts), not
+ * serialised again — that is what keeps an integer past 2^53 whole across the
+ * proxy — so a change made in place would never be sent.
+ *
+ * Only for an interceptor that says so ({@link Interceptor.keepsMessagesWhole}):
+ * the runner's own do. One that does not — an embedder's, written when a
+ * forwarded message was always serialised again — gets each message as it
+ * always did, and a change it makes in place is sent.
  */
 export interface Interceptor {
+    /** It never changes a message it is handed: what it forwards may go out as the text that came in. */
+    readonly keepsMessagesWhole?: boolean;
     /** Called for every host→upstream message. Default: forward unchanged. */
     onHostMessage?(msg: JsonRpcMessage): HostDecision | void;
     /**

package/dist/proxy/relay.js

@@ -22,9 +22,17 @@
  * request the proxy originates itself lives in the disjoint `bir:` id space
  * (see `upstream/client.ts`), so a collision cannot happen.
  */
-import { readFrames, writeFrame } from "../jsonrpc/framing.js";
+import { forgetText, readFrames, writeFrame } from "../jsonrpc/framing.js";
 import { JsonRpcErrorCode, errorResponse, isRequest, isResponse, paramsObject, } from "../jsonrpc/types.js";
 import { logDetail, logLine, errText } from "../util/log.js";
+/**
+ * Before `interceptor` sees `msg`: one that may change it in place gets it to
+ * be serialised again when written, so the change is what goes out.
+ */
+function handTo(interceptor, msg) {
+    if (interceptor && !interceptor.keepsMessagesWhole)
+        forgetText(msg);
+}
 export class Relay {
     pending = new Map();
     opts;
@@ -46,6 +54,7 @@ export class Relay {
                 this.pending.delete(id);
                 let out = msg;
                 try {
+                    handTo(interceptor, msg);
                     const replaced = interceptor?.onUpstreamResponse?.(p, msg);
                     if (replaced)
                         out = replaced;
@@ -58,6 +67,7 @@ export class Relay {
                 return;
             }
             try {
+                handTo(interceptor, msg);
                 interceptor?.onUpstreamMessage?.(msg);
             }
             catch (err) {
@@ -94,6 +104,7 @@ export class Relay {
         const { upstream, hostOut, interceptor, label } = this.opts;
         let decision = { action: "forward" };
         try {
+            handTo(interceptor, msg);
             decision = interceptor?.onHostMessage?.(msg) ?? { action: "forward" };
         }
         catch (err) {

package/dist/proxy/session.d.ts

@@ -261,7 +261,13 @@ export declare class ProxySession {
     private reregister;
     /** Sleep `ms`, or less if {@link wakeLoop} is called first. True when woken early. */
     private pause;
-    /** No control server: record on our own if this project opted in, else stay out of the way. */
+    /**
+     * No control server: record on our own if this project opted in, else stay out of the way.
+     *
+     * `atClose`: for {@link close}, with steps still held. No jitter, and no
+     * stopping because the proxy is closing: both are for a proxy with a session
+     * ahead of it, and at close they are what left the held steps without an owner.
+     */
     private settleUnbound;
     /** While not bound, look for a control server again now and then. */
     private scheduleRebind;
@@ -352,5 +358,6 @@ export declare class ProxySession {
      * long as the process lives.
      */
     close(): Promise<void>;
+    private closeWithinBudget;
 }
 //# sourceMappingURL=session.d.ts.map

package/dist/proxy/session.js

@@ -546,17 +546,31 @@ export class ProxySession {
             this.wakeLoop = wake;
         });
     }
-    /** No control server: record on our own if this project opted in, else stay out of the way. */
-    async settleUnbound(why) {
+    /**
+     * No control server: record on our own if this project opted in, else stay out of the way.
+     *
+     * `atClose`: for {@link close}, with steps still held. No jitter, and no
+     * stopping because the proxy is closing: both are for a proxy with a session
+     * ahead of it, and at close they are what left the held steps without an owner.
+     */
+    async settleUnbound(why, atClose = false) {
         if (!(await this.optedIn())) {
             this.becomePassthrough("this directory is not set up for recording, and no recorder is running for it");
             return;
         }
-        // Only the real recorder authenticates; an injected one (tests) has nothing to spread.
-        if (!this.opts.recorderFactory)
-            await sleep(Math.floor(Math.random() * STANDALONE_JITTER_MS));
-        if (this.closing)
-            return;
+        if (!atClose) {
+            // Only the real recorder authenticates; an injected one (tests) has
+            // nothing to spread. Waited in short turns, so a proxy that closes
+            // meanwhile hands over at once: close() has its whole budget for the
+            // steps it holds, not what a 2 s wait left of it.
+            if (!this.opts.recorderFactory) {
+                const until = Date.now() + Math.floor(Math.random() * STANDALONE_JITTER_MS);
+                while (!this.closing && Date.now() < until)
+                    await sleep(Math.min(100, until - Date.now()));
+            }
+            if (this.closing)
+                return;
+        }
         await this.becomeStandalone(why);
     }
     /** While not bound, look for a control server again now and then. */
@@ -782,7 +796,10 @@ export class ProxySession {
         // instead read as "issued by another service" (auth.url_mismatch), and
         // the proxy recorded nothing for its whole life.
         const baseUrl = await normalizedServiceUrl(configured);
-        if (this.closing)
+        // Closing with nothing held: not worth a sign-in round trip, nor an empty
+        // run on the service. With steps held it is: close() is waiting, inside
+        // its budget, for exactly this recorder.
+        if (this.closing && this.buffer.length === 0)
             return new NullRecorder();
         // A proxy runs inside the host's process tree with its stdio bound to the
         // JSON-RPC stream: there is nowhere to prompt, and blocking on one would
@@ -984,6 +1001,21 @@ export class ProxySession {
      * long as the process lives.
      */
     async close() {
+        // Every wait in here is on a timer that does not hold the process up, and
+        // at shutdown nothing else may: the host has closed stdin, and a stdio
+        // server exits within milliseconds of that. bir-proxy then ended on its
+        // own, exit 0, some 20 ms into this function — before a held step had an
+        // owner, and before `finishRun`. One timer that does hold it, for no
+        // longer than the budget (and the final flush's minimum past it).
+        const hold = setTimeout(() => undefined, CLOSE_BUDGET_MS + MIN_FINAL_FLUSH_MS);
+        try {
+            await this.closeWithinBudget();
+        }
+        finally {
+            clearTimeout(hold);
+        }
+    }
+    async closeWithinBudget() {
         const deadline = Date.now() + CLOSE_BUDGET_MS;
         const left = () => Math.max(0, deadline - Date.now());
         // Stops the work loop at its next turn. It is not awaited: it may be parked
@@ -1004,8 +1036,33 @@ export class ProxySession {
         await new Promise((resolve) => setImmediate(resolve));
         // Negotiation stops at its next turn once `closing` is set, but a turn can
         // be a sign-in refresh against a slow service: bounded, not awaited whole.
-        if (this.negotiation)
-            await settledWithin(this.negotiation, left());
+        let negotiated = !this.negotiation;
+        if (this.negotiation) {
+            await settledWithin(this.negotiation.then(() => {
+                negotiated = true;
+            }), left());
+        }
+        if (this.tierValue === "pending" && this.buffer.length > 0) {
+            // Stopped before it had settled a tier, and the steps taken meanwhile
+            // are still held: a host with no control server whose session was
+            // shorter than the discovery window (a scripted agent run of a few
+            // seconds). Flushed as they were, they found no recorder, were held
+            // again, and went with the process — a whole run, and not a line about
+            // it. So they get their owner now, inside what is left of the budget.
+            // Not while negotiation is still out (it overran the budget): two
+            // recorders would be built, and there is no time left for one.
+            if (negotiated) {
+                await settledWithin(this.settleUnbound("the proxy closed before a control server answered", true), left());
+            }
+            if (this.tierValue === "pending") {
+                this.lossyValue = true;
+                logLine("run.lossy", {
+                    why: "closed before a recorder was ready",
+                    server: this.serverName,
+                    dropped: this.buffer.length,
+                });
+            }
+        }
         this.flushBuffer();
         // Steps waiting behind a slow service: each is handed to the recorder at
         // once now (dispatch skips its per-step wait while closing), so this is

package/dist/record/recorder.d.ts

@@ -13,12 +13,16 @@ export interface StartRunOptions {
      * `handoverId`: the hand-over's id, which its continuation request carried
      * too, so the service counts the hand-over once. `counted`: the same for a
      * service from before ids — it counted the hand-over when asked for its
-     * continuation.
+     * continuation. `stop`: where the stopped step stood — `not_run`, `failed`,
+     * `ran`, `uncertain`, … — sent for a `step_failed`, so the service never
+     * continues a hand-over after a step that ran, or may have, with work that
+     * starts with that step (the service's fallbk.md, "never continued").
      */
     fallbackOf?: {
         scenarioId: string;
         stepIndex: number;
         kind?: string;
+        stop?: string;
         handoverId?: string;
         counted?: boolean;
     };
@@ -327,6 +331,7 @@ export interface IntentMatchRequest {
         scenarioId: string;
         stepIndex: number;
         kind?: string;
+        stop?: string;
         id?: string;
     };
 }

package/dist/record/redact.d.ts

@@ -45,13 +45,23 @@
  * `token: newToken`). A separator never spans a line break: an empty
  * `DB_PASSWORD=` must not take the next line with it.
  *
+ * A VALUE IN QUOTES IS READ TO ITS CLOSING QUOTE, spaces, `&`, `;` and all: a
+ * passphrase has words in it. Nor is it code for what it starts with or holds:
+ * a password may start with `$`, `!` or `(` and have a bracket in it
+ * (`"p@ss(w0rd)1"`), and went out as it was while that made a value look like
+ * code. Only a reference — `${VAR}`, `$(cmd)`, `<placeholder>`, `{{ template }}`
+ * — exempts it. Unquoted, an expression still shows by its shape.
+ *
  * JSON TEXT IS REDACTED AS JSON. A serialized tool payload goes through
  * {@link redactJsonText}, which parses it and runs the rules on each string
  * leaf — the same pass its producer's {@link redact} made — so the result is
  * always valid JSON and, when nothing new was found, the producer's bytes
- * exactly (live replay serializes a result the same way and compares). The
- * rules still tolerate JSON-escaped text (a string leaf that holds a JSON
- * document, a preview of one): they never start a match inside an escape
+ * exactly (live replay serializes a result the same way and compares). A
+ * string leaf is text, whatever it holds: a JSON document in one — a file's
+ * content, what an MCP tool returns in `content[].text` — gets the text rules
+ * where it stands, and is never parsed and written back. The text rules read
+ * JSON text, plain and JSON-escaped (a document held in a string, a preview of
+ * one cut off before it parses): they never start a match inside an escape
  * sequence and never replace a quote or a backslash, so an escaped document
  * stays parseable.
  *
@@ -117,7 +127,11 @@ export declare function redactText(text: string): string;
  * producers redact first — the original bytes come back untouched: live replay
  * serializes a result the same way and compares against what was recorded.
  * Text that is not JSON (a truncated preview, a producer's plain error) gets
- * {@link redactText}: there is no structure to keep.
+ * {@link redactText}: there is no structure to keep. Unless the rules gave it
+ * one: a private key written over several lines can be all that kept a
+ * document from parsing, and with the key gone it is redacted as the JSON it
+ * now is — or the next pass over it (the recorder's, after its producer's)
+ * would be the one to do that, and move its bytes.
  */
 export declare function redactJsonText(text: string): string;
 /**