@basein/runner 0.2.12 → 0.3.0

package/dist/record/recorder.d.ts

@@ -16,6 +16,17 @@ export interface RunMetrics {
     costUsd?: number;
     durationMs?: number;
 }
+/** How long a caller is prepared to wait for {@link Recorder.flush}. */
+export interface FlushOptions {
+    /**
+     * Stop waiting after this long; the sends carry on in the background. A
+     * recorder picks a bounded default when this is absent (RemoteRecorder: 2 s,
+     * `BIR_FLUSH_TIMEOUT_MS`), because a flush behind a dead service must never
+     * be what holds a hook or a shutdown — and it stops waiting sooner, at once,
+     * when the service is known to be failing (the health verdict's cool-down).
+     */
+    timeoutMs?: number;
+}
 export interface Recorder {
     /**
      * Create the run; returns the client-generated runId synchronously.
@@ -57,9 +68,39 @@ export interface Recorder {
         answer: string;
     }): string;
     finishRun(runId: string, finalOutput?: string, metrics?: RunMetrics): void;
-    /** Await every queued send for a run. Called once at session end. */
-    flush(runId: string): Promise<void>;
+    /**
+     * Await every queued send for a run. Called once at session end. Bounded:
+     * see {@link FlushOptions}.
+     */
+    flush(runId: string, opts?: FlushOptions): Promise<void>;
+}
+/**
+ * What a recorder can say about its own sending, for `/health` and
+ * `bir doctor`. The queue a hook server keeps drains instantly; the real
+ * backlog is here, so this is where "lossy" is actually known.
+ */
+export interface RecorderHealth {
+    /**
+     * `recording`, or why nothing is being sent: `signed_out` (credentials.json
+     * was removed — `bir logout`), `auth_rejected` (the service refused the
+     * session and there was nothing newer to adopt), `other_service` (the
+     * credentials now belong to a different service address).
+     */
+    state: "recording" | "signed_out" | "auth_rejected" | "other_service";
+    /** Sends queued and not yet started. */
+    pendingSends: number;
+    /** Their approximate size. */
+    pendingBytes: number;
+    /** Sends dropped since start: the backlog bound, a signed-out session, a run the service never created. */
+    droppedSends: number;
+    /** Sends that were tried and failed since start. */
+    failedSends: number;
+}
+/** Optional capability: a recorder that knows its own backlog. */
+export interface RecorderHealthReporter {
+    recorderHealth(): RecorderHealth;
 }
+export declare function isRecorderHealthReporter(r: Recorder): r is Recorder & RecorderHealthReporter;
 /**
  * A similar-prompt hit reported by `POST /recordings/runs`. On a hit the server
  * does **not** create a run, so every later step post for that id would 404 —
@@ -200,9 +241,16 @@ export interface IntentMatchAnswer {
     bestStepSimilarity?: number;
     segmentWouldArm?: SegmentWouldArm;
 }
+/** How long a probe's caller will wait; the request is abandoned past it. */
+export interface IntentMatchOptions {
+    /** Abort the request (and free its socket) when the caller stops waiting. */
+    signal?: AbortSignal;
+    /** A deadline for the request itself. A recorder picks a short default. */
+    timeoutMs?: number;
+}
 /** Optional capability: intent matching needs a service. */
 export interface IntentMatcher {
-    matchIntent(req: IntentMatchRequest): Promise<IntentMatchAnswer | null>;
+    matchIntent(req: IntentMatchRequest, opts?: IntentMatchOptions): Promise<IntentMatchAnswer | null>;
 }
 export declare function isIntentMatcher(r: Recorder): r is Recorder & IntentMatcher;
 /**

package/dist/record/recorder.js

@@ -5,6 +5,9 @@
  * service needs no new endpoints for v1: a BaseInstRunner run is the same row
  * shape as an RRepeat one, discriminated only by `metadata.recorder`.
  */
