@basein/runner 0.2.0 → 0.2.1

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/package.json

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