@basein/runner 0.3.23 → 0.3.25

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/docs/calculatedReplayGuide.md

@@ -373,7 +373,7 @@ so there is exactly one switch and it cannot get out of step with itself.
 | `BIR_BASH_ALLOW` | *(unset: any command)* | Command prefixes a runner-side `Bash` step may run (`*` for all). Unset means any command; `none` means no command, and `Bash` steps are steered in the session. A plan's Bash steps share a working directory, exactly as the host's own Bash tool does — variables and functions do not persist, also as the host's. A call with `run_in_background`, or with its own `timeout` longer than the step's clock (`BIR_STEP_TIMEOUT_MS`), is never started on the runner: the plan hands over in front of it |
 | `BIR_PATH_ALLOW` | *(unset: any folder, from 0.3.21)* | Folders a runner-side `Read`, `Glob`, `Grep`, `Edit` or `Write` may touch (`*` for all). Unset means any path, as the agent's own tools reach it — a plan that reads the agent's memory file under `~/.claude` runs. `project` is the session's project folder alone (the rule up to 0.3.20); add folders after a comma, `~` for the home folder: `project,~/.claude`. Under a list, a path outside it, symlinks included, is refused and the plan hands over in front of it. `none` means no folder, and the file steps are steered in the session. `Bash` is `BIR_BASH_ALLOW`'s |
 | `BIR_INTENT_ARM` | *(unset: off)* | `1` lets a whole plan whose intent matches the agent's reasoning mid-turn arm in the calling tool's place, which means waiting for it (`BIR_INTENT_ARM_BUDGET_MS`, 500). Unset or `0`: off — no probe is sent and nothing arms mid-turn, as up to 0.3.18 |
-| `BIR_CONTINUATIONS` | *(unset: on, from 0.3.23)* | After a plan hands the task to the agent at a step, the agent's first call asks the service for the plan of the work recorded after an earlier hand-over at that step — once per hand-over, waiting 1.5 s at most for the answer and up to 7 s for its values — and runs it in that call's place only when the call is its first step (the same tool, on the same thing). Its saving is counted on the plan that handed over. `0`: off, and the agent's work is recorded as before. `BIR_INTENT_MATCH=0` turns it off too |
+| `BIR_CONTINUATIONS` | *(unset: on, from 0.3.23)* | After a plan hands the task to the agent at a step, the agent's first call asks the service for the plan of the work recorded after an earlier hand-over at that step — once per hand-over, waiting 1.5 s at most for the answer and up to 7 s for its values — and that plan does the rest of the task, whatever the agent's call was (from 0.3.24; 0.3.23 ran it only when the call was its first step). A call to one of the plan's own tools is answered in its place, so the plan never makes it twice; any other call runs as the agent wrote it, and the agent is told of the plan on its result. Its saving is counted on the plan that handed over. `0`: off, and the agent's work is recorded as before. `BIR_INTENT_MATCH=0` turns it off too |
 | `BIR_VERBOSE` | *(unset)* | `1` adds per-step `replay.*` detail lines |
 
 The `bir` server reads its own, from the environment Claude Code starts it with:

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@basein/runner",
-  "version": "0.3.23",
+  "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",