+export function isRecorderHealthReporter(r) {
+    return typeof r.recorderHealth === "function";
+}
 export function isMatchAware(r) {
     return typeof r.getMatch === "function";
 }

package/dist/record/redact.d.ts

@@ -4,28 +4,122 @@
  * The proxy sits on the credential path for every wrapped server (§9), and every
  * argument and result it sees crosses a process boundary and then the network.
  * So redaction runs on the recording copy of both arguments *and* results,
- * before the step report is even queued.
+ * before the step report is even queued — and once more, as the last line of
+ * defence, on every free-text field `RemoteRecorder` sends (the prompt, the
+ * answer, the reasoning, error messages), because those never pass through a
+ * structured payload at all.
  *
  * Three rules, in the order they fire:
- *   1. **By key.** A value under a key matching {@link SECRET_KEY} is replaced
- *      wholesale, whatever its type. `authorization: { scheme, token }` loses
- *      both halves, because the object as a whole is the secret.
+ *   1. **By key.** A value under a key that names a secret ({@link isSecretKey})
+ *      is replaced wholesale, whatever its type. `authorization: { scheme, token }`
+ *      loses both halves, because the object as a whole is the secret.
  *   2. **`env` blocks.** An object under an `env` key has *every* value replaced.
  *      MCP server configs put credentials there under arbitrary names, so no key
  *      pattern would catch them.
- *   3. **By shape.** A string that looks like a bearer token, a JWT, an
- *      `sk-`/`ghp_`-style key or an AWS access key id is replaced wherever it
- *      appears — including inside free text, where key-matching cannot reach.
+ *   3. **By shape.** A string that looks like a credential — a bearer token, a
+ *      JWT, a provider key, a PEM private key, a password in a URL, a
+ *      `DB_PASSWORD=…` line of a `.env` file, an `X-Api-Key:` header — is
+ *      replaced wherever it appears, including inside free text, where key
+ *      matching cannot reach. Reading `.env` or `~/.aws/credentials` is a routine
+ *      thing for an agent to do; its result is recorded like any other.
+ *
+ * KEYS ARE MATCHED ON WHOLE NAME SEGMENTS, not substrings. The old rule was one
+ * unanchored alternation, so `author`, `max_tokens`, `nextPageToken` and
+ * `tokenizer` were all "secrets" — the recording lost real arguments (numbers
+ * became the string "[redacted]") and a scenario built from it had nothing to
+ * replay. Names are split on camelCase, snake_case, kebab-case and dots, and a
+ * segment has to *be* the secret word (`token`, `accessToken`, `x-api-key`), not
+ * merely contain it. The names 0.2.12's substring rule caught that do hold
+ * credentials are still caught: plurals (`tokens`, `api_keys`), an `auth` that
+ * ends the name (`basic_auth`, `X-Upstream-Auth`), `oauth`, `authentication`,
+ * `auth_code` — and a number under the secret itself (`token: 482913`, an OTP).
+ *
+ * TEXT RULES ARE ANCHORED TO WHERE SECRETS ARE WRITTEN, not to every
+ * `name = value` in sight. A recorded Read of source code must survive: its
+ * bytes are what a scenario's output logic is authored against, and
+ * `const token = await getToken()` is not a secret. So assignments are only
+ * redacted in env/ini/YAML line form, shell `NAME=value` form, header form and
+ * JSON `"key": "value"` form, and never when the value is visibly code (a call,
+ * a member access, a `${reference}`, a type in a declaration such as
+ * `password: string`, or a variable named for the same thing such as
+ * `token: newToken`). A separator never spans a line break: an empty
+ * `DB_PASSWORD=` must not take the next line with it.
+ *
+ * JSON TEXT IS REDACTED AS JSON. A serialized tool payload goes through
+ * {@link redactJsonText}, which parses it and runs the rules on each string
+ * leaf — the same pass its producer's {@link redact} made — so the result is
+ * always valid JSON and, when nothing new was found, the producer's bytes
+ * exactly (live replay serializes a result the same way and compares). The
+ * rules still tolerate JSON-escaped text (a string leaf that holds a JSON
+ * document, a preview of one): they never start a match inside an escape
+ * sequence and never replace a quote or a backslash, so an escaped document
+ * stays parseable.
  *
  * Redaction never throws and never mutates its input: a cycle, a `BigInt`, a
  * getter that explodes — each degrades to a placeholder rather than losing the
  * step or, worse, taking the session down.
  */
 export declare const REDACTED = "[redacted]";
