@basein/runner 0.2.0 → 0.2.1

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:

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

@@ -33,6 +33,19 @@
  *   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

@@ -33,6 +33,19 @@
  *   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 +106,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 +152,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.
@@ -128,6 +183,7 @@ function buildReplayOptions(auth) {
             minSimilarity: opts.minSimilarity,
             allowServers: allowServers ? [...allowServers].join(",") : "(all wrapped)",
             derive: process.env.ANTHROPIC_API_KEY ? "anthropic" : "recorded sample values",
+            intentMatch: opts.intentMatch?.enabled ? "on" : "off",
             why: "matched prompts will run their calculated scenario — steered steps are auto-approved",
         });
     }
@@ -152,6 +208,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
@@ -902,7 +920,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