@basein/runner 0.2.0 → 0.2.2

package/README.md

@@ -61,6 +61,8 @@ the browser — the OAuth device grant, the same shape `gh auth login` uses. It
 never handles a password, so it works for accounts that only sign in with
 Google, and the link can be opened on any device, which is what makes it usable
 on a headless runner. `--no-browser` prints the link without opening one;
+`--token <value>` redeems a one-time setup token made on the console's *Set up
+the runner* page, with no browser step at all (service 2026-09 or newer);
 `--password` is the deprecated email-and-password prompt, removed next release.
 
 Check it:
@@ -199,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/auth/client.d.ts

@@ -200,6 +200,18 @@ export interface DeviceLoginOptions {
  * that a script may read, and the code block is not it.
  */
 export declare function deviceLogin(authUrl: string, opts?: DeviceLoginOptions): Promise<AuthSession | undefined>;
+/**
+ * Sign in with a setup token and cache the session.
+ *
+ * A setup token is a device code the console minted already approved for the
+ * person who was signed in there (`POST /auth/device/setup-token`), so this is
+ * the browser flow with the waiting removed: one redemption, no polling. It is
+ * the secret that opens a session, so it is never printed or logged here, for
+ * the same reason a device code never is.
+ */
+export declare function tokenLogin(authUrl: string, token: string, opts?: {
+    fetchImpl?: typeof fetch;
+}): Promise<AuthSession>;
 /**
  * Sign in with an email and a password.
  *

package/dist/auth/client.js

@@ -517,6 +517,47 @@ export async function deviceLogin(authUrl, opts = {}) {
     saveCredentials(session);
     return session;
 }
+/**
+ * Sign in with a setup token and cache the session.
+ *
+ * A setup token is a device code the console minted already approved for the
+ * person who was signed in there (`POST /auth/device/setup-token`), so this is
+ * the browser flow with the waiting removed: one redemption, no polling. It is
+ * the secret that opens a session, so it is never printed or logged here, for
+ * the same reason a device code never is.
+ */
+export async function tokenLogin(authUrl, token, opts = {}) {
+    const fetchImpl = opts.fetchImpl ?? fetch;
+    const res = await fetchImpl(`${authUrl}/auth/device/token`, {
+        method: "POST",
+        headers: { "content-type": "application/json" },
+        body: JSON.stringify({ deviceCode: token.trim() }),
+    });
+    if (res.status === 404)
+        throw new DeviceFlowUnsupported();
+    if (res.ok) {
+        const session = toSession((await res.json()));
+        saveCredentials(session);
+        logLine("auth.token_login", { url: authUrl });
+        return session;
+    }
+    const body = (await res.json().catch(() => ({})));
+    switch (body.error) {
+        case "expired_token":
+            throw new DeviceFlowAborted("this setup token has expired or was already used — make a new one on the console's " +
+                "Set up the runner page and paste it within ten minutes", "expired_token");
+        case "invalid_grant":
+        case "authorization_pending":
+        case "slow_down":
+        case "access_denied":
+            // A pending or unknown code is not a setup token: the console only hands
+            // out codes that are already approved.
+            throw new DeviceFlowAborted("that is not a valid setup token — copy the whole token from the console's " +
+                "Set up the runner page", "access_denied");
+        default:
+            throw new Error(`sign-in failed: ${body.error ?? `HTTP ${res.status}`}`);
+    }
+}
 /**
  * A name for this machine, shown on the approval page.
  *

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

@@ -27,12 +27,27 @@
  *   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)
+ *   BIR_DERIVE_RECENT_RESULTS how many of this prompt's tool results derivation
+ *                             reads, so a target named by an earlier step can be
+ *                             found (default 5; 0 off)
+ *   BIR_INTENT_SOURCES        which text a step's intent may come from
+ *                             (default text,thinking,tool)
+ *   BIR_INTENT_REQUESTS_PER_TURN  probes one turn may send (default 40).
+ *                             Separate from BIR_INTENT_MATCHES_PER_TURN: arming
+ *                             is a claim on the turn, counting hits is not
+ *   BIR_SEGMENT_ARM           1 lets a handed-out segment actually run mid-task.
+ *                             Unset is observe-only: what would have armed is
+ *                             logged and nothing is replaced
+ *   BIR_MIN_SEGMENT_STEER_SIMILARITY  minimum similarity to steer a segment
+ *                             (default 0.95)
  *   BIR_REPLAY_BUDGET_MS      whole-plan ceiling, direct mode (default 120000)
  *   BIR_STEP_TIMEOUT_MS       one direct tools/call (default 60000)
  *

package/dist/bin/bir-hooks.js

@@ -27,12 +27,27 @@
  *   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)
+ *   BIR_DERIVE_RECENT_RESULTS how many of this prompt's tool results derivation
+ *                             reads, so a target named by an earlier step can be
+ *                             found (default 5; 0 off)
+ *   BIR_INTENT_SOURCES        which text a step's intent may come from
+ *                             (default text,thinking,tool)
+ *   BIR_INTENT_REQUESTS_PER_TURN  probes one turn may send (default 40).
+ *                             Separate from BIR_INTENT_MATCHES_PER_TURN: arming
+ *                             is a claim on the turn, counting hits is not
+ *   BIR_SEGMENT_ARM           1 lets a handed-out segment actually run mid-task.
+ *                             Unset is observe-only: what would have armed is
+ *                             logged and nothing is replaced
+ *   BIR_MIN_SEGMENT_STEER_SIMILARITY  minimum similarity to steer a segment
+ *                             (default 0.95)
  *   BIR_REPLAY_BUDGET_MS      whole-plan ceiling, direct mode (default 120000)
  *   BIR_STEP_TIMEOUT_MS       one direct tools/call (default 60000)
  *
@@ -93,6 +108,29 @@ function positiveInt(value, fallback) {
     const n = Number(value);
     return Number.isFinite(n) && n > 0 ? Math.floor(n) : fallback;
 }
+/** Like {@link positiveInt}, but 0 is a meaningful setting rather than unset. */
+function nonNegativeInt(value, fallback) {
+    const n = Number(value);
+    return Number.isFinite(n) && n >= 0 ? Math.floor(n) : fallback;
+}
+/**
+ * `BIR_INTENT_SOURCES` — which text a step's intent may be read from
+ * (segmented.md R-INTENT-3). Unset or unparseable means all three.
+ *
+ * It governs only what is *sent*. Turning every source off does not stop a
+ * probe: the request still goes out with an empty text and the server builds a
+ * line from the tool name and arguments (R-HIT-4).
+ */
+function parseIntentSources(value) {
+    if (value === undefined)
+        return undefined;
+    const allowed = ["text", "thinking", "tool"];
+    const wanted = value
+        .split(",")
+        .map((s) => s.trim().toLowerCase())
+        .filter((s) => allowed.includes(s));
+    return new Set(wanted);
+}
 /**
  * Assemble the replay configuration (docs/calculatedReplay.md §5.3 of the guide).
  *
@@ -116,6 +154,25 @@ function buildReplayOptions(auth) {
             planMs: positiveInt(process.env.BIR_REPLAY_BUDGET_MS, 120_000),
             stepMs: positiveInt(process.env.BIR_STEP_TIMEOUT_MS, 60_000),
         },
+        // Intent matching in the ReAct loop (fallbk.md §Runner 4). On with replay;
+        // BIR_INTENT_MATCH=0 turns it off on its own.
+        intentMatch: {
+            enabled: process.env.BIR_INTENT_MATCH !== "0",
+            // 4 000, not 1 500: a request whose best segment lands in the not-clear
+            // band has one live question to ask under the server's own 2 500 ms
+            // attempt, and must still answer inside the hook's 30 s (segmented.md
+            // R-HIT-11).
+            budgetMs: positiveInt(process.env.BIR_INTENT_MATCH_BUDGET_MS, 4_000),
+            maxPerTurn: positiveInt(process.env.BIR_INTENT_MATCHES_PER_TURN, 3),
+            maxRequestsPerTurn: positiveInt(process.env.BIR_INTENT_REQUESTS_PER_TURN, 40),
+        },
+        // Observe-only until an operator has read the logs and turned it on
+        // (segmented.md R-OUT-10, R-LIFE-7). Arming is never the way to find out.
+        segmentArm: process.env.BIR_SEGMENT_ARM === "1",
+        minSegmentSimilarity: (() => {
+            const n = Number(process.env.BIR_MIN_SEGMENT_STEER_SIMILARITY);
+            return Number.isFinite(n) ? n : 0.95;
+        })(),
         authUrl: auth.baseUrl,
         // Read late, not captured: `RemoteRecorder` refreshes the access token as the
         // session outlives it, and a snapshot taken here would go stale mid-run.
@@ -127,7 +184,14 @@ 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",
         });
     }
@@ -152,6 +216,8 @@ async function main() {
         host: { app: "claude-code" },
         correlationDecision: process.env.BIR_CORRELATION_DECISION === "ask" ? "ask" : "allow",
         noCorrelation: process.env.BIR_NO_CORRELATION === "1",
+        deriveRecentResults: nonNegativeInt(process.env.BIR_DERIVE_RECENT_RESULTS, 5),
+        intentSources: parseIntentSources(process.env.BIR_INTENT_SOURCES),
         replay: buildReplayOptions(auth),
     });
     const address = await server.listen();

package/dist/bin/bir.js

@@ -28,7 +28,7 @@ import { isScenarioServer, isWrapped, PACKAGE_NAME, readSidecar, scenarioEntry,
 import { isRemote, resolveServers } from "../config/resolve.js";
 import { buildHooksBlock, claudeCodePaths, fileForScope, installHooks, readTextOrNull, setServerEntry, sha256, uninstallHooks, } from "../config/adapters/claude-code.js";
 import { readGenericServers, setGenericServerEntry } from "../config/adapters/generic.js";
-import { AUTH_URL_HINT, DeviceFlowAborted, DeviceFlowUnsupported, authenticate, deviceLogin, describeAuthService, legacyPasswordLogin, logout, normalizeAuthUrl, resolveAuthUrl, } from "../auth/client.js";
+import { AUTH_URL_HINT, DeviceFlowAborted, DeviceFlowUnsupported, authenticate, deviceLogin, describeAuthService, legacyPasswordLogin, tokenLogin, logout, normalizeAuthUrl, resolveAuthUrl, } from "../auth/client.js";
 import { DEFAULT_CONTROL_PORT } from "../control/server.js";
 import { errText } from "../util/log.js";
 import { packageVersion } from "../util/version.js";
@@ -67,6 +67,7 @@ Options:
   --json            machine-readable output for status / doctor
   --dry             replay against recorded outputs only; run no real tools
   --no-browser      login: print the link and code, open nothing (SSH, headless)
+  --token <value>   login: redeem a one-time setup token from the console (no browser)
   --password        login: use the old email/password prompt (deprecated)`);
     process.exit(code);
 }
@@ -115,6 +116,9 @@ function parseArgs(argv) {
             case "--no-browser":
                 args.browser = false;
                 break;
+            case "--token":
+                args.token = argv[++i] ?? "";
+                break;
             case "--config":
                 args.configPath = argv[++i];
                 break;
@@ -540,6 +544,20 @@ async function doctor(args) {
         else {
             notes.push(`recording to ${String(health.authUrl ?? "the configured BaseIn service")}`);
         }
+        // Whether a recurring sub-task the service found may actually run mid-task
+        // (segmented.md R-LIFE-8). Observe-only is the default and must be visible
+        // without reading a log: an operator turns arming on by reading what *would*
+        // have armed, and needs to know which of the two states this machine is in.
+        notes.push(health.segmentArm === true
+            ? "recurring sub-tasks MAY run mid-task (BIR_SEGMENT_ARM=1)"
+            : "recurring sub-tasks are observed only — nothing is replaced (BIR_SEGMENT_ARM unset)");
+        const sessions = health.sessions ?? [];
+        const probes = sessions.reduce((n, s) => n + (s.intent?.probes ?? 0), 0);
+        const armed = sessions.reduce((n, s) => n + (s.intent?.armed ?? 0), 0);
+        if (sessions.length > 0) {
+            notes.push(`mid-turn matching this session: ${probes} probe${probes === 1 ? "" : "s"}, ` +
+                `${armed} armed`);
+        }
     }
     else if (!resolveAuthUrl()) {
         // No control server to ask, and nothing in this shell either. That is a
@@ -582,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(", ")} — ` +
@@ -902,7 +933,29 @@ async function main() {
                 return 1;
             }
             let session;
-            if (args.password) {
+            if (args.token !== undefined) {
+                // A setup token from the console: already approved for one account, so
+                // there is no page to open and nothing to wait for.
+                if (!args.token.trim()) {
+                    process.stderr.write("[bir] --token needs the token itself: bir login --token <token>\n");
+                    return 1;
+                }
+                try {
+                    session = await tokenLogin(baseUrl, args.token);
+                }
+                catch (err) {
+                    if (err instanceof DeviceFlowAborted) {
+                        process.stderr.write(`[bir] ${err.message}\n`);
+                        return 1;
+                    }
+                    if (err instanceof DeviceFlowUnsupported) {
+                        process.stderr.write("[bir] this service does not offer setup tokens; run `bir login` without --token.\n");
+                        return 1;
+                    }
+                    throw err;
+                }
+            }
+            else if (args.password) {
                 process.stderr.write("[bir] --password is deprecated and will be removed in the next release. " +
                     "Browser sign-in works for every account, including Google-only ones.\n");
                 session = await legacyPasswordLogin(baseUrl);

package/dist/control/server.d.ts

@@ -23,6 +23,7 @@
  * token on every route, and never echoes the token back. A loopback port that
  * accepts unauthenticated step reports is a local exfiltration channel.
  */
+import { type IntentSource } from "./transcript.js";
 import { type Recorder } from "../record/recorder.js";
 import { type ReplayOptions } from "../replay/controller.js";
 /** The subset of the Claude Code hook payload we consume (all optional, all defensive). */
@@ -41,6 +42,13 @@ export interface HookPayload {
 }
 export interface ControlServerOptions {
     recorder: Recorder;
+    /**
+     * Tool results of the current prompt handed to derivation
+     * (`BIR_DERIVE_RECENT_RESULTS`, segmented.md R-PARAM-2). Default 5; 0 off.
+     */
+    deriveRecentResults?: number;
+    /** `BIR_INTENT_SOURCES` — which intent rungs may be sent (R-INTENT-3). */
+    intentSources?: ReadonlySet<IntentSource>;
     /** Session working directory — keys the discovery file. */
     cwd: string;
     /** Preferred port; 0 (or a busy port) falls back to an ephemeral one. */
@@ -107,6 +115,18 @@ export declare class ControlServer {
     private readonly pendingSeals;
     /** Calculated replay. Inert unless `opts.replay.enabled`. */
     private readonly replay;
+    /**
+     * How many of this prompt's tool results derivation may read
+     * (`BIR_DERIVE_RECENT_RESULTS`, segmented.md R-PARAM-2). A target is often
+     * named by an earlier step's output and never by the prompt.
+     */
+    private readonly deriveRecentResults;
+    /**
+     * Which rungs of R-INTENT-1 the runner may send (`BIR_INTENT_SOURCES`). It
+     * governs only what is *sent*: with every source off, the probe still goes out
+     * with an empty text and the server builds the tool line (R-HIT-4).
+     */
+    private readonly intentSources;
     constructor(opts: ControlServerOptions);
     listen(): Promise<ControlServerAddress>;
     close(): Promise<void>;
@@ -167,6 +187,8 @@ export declare class ControlServer {
      * false` and zero rather than a number that is confidently wrong.
      */
     private runCost;
+    /** Transcript cost since `mark`; unmeasured (and zero) without one. */
+    private costSince;
     private reportExecution;
     /** Seal the run *and* wait for everything queued to reach the service. */
     private finalizeRun;
@@ -183,6 +205,67 @@ export declare class ControlServer {
      *    record `tool_selected`. The hook is this step's only observer.
      */
     private onToolPre;
+    /** A controller decision as a `PreToolUse` answer, or undefined to carry on. */
+    private preToolAnswer;
+    /**
+     * Recordings this turn must not count a step hit against (segmented.md
+     * R-HIT-7).
+     *
+     * A repeat of a recording's own prompt is *prompt* recurrence, counted as
+     * `iterations`, never step recurrence. Without this, three prompt repeats
+     * would reach `SEGMENT_MIN_HITS` on every step of the whole recording and the
+     * detector would build a whole-run-sized segment beside the whole-run
+     * scenario.
+     */
+    private excludeRunsFor;
+    /**
+     * Per recording a plan of this turn came from, how far that plan got
+     * (segmented.md R-OUT-6).
+     *
+     * The server uses it to refuse a segment that starts *before* where this turn
+     * already is: re-running steps the turn has just done is worse than not
+     * replaying at all. The largest position per recording wins, and a plan
+     * declined for anything but a known-bad first step reports nothing — it ran
+     * none of the recording, so it blocks none of it.
+     *
+     * Rebuilt on every probe rather than cached: a plan that hands over between
+     * two calls changes the answer.
+     */
+    private ranThroughFor;
+    /**
+     * Intent matching in the ReAct loop (fallbk.md §Runner 4, segmented.md 10.3).
+     *
+     * Called only while the model is driving. Every unsteered, non-housekeeping
+     * tool call is sent: the service counts it as a hit on whatever recorded step
+     * it matches, and may hand back a scenario or a segment to run in its place.
+     *
+     * A call made with **no reasoning at all** still probes (R-HIT-4): the server
+     * builds an intent from the tool name and arguments, and a step the agent took
+     * without narrating it is exactly as much a recurrence as one it explained.
+     * Every failure is a miss.
+     */
+    private tryIntentMatch;
+    /**
+     * Schedule a fragment once a matched turn's plan has handed over (fallbk.md
+     * D7). Only a turn that is not already recording needs one: an unmatched turn
+     * whose intent-armed plan handed over is recording the model's work anyway.
+     */
+    private noteHandover;
+    /**
+     * Open the fragment run and record from this call on (fallbk.md D7).
+     *
+     * The run id is swapped in place: steps allocated before belonged to a turn
+     * the service never created a run for, and nothing of theirs may land in the
+     * fragment — so pending correlations are latched and built-ins forgotten.
+     */
+    private openFragment;
+    /** Resolve with `p`, or null once `ms` passes or it rejects. */
+    private withinBudget;
+    /**
+     * `PostToolUse`, and where a hand-over noticed while threading this call's
+     * output reaches the model at once, as `additionalContext` (fallbk.md D4).
+     */
+    private onToolPost;
     /**
      * `PostToolUse` / `PostToolUseFailure`. For a built-in this closes the pair.
      * For a correlated MCP call it normally does nothing — the proxy owns that
@@ -190,7 +273,7 @@ export declare class ControlServer {
      * or the call never reached it), the hook's own view is recorded after
      * {@link PROXY_REPORT_GRACE_MS} rather than the step being lost entirely.
      */
-    private onToolPost;
+    private toolPost;
     private errorText;
     /**
      * `SubagentStart` / `SubagentStop`. These carry `agent_id`, which is the only