@basein/runner 0.2.11 → 0.3.0

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

@@ -5,7 +5,9 @@
  * Normally nobody runs it: `bir install` makes it the SessionStart hook
  * (`bir-hooks ensure`), which starts it in the background for the project when no
  * recorder is running there, and `bir up` / `bir down` start and stop that
- * background process by hand. Its audit lines then go to
+ * background process by hand. `bir-hooks revive --cwd <project>` starts it
+ * again mid-session: a bound proxy spawns it, detached, when the recorder it
+ * reported to is gone (control/daemon.ts, reviveDaemon). Its audit lines then go to
  * ~/.baseinstrunner/logs/<project-key>.log. It can still be run in a terminal:
  *
  *     bir-hooks                       # start; Ctrl-C to stop
@@ -16,31 +18,69 @@
  *   2. accepts step reports from every `bir-proxy` that finds it;
  *   3. owns run identity, the monotonic `stepIndex`, and the recorder chain (D5).
  *
+ * The recorder listens first and signs in afterwards, in the background, so a
+ * slow or unreachable BaseIn service never holds a hook; it starts recording
+ * by itself when a sign-in appears (`bir login`) — no restart
+ * (control/recorder-main.ts, control/recorder-keeper.ts).
+ *
  * Environment:
  *   BIR_AUTH_URL              BaseIn auth-service. Unset, the address `bir setup`
  *                             stored in ~/.baseinstrunner/config.json is used
- *   BIR_CONTROL_PORT          preferred port (default 53411; falls back if busy)
- *   BIR_CORRELATION_DECISION  `allow` (default) or `ask` — see below
+ *   BIR_CONTROL_PORT          the port to listen on, over the project's own
+ *                             (default: the project's, else 53411, falling
+ *                             back if busy). 0 is any free port — the one
+ *                             taken is in the discovery file, /health and the
+ *                             log (tests and the smoke run; a project's hooks
+ *                             name a fixed port). A value that is not a port
+ *                             is ignored
+ *   BIR_CORRELATION_DECISION  unset (default: `auto`), `auto`, `allow` or
+ *                             `ask` — see below
  *   BIR_NO_CORRELATION=1      never inject a call id; join on fingerprints
  *   BIR_VERBOSE=1             per-step detail lines
+ *   BIR_SERVICE_TIMEOUT_MS    ceiling for one call to the service made off a
+ *                             hook's path (default 10000)
+ *   BIR_SUPERSEDED_EXIT_MS    how long a recorder the project's hooks moved
+ *                             away from (a reinstall on another port) must
+ *                             have had no session, run, live proxy or unsent
+ *                             step before it exits (default 86400000, a day)
+ *   BIR_WINDOWS_LAUNCH=spawn  Windows only: start the background recorder with
+ *                             a direct hidden spawn instead of PowerShell's
+ *                             Start-Process (faster by about a second; unsafe
+ *                             only when something above Claude Code captures
+ *                             its output — see control/daemon.ts)
  *
  *   BIR_REPLAY=0              turn OFF calculated replay — running a scenario on
  *                             a similar-meaning match (docs/calculatedReplay.md).
  *                             ON by default; unset or any value other than "0"
- *                             keeps it on. Read §13.2: a replayed step is
- *                             auto-approved, and a directly executed one never
- *                             reaches the permission system at all.
+ *                             keeps it on (`bir replay off` stores the same
+ *                             for one project). Read §13.2: only when a prompt
+ *                             matches a scenario, that scenario's own steps run
+ *                             without a prompt of their own — a steered step is
+ *                             answered `allow`, a directly executed one never
+ *                             reaches the permission system. Never in plan
+ *                             mode; every other tool call is asked as usual.
  *   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         OPTIONAL. Derivation — reading what this turn acts
+ *   BIR_DERIVE_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)
+ *                             runner. Set this (an Anthropic key) 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_USE_ANTHROPIC_API_KEY=1  let the background recorder use an
+ *                             ANTHROPIC_API_KEY from its environment for
+ *                             derivation, as older versions did. Off by
+ *                             default: a recorder the SessionStart hook starts
+ *                             has Claude Code's environment, and using the key
+ *                             found there billed the person's own account. A
+ *                             `bir-hooks` run by hand in a terminal uses that
+ *                             terminal's ANTHROPIC_API_KEY as it always did
  *   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_MATCH_BUDGET_MS       prompt-hook match wait (default 1500)
+ *   BIR_DERIVE_BUDGET_MS      derivation wait before a direct run (default 8000);
+ *                             inside a hook it is at most BIR_HOOK_DERIVE_BUDGET_MS
+ *                             (default 4000)
  *   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)
@@ -49,31 +89,32 @@
  *   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_INTENT_MATCH_BUDGET_MS  one intent probe's own ceiling (default 4000).
+ *                             Not a wait: PreToolUse does not wait for a probe
+ *                             unless arming is on (BIR_SEGMENT_ARM=1 or
+ *                             BIR_INTENT_ARM=1), and then at most
+ *                             BIR_INTENT_ARM_BUDGET_MS (default 500)
  *   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_REPLAY_BUDGET_MS      whole-plan ceiling, direct mode (unset: the
+ *                             controller's 100000, BIR_REPLAY_PLAN_BUDGET_MS)
  *   BIR_STEP_TIMEOUT_MS       one direct tools/call (default 60000)
  *
- * ABOUT `BIR_CORRELATION_DECISION`. Correlating a wrapped MCP call means
- * answering `PreToolUse` with `permissionDecision: "allow"` plus an extra
- * argument (Phase 6). That is what the design specifies — and it also
- * **auto-approves the call**, so a tool the user would have been asked about is
- * no longer asked about. Set `BIR_CORRELATION_DECISION=ask` to keep the prompt;
- * hosts that ignore `updatedInput` on a non-allow decision then fall back to
- * fingerprint matching, which is lossy under identical concurrent calls.
- */
-/**
- * Assemble the replay configuration (docs/calculatedReplay.md §5.3 of the guide).
- *
- * The steer threshold defaults **above** the service's own detection threshold
- * (0.9). Detection decides "do not record this again", which is cheap — the worst
- * case is a lost recording. Steering decides "do not think about this again",
- * which is a much stronger claim, and a 0.90-similar prompt usually covers only
- * part of the live task.
+ * ABOUT `BIR_CORRELATION_DECISION`. Correlating a wrapped MCP call exactly
+ * means answering `PreToolUse` with an extra argument, and Claude Code only
+ * takes that together with `permissionDecision: "allow"` — which also
+ * **auto-approves the call**, so a tool the user would have been asked about
+ * is no longer asked about. Unset (or `auto`), nothing is passed to the
+ * control server, which never does that for an ordinary call: it injects only
+ * where `allow` changes nothing the user is asked (a `bypassPermissions`
+ * session) and otherwise joins the proxy's report by fingerprint. `allow` is
+ * the behaviour of 0.2.12 and earlier, an explicit opt-in that is logged loudly at start
+ * — every wrapped call auto-approved and exactly correlated; `ask` keeps the
+ * prompt (a host that ignores the injection on a non-allow answer falls back
+ * to fingerprints).
  */
-/** Where the three replay switches came from, for `/health` and `bir doctor`. */
-export type ReplaySource = "env" | "sidecar" | "default";
+export type { ReplaySource } from "../control/recorder-main.js";
 //# sourceMappingURL=bir-hooks.d.ts.map