@basein/runner 0.1.0

package/dist/control/paths.js

@@ -0,0 +1,56 @@
+/**
+ * paths — where BaseInstRunner keeps its state on disk.
+ *
+ * One module so the discovery file, the credentials file and the install sidecar
+ * cannot drift apart, and so tests can redirect all three at once with
+ * `BIR_HOME`. Everything lives under `~/.baseinstrunner` (mode 0700), and no
+ * assumption is made about `$HOME` being set — Windows sets `USERPROFILE`
+ * instead, and `os.homedir()` already knows the difference.
+ */
+import { homedir } from "node:os";
+import { createHash } from "node:crypto";
+import { join } from "node:path";
+import { mkdirSync } from "node:fs";
+/** Root of BaseInstRunner's state. `BIR_HOME` overrides it (tests, sandboxes). */
+export function configDir() {
+    return process.env.BIR_HOME ?? join(homedir(), ".baseinstrunner");
+}
+/** Where control servers advertise themselves, one file per project cwd. */
+export function controlDir() {
+    return join(configDir(), "control");
+}
+/** The sidecar holding original MCP entries so `bir uninstall` can restore them. */
+export function installedPath() {
+    return join(configDir(), "installed.json");
+}
+/** Create a directory with restrictive permissions. Idempotent, never throws. */
+export function ensureDir(dir, mode = 0o700) {
+    try {
+        mkdirSync(dir, { recursive: true, mode });
+    }
+    catch {
+        /* already there, or unwritable — callers surface the later failure */
+    }
+}
+/**
+ * Separator- and case-normalised form of a path.
+ *
+ * Claude Code stores project keys with forward slashes on Windows while
+ * `process.cwd()` returns backslashes; comparing the literal strings is the
+ * number one cause of "the proxy is installed but never runs" (Phase 7.1). The
+ * same normalisation keys the discovery file, so a proxy started from
+ * `C:\proj` finds the control server registered by a hook reporting `C:/proj`.
+ */
+export function normalizePath(p) {
+    const slashed = p.replace(/\\/g, "/").replace(/\/+$/, "");
+    return process.platform === "win32" ? slashed.toLowerCase() : slashed;
+}
+/** The discovery key for a project directory: `sha256(normalised cwd)[0..16]`. */
+export function controlKey(cwd) {
+    return createHash("sha256").update(normalizePath(cwd)).digest("hex").slice(0, 16);
+}
+/** Absolute path of the discovery file for `cwd`. */
+export function discoveryPath(cwd) {
+    return join(controlDir(), `${controlKey(cwd)}.json`);
+}
+//# sourceMappingURL=paths.js.map

package/dist/control/server.d.ts