-/** Keys whose values are secret regardless of shape. */
+/**
+ * The substring rule this module used before key segments. Kept exported for
+ * anything that imported it, and applied again under `BIR_REDACT_LEGACY_KEYS=1`.
+ *
+ * @deprecated over-matches ordinary names (`author`, `max_tokens`); use {@link isSecretKey}.
+ */
 export declare const SECRET_KEY: RegExp;
-/** Replace every secret-shaped run inside a string. */
+/**
+ * A string leaf longer than this is cut before its shapes are scanned. Every
+ * consumer caps a recorded payload far below it (64 KiB), so the cut is never
+ * visible in what is sent — it only stops a 20 MB tool result from costing a
+ * few hundred milliseconds of regex work on a hook's path.
+ */
+export declare const REDACT_SCAN_MAX_CHARS: number;
+/**
+ * How strongly a key names a secret. `strong` redacts any value but a boolean
+ * — the secret itself (`password`, `token`, `api_key`, `mfa_token`) may well
+ * be a number: a one-time code, a PIN, a numeric key. `weak` (a session id,
+ * something *about* a token such as `token_id`, a list such as `tokens`)
+ * keeps numbers and booleans too, which are ids, counters and flags there far
+ * more often than they are credentials.
+ */
+export type SecretKeyStrength = "strong" | "weak";
+export declare function secretKeyStrength(name: string): SecretKeyStrength | undefined;
+/** True when a value under `name` is a secret (see {@link secretKeyStrength}). */
+export declare function isSecretKey(name: string): boolean;
+/**
+ * The same question for an UPPER_SNAKE environment variable name, where the
+ * words run together (`PGPASSWORD`, `GITHUB_TOKEN`, `AWS_SECRET_ACCESS_KEY`)
+ * and substring matching is the convention rather than the mistake — minus
+ * the counters (`MAX_TOKENS`, `TOKENIZERS_PARALLELISM`) and file pointers
+ * (`PASSWORD_FILE`, the Docker secrets convention).
+ */
+export declare function isSecretEnvName(name: string): boolean;
+/**
+ * Replace every secret-shaped run inside a string.
+ *
+ * Idempotent: redacting the result again changes nothing. That is what lets a
+ * payload be redacted by its producer and again at the recorder without its
+ * bytes moving (live replay compares against them). One pass is not always a
+ * fixed point — a match one rule declined (`Authorization: Authorization: …`)
+ * can hide a secret that only shows once a later rule has run — so a pass that
+ * changed something is followed by another, until one changes nothing.
+ */
 export declare function redactText(text: string): string;
+/**
+ * Redact a string that holds JSON — a serialized tool input, result or error —
+ * and return JSON, always.
+ *
+ * Running {@link redactText} over the serialized text could not promise that:
+ * a rule that met `\n` after an empty `KEY=` wrote `KEY=\[redacted]`, and the
+ * service stored a payload no parser accepts. So the text is parsed and every
+ * string leaf gets the rules as plain text, exactly as its producer's
+ * {@link redact} did. When that finds nothing new — the normal case, since
+ * producers redact first — the original bytes come back untouched: live replay
+ * serializes a result the same way and compares against what was recorded.
+ * Text that is not JSON (a truncated preview, a producer's plain error) gets
+ * {@link redactText}: there is no structure to keep.
+ */
+export declare function redactJsonText(text: string): string;
 /**
  * Deep-clone `value` with secrets removed. The result is always JSON-safe, so
  * the caller can serialise it without a second failure mode.