@basein/runner 0.2.1 → 0.2.2

package/README.md

@@ -201,8 +201,8 @@ what to do when they register, so there is one switch and no second copy of it:
 | `BIR_REPLAY=1` | Enable replay. Nothing below matters until it is set. |
 | `BIR_REPLAY_ALLOW_SERVERS` | Server keys eligible for **direct** execution. Unset means every wrapped server; setting it is the recommendation. |
 | `BIR_MIN_STEER_SIMILARITY` | Minimum match similarity to replay (default `0.92`, above the service's own `0.9` detection threshold). |
-| `ANTHROPIC_API_KEY` | Enables parameter derivation. Without it, replay uses the scenario's recorded sample values — free, and often still correct. |
-| `BIR_DERIVE_MODEL` | Derivation model (default `claude-haiku-4-5-20251001`). |
+| `ANTHROPIC_API_KEY` | **Optional.** Working out what a new request is about — which fleet, which file, which date — is done for you by the service on its own key, as long as you are signed in. Set this only to keep that reading on your machine, on your key. Signed out *and* unset, a scenario whose values change between requests is declined rather than replayed on stale ones. |
+| `BIR_DERIVE_MODEL` | Derivation model, when you set a key of your own (default `claude-haiku-4-5-20251001`). |
 | `BIR_MATCH_BUDGET_MS` | How long the prompt hook waits for a match (default `2500`). |
 | `BIR_DERIVE_BUDGET_MS` | How long the first `PreToolUse` waits for parameters (default `8000`). |
 | `BIR_REPLAY_BUDGET_MS` / `BIR_STEP_TIMEOUT_MS` | Whole-plan and per-step ceilings for direct execution (default `120000` / `60000`). |

package/dist/bin/bir-hooks.d.ts

@@ -27,9 +27,11 @@
  *   BIR_REPLAY_ALLOW_SERVERS  comma-separated server keys eligible for *direct*
  *                             execution. Unset means every wrapped server
  *   BIR_MIN_STEER_SIMILARITY  minimum match similarity to replay (default 0.92)
- *   ANTHROPIC_API_KEY         enables parameter derivation. Without it, replay
- *                             uses the scenario's recorded sample values — free,
- *                             and often still correct
+ *   ANTHROPIC_API_KEY         OPTIONAL. Derivation — reading what this turn acts
+ *                             on — is done by the service for a signed-in
+ *                             runner. Set this only to keep that reading on this
+ *                             machine; signed out and unset, a scenario with a
+ *                             target does not run (segmented.md R-PARAM-5)
  *   BIR_DERIVE_MODEL          derivation model (default claude-haiku-4-5-…)
  *   BIR_MATCH_BUDGET_MS       prompt-hook match wait (default 2500)
  *   BIR_DERIVE_BUDGET_MS      first PreToolUse derivation wait (default 8000)

package/dist/bin/bir-hooks.js

@@ -27,9 +27,11 @@
  *   BIR_REPLAY_ALLOW_SERVERS  comma-separated server keys eligible for *direct*
  *                             execution. Unset means every wrapped server
  *   BIR_MIN_STEER_SIMILARITY  minimum match similarity to replay (default 0.92)
- *   ANTHROPIC_API_KEY         enables parameter derivation. Without it, replay
- *                             uses the scenario's recorded sample values — free,
- *                             and often still correct
+ *   ANTHROPIC_API_KEY         OPTIONAL. Derivation — reading what this turn acts
+ *                             on — is done by the service for a signed-in
+ *                             runner. Set this only to keep that reading on this
+ *                             machine; signed out and unset, a scenario with a
+ *                             target does not run (segmented.md R-PARAM-5)
  *   BIR_DERIVE_MODEL          derivation model (default claude-haiku-4-5-…)
  *   BIR_MATCH_BUDGET_MS       prompt-hook match wait (default 2500)
  *   BIR_DERIVE_BUDGET_MS      first PreToolUse derivation wait (default 8000)
@@ -182,7 +184,13 @@ function buildReplayOptions(auth) {
         logLine("replay.enabled", {
             minSimilarity: opts.minSimilarity,
             allowServers: allowServers ? [...allowServers].join(",") : "(all wrapped)",
-            derive: process.env.ANTHROPIC_API_KEY ? "anthropic" : "recorded sample values",
+            // Who reads what this turn acts on (segmented.md R-PARAM-5). Named at
+            // startup because the third state is a replay that silently never runs.
+            derive: process.env.ANTHROPIC_API_KEY
+                ? "this machine (ANTHROPIC_API_KEY)"
+                : auth.session && auth.baseUrl
+                    ? "the service"
+                    : "recorded sample values — sign in, or a scenario with a target will not run",
             intentMatch: opts.intentMatch?.enabled ? "on" : "off",
             why: "matched prompts will run their calculated scenario — steered steps are auto-approved",
         });

package/dist/bin/bir.js

@@ -600,7 +600,20 @@ async function doctor(args) {
     if (replay?.enabled) {
         out(`Replay            : ON  servers=${replay.allowServers?.join(",") || "(all wrapped)"}  ` +
             `minSimilarity=${replay.minSimilarity ?? "?"}`);
-        out(`                    derive=${replay.deriveKey ? "anthropic" : "recorded sample values (no ANTHROPIC_API_KEY)"}`);
+        // An older control server sends only `deriveKey`; read it as the two states
+        // it could describe then.
+        const via = replay.deriveVia ?? (replay.deriveKey ? "key" : "samples");
+        const derive = via === "key"
+            ? "this machine (ANTHROPIC_API_KEY)"
+            : via === "service"
+                ? "the service (no key needed here)"
+                : "recorded sample values — scenarios with a target will NOT run";
+        out(`                    derive=${derive}`);
+        if (via === "samples") {
+            notes.push("nothing can read what this turn acts on: sign in with `bir login` so the " +
+                "service derives, or set ANTHROPIC_API_KEY to derive here. Until then a " +
+                "matched scenario with a target is declined and the agent does the task");
+        }
         const idle = wantWrapped.filter((n) => !(replay.pollingProxies ?? []).includes(n));
         if (idle.length > 0) {
             notes.push(`these proxies are not polling for replay work: ${idle.join(", ")} — ` +

package/dist/control/server.js

@@ -212,6 +212,15 @@ export class ControlServer {
                 minSimilarity: this.opts.replay?.minSimilarity ?? null,
                 allowServers: this.opts.replay?.allowServers ? [...this.opts.replay.allowServers] : null,
                 deriveKey: Boolean(this.opts.replay?.apiKey ?? process.env.ANTHROPIC_API_KEY),
+                // Who reads the turn for its parameters (segmented.md R-PARAM-5). The
+                // ordinary answer is `service`; a key here is an override; `samples`
+                // means no scenario with a target can run, which is the one state an
+                // operator must be able to see without reading a log.
+                deriveVia: (this.opts.replay?.apiKey ?? process.env.ANTHROPIC_API_KEY)
+                    ? "key"
+                    : this.opts.replay?.authUrl && this.opts.replay?.authToken
+                        ? "service"
+                        : "samples",
                 pollingProxies: this.replay.work.pollingServers(),
             },
             lossy: this.lossy,

package/dist/replay/controller.d.ts

@@ -54,7 +54,10 @@ export interface ReplayOptions {
     /** `BIR_REPLAY_ALLOW_SERVERS`; undefined means every wrapped server. */
     allowServers?: ReadonlySet<string>;
     budgets?: Partial<ReplayBudgets>;
-    /** For the lazy source-run fetch and nothing else. */
+    /**
+     * The service: the lazy source-run fetch, and the parameter derivation this
+     * runner no longer needs a key of its own for (segmented.md R-PARAM-5).
+     */
     authUrl?: string;
     authToken?: () => string;
     /** Injected by tests. */
@@ -378,6 +381,17 @@ export declare class ReplayController {
      * directive the moment the match lands; the first `PreToolUse` — or
      * `/scenario/run`, which has no hook timeout at all — is where the wait lands.
      */
+    /**
+     * Where to ask the service to read this turn (segmented.md R-PARAM-5).
+     *
+     * Undefined when there is nobody to ask — an unauthenticated session, or one
+     * whose token has gone. `derive` then falls back to the recorded samples, and
+     * a scenario with a target declines, exactly as a keyless runner always did.
+     *
+     * The token is read here rather than captured, because the recorder refreshes
+     * it as a session outlives it.
+     */
+    private deriveService;
     private startDerivation;
     /**
      * Divergence (§8). Execute the remaining steps for real, then deliver.

package/dist/replay/controller.js

@@ -246,10 +246,13 @@ export class ReplayController {
                 return decline(`target ${first ?? "(unknown)"} not found — ${errText(err)}`, "missing_target");
             }
             if (!result.derived) {
-                // No key: settings can still take their recorded values, but a target
-                // is a guess nobody is allowed to make (R-PARAM-5).
+                // 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(`no_derive_key: target ${first ?? "(unknown)"}`, "no_derive_key");
+                return decline(`${result.reason ?? "no_derive_key"}: target ${first ?? "(unknown)"}`, "no_derive_key");
             }
             if (result.missing.length > 0) {
                 return decline(`target ${result.missing[0]} not found`, "missing_target");
@@ -886,6 +889,22 @@ export class ReplayController {
      * directive the moment the match lands; the first `PreToolUse` — or
      * `/scenario/run`, which has no hook timeout at all — is where the wait lands.
      */
+    /**
+     * Where to ask the service to read this turn (segmented.md R-PARAM-5).
+     *
+     * Undefined when there is nobody to ask — an unauthenticated session, or one
+     * whose token has gone. `derive` then falls back to the recorded samples, and
+     * a scenario with a target declines, exactly as a keyless runner always did.
+     *
+     * The token is read here rather than captured, because the recorder refreshes
+     * it as a session outlives it.
+     */
+    deriveService(scenarioId) {
+        const token = this.opts.authToken?.();
+        if (!this.opts.authUrl || !token)
+            return undefined;
+        return { baseUrl: this.opts.authUrl, token, scenarioId };
+    }
     startDerivation(scenario, prompt, state, ctx = {}) {
         const derive = this.opts.deriveImpl ?? deriveParameters;
         return derive({
@@ -893,6 +912,9 @@ export class ReplayController {
             intent: scenario.intent ?? "",
             paramsObject: scenario.paramsObject,
             apiKey: this.opts.apiKey ?? process.env.ANTHROPIC_API_KEY,
+            // Where to ask when there is no key here, which is the ordinary case
+            // (segmented.md R-PARAM-5).
+            service: this.deriveService(scenario.id),
             fetchImpl: this.opts.fetchImpl,
             liveCall: ctx.liveCall,
             recentResults: ctx.recentResults,
@@ -903,7 +925,12 @@ export class ReplayController {
                 scenario: scenario.id,
                 params: Object.keys(r.params).length,
                 costUsd: r.costUsd.toFixed(4),
-                source: r.derived ? "prompt" : "recorded samples",
+                source: r.derived
+                    ? r.via === "service"
+                        ? "the service"
+                        : "prompt"
+                    : "recorded samples",
+                why: r.derived ? undefined : r.reason,
                 missing: r.missing.length > 0 ? r.missing.join(",") : undefined,
                 sampled: r.sampled.length > 0 ? r.sampled.join(",") : undefined,
             });

package/dist/replay/derive.d.ts

@@ -10,11 +10,20 @@
  * most sessions never arm. This is ~40 lines of `fetch` and it keeps the package
  * at zero runtime dependencies.
  *
- * NO KEY IS A SUPPORTED CONFIGURATION. Without `ANTHROPIC_API_KEY` the extraction
- * is skipped entirely and every parameter takes the value it had in the recorded
- * run — a plain replay of the recorded parameters, at zero cost. For a scenario
- * whose parameters rarely change that is a complete, free replay; for one that
- * keys off the prompt, it is why you want the key.
+ * NO KEY IS THE ORDINARY CONFIGURATION (segmented.md R-PARAM-5). Without
+ * `ANTHROPIC_API_KEY` the reading is done by the **service**, over one authorized
+ * POST to `/scenarios/:id/derive`, under the key it already uses to calculate
+ * scenarios and to ask its live question. That is the path nearly every session
+ * takes: the people this runs for are inside Claude Code on a subscription and
+ * have no API key to give it.
+ *
+ * A key here is an override, not a requirement. It keeps the reading on this
+ * machine — the prompt never reaches the service — which is what an in-house
+ * deployment wants, and it is one round trip faster.
+ *
+ * NEITHER is still supported and still means the same thing it always did:
+ * settings take their recorded samples and a scenario with a target declines,
+ * because a target is never guessed.
  *
  * The prompt and the parsing tolerances mirror RRepeat's
  * `deriveParametersFromScenarioPayload` exactly, so the two produce the same
@@ -34,12 +43,27 @@ export interface DeriveContext {
     liveCall?: LiveCall;
     recentResults?: string[];
 }
+/**
+ * The service, which derives when this runner has no key of its own
+ * (R-PARAM-5). All three fields or none: a session that is not signed in has
+ * nowhere to ask.
+ */
+export interface DeriveService {
+    /** `BIR_AUTH_URL`, the same base the recorder reports to. */
+    baseUrl: string;
+    /** A live access token. Read late — the recorder refreshes it mid-session. */
+    token: string;
+    /** Whose parameters to read. The service takes the schema from its own row. */
+    scenarioId: string;
+}
 export interface DeriveOptions extends DeriveContext {
     prompt: string;
     intent: string;
     paramsObject: ParamsSchema | null;
-    /** Absent → sample values, at zero cost. */
+    /** An override that keeps the reading on this machine. Absent → the service. */
     apiKey?: string;
+    /** Used when there is no `apiKey`. Absent too → recorded samples. */
+    service?: DeriveService;
     model?: string;
     signal?: AbortSignal;
     /** Injected by tests. Defaults to global `fetch`. */
@@ -50,6 +74,10 @@ export interface DeriveResult {
     costUsd: number;
     /** False when the values came from the recorded samples rather than the model. */
     derived: boolean;
+    /** Who read the turn. For the audit line, and for nothing else. */
+    via?: "key" | "service" | "samples";
+    /** Why nothing was derived, when the service said. */
+    reason?: string;
     model?: string;
     inputTokens?: number;
     outputTokens?: number;

package/dist/replay/derive.js

@@ -10,11 +10,20 @@
  * most sessions never arm. This is ~40 lines of `fetch` and it keeps the package
  * at zero runtime dependencies.
  *
- * NO KEY IS A SUPPORTED CONFIGURATION. Without `ANTHROPIC_API_KEY` the extraction
- * is skipped entirely and every parameter takes the value it had in the recorded
- * run — a plain replay of the recorded parameters, at zero cost. For a scenario
- * whose parameters rarely change that is a complete, free replay; for one that
- * keys off the prompt, it is why you want the key.
+ * NO KEY IS THE ORDINARY CONFIGURATION (segmented.md R-PARAM-5). Without
+ * `ANTHROPIC_API_KEY` the reading is done by the **service**, over one authorized
+ * POST to `/scenarios/:id/derive`, under the key it already uses to calculate
+ * scenarios and to ask its live question. That is the path nearly every session
+ * takes: the people this runs for are inside Claude Code on a subscription and
+ * have no API key to give it.
+ *
+ * A key here is an override, not a requirement. It keeps the reading on this
+ * machine — the prompt never reaches the service — which is what an in-house
+ * deployment wants, and it is one round trip faster.
+ *
+ * NEITHER is still supported and still means the same thing it always did:
+ * settings take their recorded samples and a scenario with a target declines,
+ * because a target is never guessed.
  *
  * The prompt and the parsing tolerances mirror RRepeat's
  * `deriveParametersFromScenarioPayload` exactly, so the two produce the same
@@ -120,14 +129,20 @@ export async function deriveParameters(opts) {
     if (keys.length === 0)
         return { params: {}, costUsd: 0, derived: false, missing: [], sampled: [] };
     const apiKey = opts.apiKey ?? process.env.ANTHROPIC_API_KEY;
-    // No key is a supported configuration, and `derived: false` is how the caller
-    // tells it apart from a real extraction: it declines any scenario that has a
-    // target and arms an all-settings one on its recorded values (R-PARAM-5).
+    // No key of our own is the ordinary case: the service reads the turn instead,
+    // under the key it already spends on this account (R-PARAM-5).
+    if (!apiKey && opts.service)
+        return deriveViaService(opts, opts.service, schema, keys);
+    // No key and nowhere to ask — an unauthenticated session, or a deployment that
+    // turned service derivation off. `derived: false` is how the caller tells this
+    // apart from a real extraction: it declines any scenario that has a target and
+    // arms an all-settings one on its recorded values.
     if (!apiKey)
         return {
             params: sampleValues(schema),
             costUsd: 0,
             derived: false,
+            via: "samples",
             missing: [],
             sampled: keys,
         };
@@ -213,6 +228,7 @@ export async function deriveParameters(opts) {
         params: parsed,
         costUsd,
         derived: true,
+        via: "key",
         model,
         inputTokens,
         outputTokens,
@@ -220,4 +236,88 @@ export async function deriveParameters(opts) {
         sampled,
     };
 }
+/**
+ * Ask the service to read the turn (segmented.md R-PARAM-5).
+ *
+ * One authorized POST. The body carries the turn — the prompt, and whatever else
+ * this turn has said about its target — and never the schema: the service reads
+ * that from the scenario row it owns, so a stale copy here cannot change what is
+ * asked for.
+ *
+ * Never throws, and never worse than no key. A service that is off, out of
+ * budget, too slow or simply down answers `derived: false`, and so does every
+ * failure on this side, which is precisely the keyless behaviour this replaced:
+ * settings stand on their samples, and a target does not run.
+ */
+async function deriveViaService(opts, service, schema, keys) {
+    const samples = (reason) => ({
+        params: sampleValues(schema),
+        costUsd: 0,
+        derived: false,
+        via: "service",
+        reason,
+        missing: [],
+        sampled: keys,
+    });
+    const doFetch = opts.fetchImpl ?? fetch;
+    const url = `${service.baseUrl.replace(/\/+$/, "")}/scenarios/${service.scenarioId}/derive`;
+    let body;
+    try {
+        const res = await doFetch(url, {
+            method: "POST",
+            headers: {
+                "content-type": "application/json",
+                authorization: `Bearer ${service.token}`,
+            },
+            body: JSON.stringify({
+                prompt: opts.prompt,
+                liveCall: opts.liveCall,
+                recentResults: opts.recentResults,
+            }),
+            signal: opts.signal,
+        });
+        if (!res.ok)
+            return samples(`service HTTP ${res.status}`);
+        body = (await res.json());
+    }
+    catch (err) {
+        return samples(err instanceof Error ? err.message : String(err));
+    }
+    if (!body || typeof body !== "object")
+        return samples("service sent no answer");
+    if (body.derived !== true)
+        return samples(`service: ${body.reason ?? "declined"}`);
+    // Normalised again on this side, over *our* copy of the schema. The service
+    // answers in the same shape, but the plan runs on these values and the gate
+    // reads this `missing`: an older or newer service must not be able to leave a
+    // target unaccounted for.
+    const params = { ...(body.params ?? {}) };
+    const missing = [];
+    const sampled = [];
+    for (const key of keys) {
+        const value = params[key];
+        if (value !== null && value !== undefined)
+            continue;
+        if (isTarget(schema, key)) {
+            params[key] = null;
+            missing.push(key);
+        }
+        else {
+            params[key] = schema[key].sampleValue;
+            sampled.push(key);
+        }
+    }
+    return {
+        params,
+        // What the service spent on this turn, reported back on the execution so a
+        // replay's cost stays the whole truth about it (R-MONEY-2). The account is
+        // not billed for it; the service books it on its own ledger as well.
+        costUsd: typeof body.costUsd === "number" ? body.costUsd : 0,
+        derived: true,
+        via: "service",
+        model: body.model,
+        missing,
+        sampled,
+    };
+}
 //# sourceMappingURL=derive.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.1",
+  "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",