@basein/runner 0.2.0 → 0.2.2

package/dist/replay/source-run.js

@@ -21,73 +21,103 @@
  *
  * Fetched **lazily** — only when a step actually needs it — and cached for the
  * turn, so a fully-executable replay never makes this call at all.
+ *
+ * A chain with calls draws on **several** recordings: a called segment's steps
+ * take their outputs from that segment's own recording, within its own range
+ * (segmented.md R-CALL-31). So the rows are cached per run id, and the cursors
+ * are kept per frame — a segment called twice in one chain replays from the
+ * start of its range both times, as two separate replays of it would.
  */
 import { logDetail, logLine, errText } from "../util/log.js";
-export class SourceRunOutputs {
+export class SourceRunCache {
     opts;
-    /** toolName → recorded outputs, in run order. */
-    byTool;
+    /** run id → every recorded output of that run, in order. */
+    runs = new Map();
+    loading = new Map();
+    /** `frameId#toolName` → how many of that tool the frame has drawn. */
     cursor = new Map();
-    loading;
     constructor(opts) {
         this.opts = opts;
     }
     /**
-     * The next recorded output for `step`'s tool, or undefined when the run has
-     * none left (or could not be fetched). Never throws — a missing recorded
-     * output means the step is skipped, which the caller already handles.
+     * The next recorded output for this entry's tool, from this entry's own
+     * recording and range, or undefined when there is none left (or the run could
+     * not be fetched). Never throws — a missing recorded output means the step is
+     * skipped, which the caller already handles.
      */
-    async outputFor(step) {
+    async outputFor(entry) {
+        const runId = entry.runId || this.opts.runId;
+        const toolName = entry.step.toolName;
+        if (!toolName)
+            return undefined;
         try {
-            await this.load();
+            await this.load(runId);
         }
         catch (err) {
             logLine("replay.source_run_failed", {
-                run: this.opts.runId,
+                run: runId,
                 why: "no recorded outputs available for steps that cannot run here",
                 error: errText(err),
             });
             return undefined;
         }
-        const list = this.byTool?.get(step.toolName);
-        if (!list || list.length === 0)
+        const all = this.runs.get(runId) ?? [];
+        const inRange = all.filter((o) => o.toolName === toolName &&
+            (entry.stepFrom === null ||
+                entry.stepTo === null ||
+                (o.position >= entry.stepFrom && o.position <= entry.stepTo)));
+        if (inRange.length === 0)
             return undefined;
-        const at = this.cursor.get(step.toolName) ?? 0;
-        this.cursor.set(step.toolName, at + 1);
-        return list[at];
+        const key = `${entry.frame.id}#${toolName}`;
+        const at = this.cursor.get(key) ?? 0;
+        this.cursor.set(key, at + 1);
+        return inRange[at]?.output;
     }
-    load() {
-        if (!this.loading) {
-            this.loading = this.fetchRun();
+    load(runId) {
+        let pending = this.loading.get(runId);
+        if (!pending) {
+            pending = this.fetchRun(runId);
+            this.loading.set(runId, pending);
         }
-        return this.loading;
+        return pending;
     }
-    async fetchRun() {
+    async fetchRun(runId) {
         const doFetch = this.opts.fetchImpl ?? fetch;
         const controller = new AbortController();
         const timer = setTimeout(() => controller.abort(), this.opts.timeoutMs ?? 10_000);
         timer.unref?.();
         try {
-            const res = await doFetch(`${this.opts.baseUrl.replace(/\/+$/, "")}/recordings/runs/${this.opts.runId}`, {
+            const res = await doFetch(`${this.opts.baseUrl.replace(/\/+$/, "")}/recordings/runs/${runId}`, {
                 headers: { authorization: `Bearer ${this.opts.token()}` },
                 signal: controller.signal,
             });
             if (!res.ok)
                 throw new Error(`HTTP ${res.status}`);
             const body = (await res.json());
-            const map = new Map();
+            const outputs = [];
+            // A `tool_response` belongs to the `tool_selected` before it, and it is
+            // *that* row's position the range is cut on: a response row may sit just
+            // outside a range whose call sits inside it.
+            const lastCall = new Map();
             for (const row of body.steps ?? []) {
-                if (row.type !== "tool_response" || !row.tool_name)
+                if (!row.tool_name)
+                    continue;
+                if (row.type === "tool_selected") {
+                    lastCall.set(row.tool_name, row.step_index ?? -1);
                     continue;
-                const list = map.get(row.tool_name) ?? [];
-                list.push(row.tool_output ?? "{}");
-                map.set(row.tool_name, list);
+                }
+                if (row.type !== "tool_response")
+                    continue;
+                outputs.push({
+                    toolName: row.tool_name,
+                    output: row.tool_output ?? "{}",
+                    position: lastCall.get(row.tool_name) ?? row.step_index ?? -1,
+                });
             }
-            this.byTool = map;
+            this.runs.set(runId, outputs);
             logDetail("replay.source_run_loaded", {
-                run: this.opts.runId,
-                tools: map.size,
-                outputs: [...map.values()].reduce((n, l) => n + l.length, 0),
+                run: runId,
+                outputs: outputs.length,
             });
         }
         finally {
@@ -95,4 +125,9 @@ export class SourceRunOutputs {
         }
     }
 }
+/**
+ * The name this class had before one chain could draw on more than one
+ * recording. Kept so nothing outside has to change its import.
+ */
+export { SourceRunCache as SourceRunOutputs };
 //# sourceMappingURL=source-run.js.map

package/dist/replay/types.d.ts

@@ -11,16 +11,55 @@
  * `"ready"` carries an **empty** `steps` array, by the service's own rule.
  */
 /** One step: the tool, and the JS logic that recomputes its arguments. */
+/**
+ * A segment inlined into the chain that calls it (segmented.md R-CALL-28).
+ *
+ * The caller's chain holds one *call* row where a stretch of steps used to be,
+ * and the service serves that segment's own chain inside it. Nothing is copied
+ * into the caller's scenario: this is one payload, built at serving time from
+ * the segment as it stands right now.
+ */
+export interface InlinedSegment {
+    id: string;
+    intent: string;
+    paramsObject: ParamsSchema | null;
+    runId: string;
+    stepFrom: number;
+    stepTo: number;
+    /**
+     * The segment's `chain_revision` as served. Sent back on every verdict about
+     * one of its steps, so a failure counted against a chain that has since been
+     * rebuilt is dropped (R-CALL-13, R-REUSE-5).
+     */
+    chainRevision: number;
+    /** May itself contain call rows, to the depth limit. */
+    steps: SerializedScenarioStep[];
+}
+/** Why a call cannot run right now (segmented.md 9.9). */
+export type CallUnusable = "switched_off" | "not_ready" | "missing" | "stale" | "unresolved" | "depth" | "unsupported";
 export interface SerializedScenarioStep {
     stepIndex: number;
-    /** As the recorder wrote it — `mcp__<server>__<tool>` for an MCP call. */
-    toolName: string;
-    /** JS body: `(parameters, intent, respParams) => object`. Required. */
-    toolInputLogic: string;
+    /**
+     * `"segment"` is a call: a sub-task this chain runs by calling a recorded
+     * scenario instead of carrying a copy of its steps (R-CALL-1). Absent means
+     * `"tool"`, which is what every older service sends.
+     */
+    kind?: "tool" | "segment";
+    /** As the recorder wrote it — `mcp__<server>__<tool>` for an MCP call. Null on a call row. */
+    toolName: string | null;
+    /** JS body: `(parameters, intent, respParams) => object`. Null on a call row. */
+    toolInputLogic: string | null;
     /** JS body: `(toolOutput, parameters, intent, respParams) => object`. */
     toolOutputLogic: string | null;
     /** The model's reasoning for this step, used in the steering directive. */
     reasoning: string | null;
+    /**
+     * Execution reports that blamed this step with a `failed` verdict, counted by
+     * the service (fallbk.md D1). A step whose count is above the match's
+     * `fallback.maxStepFailures` is not attempted: the plan hands the turn to the
+     * model in front of it. Absent from an older service, which means never park.
+     */
+    failureCount?: number;
     /**
      * The literal output recorded for this step.
      *
@@ -30,12 +69,50 @@ export interface SerializedScenarioStep {
      * {@link ../replay/source-run.ts} is what actually supplies recorded outputs.
      */
     recordedOutput?: string | null;
+    /** Which segment answers this call right now, if one does. */
+    segmentId?: string | null;
+    /** What the sub-task is, in one line. The ask, frozen with the chain. */
+    callIntent?: string | null;
+    /** How many of the caller's recorded steps the call covers. */
+    callStepCount?: number | null;
+    /** JS body: `(parameters, intent, respParams) => <the segment's parameters>`. */
+    paramMapLogic?: string | null;
+    /** JS body: `(out, parameters, intent, respParams) => <keys the caller reads>`. */
+    resultMapLogic?: string | null;
+    /** The segment, inlined. Absent when the call is `unusable`. */
+    segment?: InlinedSegment | null;
+    /**
+     * Set when the call cannot run: the plan stops in front of it and the agent
+     * does that stretch itself (R-CALL-29, R-FALL-5).
+     */
+    unusable?: CallUnusable;
+    /** How the answer was reached. Read only for the `plan.armed` line (R-CALL-32). */
+    resolution?: {
+        state: string;
+        score?: number;
+        verdict?: string;
+        resolvedAt?: string;
+    } | null;
 }
+/**
+ * What a parameter *is* (segmented.md R-PARAM-1). A `target` is what the task
+ * acts on and changes between requests; a `setting` is a value a user would
+ * never state. A setting that cannot be found takes its recorded sample; a
+ * target that cannot be found stops the plan, because a guessed target is how a
+ * replay does the right work on the wrong thing.
+ *
+ * Absent means target (R-PARAM-3): an older service, or a scenario the service
+ * has not classified yet, sends no kind, and the strict reading is the safe one.
+ */
+export type ParameterKind = "target" | "setting";
 /** The `paramsObject` schema: one entry per parameter the scenario takes. */
 export type ParamsSchema = Record<string, {
     sampleValue: unknown;
     description: string;
+    kind?: ParameterKind;
 }>;
+/** Whether this schema has anything the runner may not guess (R-PARAM-4). */
+export declare function hasTargets(schema: ParamsSchema | null | undefined): boolean;
 /** A `ready` scenario, as serialized by the BaseIn service on a match. */
 export interface SerializedScenario {
     id: string;
@@ -64,7 +141,25 @@ export interface SerializedScenario {
  * How a matched run's execution is classified when it is reported back.
  * Mirrors the service's zod enum on `POST /scenarios/:id/executions`.
  */
-export type ExecutionOutcome = "steered_full" | "diverged" | "not_steered" | "failed";
+export type ExecutionOutcome = "steered_full" | "diverged" | "not_steered" | "failed"
+/**
+ * The plan ran some steps, then handed the rest of the task to the model — a
+ * step broke, or the next one is known to (fallbk.md D5). Books a saving
+ * against the whole turn's cost, which may be negative.
+ */
+ | "fell_back";
+/** Why a plan handed the turn to the model (fallbk.md). */
+export type FallbackKind = 
+/** A step was attempted and broke; the model continues from it. */
+"step_failed"
+/** The plan stopped in front of a step that has failed too often, without trying it. */
+ | "known_bad_step"
+/**
+ * The plan stopped in front of a *call* that cannot run — its segment is
+ * gone, switched off, out of date, or nested too deep (segmented.md
+ * R-CALL-29). Like a known-bad step it counts nothing against any step.
+ */
+ | "unusable_call";
 /**
  * Upgrade order. `not_steered` is the floor — the control group, and the safe
  * answer if a turn dies mid-flight — and each later decision point can only move
@@ -110,6 +205,14 @@ export interface ExecutionStepResult {
     /** Message only — never a tool payload; this is rendered in a web page. */
     error?: string;
     durationMs?: number;
+    /**
+     * The scenario this step belongs to, when it ran inside a called segment: a
+     * failure is counted where a repair would happen (segmented.md R-CALL-13).
+     * Absent on a step of the reported scenario's own chain.
+     */
+    scenarioId?: string;
+    /** That segment's `chain_revision` as served. Absent at depth 0. */
+    chainRevision?: number;
 }
 /** Narrowing guard for a payload that is worth arming a plan from. */
 export declare function isReadyScenario(value: unknown): value is SerializedScenario;

package/dist/replay/types.js

@@ -10,6 +10,12 @@
  * everywhere and nothing is assumed present. A scenario whose `state` is not
  * `"ready"` carries an **empty** `steps` array, by the service's own rule.
  */
+/** Whether this schema has anything the runner may not guess (R-PARAM-4). */
+export function hasTargets(schema) {
+    if (!schema)
+        return false;
+    return Object.values(schema).some((p) => p?.kind !== "setting");
+}
 /**
  * Upgrade order. `not_steered` is the floor — the control group, and the safe
  * answer if a turn dies mid-flight — and each later decision point can only move
@@ -18,8 +24,9 @@
 export const OUTCOME_RANK = {
     not_steered: 0,
     failed: 1,
-    diverged: 2,
-    steered_full: 3,
+    fell_back: 2,
+    diverged: 3,
+    steered_full: 4,
 };
 /** Narrowing guard for a payload that is worth arming a plan from. */
 export function isReadyScenario(value) {
@@ -30,6 +37,29 @@ export function isReadyScenario(value) {
         s.state === "ready" &&
         Array.isArray(s.steps) &&
         s.steps.length > 0 &&
-        s.steps.every((step) => typeof step?.toolName === "string" && typeof step?.toolInputLogic === "string"));
+        s.steps.every(readyStep));
+}
+/**
+ * One step of a ready chain (segmented.md 10.6 step 1).
+ *
+ * A call row carries no tool of its own, so the old test — a string `toolName`
+ * and a string `toolInputLogic` — would decline every chain that contains one.
+ * A call is ready when it says it cannot run (the plan stops in front of it and
+ * the agent takes over there) or when it carries a segment whose own steps pass
+ * this same test. A call row with neither is a payload we cannot run.
+ */
+function readyStep(step) {
+    if (!step)
+        return false;
+    if (step.kind === "segment") {
+        if (step.unusable)
+            return true;
+        const segment = step.segment;
+        return (!!segment &&
+            Array.isArray(segment.steps) &&
+            segment.steps.length > 0 &&
+            segment.steps.every(readyStep));
+    }
+    return typeof step.toolName === "string" && typeof step.toolInputLogic === "string";
 }
 //# sourceMappingURL=types.js.map

package/docs/calculatedReplay.md

@@ -853,7 +853,8 @@ fail because of BaseInstRunner.**
 | Failure | Behaviour |
 |---|---|
 | `getMatch()` slower than the match budget | No plan. Ordinary turn. One `replay.decision` line |
-| No `ANTHROPIC_API_KEY` | Derivation skipped; the scenario's recorded `sampleValue`s are used. `deriveCostUsd: 0` |
+| No `ANTHROPIC_API_KEY` | The service derives instead (segmented.md R-PARAM-5). Signed out as well: settings take their recorded `sampleValue`s, a scenario with a target declines `no_derive_key`, `deriveCostUsd: 0` |
+| The service declines, is slow, or cannot be reached | The same, with its reason carried into the `replay.derived` and `replay.decision` lines. Never a throw |
 | Derivation call fails or times out | Same as above, plus a `replay.derive_failed` line |
 | `toolInputLogic` throws | Divergence (§8) — never a crash |
 | `toolOutputLogic` throws | Retire the plan, abort to an ordinary turn, outcome `failed` |
@@ -982,7 +983,8 @@ export async function deriveParameters(opts: {
   prompt: string;
   intent: string;
   paramsObject: Record<string, { sampleValue: unknown; description: string }> | null;
-  apiKey?: string;                       // ANTHROPIC_API_KEY
+  apiKey?: string;                       // ANTHROPIC_API_KEY — an override
+  service?: { baseUrl: string; token: string; scenarioId: string };  // the default path
   model?: string;                        // default claude-haiku-4-5-20251001
   signal?: AbortSignal;
 }): Promise<{ params: Record<string, unknown>; costUsd: number; derived: boolean }>;
@@ -992,11 +994,16 @@ Behaviour, matching RRepeat's `deriveParametersFromScenarioPayload` exactly so t
 same parameters from the same prompt:
 
 - No `paramsObject` keys → `{}`, `costUsd: 0`.
-- **No `apiKey` → return every key's recorded `sampleValue`**, `costUsd: 0`, `derived: false`. A plain
-  replay of the recorded parameters, free, and the documented default for anyone without a key.
-- Otherwise `POST https://api.anthropic.com/v1/messages` with the same extraction prompt, tolerant
-  JSON extraction (first balanced `{…}`, `undefined` → `null`), and any `null`/missing key filled
-  from its `sampleValue`.
+- **No `apiKey` but a `service` → `POST {baseUrl}/scenarios/{id}/derive`** with the turn (prompt,
+  live call, recent results) and a bearer token, `derived` as the service answered. This is the
+  ordinary path: nearly every session runs inside Claude Code on a subscription and has no key of
+  its own (segmented.md R-PARAM-5). The answer is re-normalised here against this runner's own copy
+  of the schema, so the gate reads a `missing` computed from what will actually run.
+- **Neither → return every key's recorded `sampleValue`**, `costUsd: 0`, `derived: false`. Settings
+  stand on their samples; a scenario with a target declines rather than run on a stale one.
+- With an `apiKey`, `POST https://api.anthropic.com/v1/messages` with the same extraction prompt,
+  tolerant JSON extraction (first balanced `{…}`, `undefined` → `null`), and any `null`/missing
+  **setting** filled from its `sampleValue` — a `null` target is named in `missing` instead.
 
 Keeping this dependency-free is not purity. `bir-proxy` is spawned inside the host's process tree for
 *every* wrapped server; an npm install that pulls a model SDK into that path is a startup-latency and
@@ -1041,7 +1048,8 @@ bir replay --scenario <scnId> --prompt "…" [--dry]     alias; the Tier 2 / deb
 source run's *recorded* outputs — no real tools, no side effects, one Haiku call. Without `--dry`,
 `bir replay` runs the same plan through the same executor against the live proxies. `bir doctor`
 gains a `replay` block: on/off, the effective `BIR_REPLAY_ALLOW_SERVERS` allowlist,
-`BIR_MIN_STEER_SIMILARITY`, and whether an `ANTHROPIC_API_KEY` was found (§13.2, mitigation 3).
+`BIR_MIN_STEER_SIMILARITY`, and who derives — this machine, the service, or nobody, which is the
+state in which a scenario with a target never runs (§13.2, mitigation 3).
 
 ---
 

package/docs/calculatedReplayGuide.md

@@ -34,7 +34,7 @@ end-to-end smoke test.
 | 3 | `SIMILARITY_DETECTION_ENABLED=true` on the server (default) | otherwise no prompt ever matches |
 | 4 | BaseInstRunnerMCP built and installed in your project | `bir status` |
 | 5 | Tier 1 — the hooks wired and `bir-hooks` running | `bir doctor` |
-| 6 | *(replay only)* `ANTHROPIC_API_KEY` in the `bir-hooks` environment | optional — see §5.3 |
+| 6 | *(replay only)* signed in, so the service can read what each request acts on | `bir doctor` — `derive=the service`; an `ANTHROPIC_API_KEY` here replaces it, see §5.3 |
 
 Tier 1 is not optional for replay. A match is a match on **the prompt**, and a standalone proxy never
 sees one (design §1.1). If `bir doctor` says `tier: standalone`, replay cannot arm, and that is the
@@ -229,7 +229,7 @@ bir doctor
 
 ```
 replay          ON      servers=chrome-devtools,fleet-api   minSimilarity=0.92
-                derive=claude-haiku-4-5-20251001 (ANTHROPIC_API_KEY present)
+                derive=the service (no key needed here)
 control         http://127.0.0.1:53411   sess=birsess_…
 wrapped         chrome-devtools ✓ proxy pid 41822   fleet-api ✓ proxy pid 41823
 recording       yes  (https://your-basein-service)
@@ -246,8 +246,8 @@ there is exactly one switch and it cannot get out of step with itself.
 | `BIR_REPLAY` | *(unset)* | `1` enables replay. Nothing below matters until it is set |
 | `BIR_REPLAY_ALLOW_SERVERS` | *(all wrapped)* | Comma-separated server keys eligible for **direct** execution. **Set this** |
 | `BIR_MIN_STEER_SIMILARITY` | `0.92` | Below this a match is detected but not replayed (§8) |
-| `ANTHROPIC_API_KEY` | *(unset)* | Enables parameter derivation. Without it, replay uses the scenario's **recorded sample values** — free, and often still correct |
-| `BIR_DERIVE_MODEL` | `claude-haiku-4-5-20251001` | The derivation model |
+| `ANTHROPIC_API_KEY` | *(unset)* | **Not required.** Derivation — reading what this request acts on — is done by the service on its key for a signed-in runner. Set this to keep the reading on this machine instead: the prompt then never leaves it, and it is one round trip faster. Signed out *and* unset, only a scenario with nothing to work out replays |
+| `BIR_DERIVE_MODEL` | `claude-haiku-4-5-20251001` | The derivation model, when this machine does the reading |
 | `BIR_MATCH_BUDGET_MS` | `2500` | How long the prompt hook waits for a match before giving up |
 | `BIR_DERIVE_BUDGET_MS` | `8000` | How long the first `PreToolUse` waits for parameters |
 | `BIR_REPLAY_BUDGET_MS` | `120000` | Whole-plan ceiling for direct execution |

package/package.json

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