@basein/runner 0.2.2 → 0.2.3

package/dist/bin/bir.js

@@ -576,6 +576,17 @@ async function doctor(args) {
         problems.push(`BIR_AUTH_URL in this shell (${shellAuthUrl}) is not a BaseIn service: ${shellAuthProblem}. ` +
             `\`bir login\` and \`bir scenario\` here will fail — ${AUTH_URL_HINT}`);
     }
+    // THE SCENARIO SERVER IS ON THE CRITICAL PATH OF THE FIRST TURN. A plan armed
+    // at `UserPromptSubmit` is delivered through `mcp__bir__run_scenario`, so a
+    // `bir` entry that starts with `npx` has to resolve and unpack the package
+    // before the tool exists at all — measured at ~13s, against a first tool call
+    // ~6s in. The turn does not fail; it just quietly runs the ordinary way, which
+    // is the failure this whole command exists to make visible.
+    const scenarioEntry = entries.find((e) => e.name === SCENARIO_SERVER_KEY);
+    if (scenarioEntry && !isRemote(scenarioEntry.config) && scenarioEntry.config.command === "npx") {
+        notes.push("the bir scenario server starts via npx, which can take longer than the first tool call " +
+            "of a turn — reinstall with `bir install --replay --global` to pin it to the installed copy");
+    }
     const sidecar = readSidecar();
     if (sidecar.controlPort && discovery && !discovery.url.endsWith(`:${sidecar.controlPort}`)) {
         problems.push(`hooks were installed for port ${sidecar.controlPort} but the control server is on ${discovery.url}`);
@@ -796,6 +807,14 @@ async function replayCommand(args) {
         }
         const r = body;
         out(`params      ${JSON.stringify(r.params ?? {})}`);
+        // The difference between "this scenario works" and "this scenario works on
+        // last week's values". A dry replay fills an unnamed target from the
+        // recording; a real turn never does, so without this line a green trace here
+        // is no evidence at all that a session would steer.
+        if (r.targetsFromSamples?.length) {
+            out(`            ↑ not named by the prompt: ${r.targetsFromSamples.join(", ")}`);
+            out("              (a live turn finds these in an earlier step, or does not run)");
+        }
         (r.steps ?? []).forEach((s, i) => {
             out(`step ${i}      ${s.toolName}  ${JSON.stringify(s.input)}`);
             const emitted = Object.keys(s.emitted ?? {});

package/dist/record/recorder.d.ts

@@ -263,6 +263,17 @@ export interface ExecutionReport {
      * two baselines of one turn. The segments' own rows are untouched.
      */
     sharedWith?: string[];
+    /**
+     * Which gate of the ladder declined, on a `not_steered` report.
+     *
+     * The one thing the recording page could never learn. "Replay on, scenario
+     * ready, prompt matched, nothing steered" has exactly one explanation and it
+     * used to live only in a stderr line on the machine that decided it — so the
+     * owner of a scenario that never runs had nothing to look at. It travels as
+     * the gate's own code rather than the sentence beside it: the prose is for a
+     * person reading the audit log, this is for the console.
+     */
+    declined?: string;
 }
 /** Optional capability: reporting needs a service, and a NullRecorder has none. */
 export interface ScenarioReporter {

package/dist/record/remote-recorder.js

@@ -212,6 +212,9 @@ export class RemoteRecorder {
                 fallbackKind: report.fallbackKind,
                 baselineEligible: report.baselineEligible,
                 sharedWith: report.sharedWith,
+                // Why nothing ran, when nothing ran. Additive: an older service drops
+                // the field and books the cost exactly as it always did.
+                declined: report.declined,
             });
             const r = (body ?? {});
             const failed = report.steps?.filter((s) => s.status === "failed").length ?? 0;
@@ -228,6 +231,7 @@ export class RemoteRecorder {
                 stepsFailed: failed || undefined,
                 baselineEligible: report.baselineEligible === false ? false : undefined,
                 sharedWith: report.sharedWith?.length,
+                declined: report.declined,
             });
         });
     }

package/dist/replay/controller.js

@@ -25,6 +25,7 @@ import { ScenarioReplayPlan } from "./plan.js";
 import { PRICING_VERSION } from "./pricing.js";
 import { SourceRunOutputs } from "./source-run.js";
 import { clampToFrameStart, flattenChain, } from "./flatten.js";
+import { blockingTargets } from "./targets.js";
 import { toolResultError } from "./tool-error.js";
 import { OUTCOME_RANK, hasTargets, isReadyScenario, } from "./types.js";
 /** The first-party tool a `direct` plan is delivered through (§6.3). */
