@basein/runner 0.2.12 → 0.3.1

package/dist/bin/scenario-liveness.js

@@ -0,0 +1,459 @@
+/**
+ * scenario-liveness — the two things `bir-scenario` does besides answering MCP:
+ * it tells its project's recorder that a delivery tool is live
+ * (`POST /scenario/hello`), and it brings back a recorder that died
+ * mid-session (`bir-hooks revive`).
+ *
+ * WHY HELLO. A direct plan tells the model to call `mcp__bir__run_scenario`
+ * before any other tool. The control server used to announce one whenever the
+ * MCP config listed the `bir` server — but a configured server is not a
+ * connected one: a stale node path, a crash, the server disabled in `/mcp`, or
+ * a session run with `BIR_OFF=1` (which lists no tools) all leave the model
+ * told to call a tool it does not have. So this server says, on `initialize`,
+ * on `tools/list`, when the off switch flips, whenever its recorder changes,
+ * and every {@link HELLO_EVERY_MS} while it runs: this pid, this version, this
+ * many tools, off or not. The control server announces a direct plan only on
+ * the word of a live pid that lists a tool.
+ *
+ * WHY REVIVE. Every hook but SessionStart is an HTTP post to the recorder.
+ * With the recorder gone — killed by an antivirus, out of memory — Claude Code
+ * shows a hook error on every prompt and tool call until the next session
+ * start, `/clear` or compaction, because nothing else starts one mid-session.
+ * This server is the one long-lived process in every session of an installed
+ * project, wrapped servers or none, so it starts `bir-hooks revive --cwd <dir>`
+ * (which runs the ordinary ensure, under the ordinary start lock).
+ *
+ * NEITHER MAY COST THE SESSION ANYTHING.
+ *   - A hello is fire-and-forget: nothing on the MCP path awaits it, it is
+ *     bounded by {@link HELLO_TIMEOUT_MS}, one is in flight at a time, and a
+ *     recorder that cannot take it (not up yet, busy, an older version with no
+ *     such route) costs a retry later, never an error.
+ *   - A revive is a detached child that is never waited for, and it is started
+ *     only when the discovery file names a pid that is DEAD and the recorder's
+ *     address REFUSES the connection. A recorder that is alive but slow is never
+ *     replaced (that is how duplicates that cannot bind were made). A missing
+ *     discovery file is never revived either: `bir down` removes it, and a
+ *     recorder somebody stopped on purpose stays stopped. Only an installed
+ *     project is revived, at most once per {@link REVIVE_EVERY_MS} per process
+ *     (after a random wait of up to {@link REVIVE_JITTER_MS}, so the several
+ *     processes of a session that see the same death do not all start one),
+ *     less often each time a revive did not bring a recorder back, and not in
+ *     the server's first {@link REVIVE_GRACE_MS}, while the SessionStart hook
+ *     is starting the recorder itself.
+ *   - Neither writes a byte to stdout (the host's JSON-RPC stream), and
+ *     neither throws.
+ */
+import { spawn } from "node:child_process";
+import { readFileSync, statSync } from "node:fs";
+import { pidAlive } from "../control/discovery.js";
+import { configDir, discoveryPath } from "../control/paths.js";
+import { nodeFlagsToCarry, projectRecord, readSidecar } from "../config/generate.js";
+import { errText, logDetail, logLine } from "../util/log.js";
+import { packageVersion } from "../util/version.js";
+/** A hello waits no longer than this for the recorder's answer. */
+export const HELLO_TIMEOUT_MS = 1_000;
+/** A hello is repeated this often while the server runs (the recorder trusts one for 30 min). */
+export const HELLO_EVERY_MS = 5 * 60_000;
+/**
+ * How often the discovery file is looked at: whether the recorder changed (a
+ * hello is owed to the new one) or died (a revive may be). One `stat`, and a
+ * parse only when the file changed.
+ */
+export const WATCH_EVERY_MS = 2_000;
+/** At most one revive per this long per process; doubled each time one did not help. */
+export const REVIVE_EVERY_MS = 30_000;
+/** The longest a revive waits, at random, before it looks again and starts. */
+export const REVIVE_JITTER_MS = 5_000;
+/** The longest wait between revives that did not bring a recorder back. */
+export const REVIVE_MAX_EVERY_MS = 5 * 60_000;
+/**
+ * No revive in a server's first this-long: it starts with the session, and so
+ * does the SessionStart hook, whose own ensure (up to 11 s, ensure-hook.ts) is
+ * what starts the recorder then — typically over a dead record left from
+ * before a reboot. Reviving beside it would only race it.
+ */
+export const REVIVE_GRACE_MS = 12_000;
+/** How long the "does anything listen there" probe waits before calling the recorder busy. */
+export const REFUSED_PROBE_MS = 2_000;
+/** The longest wait between hellos a recorder could not take. */
+const HELLO_RETRY_MAX_MS = 60_000;
+let recordCache;
+/**
+ * This project's discovery record, whether or not its pid is alive — the
+ * shared reader drops a dead pid's record, and a dead pid is exactly what a
+ * revive needs to see. Parsed again only when the file changed. Never throws.
+ */
+export function readRecorderRecord(cwd) {
+    try {
+        const path = discoveryPath(cwd);
+        let stamp;
+        try {
+            const st = statSync(path);
+            // The inode too: the file is replaced by a rename, and a coarse clock can
+            // give the replacement the same time and, by chance, the same size.
+            stamp = `${st.ino}:${st.mtimeMs}:${st.size}`;
+        }
+        catch {
+            recordCache = { path, stamp: "-", record: undefined };
+            return undefined;
+        }
+        if (recordCache && recordCache.path === path && recordCache.stamp === stamp)
+            return recordCache.record;
+        let record;
+        try {
+            const parsed = JSON.parse(readFileSync(path, "utf8"));
+            record =
+                typeof parsed.url === "string" && typeof parsed.token === "string" && typeof parsed.pid === "number"
+                    ? { url: parsed.url, token: parsed.token, pid: parsed.pid }
+                    : undefined;
+        }
+        catch {
+            record = undefined; // being replaced this instant, or damaged: nothing to go on
+        }
+        recordCache = { path, stamp, record };
+        return record;
+    }
+    catch {
+        return undefined;
+    }
+}
+/** Whether `cwd` is a project `bir setup`/`bir install` put the runner in. Never throws. */
+export function projectInstalled(cwd) {
+    try {
+        return projectRecord(readSidecar(), cwd) !== undefined;
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * Start `bir-hooks revive --cwd <cwd>` from this package, detached, and forget
+ * it: it reads nothing, writes nothing we could see, and exits by itself.
+ */
+export async function launchRevive(cwd) {
+    // Loaded here, not at the top: a revive is rare, and the module graph behind
+    // the daemon is not needed to answer MCP.
+    const { hooksScriptPath } = await import("../control/daemon.js");
+    const child = spawn(process.execPath, [...nodeFlagsToCarry(), hooksScriptPath(), "revive", "--cwd", cwd], {
+        // Not the project: on Windows a process holds its current directory, and
+        // the project folder must stay free to rename or delete (daemon.ts).
+        cwd: configDir(),
+        detached: true,
+        stdio: "ignore",
+        // A detached child on Windows would get a console window of its own.
+        windowsHide: true,
+        env: process.env,
+    });
+    child.on("error", (err) => logLine("scenario.revive_failed", { error: errText(err) }));
+    child.unref();
+}
+/** How a fetch to the recorder failed: busy (timed out), refused (nothing listens), or otherwise. */
+function reachOf(err) {
+    const e = err;
+    if (e?.name === "TimeoutError" || e?.name === "AbortError")
+        return "timeout";
+    if (e?.cause?.name === "TimeoutError")
+        return "timeout";
+    if (e?.cause?.code === "ECONNREFUSED")
+        return "refused";
+    // A host name with two addresses fails as one AggregateError of both.
+    const all = e?.cause?.errors;
+    if (Array.isArray(all) && all.length > 0 && all.every((x) => x?.code === "ECONNREFUSED"))
+        return "refused";
+    return "error";
+}
+function trimUrl(url) {
+    return url.replace(/\/+$/, "");
+}
+const unrefSleep = (ms) => new Promise((resolve) => {
+    const t = setTimeout(resolve, ms);
+    t.unref?.();
+});
+/** See the module comment. One per `bir-scenario` process. */
+export class ScenarioLiveness {
+    opts;
+    cwd;
+    now;
+    random;
+    fetchImpl;
+    record;
+    alive;
+    installed;
+    launch;
+    sleep;
+    env;
+    timer;
+    stopped = false;
+    /** No revive before this (see {@link REVIVE_GRACE_MS}). */
+    reviveFrom;
+    // ── hello ──
+    helloBusy = false;
+    /** A hello asked for while one was in flight: sent when it ends, with the state as it is then. */
+    helloOwed;
+    /** The recorder the last hello was answered by (`url#pid`). */
+    reached;
+    /** The recorder the last hello was sent to, answered or not. */
+    tried;
+    lastHelloAt = 0;
+    helloFailures = 0;
+    helloNotBefore = 0;
+    // ── revive ──
+    reviveBusy = false;
+    reviveNotBefore = 0;
+    /** Revives started since a recorder was last seen alive. */
+    revivesInARow = 0;
+    /** When this process last started one (0: never). */
+    lastReviveAt = 0;
+    /** Revives started by this process. */
+    revives = 0;
+    /** Hellos a recorder answered. */
+    hellos = 0;
+    constructor(opts) {
+        this.opts = opts;
+        this.cwd = opts.cwd;
+        this.now = opts.now ?? Date.now;
+        this.random = opts.random ?? Math.random;
+        this.fetchImpl = opts.fetch ?? fetch;
+        this.record = opts.record ?? readRecorderRecord;
+        this.alive = opts.alive ?? pidAlive;
+        this.installed = opts.installed ?? projectInstalled;
+        this.launch = opts.launch ?? launchRevive;
+        this.sleep = opts.sleep ?? unrefSleep;
+        this.env = opts.env ?? process.env;
+        this.reviveFrom = this.now() + Math.max(0, opts.reviveGraceMs ?? REVIVE_GRACE_MS);
+    }
+    /** Watch the discovery file every {@link WATCH_EVERY_MS}, on a timer that never keeps the process alive. */
+    start(everyMs = WATCH_EVERY_MS) {
+        if (this.timer || this.stopped)
+            return;
+        this.timer = setInterval(() => void this.tick(), everyMs);
+        this.timer.unref();
+    }
+    /** The host is gone: nothing more is sent or started. */
+    stop() {
+        this.stopped = true;
+        if (this.timer)
+            clearInterval(this.timer);
+        this.timer = undefined;
+    }
+    /**
+     * Tell the recorder what this server lists, now — or, while a hello is in
+     * flight, as soon as it ends. Returns at once; never throws.
+     */
+    hello(why) {
+        if (this.stopped)
+            return;
+        if (this.helloBusy) {
+            this.helloOwed = why;
+            return;
+        }
+        this.helloBusy = true;
+        // On the next turn of the loop: the answer this follows goes out first,
+        // and not even reading the discovery file happens before it.
+        setImmediate(() => void this.sendHello(why));
+    }
+    /**
+     * Something on the MCP path found no recorder (`run_scenario` found no live
+     * discovery file, or its request was refused): look now rather than at the
+     * next tick. Returns at once; never throws.
+     */
+    recorderGone(why) {
+        if (this.stopped)
+            return;
+        setImmediate(() => void this.checkRevive(why));
+    }
+    /** One look at the discovery file. Exposed for tests; never throws. */
+    async tick() {
+        if (this.stopped)
+            return;
+        try {
+            const rec = this.record(this.cwd);
+            if (rec && !this.alive(rec.pid)) {
+                await this.checkRevive("the recorder's pid is gone");
+                return;
+            }
+            if (rec)
+                this.recorderSeenAlive();
+            const target = this.target();
+            if (!target)
+                return;
+            const now = this.now();
+            if (target.identity !== this.tried) {
+                this.hello("recorder");
+                return;
+            }
+            if (now < this.helloNotBefore)
+                return;
+            if (target.identity !== this.reached || now - this.lastHelloAt >= HELLO_EVERY_MS) {
+                this.hello(target.identity !== this.reached ? "retry" : "periodic");
+            }
+        }
+        catch (err) {
+            logDetail("scenario.liveness_failed", { error: errText(err) });
+        }
+    }
+    /**
+     * Where a hello goes, the way `run_scenario`'s request does: `BIR_CONTROL_URL`
+     * (with `BIR_CONTROL_TOKEN`, or the discovery file's token), else the
+     * discovery file — whose pid must be alive.
+     */
+    target() {
+        const rec = this.record(this.cwd);
+        const live = rec && this.alive(rec.pid) ? rec : undefined;
+        const envUrl = this.env.BIR_CONTROL_URL?.trim();
+        if (envUrl) {
+            const token = this.env.BIR_CONTROL_TOKEN || live?.token;
+            if (!token)
+                return undefined;
+            return { url: trimUrl(envUrl), token, identity: `${trimUrl(envUrl)}#${live?.pid ?? 0}` };
+        }
+        if (!live)
+            return undefined;
+        return { url: trimUrl(live.url), token: live.token, identity: `${trimUrl(live.url)}#${live.pid}` };
+    }
+    state() {
+        try {
+            const s = this.opts.state();
+            return { tools: Number.isInteger(s.tools) && s.tools >= 0 ? s.tools : 0, off: s.off === true };
+        }
+        catch {
+            return { tools: 0, off: false };
+        }
+    }
+    async sendHello(why) {
+        this.helloBusy = true;
+        try {
+            if (this.stopped)
+                return;
+            // No recorder yet (the host often starts this server before SessionStart
+            // starts the recorder): the watch says hello when one appears.
+            const target = this.target();
+            if (!target)
+                return;
+            const { tools, off } = this.state();
+            const body = { pid: process.pid, version: packageVersion(), tools, off };
+            this.tried = target.identity;
+            this.lastHelloAt = this.now();
+            let reach;
+            let status;
+            try {
+                const res = await this.fetchImpl(`${target.url}/scenario/hello`, {
+                    method: "POST",
+                    headers: { "content-type": "application/json", authorization: `Bearer ${target.token}` },
+                    body: JSON.stringify(body),
+                    signal: AbortSignal.timeout(HELLO_TIMEOUT_MS),
+                });
+                status = res.status;
+                // The answer is `{ok:true}` and nothing here needs it; read it so the
+                // connection can be reused, within the same bound.
+                await res.arrayBuffer().catch(() => undefined);
+                reach = "answered";
+            }
+            catch (err) {
+                reach = reachOf(err);
+            }
+            if (reach === "answered") {
+                this.reached = target.identity;
+                this.hellos += 1;
+                this.helloFailures = 0;
+                this.helloNotBefore = 0;
+                // A recorder from before this route answers 404: it does not ask for
+                // hellos, so there is nothing to retry until it is replaced.
+                logDetail("scenario.hello", { why, tools, off, status });
+                return;
+            }
+            this.helloFailures += 1;
+            this.helloNotBefore =
+                this.now() + Math.min(WATCH_EVERY_MS * 2 ** Math.min(this.helloFailures - 1, 10), HELLO_RETRY_MAX_MS);
+            logDetail("scenario.hello_failed", { why, reach });
+            if (reach === "refused")
+                this.recorderGone("the recorder refused a hello");
+        }
+        catch (err) {
+            logDetail("scenario.hello_failed", { why, error: errText(err) });
+        }
+        finally {
+            this.helloBusy = false;
+            const owed = this.helloOwed;
+            this.helloOwed = undefined;
+            if (owed !== undefined && !this.stopped)
+                this.hello(owed);
+        }
+    }
+    /** Whether anything listens at `url`: only a refused connection counts as nothing. */
+    async probe(url) {
+        try {
+            const res = await this.fetchImpl(`${trimUrl(url)}/health`, { signal: AbortSignal.timeout(REFUSED_PROBE_MS) });
+            await res.arrayBuffer().catch(() => undefined);
+            return "answered";
+        }
+        catch (err) {
+            return reachOf(err);
+        }
+    }
+    /**
+     * A recorder is up: the revives before it helped (or were not needed), so the
+     * next death waits the plain {@link REVIVE_EVERY_MS} since the last one, not
+     * a doubled wait.
+     */
+    recorderSeenAlive() {
+        if (this.revivesInARow === 0)
+            return;
+        this.revivesInARow = 0;
+        this.reviveNotBefore = Math.min(this.reviveNotBefore, this.lastReviveAt + REVIVE_EVERY_MS);
+    }
+    /** Start a revive if — and only if — the recorder is dead, refused and this project's. */
+    async checkRevive(why) {
+        if (this.stopped || this.reviveBusy)
+            return;
+        const now = this.now();
+        if (now < this.reviveNotBefore || now < this.reviveFrom)
+            return;
+        this.reviveBusy = true;
+        try {
+            // Every process of the session sees the same death at about the same
+            // moment. Each waits a moment of its own and looks again: whoever went
+            // first has usually brought a recorder back by then.
+            const wait = Math.floor(Math.max(0, Math.min(1, this.random())) * REVIVE_JITTER_MS);
+            if (wait > 0)
+                await this.sleep(wait);
+            if (this.stopped)
+                return;
+            const rec = this.record(this.cwd);
+            // No record: `bir down` removed it (stopped on purpose, so it stays
+            // stopped), or no recorder ever ran here. A live pid: busy, or back.
+            if (!rec)
+                return;
+            if (this.alive(rec.pid)) {
+                this.recorderSeenAlive();
+                return;
+            }
+            const every = Math.min(REVIVE_EVERY_MS * 2 ** Math.min(this.revivesInARow, 10), REVIVE_MAX_EVERY_MS);
+            this.reviveNotBefore = this.now() + every;
+            if (!this.installed(this.cwd))
+                return;
+            const reach = await this.probe(rec.url);
+            // Something answers there (a recorder that has not rewritten the file
+            // yet), or it is slow to: not ours to replace.
+            if (reach !== "refused" || this.stopped)
+                return;
+            logLine("scenario.recorder_revive", {
+                pid: rec.pid,
+                url: rec.url,
+                why,
+                detail: "the project's recorder is gone mid-session; starting it again so its hooks answer",
+            });
+            this.revives += 1;
+            this.revivesInARow += 1;
+            this.lastReviveAt = this.now();
+            await this.launch(this.cwd);
+        }
+        catch (err) {
+            logLine("scenario.revive_failed", { error: errText(err) });
+        }
+        finally {
+            this.reviveBusy = false;
+        }
+    }
+}
+//# sourceMappingURL=scenario-liveness.js.map

package/dist/bin/scenario-stderr.d.ts

@@ -0,0 +1,43 @@
+/**
+ * scenario-stderr — how the `bir` MCP server (bir-scenario) reads the stderr
+ * of a `bir` it spawned for a scenario tool.
+ *
+ * Two kinds of line arrive there, mixed: `bir`'s audit lines
+ * (`[bir] <iso time> <event> …`), which belong in the log where `bir doctor`
+ * and a person look, and the sentences `bir` wrote for a person
+ * ("[bir] not signed in — run `bir login`"), which the model needs when the
+ * command failed. They are sorted line by line AS THEY ARRIVE: audit lines go
+ * straight on, and of the rest only the LAST so many characters are kept.
+ *
+ * WHY AS THEY ARRIVE, AND WHY THE LAST. Sorting after the exit, with the first
+ * 8 000 characters kept, lost exactly the line that mattered: with
+ * `BIR_VERBOSE=1` the audit lines filled the cap, and `bir`'s closing reason —
+ * the last thing it prints — never reached the model, which got "exited with
+ * code 1" and nothing to act on.
+ *
+ * Its own module so it can be tested: bir-scenario starts serving on import.
+ */
+/** `bir`'s own audit lines — for the log, not for the model. */
+export declare const AUDIT_LINE: RegExp;
+export interface StderrSorterOptions {
+    /** How much of the non-audit text is kept: the last this many characters. */
+    keepChars: number;
+    /** How much audit text is passed on, at most; the rest is dropped. */
+    forwardChars: number;
+    /** Where an audit line goes (one line, without its newline). Must not throw. */
+    forward: (line: string) => void;
+}
+export declare class StderrSorter {
+    private readonly opts;
+    private partial;
+    /** Where the rest of a line cut for length goes, once its start was sorted. */
+    private continuing;
+    private kept;
+    private forwarded;
+    constructor(opts: StderrSorterOptions);
+    push(chunk: string): void;
+    /** Everything that was not an audit line (the last of it), once the stream ended. */
+    end(): string;
+    private line;
+}
+//# sourceMappingURL=scenario-stderr.d.ts.map

package/dist/bin/scenario-stderr.js

@@ -0,0 +1,76 @@
+/**
+ * scenario-stderr — how the `bir` MCP server (bir-scenario) reads the stderr
+ * of a `bir` it spawned for a scenario tool.
+ *
+ * Two kinds of line arrive there, mixed: `bir`'s audit lines
+ * (`[bir] <iso time> <event> …`), which belong in the log where `bir doctor`
+ * and a person look, and the sentences `bir` wrote for a person
+ * ("[bir] not signed in — run `bir login`"), which the model needs when the
+ * command failed. They are sorted line by line AS THEY ARRIVE: audit lines go
+ * straight on, and of the rest only the LAST so many characters are kept.
+ *
+ * WHY AS THEY ARRIVE, AND WHY THE LAST. Sorting after the exit, with the first
+ * 8 000 characters kept, lost exactly the line that mattered: with
+ * `BIR_VERBOSE=1` the audit lines filled the cap, and `bir`'s closing reason —
+ * the last thing it prints — never reached the model, which got "exited with
+ * code 1" and nothing to act on.
+ *
+ * Its own module so it can be tested: bir-scenario starts serving on import.
+ */
+/** `bir`'s own audit lines — for the log, not for the model. */
+export const AUDIT_LINE = /^\[bir\] \d{4}-\d\d-\d\dT/;
+export class StderrSorter {
+    opts;
+    partial = "";
+    /** Where the rest of a line cut for length goes, once its start was sorted. */
+    continuing;
+    kept = "";
+    forwarded = 0;
+    constructor(opts) {
+        this.opts = opts;
+    }
+    push(chunk) {
+        const lines = `${this.partial}${chunk}`.split("\n");
+        this.partial = lines.pop() ?? "";
+        for (const line of lines) {
+            this.line(line);
+            this.continuing = undefined;
+        }
+        // A "line" with no end in sight is sorted in pieces rather than held whole.
+        if (this.partial.length > this.opts.keepChars) {
+            this.line(this.partial);
+            this.partial = "";
+        }
+    }
+    /** Everything that was not an audit line (the last of it), once the stream ended. */
+    end() {
+        if (this.partial !== "")
+            this.line(this.partial);
+        this.partial = "";
+        this.continuing = undefined;
+        return this.kept;
+    }
+    line(raw) {
+        const line = raw.replace(/\r$/, "");
+        const kind = this.continuing ?? (AUDIT_LINE.test(line) ? "audit" : "kept");
+        this.continuing = kind;
+        if (line.trim() === "")
+            return;
+        if (kind === "audit") {
+            if (this.forwarded >= this.opts.forwardChars)
+                return;
+            this.forwarded += line.length + 1;
+            try {
+                this.opts.forward(line);
+            }
+            catch {
+                // The log is gone; nothing to do about that here.
+            }
+            return;
+        }
+        this.kept += `${line}\n`;
+        if (this.kept.length > this.opts.keepChars)
+            this.kept = this.kept.slice(-this.opts.keepChars);
+    }
+}
+//# sourceMappingURL=scenario-stderr.js.map

package/dist/bin/service-read.d.ts

@@ -0,0 +1,88 @@
+/**
+ * service-read — what `bir scenario show|edits` and `bir investigate` share
+ * about asking the service and printing its answer, so a slow service, a
+ * signed-out machine or a large scenario never turns into a stall or a flood.
+ *
+ * WHY A BOUND OF THEIR OWN. The `service()` these commands are handed settles
+ * the service address with a `/health` probe, may refresh the session, and
+ * then makes its request; a service (or a corporate proxy in front of it) that
+ * accepts the connection and never answers held every one of those for as long
+ * as Node's fetch waits — measured at 120 s through the `bir` MCP server, which
+ * is 120 s of a turn stalled on a debugging tool. A read is safe to abandon:
+ * nothing was asked to change. So each one gets {@link readTimeoutMs} — a
+ * command that reads twice shares it between them ({@link ReadClock}) — and
+ * then an answer in words. Writes (`check`, `edit`, `undo`, `calc`) are not
+ * bounded here — abandoning one would leave "was it saved?" unanswerable — and
+ * the MCP server bounds the whole command instead.
+ *
+ * WHY COMPACT JSON UNDER THE MCP SERVER. The `bir` MCP server runs these
+ * commands with `BIR_MCP=1` and hands their `--json` output to the model.
+ * Indentation is for a person at a terminal; in a model's context it is a
+ * quarter of the tokens and none of the meaning.
+ */
+/** Default bound on one command's reads of the service. `BIR_READ_TIMEOUT_MS` overrides it. */
+export declare const DEFAULT_READ_TIMEOUT_MS = 15000;
+/**
+ * The most any timer here is set for from the environment. Node turns a delay
+ * past 2^31 - 1 ms into 1 ms, so a mistyped `BIR_READ_TIMEOUT_MS=3000000000`
+ * used to make every read give up at once; ten minutes is already far longer
+ * than anybody waits for a debugging tool.
+ */
+export declare const MAX_ENV_TIMEOUT_MS = 600000;
+/**
+ * A number of milliseconds from the environment: positive and at most
+ * {@link MAX_ENV_TIMEOUT_MS}, or `fallback`. Out of range is a mistake, and
+ * the default is the value known to work.
+ */
+export declare function envTimeoutMs(name: string, fallback: number): number;
+export declare function readTimeoutMs(): number;
+/** True when the `bir` MCP server ran this command for a model (it sets `BIR_MCP=1`). */
+export declare function underMcp(): boolean;
+/** `--json` output: indented for a person, compact for a model. */
+export declare function jsonText(value: unknown): string;
+/**
+ * `pending`, or `{ error }` when it takes longer than `ms`. The request itself
+ * is not cancelled — `bir` exits as soon as the command returns, which is what
+ * ends it — and a late rejection is observed here, so it can never surface as
+ * an unhandled one. `statedMs` is the bound the answer names, when `ms` is
+ * only what was left of it ({@link ReadClock}).
+ */
+export declare function readWithin<T>(pending: Promise<T | {
+    error: string;
+}>, ms?: number, statedMs?: number): Promise<T | {
+    error: string;
+}>;
+/**
+ * One command's reads of the service, sharing one bound. A command that reads
+ * twice — `scenario edits` on a `run_` id finds the scenario, then its
+ * history; `investigate` tries the matched run after a "no" — used to give
+ * each read the whole bound, so a service that answered the first slowly and
+ * held the second took twice as long as the `bir` MCP server allows a
+ * reading tool, and was killed there with none of the answer the command
+ * already had (the journal half of `investigate`, say). Sharing the bound
+ * keeps the whole command inside it, and the timeout still names the bound,
+ * not the scrap of it the last read had left.
+ */
+export declare class ReadClock {
+    readonly totalMs: number;
+    private readonly deadline;
+    constructor(totalMs?: number);
+    /** What is left of the bound, in ms (0 once it is spent). */
+    remaining(): number;
+    /** {@link readWithin}, with what is left of the command's bound. */
+    within<T>(pending: Promise<T | {
+        error: string;
+    }>): Promise<T | {
+        error: string;
+    }>;
+}
+/** Whether a `{ error }` means the service could not be reached at all, as opposed to answering. */
+export declare function unreachable(error: string): boolean;
+/**
+ * A failure to reach the service, in words a person (or a model) can act on.
+ * The transport's own words — "fetch failed", "This operation was aborted" —
+ * say nothing about what to do, so they are replaced; the sentences `bir`
+ * itself wrote ("not signed in — run `bir login`") are already the answer.
+ */
+export declare function serviceProblem(error: string): string;
+//# sourceMappingURL=service-read.d.ts.map