@basein/runner 0.3.24 → 0.3.25

package/dist/replay/bundle.d.ts

@@ -13,6 +13,20 @@
  * fresh execution (§8.1). It is surfaced in the header *and* per entry, because
  * a bundle that quietly passed off a stale result as a live one would be the
  * worst outcome available here.
+ *
+ * The agent pays to take the bundle in, so it carries nothing the model already
+ * has (docs/calculatedReplay.md, "How a bundle reads"): a result is its text,
+ * not MCP's JSON envelope, and consecutive calls to one tool share a section
+ * that says once what they share.
+ *
+ * And it carries detail only where detail is needed. A run that went entirely
+ * well is laid out briefly ({@link AssembleOptions.brief}): the agent's job is
+ * to see that the steps were right and say what was done, which takes every
+ * record and field a long result has — the IDs, dates, senders and names it
+ * checks the steps against — but not every word of its long text. Anything
+ * else — a step that broke, a run that stopped short, a recorded stand-in, a
+ * sub-task the agent carries on with — gets every result whole, because that
+ * is what the agent works from.
  */
 /** `permissionDecisionReason` is fed to the model as text; keep denials bounded. */
 export declare const MAX_REPLAY_REASON = 60000;
@@ -63,11 +77,73 @@ export interface AssembleOptions {
      * leave the agent its tools.
      */
     reportTool?: string;
+    /**
+     * Lay the run out briefly if it went entirely well, with `summary` — the
+     * plan's response model — in a few words above the footer. Asked for by a
+     * caller whose agent answers from the bundle and nothing else (`bir-
+     * scenario`'s run of a whole plan); `summary` may be absent or `{}`.
+     *
+     * Entirely well means every entry ran live and none reported an error, and
+     * the agent is to answer now: with `handover` or `subTask` set, a recorded
+     * entry, or a result marked as an error, the bundle is laid out in full as
+     * if this were not set. The summary is then the caller's to deliver.
+     */
+    brief?: {
+        summary?: Record<string, unknown>;
+    };
 }
 /**
  * Compose the bundle. `maxChars` is a hard ceiling on the returned string.
  */
 export declare function assembleBundle(entries: readonly BundleEntry[], maxChars: number, opts?: AssembleOptions): string;
+/**
+ * Whether a run went entirely well and the agent answers now — the one case a
+ * bundle may be brief ({@link AssembleOptions.brief}). A run that went wrong
+ * anywhere, stood on a recording, or is one the agent carries on from is what
+ * the agent works from next: it gets every result.
+ */
+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.
+ */
+export declare function cutLongText(json: string): string;
+/**
+ * `key = value` for each field, each value in a few words ({@link briefValue}),
+ * ended at a field's end with "…" rather than run past `max` characters.
+ */
+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.
+ */
+export declare function briefValue(value: unknown, depth?: number): string;
+/**
+ * A tool result as the model should read it.
+ *
+ * Executors hand the bundle the JSON of MCP's `CallToolResult`. Laid out as it
+ * came, every result pays for the envelope —
+ * `{"content":[{"type":"text","text":"…"}],"isError":false}`, some fifty
+ * characters — and for a second layer of escaping: every quote in the text
+ * written `\"`, every backslash `\\`. Neither tells the model anything, and on
+ * a long plan they are a large share of what it reads (and of what the agent
+ * pays to put in its context). A result whose content is text and nothing else
+ * is shown as that text, marked when `isError` is true. Anything else — an
+ * image, a resource, structured content, an answer that is not a
+ * `CallToolResult` at all — is shown exactly as it came.
+ */
+export declare function resultText(response: string): {
+    text: string;
+    error: boolean;
+};
 /** Truncate to `max` chars, appending a marker naming how much was dropped. */
 export declare function truncate(s: string, max: number): string;
 //# sourceMappingURL=bundle.d.ts.map

package/dist/replay/bundle.js

@@ -13,6 +13,20 @@
  * fresh execution (§8.1). It is surfaced in the header *and* per entry, because
  * a bundle that quietly passed off a stale result as a live one would be the
  * worst outcome available here.