@@ -233,29 +234,60 @@ export class ReplayController {
         // because it is the only one that spends a model call and waits. A scenario
         // whose parameters are all settings arms at once, as before: there is
         // nothing the turn has to supply.
+        //
+        // A target the turn did not name stops the plan only when *this* plan could
+        // act on its recorded value; a target the chain discovers for itself does
+        // not ({@link ./targets.ts}). The unnamed value stays null either way, so
+        // nothing here ever runs on last week's.
         if (hasTargets(scenario.paramsObject)) {
+            // Of the targets this answer left unnamed, the ones this plan could act
+            // on the recorded value of. Empty means the chain finds them for itself.
+            const blocking = (missing) => blockingTargets(missing, scenario.paramsObject, planned);
             let result;
             try {
                 result = await this.withBudget(derivation, this.budgets.deriveMs, "derivation");
             }
             catch (err) {
-                // Out of budget, or the call threw. Either way the turn has not said
-                // what this task is to act on, and running it would act on something
-                // else (R-PARAM-3).
-                const first = firstTargetKey(scenario.paramsObject);
-                return decline(`target ${first ?? "(unknown)"} not found — ${errText(err)}`, "missing_target");
+                // Out of budget, or the call threw. The turn has not said what this task
+                // is to act on, so every target is unnamed (R-PARAM-3).
+                const blocked = blocking(targetKeys(scenario.paramsObject));
+                if (blocked.length > 0) {
+                    return decline(`target ${blocked[0]} not found — ${errText(err)}`, "missing_target");
+                }
+                logLine("replay.targets_unread", {
+                    scenario: scenario.id,
+                    why: "the derivation did not answer, and this chain takes no target from the caller",
+                    error: errText(err),
+                });
             }
-            if (!result.derived) {
+            if (result && !result.derived) {
                 // Nobody read the turn — no key here and no service to ask, or the
                 // service declined. Settings can still take their recorded values, but a
                 // target is a guess nobody is allowed to make (R-PARAM-5). The reason
                 // travels into the line, because "it did not run" without one is how
                 // this stayed invisible before.
-                const first = firstTargetKey(scenario.paramsObject);
-                return decline(`${result.reason ?? "no_derive_key"}: target ${first ?? "(unknown)"}`, "no_derive_key");
+                //
+                // Every target is judged, not `missing`: an answer that derived nothing
+                // carries the recorded sample for *all* of them, so a chain that reads
+                // one would run on last week's value rather than on nothing.
+                const blocked = blocking(targetKeys(scenario.paramsObject));
+                if (blocked.length > 0) {
+                    return decline(`${result.reason ?? "no_derive_key"}: target ${blocked[0]}`, "no_derive_key");
+                }
             }
-            if (result.missing.length > 0) {
-                return decline(`target ${result.missing[0]} not found`, "missing_target");
+            else if (result && result.missing.length > 0) {
+                const blocked = blocking(result.missing);
+                if (blocked.length > 0) {
+                    return decline(`target ${blocked[0]} not found`, "missing_target");
+                }
+                // Worth a line of its own: this is the difference between a scenario
+                // that never runs and one that does, and it is the first thing to look
+                // at when a replay acts on the wrong thing.
+                logLine("replay.targets_found_by_chain", {
+                    scenario: scenario.id,
+                    unnamed: result.missing.join(","),
+                    why: "the chain computes these from its own steps; none is read from the caller",
+                });
             }
         }
         // A plan armed by intent runs inside a task the agent is already doing, so
@@ -681,10 +713,14 @@ export class ReplayController {
         const total = state.deriveCostUsd + d.sessionCostUsd + state.fallbackCostUsd;
         const steps = this.stepResultsOf(state);
         const isBaseline = state.outcome === "not_steered" || state.outcome === "failed";
-        // A costless decline is noise on both sides — *unless* a step actually broke,
-        // which is the one thing the recording page cannot learn any other way. The
-        // service accepts a costless report that says why (its errorshandling.md).
-        if (isBaseline && total <= 0 && !steps?.some((s) => s.status === "failed")) {
+        // A costless decline is noise on both sides — *unless* it says something the
+        // recording page cannot learn any other way: a step that actually broke, or
+        // the gate that declined. The service accepts a costless report that carries
+        // either (its errorshandling.md).
+        if (isBaseline &&
+            total <= 0 &&
+            !state.declined &&
+            !steps?.some((s) => s.status === "failed")) {
             return undefined;
         }
         const blame = this.blameStep(steps);
@@ -709,6 +745,10 @@ export class ReplayController {
             errorStage: blame?.stage,
             errorStepIndex: blame?.stepIndex,
             errorToolName: blame?.toolName,
+            // Which gate said no. Only ever set on a decline, and the decline is
+            // always `not_steered`, so a steered report carries it byte-identically
+            // to before.
+            declined: state.declined,
             // Where the plan handed the task to the model (fallbk.md). Only on
             // `fell_back`: a hand-over before any step ran is `failed`, and a parked
             // step found after a divergence is still a divergence.
@@ -1292,11 +1332,11 @@ export class ReplayController {
         });
     }
 }
-/** The first target of a schema, for the sentence a decline logs. */
-function firstTargetKey(schema) {
+/** Every target of a schema. A parameter with no kind is one (R-PARAM-3). */
+function targetKeys(schema) {
     if (!schema)
-        return undefined;
-    return Object.keys(schema).find((k) => schema[k]?.kind !== "setting");
+        return [];
+    return Object.keys(schema).filter((k) => schema[k]?.kind !== "setting");
 }
 /**
  * Position of the first step whose failure count is above `maxStepFailures`

package/dist/replay/targets.d.ts

@@ -0,0 +1,52 @@
+/**
+ * Which missing targets actually stop a plan (segmented.md R-PARAM-3).
+ *
+ * The rule a target exists for is "never do the right work on the wrong thing":
+ * a value the turn did not name must never be filled in from the recording. The
+ * gate that enforces it used to read `missing.length > 0` and decline, which is
+ * the same thing only when every target is something the chain *takes from the
+ * caller*.
+ *
+ * It often is not. An analysis routinely lists a value that a later step
+ * computes from an earlier step's output and keeps the caller's copy as a bare
+ * fallback:
+ *
+ *     step 0  return { fleet: parameters.fleet };
+ *     step 1  return { id: (respParams.rankedDeviceIds || [])[0] ?? parameters.id };
+ *
+ * `id` is classified a target — it is what the second call acts on and it does
+ * change between requests — but no prompt ever names it, because the chain
+ * discovers it. Declining on it meant a scenario that matched, was ready, was
+ * enabled and would have run perfectly never ran at all, on every turn, with the
+ * reason only in a stderr line.
+ *
+ * So the question is not "did the turn name every target" but the narrower one
+ * the rule actually cares about: **could this plan act on the recorded value of
+ * a target the turn did not name?** It could, in exactly two ways:
+ *
+ *  1. some step reads `parameters.<key>` outright, rather than as the fallback
+ *     of a value computed at run time; or
+ *  2. some step's logic carries the recorded sample as a literal, so the value
+ *     is baked into the chain whether or not anybody reads the parameter.
+ *
+ * Neither true means the recorded value cannot reach a tool. The missing target
+ * stays `null` all the way through — {@link ./derive.ts} sets it, `paramsLogic`
+ * copies it, the `??` passes over it — so a chain that can compute the value
+ * runs on this turn's value, and one that cannot calls a tool with `null` and
+ * falls back to the model. What never happens, either way, is last week's fleet.
+ *
+ * Only frame 0 is judged here. A called segment runs on the parameters its
+ * call's `paramMapLogic` builds, not on these, so that body is scanned as a
+ * consumer and the segment's own steps are not (R-CALL-29).
+ */
+import type { FlatEntry } from "./flatten.js";
+import type { ParamsSchema } from "./types.js";
+/**
+ * The subset of `missing` this plan must decline on.
+ *
+ * Empty means every target the turn left unnamed is one the chain finds for
+ * itself. `missing` is returned unchanged whenever the schema or the plan is
+ * missing, so a caller that knows less than this one is never made to guess.
+ */
+export declare function blockingTargets(missing: readonly string[], schema: ParamsSchema | null | undefined, planned: readonly FlatEntry[]): string[];
+//# sourceMappingURL=targets.d.ts.map

package/dist/replay/targets.js

@@ -0,0 +1,133 @@
+/**
+ * Which missing targets actually stop a plan (segmented.md R-PARAM-3).
+ *
+ * The rule a target exists for is "never do the right work on the wrong thing":
+ * a value the turn did not name must never be filled in from the recording. The
+ * gate that enforces it used to read `missing.length > 0` and decline, which is
+ * the same thing only when every target is something the chain *takes from the
+ * caller*.
+ *
+ * It often is not. An analysis routinely lists a value that a later step
+ * computes from an earlier step's output and keeps the caller's copy as a bare
+ * fallback:
+ *
+ *     step 0  return { fleet: parameters.fleet };
+ *     step 1  return { id: (respParams.rankedDeviceIds || [])[0] ?? parameters.id };
+ *
+ * `id` is classified a target — it is what the second call acts on and it does
+ * change between requests — but no prompt ever names it, because the chain
+ * discovers it. Declining on it meant a scenario that matched, was ready, was
+ * enabled and would have run perfectly never ran at all, on every turn, with the
+ * reason only in a stderr line.
+ *
+ * So the question is not "did the turn name every target" but the narrower one
+ * the rule actually cares about: **could this plan act on the recorded value of
+ * a target the turn did not name?** It could, in exactly two ways:
+ *
+ *  1. some step reads `parameters.<key>` outright, rather than as the fallback
+ *     of a value computed at run time; or
+ *  2. some step's logic carries the recorded sample as a literal, so the value
+ *     is baked into the chain whether or not anybody reads the parameter.
+ *
+ * Neither true means the recorded value cannot reach a tool. The missing target
+ * stays `null` all the way through — {@link ./derive.ts} sets it, `paramsLogic`
+ * copies it, the `??` passes over it — so a chain that can compute the value
+ * runs on this turn's value, and one that cannot calls a tool with `null` and
+ * falls back to the model. What never happens, either way, is last week's fleet.
+ *
+ * Only frame 0 is judged here. A called segment runs on the parameters its
+ * call's `paramMapLogic` builds, not on these, so that body is scanned as a
+ * consumer and the segment's own steps are not (R-CALL-29).
+ */
+/**
+ * The subset of `missing` this plan must decline on.
+ *
+ * Empty means every target the turn left unnamed is one the chain finds for
+ * itself. `missing` is returned unchanged whenever the schema or the plan is
+ * missing, so a caller that knows less than this one is never made to guess.
+ */
+export function blockingTargets(missing, schema, planned) {
+    if (missing.length === 0)
+        return [];
+    if (!schema || planned.length === 0)
+        return [...missing];
+    const bodies = callerBodies(planned);
+    // Nothing to read the parameters: a plan with no logic at all cannot act on
+    // anything, but it is also not a shape worth reasoning about — keep it strict.
+    if (bodies.length === 0)
+        return [...missing];
+    return missing.filter((key) => bodies.some((body) => readsOutright(body, key) || carriesLiteral(body, schema[key]?.sampleValue)));
+}
+/**
+ * Every logic body that runs with the caller's own `parameters`.
+ *
+ * Both of a step's bodies, because `toolOutputLogic` is handed `parameters`
+ * too and a value baked in there travels just as far. Plus the `paramMapLogic`
+ * of each segment called directly from frame 0: it reads the caller's
+ * parameters to build the segment's.
+ */
+function callerBodies(planned) {
+    const bodies = [];
+    const seenFrames = new Set();
+    for (const entry of planned) {
+        if (entry.depth === 0) {
+            if (entry.step.toolInputLogic)
+                bodies.push(entry.step.toolInputLogic);
+            if (entry.step.toolOutputLogic)
+                bodies.push(entry.step.toolOutputLogic);
+            continue;
+        }
+        // The frame's own mapping, once, and only when its caller is frame 0.
+        const frame = entry.frame;
+        if (frame.depth !== 1 || seenFrames.has(frame.id))
+            continue;
+        seenFrames.add(frame.id);
+        if (frame.paramMapLogic)
+            bodies.push(frame.paramMapLogic);
+    }
+    return bodies;
+}
+/** `parameters.key`, `parameters["key"]`, `parameters['key']` — all three forms. */
+function referencePattern(key) {
+    const k = escapeRegExp(key);
+    return new RegExp(`parameters\\s*(?:\\.\\s*${k}\\b|\\[\\s*["']${k}["']\\s*\\])`, "g");
+}
+/**
+ * Whether `body` reads `key` other than as a fallback.
+ *
+ * A reference is a fallback when what stands immediately before it is `??` or
+ * `||` — the shape an analysis writes when the chain computes the value and
+ * keeps the caller's as a last resort. Every other reference is a read: the
+ * step wants the caller's value and nothing else will do.
+ */
+function readsOutright(body, key) {
+    const pattern = referencePattern(key);
+    for (let m = pattern.exec(body); m; m = pattern.exec(body)) {
+        const before = body.slice(0, m.index).trimEnd();
+        if (!before.endsWith("??") && !before.endsWith("||"))
+            return true;
+    }
+    return false;
+}
+/**
+ * Whether `body` carries the recorded sample as a literal.
+ *
+ * This is the case the parameter reference cannot see: `return { id: 'dev_4411' }`
+ * acts on last week's device without mentioning `parameters` at all. Read
+ * generously — a sample too short to search for (`1`, `on`) counts as carried,
+ * because a false "this plan is safe" is the one answer this file must not give.
+ */
+function carriesLiteral(body, sample) {
+    if (sample === null || sample === undefined)
+        return false;
+    const text = typeof sample === "string" ? sample : JSON.stringify(sample);
+    if (typeof text !== "string" || text.length === 0)
+        return false;
+    if (text.length < 3)
+        return true;
+    return body.includes(text);
+}
+function escapeRegExp(text) {
+    return text.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+}
+//# sourceMappingURL=targets.js.map

package/package.json

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