@basein/runner 0.3.25 → 0.3.27

package/dist/replay/bundle.d.ts

@@ -104,13 +104,16 @@ export declare function assembleBundle(entries: readonly BundleEntry[], maxChars
  */
 export declare function wentWell(entries: readonly BundleEntry[], opts: Pick<AssembleOptions, "handover" | "subTask">): boolean;
 /**
- * JSON text with every string longer than 40 characters cut to its first 40
- * and "…". Keys, numbers and short strings stay as they are, and an escape is
- * never split. Works on JSON a parser would refuse — a tool's `NaN`, a result
- * cut short — because it walks the text's string literals from the start, so
- * it always knows which quote opens one: the text between two strings, a
- * list of numbers say, is never taken for one. An unterminated string is left
- * as it is.
+ * JSON text with every string of prose longer than 40 characters cut to its
+ * first 40 and "…". Keys, numbers, short strings and strings with no space in
+ * them ({@link BRIEF_ID_CHARS}: a link, a path, an id) stay as they are. A
+ * character is never split: an escape counts as one, `\n` and a Unicode
+ * escape (a backslash, a `u` and four hex digits) alike, and so does a pair of
+ * surrogates, written out (an emoji) or as two such escapes.
+ * Works on JSON a parser would refuse — a tool's `NaN`, a result cut short —
+ * because it walks the text's string literals from the start, so it always
+ * knows which quote opens one: the text between two strings, a list of numbers
+ * say, is never taken for one. An unterminated string is left as it is.
  */
 export declare function cutLongText(json: string): string;
 /**
@@ -120,10 +123,11 @@ export declare function cutLongText(json: string): string;
 export declare function briefFields(fields: Record<string, unknown>, max: number): string;
 /**
  * A value of the plan's summary in a few words. Numbers, booleans and short
- * strings whole; a long string cut; a list or object whose JSON is short —
- * a few IDs, names or addresses — whole; a longer list counted; a longer
- * object by its first fields, one level down, below which it is counted too.
- * A summary's long lists are mostly the records the steps above already show.
+ * strings whole; long text cut, as a result's is ({@link cutLongText}: a link
+ * or an id is whole); a list or object whose JSON is short — a few IDs, names
+ * or addresses — whole; a longer list counted; a longer object by its first
+ * fields, one level down, below which it is counted too. A summary's long
+ * lists are mostly the records the steps above already show.
  */
 export declare function briefValue(value: unknown, depth?: number): string;
 /**

package/dist/replay/bundle.js

@@ -44,6 +44,14 @@ export const BASH_CHANNEL_MAX = 25_000;
 const MAX_INPUT_CHARS = 2_000;
 /** Fixed structural overhead reserved per step (labels, separators). */
 const PER_STEP_OVERHEAD = 80;
+/**
+ * The least each result is shown of. When the inputs leave the results less
+ * than this each, the results keep it and the inputs give up the difference:
+ * the results are what the agent answers from, and fourteen inputs at their cap
+ * once left them nothing at all, every "Result:" empty under a header that
+ * calls it the call's actual output.
+ */
+const MIN_RESULT_CHARS = 200;
 /** The test's words, one line and short, for a bundle or a note. */
 export function testWords(text) {
     const line = (text ?? "").trim().split(/\r?\n/, 1)[0]?.trim() ?? "";
@@ -134,7 +142,8 @@ const BRIEF_HEADER = "[BaseInstRunner calculated replay] The tool calls below ha
     "for real, moments ago, against the live system, on the user's behalf. Every one " +
     "of them succeeded, and every side effect is already in place. Do NOT repeat, redo " +
     "or re-verify this work, and do NOT call any tools. In a long result, every record " +
-    "and field is shown, and text longer than 40 characters is cut short with \"…\".";
+    "and field is shown, and text longer than 40 characters is cut short with \"…\"; " +
+    "a link, a path or an id (no spaces, up to 300 characters) is shown whole.";
 /** The reply is output, the dearest tokens an agent spends: asked for briefly. */
 const BRIEF_FOOTER = "\n\nThe work above is done. Answer the user's request from it in a few sentences: " +
     "what was done, and the key results. Do not call any tools.";
@@ -144,6 +153,13 @@ const BRIEF_RESULT_CHARS = 300;
 const BRIEF_SUMMARY_CHARS = 1_000;
 /** A longer string — in a long result, or in the summary — is cut to this many characters. */
 const BRIEF_STRING_CHARS = 40;
+/**
+ * But a string with no space in it — a link, a path, an id, a hash, an e-mail
+ * address — is what the agent passes on to the user, and cut it opens nothing
+ * and names nothing: it is kept whole up to this many characters. Past them it
+ * is a blob (an encoded image, a minified line), and is cut like text.
+ */
+const BRIEF_ID_CHARS = 300;
 /** A list or object in the summary whose JSON is up to this long is shown whole; a longer one is counted. */
 const BRIEF_INLINE_CHARS = 160;
 /** A longer object in the summary shows its first fields, this many. */
@@ -171,26 +187,40 @@ export function assembleBundle(entries, maxChars, opts = {}) {
             ? SUBTASK_FOOTER
             : withReportException(brief ? BRIEF_FOOTER : anyRecorded ? MIXED_FOOTER : LIVE_FOOTER, opts.reportTool);
     const summary = brief ? briefSummary(opts.brief?.summary) : "";
-    const fixedCost = header.length +
-        footer.length +
-        summary.length +
-        entries.reduce((sum, e) => sum +
-            PER_STEP_OVERHEAD +
-            e.toolName.length +
-            e.input.length +
-            // A left-out step's line, which has no response to take from.
-            (e.notNeeded ? PER_STEP_OVERHEAD + (testWords(e.notNeeded.text)?.length ?? 0) : 0), 0);
-    const responseBudget = Math.max(0, maxChars - fixedCost);
-    const perResponse = n > 0 ? Math.floor(responseBudget / n) : responseBudget;
+    const labels = entries.reduce((sum, e) => sum +
+        PER_STEP_OVERHEAD +
+        e.toolName.length +
+        // A left-out step's line, which has no response to take from.
+        (e.notNeeded ? PER_STEP_OVERHEAD + (testWords(e.notNeeded.text)?.length ?? 0) : 0), 0);
+    const inputs = entries.reduce((sum, e) => sum + e.input.length, 0);
+    // What the frame and the labels leave is shared by the inputs and the
+    // results. The inputs go in whole and the results split what they leave —
+    // unless that is less than a floor each (or nothing at all, when the inputs
+    // alone pass the limit): then each result keeps the floor, and the inputs,
+    // cut to a share of the rest, say how much of themselves is left out.
+    const free = Math.max(0, maxChars - (header.length + footer.length + summary.length + labels));
+    let perResponse = n > 0 ? Math.floor(Math.max(0, free - inputs) / n) : Math.max(0, free - inputs);
+    let inputCap = Number.POSITIVE_INFINITY;
+    const floor = Math.min(MIN_RESULT_CHARS, Math.floor(free / (2 * Math.max(1, n))));
+    if (n > 0 && perResponse < floor) {
+        perResponse = floor;
+        inputCap = Math.floor((free - n * floor) / entries.length);
+    }
+    const shownEntries = Number.isFinite(inputCap)
+        ? entries.map((e) => ({ ...e, input: truncate(e.input, inputCap) }))
+        : entries;
     const show = (e) => {
         const result = resultText(e.response);
+        // A built-in's result is shown as its own text, whole within its share.
+        const own = brief ? builtinText(e.toolName, e.response) : undefined;
+        const text = own ?? result.text;
         return {
-            text: brief ? briefResult(result.text, perResponse) : truncate(result.text, perResponse),
+            text: brief && own === undefined ? briefResult(text, perResponse) : truncate(text, perResponse),
             marks: resultMarks(e.recorded, result.error),
         };
     };
     const sections = [];
-    for (const run of consecutiveRuns(entries)) {
+    for (const run of consecutiveRuns(shownEntries)) {
         if (run.length === 1) {
             const { entry: e, index: i } = run[0];
             if (e.notNeeded) {
@@ -209,7 +239,14 @@ export function assembleBundle(entries, maxChars, opts = {}) {
         }
         sections.push(runSection(run, show));
     }
-    return truncate(header + sections.join("") + summary + footer, maxChars);
+    // The labels are an estimate, and a bundle that still passes the limit loses
+    // its middle, never its footer: the last thing the agent is told. Where even
+    // that does not fit the limit, the end goes, as it always did.
+    const whole = header + sections.join("") + summary + footer;
+    if (whole.length <= maxChars)
+        return whole;
+    const keepFooter = truncate(header + sections.join("") + summary, Math.max(0, maxChars - footer.length)) + footer;
+    return keepFooter.length <= maxChars ? keepFooter : truncate(whole, maxChars);
 }
 /**
  * Whether a run went entirely well and the agent answers now — the one case a
@@ -239,14 +276,67 @@ function briefResult(text, budget) {
         return truncate(cutLongText(text), budget);
     return truncate(text, budget);
 }
+/** The runner's built-ins whose results {@link builtinText} lays out as text. */
+const BUILTIN_RESULT_TOOLS = new Set(["Bash", "Read", "Glob", "Grep"]);
+/**
+ * A built-in tool's result as the text it is, or undefined when it is not one
+ * the brief layout can show so: what a command printed, a file's lines, a
+ * search's lines or file names.
+ *
+ * The runner's own tools answer in the hook's shape — `{stdout, stderr, …}`,
+ * `{type, file: {content, …}}`, `{mode, content | filenames, …}`, `{filenames,
+ * …}` — and not in MCP's `CallToolResult`, so {@link resultText} leaves them as
+ * JSON, and the brief layout took all of it for one long string: a command's
+ * output of 470 characters ending "TOTAL DIFFERENCE 100.00" was cut to its
+ * first 40, a Glob's file names every one, under a header that says to call no
+ * tools. The same words from an MCP tool were shown whole.
+ */
+function builtinText(toolName, response) {
+    if (!BUILTIN_RESULT_TOOLS.has(toolName))
+        return undefined;
+    let parsed;
+    try {
+        parsed = JSON.parse(response);
+    }
+    catch {
+        return undefined;
+    }
+    if (!parsed || typeof parsed !== "object" || Array.isArray(parsed))
+        return undefined;
+    const r = parsed;
+    const lines = (v) => Array.isArray(v) && v.every((x) => typeof x === "string") ? v.join("\n") : undefined;
+    let body;
+    if (toolName === "Bash") {
+        if (typeof r.stdout !== "string" || r.interrupted === true || r.isImage === true)
+            return undefined;
+        const stderr = typeof r.stderr === "string" && r.stderr !== "" ? `stderr: ${r.stderr}` : "";
+        body = stderr && r.stdout !== "" && !r.stdout.endsWith("\n") ? `${r.stdout}\n${stderr}` : r.stdout + stderr;
+    }
+    else if (toolName === "Read") {
+        const file = r.file;
+        body = r.type === "text" && typeof file?.content === "string" ? file.content : undefined;
+    }
+    else {
+        body = typeof r.content === "string" && toolName === "Grep" ? r.content : lines(r.filenames);
+    }
+    if (body === undefined)
+        return undefined;
+    if (body === "")
+        return toolName === "Bash" ? "(no output)" : toolName === "Read" ? "(empty file)" : "(nothing found)";
+    // A list the tool cut where it made it: its text alone would read as the whole answer.
+    return r.truncated === true ? `${body}\n(cut short by the tool: there may be more than is shown)` : body;
+}
 /**
- * JSON text with every string longer than 40 characters cut to its first 40
- * and "…". Keys, numbers and short strings stay as they are, and an escape is
- * never split. Works on JSON a parser would refuse — a tool's `NaN`, a result
- * cut short — because it walks the text's string literals from the start, so
- * it always knows which quote opens one: the text between two strings, a
- * list of numbers say, is never taken for one. An unterminated string is left
- * as it is.
+ * JSON text with every string of prose longer than 40 characters cut to its
+ * first 40 and "…". Keys, numbers, short strings and strings with no space in
+ * them ({@link BRIEF_ID_CHARS}: a link, a path, an id) stay as they are. A
+ * character is never split: an escape counts as one, `\n` and a Unicode
+ * escape (a backslash, a `u` and four hex digits) alike, and so does a pair of
+ * surrogates, written out (an emoji) or as two such escapes.
+ * Works on JSON a parser would refuse — a tool's `NaN`, a result cut short —
+ * because it walks the text's string literals from the start, so it always
+ * knows which quote opens one: the text between two strings, a list of numbers
+ * say, is never taken for one. An unterminated string is left as it is.
  */
 export function cutLongText(json) {
     let out = "";
@@ -256,24 +346,68 @@ export function cutLongText(json) {
         if (open < 0)
             return out + json.slice(at);
         out += json.slice(at, open + 1);
-        // Walk the string a unit at a time — a character, or an escape with what
-        // it escapes — to its closing quote, noting where the 40th unit ends.
+        // Walk the string a character at a time to its closing quote, noting where
+        // the 40th ends and whether the text has a space in it.
         let end = open + 1;
         let units = 0;
         let cutAt = -1;
+        let spaced = false;
         while (end < json.length && json[end] !== '"') {
-            end += json[end] === "\\" ? 2 : 1;
+            const code = json.charCodeAt(end);
+            if (code === 92 || (code >= 0xd800 && code <= 0xdbff)) {
+                // An escape, or the first half of a surrogate pair: it may take more
+                // than one character of the text.
+                const unit = characterAt(json, end);
+                end += unit.length;
+                spaced ||= unit.space;
+            }
+            else {
+                // Nearly every character, and a result may be megabytes of them: one
+                // of the text, a space only when it says so.
+                spaced ||= code === 32 || ((code < 32 || code > 126) && /\s/.test(json[end]));
+                end += 1;
+            }
             units += 1;
             if (units === BRIEF_STRING_CHARS)
                 cutAt = end;
         }
         if (end >= json.length)
             return out + json.slice(open + 1);
-        out += units > BRIEF_STRING_CHARS ? `${json.slice(open + 1, cutAt)}…"` : json.slice(open + 1, end + 1);
+        const cut = units > (spaced ? BRIEF_STRING_CHARS : BRIEF_ID_CHARS);
+        out += cut ? `${json.slice(open + 1, cutAt)}…"` : json.slice(open + 1, end + 1);
         at = end + 1;
     }
     return out;
 }
+/**
+ * The character of a JSON string's text that starts at `i`: how many
+ * characters of the text it takes, and whether it is a space (a `\t`, or a
+ * Unicode escape of a space, is one as much as the character itself).
+ */
+function characterAt(text, i) {
+    const c = text[i];
+    if (c === "\\") {
+        const unit = unicodeEscape(text, i);
+        if (unit === undefined)
+            return { length: 2, space: /^[nrtf]$/.test(text[i + 1] ?? "") };
+        // Two escapes that are the halves of one character are one character.
+        const low = unit >= 0xd800 && unit <= 0xdbff ? unicodeEscape(text, i + 6) : undefined;
+        if (low !== undefined && low >= 0xdc00 && low <= 0xdfff)
+            return { length: 12, space: false };
+        return { length: 6, space: /\s/.test(String.fromCharCode(unit)) };
+    }
+    const code = c.charCodeAt(0);
+    const next = text.charCodeAt(i + 1);
+    if (code >= 0xd800 && code <= 0xdbff && next >= 0xdc00 && next <= 0xdfff)
+        return { length: 2, space: false };
+    return { length: 1, space: /\s/.test(c) };
+}
+/** The code unit of a `\uXXXX` escape at `i`, or undefined when there is none there. */
+function unicodeEscape(text, i) {
+    return text[i] === "\\" && text[i + 1] === "u" && /^[0-9a-fA-F]{4}$/.test(text.slice(i + 2, i + 6))
+        ? parseInt(text.slice(i + 2, i + 6), 16)
+        : undefined;
+}
 /**
  * The plan's summary (its response model) in a few words, or "" when it has
  * nothing to add: none at all, or only the note that it was left out — which
@@ -304,15 +438,15 @@ export function briefFields(fields, max) {
 }
 /**
  * A value of the plan's summary in a few words. Numbers, booleans and short
- * strings whole; a long string cut; a list or object whose JSON is short —
- * a few IDs, names or addresses — whole; a longer list counted; a longer
- * object by its first fields, one level down, below which it is counted too.
- * A summary's long lists are mostly the records the steps above already show.
+ * strings whole; long text cut, as a result's is ({@link cutLongText}: a link
+ * or an id is whole); a list or object whose JSON is short — a few IDs, names
+ * or addresses — whole; a longer list counted; a longer object by its first
+ * fields, one level down, below which it is counted too. A summary's long
+ * lists are mostly the records the steps above already show.
  */
 export function briefValue(value, depth = 0) {
-    if (typeof value === "string") {
-        return JSON.stringify(value.length > BRIEF_STRING_CHARS ? `${value.slice(0, BRIEF_STRING_CHARS)}…` : value);
-    }
+    if (typeof value === "string")
+        return cutLongText(JSON.stringify(value));
     if (value === null || typeof value !== "object")
         return String(value);
     let whole;

package/dist/replay/controller.d.ts

@@ -14,6 +14,7 @@
 import type { ExecutionReport } from "../record/recorder.js";
 import { type ReplayMode, type StepReach } from "./coverage.js";
 import { deriveParameters, type AgentDay, type DeriveContext, type DeriveResult } from "./derive.js";
+import { type HandoverStopReason } from "./handover.js";
 import { ProxyWorkQueue } from "./executor.js";
 import { ScenarioReplayPlan } from "./plan.js";
 import { type HostSinks } from "./safety.js";
@@ -91,6 +92,13 @@ export interface PreToolOptions {
      * route's deadline guard spoke first. No further step is started.
      */
     signal?: AbortSignal;
+    /**
+     * The call only looks and changes nothing (replay/reads-only.ts), as the
+     * control server judged it with what the tool's server says of it. A direct
+     * plan the model has not asked for yet lets such a call through and waits
+     * for `run_scenario` (B2 is11.md); nothing runs in its place.
+     */
+    readsOnly?: boolean;
 }
 /**
  * What the caller knows about how a pinned call ended, beyond its error text
@@ -310,6 +318,39 @@ export interface IntentMatchOptions {
     maxRequestsPerTurn: number;
 }
 export declare const DEFAULT_INTENT_MATCH: IntentMatchOptions;
+/**
+ * Where the stopped step stood when a plan handed over, in the words the
+ * service reads (its recordings/repo.ts `handoverFamily`): did the step
+ * happen. Its tool ran and only its output could not be read: `ran`. It was
+ * sent and nothing came back: `uncertain`. Stopped in front of it — the plan's
+ * time ran out (`budget`), its caller left (`cancelled`), its test could not
+ * say whether this request needs it (`test_failed`) — it was never sent:
+ * `not_run`. Otherwise the stop's own reason (`not_run`, `failed`,
+ * `concurrent`, `host_rejected`, `host_edited`), and a plain failure, which
+ * carries none, reads `failed`.
+ *
+ * The service continues a hand-over only with work that was recorded where the
+ * step had not happened (`not_run`, `failed`): the agent's work there starts
+ * with that very step. Continued after a step that ran, or may have, the plan
+ * made of it ran the step a second time. The three stops in front of a step
+ * went out under their own names, which the service reads as "may have run":
+ * a plan stopped by its time budget was never continued.
+ */
+export declare function stopOf(h: {
+    ranThisStep?: boolean;
+    inFlight?: unknown;
+    stopReason?: HandoverStopReason;
+}): string;
+/**
+ * Whether a run of the plan sent at least one of its calls: a step did its
+ * work, its tool answered with an error, its output could not be read after
+ * the tool ran, or it was sent and has not been seen through (a pin still out,
+ * a stop that may have happened). A step its test left out, one whose logic
+ * broke before its call, one that could not be sent and a recorded stand-in
+ * sent nothing — a plan that only did those has nothing a second run could
+ * repeat.
+ */
+export declare function sentACall(state: ReplayState): boolean;
 /** The turn handed back to the model part-way (fallbk.md). */
 export interface Handover {
     kind: FallbackKind;
@@ -317,6 +358,8 @@ export interface Handover {
     stepIndex: number;
     toolName?: string;
     error?: string;
+    /** For a `step_failed`: where the stopped step stood ({@link stopOf}). */
+    stop?: string;
     /** What the model is told. Always built, even when delivery fails. */
     note: string;
     /** Set once the note reached the model, so it is never delivered twice. */
@@ -478,12 +521,28 @@ export interface ReplayState {
     running?: Promise<RunArmedResult>;
     /** The model called `run_scenario` for this plan (its `PreToolUse` was seen). */
     directRequested?: boolean;
+    /**
+     * Calls that only look, made while this direct plan waited for
+     * `run_scenario` (B2 is11.md): each ran as the model wrote it, and the plan
+     * stayed announced. The first is told the plan still waits, once.
+     */
+    readsWaited?: number;
     /**
      * The direct run's caller went away mid-run — Esc on `run_scenario`, or its
      * client timing out. The turn it cut short is no measurement of the task, so
      * the execution report says `measured: false`.
      */
     callerCancelled?: boolean;
+    /**
+     * The plan ran to its end while its caller was gone, so its results reached
+     * nobody and no hand-over note exists: this says so, once, to the model
+     * ({@link ReplayController.takeNote}), so that it does not run the steps
+     * again.
+     */
+    unseen?: {
+        note: string;
+        delivered: boolean;
+    };
     /**
      * The derivation is the service's to answer (no key here), so waiting on it
      * is waiting on the service, and obeys its breaker (util/service-health.ts).
@@ -618,12 +677,36 @@ export type DeclineCode = "replay_disabled" | "not_ready" | "known_bad_first_ste
  * arms on the model's first call after the hand-over, whatever that is.)
  */
  | "not_taken"
+/**
+ * The plan was cancelled by its caller (Esc on `run_scenario`, or a timeout)
+ * a few minutes ago, after at least one step had run, and the same plan came
+ * back: not armed again, so the steps whose side effects are in place do not
+ * run a second time. The agent does the task, told what ran. Set by the
+ * control server.
+ */
+ | "after_cancel"
 /**
  * A continuation whose own code for working out its values (`paramsLogic`)
  * failed on this request, so none of its steps could be computed. Set by
  * the control server.
  */
- | "params_failed";
+ | "params_failed"
+/**
+ * A direct plan announced to the model, which made a call that may change
+ * something before it called `run_scenario`: the plan retired running
+ * nothing, because run after the model's own change it could do the same
+ * work twice. Calls that only look before it do not count (B2 is11.md).
+ * Set by the control server (runners after 0.3.26; up to it, such a plan
+ * was retired at any first call, and reported no reason).
+ */
+ | "changed_first"
+/**
+ * A direct plan whose `run_scenario` call never reached the runner: the
+ * person refused it, a rule denied it, or it failed on the way. Refused
+ * means refused: the plan retired running nothing. Set by the control
+ * server (runners after 0.3.26; up to it, reported with no reason).
+ */
+ | "run_refused";
 /**
  * What a continuation continues (the service's fallbk.md Part 3): the plan
  * that handed over, the step it stopped in front of, and the recording of the
@@ -774,6 +857,12 @@ export declare class ReplayController {
      * against the plan; the outcome is `fell_back` when a step ran and `failed`
      * when none did, as for every hand-over. The note is the caller's to
      * deliver ({@link takeNote}). Returns false when there was no live plan.
+     *
+     * A step the adapter was given and has not reported back on may be running:
+     * the plan stops after it, as for a call beside a pin ({@link concurrentCall}),
+     * and the hand-over says the step may have happened — never "did not run",
+     * which the service would continue with work that starts by running it
+     * again. Its result is still read when it lands.
      */
     hostHandOver(state: ReplayState, why: "own_call" | "closed" | "late"): boolean;
     /**
@@ -814,6 +903,8 @@ export declare class ReplayController {
      * Returns it once and marks it delivered; undefined when there is none.
      */
     takeNote(state: ReplayState | undefined): string | undefined;
+    /** Whether a note about this plan is still to be told to the model: a hand-over's, or the unseen results'. */
+    hasUndeliveredNote(state: ReplayState | undefined): boolean;
     /**
      * Deliver text to the model in place of the tool call it was about to make:
      * as genuine command output for `Bash`, as the denial reason otherwise — the