@@ -0,0 +1,272 @@
+/**
+ * control/server — the local control plane (Phase 5) and the Tier 1 recorder.
+ *
+ * WHY THIS EXISTS AT ALL (§3.2). Three proxies recording independently would
+ * produce three interleaved step streams with no shared ordering, and would
+ * double-record every call the hook also sees. One control server gives one
+ * `stepIndex` sequence, one run lifecycle, one HTTP chain to the recorder, and
+ * one place to dedupe.
+ *
+ * It is two things in one process, deliberately: the **Claude Code hook
+ * receiver** (Claude Code POSTs each lifecycle event to an HTTP hook) and the
+ * **control plane** the proxies report to. They share the run, so they must
+ * share the process.
+ *
+ * RUN BOUNDARIES follow RRepeat's: a Claude Code *session* holds many prompts,
+ * and each `UserPromptSubmit → Stop` turn is one run. Creation is deferred to
+ * the first prompt so the server's similar-prompt detection runs against the
+ * real prompt rather than an empty string; a proxy step that arrives before any
+ * prompt (an SDK session with no hooks) lazily opens a run with empty input,
+ * which is honest rather than lossy.
+ *
+ * SECURITY (§9): binds 127.0.0.1 only, requires the discovery file's bearer
+ * 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 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). */
+export interface HookPayload {
+    session_id?: string;
+    transcript_path?: string;
+    cwd?: string;
+    hook_event_name?: string;
+    prompt?: string;
+    tool_name?: string;
+    tool_input?: unknown;
+    tool_response?: unknown;
+    tool_use_id?: string;
+    error?: unknown;
+    agent_id?: string;
+}
+export interface ControlServerOptions {
+    recorder: Recorder;
+    /** Session working directory — keys the discovery file. */
+    cwd: string;
+    /** Preferred port; 0 (or a busy port) falls back to an ephemeral one. */
+    port?: number;
+    /** Loopback bearer token. Generated when omitted. */
+    token?: string;
+    /** Config keys of the servers a proxy wraps. Grows as proxies register. */
+    wrappedServers?: string[];
+    /** Host application, for run metadata. */
+    host?: {
+        app?: string;
+        version?: string;
+    };
+    /**
+     * What `PreToolUse` answers when it injects a correlation id.
+     *
+     * `"allow"` is what §6/Phase 6 specifies, and what makes injection reliable —
+     * but it also **auto-approves the call**, skipping a permission prompt the user
+     * might otherwise have seen. `"ask"` keeps the prompt at the cost of some hosts
+     * ignoring `updatedInput` on a non-allow decision (correlation then degrades to
+     * the fingerprint path). Set with `BIR_CORRELATION_DECISION`.
+     */
+    correlationDecision?: "allow" | "ask";
+    /** Disable id injection; use `(server, tool, hash(args))` matching instead. */
+    noCorrelation?: boolean;
+    /**
+     * Whether steps actually reach a service. Defaults to "the recorder is not a
+     * {@link NullRecorder}", which is right in every case so far.
+     *
+     * It is reported on `/health` because **this process is the only one that
+     * knows**: `bir doctor` runs in a different shell, with a different
+     * environment, and inferring it from `BIR_AUTH_URL` there once produced a
+     * confident "nothing will be recorded" on a session that was recording fine.
+     */
+    recording?: boolean;
+    /**
+     * Calculated replay (v2, docs/calculatedReplay.md). Omitted or
+     * `{ enabled: false }` leaves v1's behaviour exactly as it was: a match stops
+     * recording and nothing else happens.
+     */
+    replay?: ReplayOptions;
+}
+export interface ControlServerAddress {
+    url: string;
+    port: number;
+    token: string;
+    sessionId: string;
+}
+export declare class ControlServer {
+    readonly token: string;
+    readonly sessionId: string;
+    private readonly opts;
+    private readonly recorder;
+    private readonly queue;
+    private readonly sessions;
+    /** Config keys known to be wrapped: from install config plus live registrations. */
+    private readonly wrapped;
+    /** serverName → registration facts, for `bir doctor`. */
+    private readonly registrations;
+    private server?;
+    private address?;
+    private lossy;
+    /** Seals whose answer text is still being waited for. Awaited before any flush. */
+    private readonly pendingSeals;
+    /** Calculated replay. Inert unless `opts.replay.enabled`. */
+    private readonly replay;
+    constructor(opts: ControlServerOptions);
+    listen(): Promise<ControlServerAddress>;
+    close(): Promise<void>;
+    /** Facts for `bir doctor` / `GET /health`. */
+    health(): Record<string, unknown>;
+    private handle;
+    private send;
+    private readJson;
+    private ensureSession;
+    /** Open a run for `session`, or return the open one. */
+    private ensureRun;
+    private runMetadata;
+    /**
+     * A similar-prompt hit means the service created no run, so every later step
+     * post would 404. Stop recording it — that half is v1 and is mandatory.
+     *
+     * What replaces the recording is v2 (docs/calculatedReplay.md): the matched
+     * scenario is put through the gate ladder and, if every gate passes, armed as a
+     * plan. Memoized, because `ensureRun` is reached from five different hooks and
+     * arming twice would run the scenario twice.
+     *
+     * Resolves with the steering directive to inject, or undefined.
+     */
+    private watchForMatch;
+    /**
+     * Close the run's books, without waiting for the network.
+     *
+     * SEALING IS SPLIT FROM FLUSHING ON PURPOSE. `Stop` — the end of the turn, and
+     * the run boundary this whole design names — is a synchronous hook the session
+     * is waiting on, so it must not block on an HTTP flush. And `SessionEnd`, the
+     * event that used to be the *only* thing that finished a run, does not reliably
+     * arrive at all: it fires as the host process is exiting and loses the race.
+     * A run whose completeness depends on winning that race is a run that is
+     * routinely left half-open, which is what happened in practice.
+     *
+     * Idempotent: the second caller sees `finished` and does nothing.
+     */
+    private sealRun;
+    /**
+     * Report what a matched turn cost (docs/calculatedReplay.md §11).
+     *
+     * The live session's tokens come from the transcript **delta** since this run
+     * opened — never the whole file, which would bill run 3 for runs 1+2+3 and hand
+     * the ledger a baseline several times the truth (§11.4). A run with no
+     * watermark (one opened lazily by a proxy step, before any prompt) is reported
+     * `measured: false`: saying "unmeasured" is better than quietly inflating a
+     * baseline.
+     *
+     * Queued rather than awaited — `Stop` is a synchronous hook the session is
+     * waiting on, and a report is never worth a stall.
+     */
+    /**
+     * What this turn cost the model, from the transcript **delta** since the run
+     * opened — never the whole file, which would bill run 3 for runs 1+2+3
+     * (docs/calculatedReplay.md §11.4).
+     *
+     * No watermark means the delta is unknowable, so this reports `measured:
+     * false` and zero rather than a number that is confidently wrong.
+     */
+    private runCost;
+    private reportExecution;
+    /** Seal the run *and* wait for everything queued to reach the service. */
+    private finalizeRun;
+    private onSessionStart;
+    private onPrompt;
+    /**
+     * `PreToolUse`. Two shapes of answer:
+     *
+     *  - **Wrapped MCP tool** → mint a call id and ask Claude Code to carry it in
+     *    the tool's arguments, so the proxy's report and this hook's view join into
+     *    one step (Phase 6). No step is recorded yet: the proxy owns the result and
+     *    allocates the index when it reports.
+     *  - **Anything else** (built-ins, unwrapped MCP) → allocate the pair now and
+     *    record `tool_selected`. The hook is this step's only observer.
+     */
+    private onToolPre;
+    /**
+     * `PostToolUse` / `PostToolUseFailure`. For a built-in this closes the pair.
+     * For a correlated MCP call it normally does nothing — the proxy owns that
+     * result — but it arms a short fallback: if the proxy never reports (it died,
+     * 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 errorText;
+    /**
+     * `SubagentStart` / `SubagentStop`. These carry `agent_id`, which is the only
+     * way to tell a subagent's tool calls from the main thread's — Claude Code
+     * interleaves them into one hook stream otherwise.
+     *
+     * v1 attributes rather than partitions: the active agent id is remembered and
+     * prefixed onto each step's `context`, because the recording schema has no
+     * agent column and inventing one server-side is out of scope (D6). The
+     * partition is available in the audit log for anyone who needs it sooner.
+     */
+    private onAgent;
+    private onStop;
+    private onSessionEnd;
+    private onProxyRegister;
+    /**
+     * `POST /proxy/poll` — the control→proxy channel (docs/calculatedReplay.md §16.2).
+     *
+     * The proxy dials out and parks; the server answers with work, or empty at the
+     * hold deadline so the proxy re-polls. Keeping the direction outbound is what
+     * avoids N new loopback listeners and N new tokens for a latency saving that
+     * would be invisible next to the upstream's own round trip (D12).
+     */
+    private onProxyPoll;
+    /** `POST /proxy/result` — the answer to one dispatched `tools/call`. */
+    private onProxyResult;
+    /**
+     * `POST /scenario/run` — `bir-scenario` asking for the armed plan to run.
+     *
+     * This is `direct` mode's whole execution: every step goes to the proxy that
+     * already owns its upstream, so the model spends nothing beyond the turn that
+     * reads the results. There is no hook timeout here, which is exactly why the
+     * derivation wait was deferred to it (§10).
+     */
+    private onScenarioRun;
+    /**
+     * `POST /scenario/replay` — `bir replay`, i.e. a scenario nobody matched.
+     *
+     * The CLI holds the credentials, so it fetches the scenario and posts it here;
+     * this process holds the proxies, so it runs it. Enabled independently of
+     * `BIR_REPLAY`: the operator typed a scenario id, which is a far more explicit
+     * consent than a similarity score, and the gate that flag guards is automatic
+     * arming rather than execution itself.
+     */
+    private onScenarioReplay;
+    /**
+     * A proxy's `ProxyStepReport`. Three joins, tried in order:
+     *   1. the injected `callId` (Tier 1, exact);
+     *   2. the fingerprint, inside a 30 s window (`--no-correlation`, lossy under
+     *      identical concurrent calls — §6 says so, and so does this code);
+     *   3. nothing — record it standalone, which is what an SDK session with no
+     *      hooks produces and is a complete MCP step in its own right.
+     */
+    private onProxyStep;
+    /**
+     * Which session a proxy's step belongs to.
+     *
+     * A proxy has no session id of its own — stdio MCP servers are never told one
+     * — so the control server decides. The order matters: preferring *any known*
+     * session over minting a new one is what stops a step that lands between
+     * `SessionStart` and the first prompt from opening a second, parallel run,
+     * which would split one session's steps across two recordings.
+     */
+    private sessionForProxyStep;
+    private matchByFingerprint;
+    /** Record the merged pair for a correlation and latch it against re-entry. */
+    private settle;
+    /** The one place a tool step pair is written. Redaction and caps live here. */
+    private record;
+}
+/**
+ * The port `bir install` writes into the hook URLs, and the one `bir-hooks`
+ * prefers. Claude Code's `settings.json` needs a *static* URL, so the control
+ * server cannot be purely ephemeral: it asks for this port and falls back to an
+ * ephemeral one only if it is taken — in which case the installed hooks point at
+ * a port nobody is listening on, and both `bir-hooks` and `bir doctor` say so.
+ */
+export declare const DEFAULT_CONTROL_PORT = 53411;
+//# sourceMappingURL=server.d.ts.map