+ *
+ * The agent pays to take the bundle in, so it carries nothing the model already
+ * has (docs/calculatedReplay.md, "How a bundle reads"): a result is its text,
+ * not MCP's JSON envelope, and consecutive calls to one tool share a section
+ * that says once what they share.
+ *
+ * And it carries detail only where detail is needed. A run that went entirely
+ * well is laid out briefly ({@link AssembleOptions.brief}): the agent's job is
+ * to see that the steps were right and say what was done, which takes every
+ * record and field a long result has — the IDs, dates, senders and names it
+ * checks the steps against — but not every word of its long text. Anything
+ * else — a step that broke, a run that stopped short, a recorded stand-in, a
+ * sub-task the agent carries on with — gets every result whole, because that
+ * is what the agent works from.
  */
 /** `permissionDecisionReason` is fed to the model as text; keep denials bounded. */
 export const MAX_REPLAY_REASON = 60_000;
@@ -111,6 +125,29 @@ const SUBTASK_HEADER = "[BaseInstRunner calculated replay] The tool calls below
     "steps are done: do not repeat these calls. Continue your task from where they end, " +
     "calling tools as needed.";
 const SUBTASK_FOOTER = "\n\nThe calls above are done. Continue your task, calling tools as needed.";
+/**
+ * Every step ran live and succeeded ({@link AssembleOptions.brief}). The same
+ * assurances as {@link LIVE_HEADER} — it happened, now, for real — plus what
+ * the agent needs to read the steps below: why some text ends in "…".
+ */
+const BRIEF_HEADER = "[BaseInstRunner calculated replay] The tool calls below have JUST been executed " +
+    "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 \"…\".";
+/** 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.";
+/** A result up to this long is shown whole even in a brief bundle: it is its own best evidence. */
+const BRIEF_RESULT_CHARS = 300;
+/** At most this much of a brief bundle is the plan's summary. */
+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;
+/** 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. */
+const BRIEF_OBJECT_FIELDS = 6;
 /**
  * Compose the bundle. `maxChars` is a hard ceiling on the returned string.
  */
@@ -119,6 +156,7 @@ export function assembleBundle(entries, maxChars, opts = {}) {
     // that answered split it.
     const n = entries.filter((e) => !e.notNeeded).length;
     const anyRecorded = entries.some((e) => e.recorded);
+    const brief = opts.brief !== undefined && wentWell(entries, opts);
     // A hand-over outranks a sub-task: it says "continue" too, and it also has to
     // say that the plan stopped short. A sub-task outranks the live and mixed
     // headers, whose wording forbids further tool calls.
@@ -126,14 +164,16 @@ export function assembleBundle(entries, maxChars, opts = {}) {
         ? HANDOVER_HEADER
         : opts.subTask
             ? SUBTASK_HEADER
-            : withReportException(anyRecorded ? MIXED_HEADER : LIVE_HEADER, opts.reportTool);
+            : withReportException(brief ? BRIEF_HEADER : anyRecorded ? MIXED_HEADER : LIVE_HEADER, opts.reportTool);
     const footer = opts.handover
         ? HANDOVER_FOOTER
         : opts.subTask
             ? SUBTASK_FOOTER
-            : withReportException(anyRecorded ? MIXED_FOOTER : LIVE_FOOTER, opts.reportTool);
+            : 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 +
@@ -142,20 +182,277 @@ export function assembleBundle(entries, maxChars, opts = {}) {
             (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 sections = entries.map((e, i) => {
-        if (e.notNeeded) {
-            // Never "skipped" or "failed": the step was left out on purpose, because
-            // this request does not need it, and nothing is missing for its absence.
-            const why = testWords(e.notNeeded.text);
-            return (`\n\n--- Step ${i + 1}: ${e.toolName} (not needed) ---\n` +
-                `Not run: this request does not need it${why ? ` — it is only for when ${why}` : ""}.`);
+    const show = (e) => {
+        const result = resultText(e.response);
+        return {
+            text: brief ? briefResult(result.text, perResponse) : truncate(result.text, perResponse),
+            marks: resultMarks(e.recorded, result.error),
+        };
+    };
+    const sections = [];
+    for (const run of consecutiveRuns(entries)) {
+        if (run.length === 1) {
+            const { entry: e, index: i } = run[0];
+            if (e.notNeeded) {
+                // Never "skipped" or "failed": the step was left out on purpose, because
+                // this request does not need it, and nothing is missing for its absence.
+                const why = testWords(e.notNeeded.text);
+                sections.push(`\n\n--- Step ${i + 1}: ${e.toolName} (not needed) ---\n` +
+                    `Not run: this request does not need it${why ? ` — it is only for when ${why}` : ""}.`);
+                continue;
+            }
+            const shown = show(e);
+            sections.push(`\n\n--- Step ${i + 1}: ${e.toolName} ---\n` +
+                `Call: ${e.input}\n` +
+                `Result${shown.marks}: ${shown.text}`);
+            continue;
+        }
+        sections.push(runSection(run, show));
+    }
+    return truncate(header + sections.join("") + summary + footer, maxChars);
+}
+/**
+ * Whether a run went entirely well and the agent answers now — the one case a
+ * bundle may be brief ({@link AssembleOptions.brief}). A run that went wrong
+ * anywhere, stood on a recording, or is one the agent carries on from is what
+ * the agent works from next: it gets every result.
+ */
+export function wentWell(entries, opts) {
+    return (!opts.handover &&
+        !opts.subTask &&
+        entries.every((e) => e.notNeeded || (!e.recorded && !resultText(e.response).error)));
+}
+/**
+ * A result in a brief bundle. Whole when it is short. A long one that is JSON
+ * — a search's records, nearly always — keeps every record and field, and
+ * only its long text is cut ({@link cutLongText}): the agent checks the steps
+ * against the IDs, dates, senders and names, and those are short. A long
+ * result in words is shown whole: it may be the very answer.
+ *
+ * Measured on B2's length tests: showing only the values the plan took from a
+ * result instead left the agent unable to check the plan's choices — "I
+ * couldn't confirm these were the newest", "or who sent them" — in one reply
+ * in six, and once it reported a correct run as wrong.
+ */
+function briefResult(text, budget) {
+    if (text.length > BRIEF_RESULT_CHARS && /^\s*[[{]/.test(text))
+        return truncate(cutLongText(text), budget);
+    return truncate(text, budget);
+}
+/**
+ * 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.
+ */
+export function cutLongText(json) {
+    let out = "";
+    let at = 0;
+    while (at < json.length) {
+        const open = json.indexOf('"', at);
+        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.
+        let end = open + 1;
+        let units = 0;
+        let cutAt = -1;
+        while (end < json.length && json[end] !== '"') {
+            end += json[end] === "\\" ? 2 : 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);
+        at = end + 1;
+    }
+    return out;
+}
+/**
+ * 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
+ * sends the model to the steps, and they are right above it.
+ */
+function briefSummary(model) {
+    if (!model)
+        return "";
+    const keys = Object.keys(model);
+    if (keys.length === 0 || keys.every((k) => k === "summaryLeftOut"))
+        return "";
+    return `\n\nThe plan's summary: ${briefFields(model, BRIEF_SUMMARY_CHARS)}`;
+}
+/**
+ * `key = value` for each field, each value in a few words ({@link briefValue}),
+ * ended at a field's end with "…" rather than run past `max` characters.
+ */
+export function briefFields(fields, max) {
+    let out = "";
+    for (const [key, value] of Object.entries(fields)) {
+        const part = `${key} = ${briefValue(value)}`;
+        const next = out ? `${out}; ${part}` : part;
+        if (next.length > max)
+            return out ? `${out}; …` : truncate(part, max);
+        out = next;
+    }
+    return out;
+}
+/**
+ * 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.
+ */
+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 (value === null || typeof value !== "object")
+        return String(value);
+    let whole;
+    try {
+        whole = JSON.stringify(value) ?? "";
+    }
+    catch {
+        return "[unserializable]";
+    }
+    if (whole.length <= BRIEF_INLINE_CHARS)
+        return whole;
+    if (Array.isArray(value))
+        return `${value.length} ${value.length === 1 ? "item" : "items"}`;
+    const fields = Object.entries(value);
+    if (depth >= 1)
+        return `{${fields.length} ${fields.length === 1 ? "field" : "fields"}}`;
+    const shown = fields.slice(0, BRIEF_OBJECT_FIELDS).map(([k, v]) => `${k}: ${briefValue(v, depth + 1)}`);
+    return `{${shown.join(", ")}${fields.length > BRIEF_OBJECT_FIELDS ? ", …" : ""}}`;
+}
+/**
+ * A tool result as the model should read it.
+ *
+ * Executors hand the bundle the JSON of MCP's `CallToolResult`. Laid out as it
+ * came, every result pays for the envelope —
+ * `{"content":[{"type":"text","text":"…"}],"isError":false}`, some fifty
+ * characters — and for a second layer of escaping: every quote in the text
+ * written `\"`, every backslash `\\`. Neither tells the model anything, and on
+ * a long plan they are a large share of what it reads (and of what the agent
+ * pays to put in its context). A result whose content is text and nothing else
+ * is shown as that text, marked when `isError` is true. Anything else — an
+ * image, a resource, structured content, an answer that is not a
+ * `CallToolResult` at all — is shown exactly as it came.
+ */
+export function resultText(response) {
+    const asIs = { text: response, error: false };
+    let parsed;
+    try {
+        parsed = JSON.parse(response);
+    }
+    catch {
+        return asIs;
+    }
+    if (!parsed || typeof parsed !== "object" || Array.isArray(parsed))
+        return asIs;
+    const result = parsed;
+    if (!Object.keys(result).every((k) => k === "content" || k === "isError"))
+        return asIs;
+    if (result.isError !== undefined && typeof result.isError !== "boolean")
+        return asIs;
+    if (!Array.isArray(result.content) || result.content.length === 0)
+        return asIs;
+    const texts = [];
+    for (const item of result.content) {
+        if (!item || typeof item !== "object" || Array.isArray(item))
+            return asIs;
+        const part = item;
+        if (part.type !== "text" || typeof part.text !== "string")
+            return asIs;
+        if (!Object.keys(part).every((k) => k === "type" || k === "text"))
+            return asIs;
+        texts.push(part.text);
+    }
+    return { text: texts.join("\n"), error: result.isError === true };
+}
+/** `(recorded)`, `(error)` or `(recorded, error)` after a result's label; "" for a plain live result. */
+function resultMarks(recorded, error) {
+    const marks = [recorded ? "recorded" : "", error ? "error" : ""].filter(Boolean);
+    return marks.length > 0 ? ` (${marks.join(", ")})` : "";
+}
+/**
+ * The entries cut into runs of consecutive calls to one tool. A long plan is
+ * mostly such runs — eleven look-ups, then thirty-two forwards — and laying
+ * each step out on its own repeats the tool's name and the section frame every
+ * time. A step left out stands alone, so its "not needed" line reads as before.
+ */
+function consecutiveRuns(entries) {
+    const runs = [];
+    entries.forEach((entry, index) => {
+        const last = runs.at(-1);
+        const prev = last?.at(-1)?.entry;
+        if (last && prev && !prev.notNeeded && !entry.notNeeded && prev.toolName === entry.toolName) {
+            last.push({ entry, index });
+        }
+        else {
+            runs.push([{ entry, index }]);
         }
-        const response = truncate(e.response, perResponse);
-        return (`\n\n--- Step ${i + 1}: ${e.toolName} ---\n` +
-            `Call: ${e.input}\n` +
-            `Result${e.recorded ? " (recorded)" : ""}: ${response}`);
     });
-    return truncate(header + sections.join("") + footer, maxChars);
+    return runs;
+}
+/**
+ * Two or more consecutive calls to one tool, as one section: one line per call,
+ * numbered as its step, with its result after the arrow. What every call shares
+ * is said once above the calls — input fields with the same value in each, and
+ * the answer, when every call got the same one. Each result is shown as `show`
+ * shows a step on its own, budget included.
+ */
+function runSection(run, show) {
+    const first = run[0];
+    const head = `\n\n--- Steps ${first.index + 1}-${run[run.length - 1].index + 1}: ${first.entry.toolName} (${run.length} calls) ---`;
+    const inputs = sharedInput(run.map(({ entry }) => entry.input));
+    const shown = run.map(({ entry, index }, i) => ({ step: index + 1, input: inputs.own[i], ...show(entry) }));
+    const lines = inputs.shared === null ? "" : `\nIn every call: ${inputs.shared}`;
+    const same = shown.every((s) => s.text === shown[0].text && s.marks === shown[0].marks);
+    if (same) {
+        return (`${head}${lines}\nEvery call's result${shown[0].marks}: ${shown[0].text}` +
+            shown.map((s) => `\n${s.step}: ${s.input}`).join(""));
+    }
+    return head + lines + shown.map((s) => `\n${s.step}${s.marks}: ${s.input} -> ${s.text}`).join("");
+}
+/**
+ * The input fields a run of calls all share, said once, and what is left of
+ * each call's input. A forward sends thirty-two emails to one recipient; the
+ * recipient need not be read thirty-two times. Only plain JSON objects are
+ * split, and only on fields present in every call with the same value; an
+ * input that was capped, or is not an object, leaves the run as it came.
+ */
+function sharedInput(inputs) {
+    const asCame = { shared: null, own: [...inputs] };
+    const objects = [];
+    for (const input of inputs) {
+        let parsed;
+        try {
+            parsed = JSON.parse(input);
+        }
+        catch {
+            return asCame;
+        }
+        if (!parsed || typeof parsed !== "object" || Array.isArray(parsed))
+            return asCame;
+        objects.push(parsed);
+    }
+    const value = (o, key) => JSON.stringify(o[key]);
+    const common = Object.keys(objects[0]).filter((key) => objects.every((o) => Object.hasOwn(o, key) && value(o, key) === value(objects[0], key)));
+    if (common.length === 0)
+        return asCame;
+    const pick = (o, keep) => JSON.stringify(Object.fromEntries(Object.entries(o).filter(([key]) => keep(key))));
+    return {
+        shared: pick(objects[0], (key) => common.includes(key)),
+        own: objects.map((o) => pick(o, (key) => !common.includes(key))),
+    };
 }
 /** Truncate to `max` chars, appending a marker naming how much was dropped. */
 export function truncate(s, max) {

package/dist/replay/controller.d.ts

@@ -199,7 +199,8 @@ export declare function clampDirectRun(budgets: ReplayBudgets, logicMs?: number)
  *
  *  - **ok** — the plan ran to its end: `{ ok: true, text, responseModel, steps,
  *    partial: false }`. `text` is the bundle; `responseModel` what the
- *    scenario's own logic built from it (`{}` when it has none).
+ *    scenario's own logic built from it (`{}` when it has none, and when the
+ *    bundle is brief and carries it already — plan.ts, `DriveOptions.brief`).
  *  - **partial** — the plan stopped part-way after running steps here: `{ ok:
  *    true, text, responseModel: {}, steps, partial }`. `text` opens with the
  *    hand-over note (text beginning `[BaseInstRunner calculated replay]`) and

package/dist/replay/controller.js

@@ -1757,7 +1757,15 @@ export class ReplayController {
         const deadline = Date.now() + this.budgets.planMs;
         let result;
         try {
-            result = await plan.runToCompletion(this.executeStep(state, { deadline }), this.recordedSource(state), this.observeStep(state), deadline, MAX_REPLAY_REASON, { stopOnFailure: true, recordedFallback: this.recordedFallback, signal, reportTool: this.reportToolFor(state) });
+            result = await plan.runToCompletion(this.executeStep(state, { deadline }), this.recordedSource(state), this.observeStep(state), deadline, MAX_REPLAY_REASON, {
+                stopOnFailure: true,
+                recordedFallback: this.recordedFallback,
+                signal,
+                reportTool: this.reportToolFor(state),
+                // The agent answers from the bundle alone: a run that went entirely
+                // well is laid out briefly, with the plan's summary in it.
+                brief: true,
+            });
         }
         catch (err) {
             // The scenario's own logic failed. Retire and let the model do the work.
@@ -1875,12 +1883,18 @@ export class ReplayController {
         }
         // Live steps only, as above: a recorded stand-in did no work here.
         state.stepsPinned += result.executed;
+        // A brief bundle carries the plan's summary itself, in a few words, so it
+        // is not delivered a second time beside it.
         let responseModel = {};
-        try {
-            responseModel = plan.responseModel();
-        }
-        catch (err) {
-            logDetail("replay.response_model_failed", { error: errText(err) });
+        if (result.summaryError)
+            logDetail("replay.response_model_failed", { error: result.summaryError });
+        if (!result.brief) {
+            try {
+                responseModel = plan.responseModel();
+            }
+            catch (err) {
+                logDetail("replay.response_model_failed", { error: errText(err) });
+            }
         }
         // A plan whose tools errored ran to the end and did nothing. `steered_full`
         // would book the largest saving available for it; `failed` books a baseline

package/dist/replay/plan.d.ts

@@ -125,6 +125,14 @@ export interface DriveOptions {
      * they always were (bundle.ts, `AssembleOptions.reportTool`).
      */
     reportTool?: string;
+    /**
+     * Lay a run that went entirely well out briefly, with the plan's summary in
+     * it (bundle.ts, `AssembleOptions.brief`), and say so in the result's
+     * `brief`. For a caller whose agent answers from the bundle alone —
+     * `bir-scenario`'s run of a whole plan — not for an operator's `bir replay`,
+     * which reads every result. A run that went wrong is laid out in full.
+     */
+    brief?: boolean;
 }
 /**
  * Supplies a step's recorded output when its tool cannot run here (§8.1).
@@ -213,6 +221,13 @@ export interface ComposeResult {
      * the end of the planned steps.
      */
     endedAt: number;
+    /**
+     * The bundle is brief ({@link DriveOptions.brief}), and the plan's summary,
+     * when it has one, is in `text`: the caller must not deliver it again.
+     */
+    brief?: boolean;
+    /** Building the summary for a brief bundle threw: why. The bundle went without it. */
+    summaryError?: string;
 }
 /** Where, and why, a run stopped short of the chain's end (fallbk.md). */
 export interface PlanStop {

package/dist/replay/plan.js

@@ -21,7 +21,7 @@
  *      output, and skipping.
  */
 import { evalParamsLogic, evalResponseParamsLogic, evalToolInputLogic, evalToolOutputLogic, evalWhenLogic, LogicTimeoutError, } from "./logic.js";
-import { assembleBundle, bundleInput, MAX_REPLAY_REASON, testWords } from "./bundle.js";
+import { assembleBundle, bundleInput, MAX_REPLAY_REASON, testWords, wentWell, } from "./bundle.js";
 import { redact, redactText } from "../record/redact.js";
 import { sinkOfPlan, unsafeParameter } from "./safety.js";
 import { testedOnlyTargets } from "./targets.js";
@@ -883,6 +883,29 @@ export class ScenarioReplayPlan {
         // The intent is a paragraph the analyser wrote; it is context, not an
         // instruction, so it is clipped rather than dumped whole into the prompt.
         const intent = this.intent.length > 240 ? `${this.intent.slice(0, 240)}…` : this.intent;
+        if (this.mode === "direct") {
+            // The steps are not listed. The model does not call them, and what the
+            // tool returns names every call and says whether the run was whole or
+            // stopped short — what a list here once told it ahead of time. The list
+            // cost the agent up to 2,000 characters in the first call of every turn
+            // a plan was armed for (docs/calculatedReplay.md, "How a bundle reads"),
+            // and the tool's result shows an operator watching the session what ran.
+            return [
+                "[BaseInstRunner calculated replay] A known-good tool sequence was recorded",
+                `for this request${intent ? ` (intent: ${intent})` : ""}.`,
+                "",
+                `Call ${directToolName} once, with no arguments, before any other tool. It runs the`,
+                "sequence and returns what each call did.",
+                subTask
+                    ? "Then continue your task from the results it returns, calling tools as needed."
+                    : this.stopsEarly()
+                        ? "Then continue the user's request from the results it returns."
+                        : "Then answer the user's request from the results it returns.",
+                // A parked step (fallbk.md D3): the model is told up front that the
+                // plan is partial, so the hand-over that follows is expected.
+                ...(this.stopsEarly() ? ["", "The system will then hand the rest of the task back to you."] : []),
+            ].join("\n");
+        }
         // Each step's reasoning is another session's narration ("I'll now drop the
         // temp table…"), injected into this one. It is a label here, not a
         // paragraph: its first line, clipped. A chain long enough that even the
@@ -931,30 +954,6 @@ export class ScenarioReplayPlan {
         const tail = this.stopsEarly()
             ? ["", "The system will then hand the rest of the task back to you."]
             : [];
-        if (this.mode === "direct") {
-            // The sequence is listed even though the model does not call it itself:
-            // it is about to receive these results, and knowing what was run is what
-            // lets it tell a complete answer from a partial one. It is also the only
-            // place an operator watching the session can see what a replay is doing.
-            return [
-                "[BaseInstRunner calculated replay] A known-good tool sequence was recorded",
-                `for this request${intent ? ` (intent: ${intent})` : ""}.`,
-                "",
-                anyTest
-                    ? 'It runs these tools, in order, and returns their results. A step marked "only when" runs only when this request needs it, and the results say which ones did not:'
-                    : "It runs these tools, in order, and returns their results:",
-                "",
-                ...lines,
-                "",
-                `Call ${directToolName} once, with no arguments, before any other tool.`,
-                subTask
-                    ? "Then continue your task from the results it returns, calling tools as needed."
-                    : this.stopsEarly()
-                        ? "Then continue the user's request from the results it returns."
-                        : "Then answer the user's request from the results it returns.",
-                ...tail,
-            ].join("\n");
-        }
         return [
             "[BaseInstRunner calculated replay] A known-good tool sequence was previously",
             "recorded for this request. Call exactly these tools, in order, one at a time:",
@@ -1343,12 +1342,29 @@ export class ScenarioReplayPlan {
                 position: this.stopAt,
             };
         }
+        const layout = {
+            handover: stopped !== undefined,
+            subTask: this.subTask,
+            reportTool: opts.reportTool,
+        };
+        // Brief only for a run that went entirely well (bundle.ts, `wentWell`). A
+        // tool error that is not an MCP `isError` — a JSON-RPC error, which the
+        // bundle cannot tell from a result — is counted in `errored`, and is just
+        // as much a reason for the agent to see everything.
+        const brief = opts.brief === true && errored === 0 && wentWell(entries, layout);
+        let summaryError;
+        if (brief) {
+            let summary;
+            try {
+                summary = this.responseModel();
+            }
+            catch (err) {
+                summaryError = errText(err);
+            }
+            layout.brief = { summary };
+        }
         return {
-            text: assembleBundle(entries, maxChars, {
-                handover: stopped !== undefined,
-                subTask: this.subTask,
-                reportTool: opts.reportTool,
-            }),
+            text: assembleBundle(entries, maxChars, layout),
             executed,
             recorded: recordedCount,
             skipped,
@@ -1359,6 +1375,8 @@ export class ScenarioReplayPlan {
             stopped,
             aborted: aborted || undefined,
             endedAt: this.stepIndex,
+            brief: brief || undefined,
+            summaryError,
         };
     }
     /**

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.25",
   "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",