agent-shim 7.7.0 → 7.9.0

package/dist/types/credential.d.ts

@@ -0,0 +1,136 @@
+import type { Credential, CredentialSource, CredentialTarget, CredentialTargetVar } from "./config/schema";
+import { type CredentialCachePort } from "./credentialCache";
+/** The exit status for a launch whose selected provider or identity has a credential block none of whose sources yields a token: 64, the conventional `EX_USAGE`, because the invocation asked for a credential the environment cannot supply. */
+export declare const CREDENTIAL_UNAVAILABLE_EXIT = 64;
+/** How long a non-interactive credential command may run. Secret-store CLIs answer from a local cache or agent well within a second, so this leaves a wide margin while still failing a wedged command quickly instead of stalling the launch. */
+export declare const CREDENTIAL_COMMAND_TIMEOUT_MS = 10000;
+/** How long an interactive credential command may run: long enough for a person to notice and approve a biometric or password prompt, short enough that a prompt nobody is watching fails the launch rather than hanging it. */
+export declare const CREDENTIAL_INTERACTIVE_TIMEOUT_MS = 120000;
+/** What reading one `file` source found: nothing at that path, or its contents and permission bits. `mode` is undefined on a platform with no POSIX permission bits (Windows), where the looseness check cannot apply. */
+type SecretFileRead = {
+    readonly found: false;
+} | {
+    readonly found: true;
+    readonly content: string;
+    readonly mode: number | undefined;
+};
+/** The outcome of one credential command. `stderr` is empty for an interactive run, whose stderr goes to the terminal so a person sees any prompt. */
+export interface CredentialCommandResult {
+    readonly status: number | null;
+    readonly stdout: string;
+    readonly stderr: string;
+    readonly timedOut: boolean;
+}
+/**
+ * Everything resolving a credential needs from the outside world, injected so the resolver (and every launcher test) runs without `op`, the Keychain, real secret files or a terminal. `src/realPorts.ts` wires the real one; tests wire a fake.
+ */
+export interface CredentialPort {
+    /** Reads a `file` source's path (absolute or `~`-rooted). */
+    readonly readSecretFile: (filePath: string) => SecretFileRead;
+    /** Runs a command source's argv directly (no shell) under a timeout, capturing stdout. An interactive run inherits the terminal's stdin and stderr so a person can answer a prompt. */
+    readonly runCommand: (argv: readonly [string, ...string[]], options: {
+        readonly timeoutMs: number;
+        readonly interactive: boolean;
+    }) => CredentialCommandResult;
+    /** Whether a person can answer a prompt now: standard input is a terminal, or there is a desktop session to show a dialog in. */
+    readonly personPresent: () => boolean;
+    /** Where cached credentials live, used only for a credential block that asks for caching. Omit to resolve every launch from the sources. */
+    readonly cache?: CredentialCacheEnv;
+}
+/** The sources that run a command: `command` itself and the two presets that compile to one. */
+type CommandBackedSource = Extract<CredentialSource, {
+    readonly command: unknown;
+} | {
+    readonly op: unknown;
+} | {
+    readonly keychain: unknown;
+}>;
+/**
+ * The argv a command-backed source runs, with the `op` and `keychain` presets compiled to theirs: `op read <ref>` and `security find-generic-password -s <service> [-a <account>] -w`.
+ */
+export declare function commandArgv(source: CommandBackedSource): readonly [string, ...string[]];
+/**
+ * Whether a source needs a person present. An explicit `interactive` always wins. Otherwise only `op` defaults to interactive, because the desktop app's integration asks for approval, unless `OP_SERVICE_ACCOUNT_TOKEN` is set, in which case `op` authenticates as the service account with nobody asked. A plain `command` and a `keychain` read default to non-interactive: a Keychain item whose access list already trusts `security` reads silently, and one that does not fails at once with "User interaction is not allowed" rather than hanging.
+ */
+export declare function isInteractiveSource(source: CredentialSource, env: Readonly<Record<string, string | undefined>>): boolean;
+/** One source as `check`, `doctor` and every `--json` output report it: its kind plus the same non-secret identifying detail `describeSource` prints. */
+type CredentialSourceSummary = {
+    readonly kind: "env";
+    readonly variable: string;
+} | {
+    readonly kind: "file";
+    readonly path: string;
+} | {
+    readonly kind: "command";
+    readonly program: string;
+} | {
+    readonly kind: "op";
+    readonly reference: string;
+} | {
+    readonly kind: "keychain";
+    readonly service: string;
+    readonly account?: string;
+} | {
+    readonly kind: "literal";
+};
+/** A credential block as it is reported: its effective target and each source's summary, in order. */
+export interface CredentialSummary {
+    readonly target: CredentialTarget;
+    readonly sources: readonly CredentialSourceSummary[];
+    /** The block's cache setting when it asks for caching: how long a token is kept (absent for no expiry) and where. */
+    readonly cache?: {
+        readonly ttl?: string;
+        readonly store?: string;
+    };
+}
+/** Summarises a credential block for reporting, with `target` resolved to its default. */
+export declare function summariseCredential(credential: Credential): CredentialSummary;
+/** Renders a source for a message, as `formatSourceSummary` does its summary. */
+export declare function describeSource(source: CredentialSource): string;
+/** Renders a credential summary on one line for human-readable output: `bearer from env Z_API_TOKEN, then op op://...`. */
+export declare function formatCredentialSummary(summary: CredentialSummary): string;
+/** Renders a credential block on one line, as `formatCredentialSummary` does its summary. */
+export declare function describeCredential(credential: Credential): string;
+/** Inputs to `resolveCredential`. */
+export interface ResolveCredentialParams {
+    readonly credential: Credential;
+    /** The launching environment: where `env` sources are read, and what decides whether `op` is interactive. */
+    readonly env: Readonly<Record<string, string | undefined>>;
+    readonly port: CredentialPort;
+    /** What the credential belongs to, for messages and as its cache key: `provider z` or `identity work`. */
+    readonly subject: string;
+    /** True to skip a cached token and fetch from the sources, replacing the cached copy: what `credential warm` does. */
+    readonly refresh?: boolean;
+}
+/** What caching a credential needs beyond the block's own `cache` setting: the port holding entries, the platform that picks the default store, and the clock the TTL is measured on. */
+export interface CredentialCacheEnv {
+    readonly port: CredentialCachePort;
+    readonly platform: NodeJS.Platform;
+    readonly now: () => number;
+}
+/** A resolved credential: the token, where it goes, and which source produced it. `warnings` carries any source refused on the way for a reason worth reporting (a secret file with loose permissions). */
+export interface ResolvedCredential {
+    readonly target: CredentialTarget;
+    readonly token: string;
+    readonly source: CredentialSource;
+    readonly warnings: readonly string[];
+    /** When the token was fetched, if it came from the cache rather than a source; undefined for a live fetch. */
+    readonly cachedAt?: number;
+}
+/** The outcome of `resolveCredential`: a resolved credential, or a message naming every source and why none yielded a token. */
+export type CredentialResolution = {
+    readonly ok: true;
+    readonly credential: ResolvedCredential;
+} | {
+    readonly ok: false;
+    readonly message: string;
+};
+/**
+ * Resolves a credential block: a fresh cached token if the block caches one, else tries each source in order and returns the first non-empty token, with the block's target, storing it when the block caches. When none yields one, the message names every source and why, and never a value; for a caching block it also names the command that fills the cache from a terminal. Pure over its injected ports.
+ */
+export declare function resolveCredential(params: ResolveCredentialParams): CredentialResolution;
+/**
+ * The credential variables a child environment gets for a resolved token: the target's variable set to the token, and the other two set to undefined so that merging this over an environment removes them, and an ambient one inherited from the parent can neither outrank nor sit alongside the credential agent-shim chose. Removing a variable (rather than setting it to the empty string) leaves nothing for Claude Code to interpret.
+ */
+export declare function credentialVariables(target: CredentialTarget, token: string): Record<CredentialTargetVar, string | undefined>;
+export {};

package/dist/types/credentialCache.d.ts

@@ -0,0 +1,46 @@
+import { z } from "zod";
+import { type CredentialCache, type CredentialCacheStore } from "./config/schema";
+/** What a cache stores for one credential: the token, when it was fetched, and the source that produced it (a non-secret descriptor, kept so `check` and the launch log can still say where the token came from). */
+export declare const CachedCredentialSchema: z.ZodObject<{
+    token: z.ZodString;
+    fetchedAt: z.ZodNumber;
+    source: z.ZodUnion<readonly [z.ZodObject<{
+        env: z.ZodString;
+    }, z.core.$strict>, z.ZodObject<{
+        file: z.ZodString;
+    }, z.core.$strict>, z.ZodObject<{
+        interactive: z.ZodOptional<z.ZodBoolean>;
+        timeoutMs: z.ZodOptional<z.ZodInt>;
+        command: z.ZodTuple<[z.ZodString], z.ZodString>;
+    }, z.core.$strict>, z.ZodObject<{
+        interactive: z.ZodOptional<z.ZodBoolean>;
+        timeoutMs: z.ZodOptional<z.ZodInt>;
+        op: z.ZodString;
+    }, z.core.$strict>, z.ZodObject<{
+        interactive: z.ZodOptional<z.ZodBoolean>;
+        timeoutMs: z.ZodOptional<z.ZodInt>;
+        keychain: z.ZodObject<{
+            service: z.ZodString;
+            account: z.ZodOptional<z.ZodString>;
+        }, z.core.$strict>;
+    }, z.core.$strict>, z.ZodObject<{
+        literal: z.ZodString;
+    }, z.core.$strict>]>;
+}, z.core.$strict>;
+export type CachedCredential = z.infer<typeof CachedCredentialSchema>;
+/**
+ * Where cached credentials live, injected so resolution and its tests need neither the Keychain nor a real directory. `owner` names what the credential belongs to (`identity work`, `provider z`) and is the entry's key; `store` picks the backing store. `read` returns undefined for a missing or unreadable entry, since an entry that cannot be used is the same as no entry.
+ */
+export interface CredentialCachePort {
+    readonly read: (store: CredentialCacheStore, owner: string) => CachedCredential | undefined;
+    readonly write: (store: CredentialCacheStore, owner: string, entry: CachedCredential) => void;
+    readonly remove: (store: CredentialCacheStore, owner: string) => void;
+}
+/** The store a block uses: its own choice, else the Keychain on macOS and a file elsewhere. */
+export declare function effectiveStore(cache: Readonly<CredentialCache>, platform: NodeJS.Platform): CredentialCacheStore;
+/** A `ttl` such as `12h` in milliseconds, or undefined for no expiry. */
+export declare function ttlMs(cache: Readonly<CredentialCache>): number | undefined;
+/** Whether a cached entry is still within its TTL at `now`. A cache with no TTL never expires; an entry stamped in the future (a clock that moved back) is treated as expired. */
+export declare function isFresh(entry: CachedCredential, cache: Readonly<CredentialCache>, now: number): boolean;
+/** How old a cached entry is, for `check` and `doctor` to report without the value. */
+export declare function cacheAgeMs(entry: CachedCredential, now: number): number;

package/dist/types/directoryRulesStore.d.ts

@@ -0,0 +1,43 @@
+import { type DirectoryRule, type DirectoryRules } from "./config/schema";
+import { CliError } from "./cliError";
+import type { LayoutPaths } from "./paths";
+/** Raised by `removeDirectoryRule`, `updateDirectoryRule` and `rule show` when no rule matches the given path exactly. */
+export declare class DirectoryRuleNotFoundError extends CliError {
+    readonly rulePath: string;
+    constructor(rulePath: string);
+}
+/** Raised by `addDirectoryRule` when neither `--config-profile` nor `--identity` is given, and by `updateDirectoryRule` when an update would leave a rule that sets nothing at all: a rule that pins and overrides nothing would do nothing. */
+export declare class DirectoryRuleMissingTargetError extends CliError {
+    constructor();
+}
+/** Raised by `addDirectoryRule` when a rule for the exact path already exists: `rule add` creates, `rule set` updates. */
+export declare class DirectoryRuleAlreadyExistsError extends CliError {
+    readonly rulePath: string;
+    constructor(rulePath: string);
+}
+/** Reads `~/.agent-shim/directory-rules.json`, or an empty rule set when the file does not exist yet. */
+export declare function readDirectoryRules(paths: LayoutPaths): DirectoryRules;
+/** Validates and writes the whole `~/.agent-shim/directory-rules.json` file. Exported so `src/configure.ts` can update a single rule's `categories`/`entries` in place without duplicating this validate-then-write step. Throws `ConfigValidationError` when `rules` fails `DirectoryRulesSchema`, rather than letting the underlying `ZodError` escape as an unhandled crash. */
+export declare function writeDirectoryRules(paths: LayoutPaths, rules: DirectoryRules): void;
+/** Lists every directory rule, in file order. */
+export declare function listDirectoryRules(paths: LayoutPaths): readonly DirectoryRule[];
+/** Inputs to `addDirectoryRule` beyond the path itself. */
+export interface AddDirectoryRuleOptions {
+    readonly configProfile?: string;
+    readonly identity?: string;
+}
+/**
+ * Adds a new directory rule for `rulePath`. Throws `DirectoryRuleAlreadyExistsError` when a rule for that exact path already exists (`updateDirectoryRule` changes one), and `DirectoryRuleMissingTargetError` when neither `configProfile` nor `identity` is given, since a rule that pins neither would do nothing.
+ */
+export declare function addDirectoryRule(paths: LayoutPaths, rulePath: string, options: AddDirectoryRuleOptions): DirectoryRule;
+/** The fields `updateDirectoryRule` changes. A value of `false` removes that field from the rule. */
+export interface UpdateDirectoryRuleOptions {
+    readonly configProfile?: string | false;
+    readonly identity?: string | false;
+}
+/**
+ * Updates the existing directory rule for `rulePath` in place, keeping its position in the file and every field not named. Throws `DirectoryRuleNotFoundError` when no rule matches that exact path, and `DirectoryRuleMissingTargetError` when the update would leave a rule that does nothing (remove it with `removeDirectoryRule` instead).
+ */
+export declare function updateDirectoryRule(paths: LayoutPaths, rulePath: string, options: UpdateDirectoryRuleOptions): DirectoryRule;
+/** Removes the directory rule for `rulePath`. Throws `DirectoryRuleNotFoundError` when no rule matches that exact path. */
+export declare function removeDirectoryRule(paths: LayoutPaths, rulePath: string): void;

package/dist/types/doctorReport.d.ts

@@ -0,0 +1,117 @@
+import { type ClaudeShimState, type PathShadowStatus } from "./claudeShim";
+import type { LayoutPaths } from "./paths";
+import type { RunPort } from "./launcher/ports";
+import type { DiscoveredClaudeBinary } from "./versionDiscovery";
+type DoctorSeverity = "pass" | "warn" | "fail";
+type DoctorSection = "ambient-credential" | "binary-discovery" | "claude-shim" | "path-resolution" | "legacy-name" | "config-profile" | "identity" | "pool" | "provider" | "keychain" | "directory-rules" | "global-config" | "categories-local" | "active-identity" | "headroom";
+/** One line of `agent-shim doctor`'s report. `subject` names the identity/profile/rule the finding is about, when the section has more than one of those. */
+interface DoctorFinding {
+    readonly section: DoctorSection;
+    readonly subject?: string;
+    readonly severity: DoctorSeverity;
+    readonly message: string;
+}
+/** The full result of `runDoctor`. `ok` is false iff any finding is a `fail` — a `warn` never fails the report on its own. */
+export interface DoctorReport {
+    readonly findings: readonly DoctorFinding[];
+    readonly ok: boolean;
+}
+/** One identity's raw `identity.json`, unparsed — `runDoctor` does its own JSON.parse/schema validation so one malformed file never aborts the rest of the report. */
+export interface DoctorIdentityInput {
+    readonly name: string;
+    readonly path: string;
+    readonly raw: string | undefined;
+    /** The identity's own farm root (`identitiesDir/<name>`) — the account name the Keychain lookup uses. */
+    readonly farmRoot: string;
+}
+/** One configuration profile's raw `<name>.json`, unparsed. */
+export interface DoctorConfigProfileInput {
+    readonly name: string;
+    readonly path: string;
+    readonly raw: string | undefined;
+}
+/** One provider's raw `<name>.json`, unparsed. */
+export interface DoctorProviderInput {
+    readonly name: string;
+    readonly path: string;
+    readonly raw: string | undefined;
+}
+/** A single optional top-level file `runDoctor` validates against a schema when present — absent is a legitimate, unconfigured state, not a failure. */
+interface DoctorFileInput {
+    readonly path: string;
+    readonly raw: string | undefined;
+}
+/** The outcome of resolving the real Claude Code binary, pre-resolved by the wiring layer since `discoverClaudeBinary` is not itself a parse-shaped pure operation and already has its own dedicated test coverage. */
+type DoctorBinaryDiscovery = {
+    readonly ok: true;
+    readonly binary: DiscoveredClaudeBinary;
+} | {
+    readonly ok: false;
+    readonly message: string;
+};
+/**
+ * Where a bare command name resolves for the two names this tool owns.
+ *
+ * `ownExecutablePath` is this process's own PATH-visible location (`realOwnExecutablePath()`); `agentShim` is `findPathShadow`'s verdict for a bare `agent-shim` against the directory that executable lives in. `claude` is only populated when a shim is actually enabled — without one, a `claude` on PATH is Claude Code's own binary, which is not a shadow of anything.
+ */
+interface DoctorPathResolution {
+    readonly ownExecutablePath: string;
+    readonly agentShim: PathShadowStatus;
+    readonly claude?: PathShadowStatus;
+}
+/**
+ * Collapses a `shadowed` verdict back to `ok` when the shadowing entry and this executable are literally the same file reached by two names — `findPathShadow` compares *directories*, so a symlink on PATH pointing at the running executable's own real location otherwise reads as a shadow of itself.
+ *
+ * `realpath` must resolve symlinks, and must return its argument unchanged rather than throwing when the path cannot be resolved (a broken symlink, a race with an uninstall), so an unresolvable path simply stays unequal and the shadow verdict stands.
+ */
+export declare function refinePathShadow(status: PathShadowStatus, ownExecutablePath: string, realpath: (target: string) => string): PathShadowStatus;
+/** Everything `runDoctor` needs, all of it already loaded/injected — nothing in `runDoctor` itself reads a file, shells out, or touches the farm. */
+export interface RunDoctorParams {
+    readonly env: Readonly<Record<string, string | undefined>>;
+    readonly identities: readonly DoctorIdentityInput[];
+    readonly configProfiles: readonly DoctorConfigProfileInput[];
+    readonly providers: readonly DoctorProviderInput[];
+    readonly directoryRules: DoctorFileInput;
+    readonly globalConfig: DoctorFileInput;
+    readonly categoriesLocal: DoctorFileInput;
+    readonly activeIdentity: DoctorFileInput;
+    readonly binaryDiscovery: DoctorBinaryDiscovery;
+    /** Whether `agent-shim shim enable` has been run, and whether its recorded target still exists on disk — pre-resolved by the wiring layer, since checking a file's existence is real I/O, not a parse-shaped pure operation. */
+    readonly claudeShim: {
+        readonly state: ClaudeShimState | undefined;
+        readonly targetExists: boolean;
+    };
+    /** Which executables a bare `agent-shim` (and, when the shim is enabled, a bare `claude`) would actually run — pre-resolved by the wiring layer, since scanning PATH is real I/O. */
+    readonly pathResolution: DoctorPathResolution;
+    /** The resolved state root (`paths.root`), whose directory name says whether this installation still lives under the former `.claude-use` name. */
+    readonly rootPath: string;
+    /** Runs `security find-generic-password` for the per-identity Keychain check. Omit to skip that check entirely (e.g. off macOS). */
+    readonly run?: RunPort;
+    /** `process.platform` in real use; the Keychain check only ever runs when this is `"darwin"`. */
+    readonly platform: string;
+    /** The headroom daemon's state.json plus a zombie-aware liveness predicate for the pids it names (a defunct daemon holds no port but still answers signal 0). Omit the raw text when the daemon has never run; that is a pass, not a failure. */
+    readonly headroom: {
+        readonly state: DoctorFileInput;
+        readonly isRunning: (pid: number) => boolean;
+    };
+}
+/**
+ * Audits the whole `~/.agent-shim` config graph for internal consistency: every identity, every configuration profile's own `extends` chain, every provider, `directory-rules.json`, `config.json`, `categories.local.json`, `active-identity`, plus real Claude Code binary discoverability and ambient-credential exposure.
+ *
+ * Deliberately identity/directory-agnostic, unlike `runCheck` — there is no single cascade to resolve `doctor` against, so it never touches settings-exposure (which only means anything relative to one resolved cascade).
+ *
+ * Every check aggregates rather than throws: a malformed file becomes one `fail` finding for that file, not an aborted report. This is the one place in the codebase that deliberately breaks the "throw a validation error and let it propagate" convention every other command relies on — `doctor`'s whole purpose is to survive a broken file and keep auditing everything else.
+ */
+export declare function runDoctor(params: RunDoctorParams): DoctorReport;
+/** Renders a full `DoctorReport` as plain text lines, one section header at a time, in the order `agent-shim doctor` prints them. */
+export declare function formatDoctorReport(report: DoctorReport): string[];
+/** What `collectDoctorReport` needs from its caller. */
+export interface CollectDoctorReportParams {
+    readonly paths: LayoutPaths;
+    readonly env: NodeJS.ProcessEnv;
+}
+/**
+ * Audits the whole state root against this machine: the edge adapter that enumerates every identity, configuration profile and provider on disk, reads every top-level config file as raw text (never pre-parsing, so one malformed file cannot abort the report), discovers the real Claude Code binary and resolves where a bare command name runs from, and hands the facts to the pure `runDoctor`.
+ */
+export declare function collectDoctorReport(params: CollectDoctorReportParams): DoctorReport;
+export {};

package/dist/types/frontdoor/custody.d.ts

@@ -0,0 +1,32 @@
+import type { IncomingHttpHeaders } from "node:http";
+/** What stands in for a credential while its request crosses headroom: an opaque word that authenticates nothing anywhere. */
+export declare const SEQUESTERED_CREDENTIAL = "agent-shim-sequestered";
+/** The credential headers one custody record holds, exactly as the client sent them. */
+type HeldCredentials = Readonly<Record<string, string | readonly string[]>>;
+/** One request's headers with its credentials swapped out, and the id that redeems them. */
+interface Sequestered {
+    readonly hopId: string;
+    readonly headers: Record<string, string | string[] | undefined>;
+}
+/**
+ * Holds a provider session's real credentials in this process's memory while its request takes the headroom hop, so the credential never crosses headroom or the plain-HTTP leg back to the door.
+ *
+ * The hop calls `sequester`, sends headroom the placeholder headers plus the hop id, and calls `release` once its response to the client has finished or the client has gone. The direct listener calls `redeem` with the hop id and the provider its request path names: a live id recorded for that same provider yields the real headers, anything else yields nothing and the request is refused. A process that binds the direct port therefore receives only placeholders and an id that is worthless once the hop ends, and nothing outside this process can mint an id.
+ *
+ * An id stays redeemable for the whole hop rather than exactly once, because headroom legitimately sends one client request upstream more than once: it retries 429, 529 and 5xx answers, and its memory-tool and CCR continuations call the upstream again inside the same client turn, all with the headers it was handed.
+ */
+export interface CredentialCustody {
+    /** Takes custody of `headers`' credential headers for one hop to `provider`, returning the headers to send headroom (placeholders where the credentials were) and the hop id that redeems them. */
+    readonly sequester: (headers: Readonly<IncomingHttpHeaders>, provider: string) => Sequestered;
+    /** Ends a hop: its id stops redeeming. Idempotent. */
+    readonly release: (hopId: string) => void;
+    /** The real credential headers for a live hop to `provider`, or undefined for an unknown, released or mismatched id. */
+    readonly redeem: (hopId: string, provider: string) => HeldCredentials | undefined;
+}
+/** Creates an empty custody store. `randomId` must be unguessable (a v4 UUID or better): the id is the only thing that redeems a credential. */
+export declare function createCredentialCustody(randomId: () => string): CredentialCustody;
+/**
+ * The headers a redeemed request is routed with: every credential header headroom forwarded (placeholders, or anything else headroom chose to send) is dropped, and the held originals take their place. Whatever the hop's request carried in those headers is never trusted; only what the client sent is.
+ */
+export declare function restoreCredentials(headers: Readonly<IncomingHttpHeaders>, credentials: HeldCredentials): IncomingHttpHeaders;
+export {};

package/dist/types/frontdoor/headroomHop.d.ts

@@ -0,0 +1,22 @@
+import type { CredentialCustody } from "./custody";
+import { type RoutedRequest, type RoutedResponse } from "./route";
+/** Everything the headroom hop depends on, injected so the pipeline's ordering tests can point it at a scripted daemon. */
+export interface HeadroomHopDeps {
+    /**
+     * The headroom daemon's loopback port, read per request rather than captured at start-up: the daemon can crash and restart on a different port while this door keeps listening, and the hop must follow it. Undefined while the daemon is down (the restart window).
+     */
+    readonly headroomPort: () => number | undefined;
+    /**
+     * The per-generation secret the direct listener requires on what the hop forwards back. Headroom passes non-x-headroom headers through untouched, so the secret survives the round trip and arrives where this process can check it, while no loopback process outside this door ever holds it.
+     */
+    readonly hopSecret: string;
+    /** Holds a provider session's real credentials while its request crosses headroom; the direct listener redeems them by the hop id. */
+    readonly custody: CredentialCustody;
+    readonly log: (line: string) => void;
+}
+/**
+ * Applies the headroom hop: forwards the request, still Anthropic-shaped, to the headroom daemon as a backend hop and streams its response back to the client. The hop ALWAYS sits before the route's own serving (a translator needs the request headroom has compressed, never the reverse), which is why this runs in the pipeline and not inside any route.
+ *
+ * `upstream` is what headroom is told to forward to once it has done its work (its per-request base URL header). When it is set it is always this door's direct listener (every provider route declares exactly that), and the provider credential is then taken into custody for the hop: headroom receives placeholders and a hop id, and the direct listener restores the real headers when headroom forwards the request back. Neither headroom nor anything that binds a port on that plain-HTTP round trip ever holds the credential. Undefined leaves headroom's default upstream (Claude Code's API) in charge, which is exactly what an OAuth session wants, and the OAuth bearer then passes through untouched: headroom forwards it straight to that API, never back here, and uses it for its subscription tracking. The session's project identity is re-set here, and only here: the identity step stripped it from everything that leaves the machine, and headroom is the one consumer that needs it.
+ */
+export declare function applyHeadroomHop(request: RoutedRequest, response: RoutedResponse, upstream: string | undefined, deps: HeadroomHopDeps): Promise<void>;

package/dist/types/frontdoor/pipeline.d.ts

@@ -0,0 +1,109 @@
+import type { IncomingHttpHeaders, IncomingMessage, ServerResponse } from "node:http";
+import { type HeadroomHopDeps } from "./headroomHop";
+import { type FrontDoorRoute, type RoutedRequest, type RoutedResponse, type SessionIdentity } from "./route";
+/** What one routed response looked like as it started back to the client: the typed event response middleware observes. */
+export interface RoutedResponseEvent {
+    readonly session: SessionIdentity;
+    /** The route that served the response. */
+    readonly route: string;
+    /** The request's method. */
+    readonly method: string;
+    /** The request target's path, without its query string. */
+    readonly path: string;
+    /** When the pipeline received the request, in epoch milliseconds from the injected clock. */
+    readonly receivedAt: number;
+    readonly status: number;
+    readonly headers: Readonly<Record<string, string>>;
+}
+/** How a routed response's body finished: written to the end, or cut short (the client went away, or the route destroyed the response after an upstream failure). */
+export type ResponseOutcome = "completed" | "aborted";
+/**
+ * Follows one response's body as the client receives it. `chunk` sees each chunk after it has been handed to the client's socket, so observing never holds a byte back; `end` is called exactly once, when the body has finished either way. Like the observer that returned it, a body observer that throws is logged and dropped for the rest of that response, never allowed to break it.
+ */
+export interface ResponseBodyObserver {
+    readonly chunk: (chunk: Uint8Array) => void;
+    readonly end: (outcome: ResponseOutcome) => void;
+}
+/**
+ * Response middleware: called once per routed response, in registration order, once the route's response head is known and before any of it is written to the client. It returns a body observer when it wants to follow the body, or undefined when the head was all it needed. Observing must be side-effect-only: an observer that throws is logged and skipped, never allowed to break routing, and an observer must not block the response.
+ *
+ * Usage tracking registers here (see `src/usage/middleware.ts`): the head carries the rate-limit headers, and the body carries the token usage.
+ */
+export type ResponseObserver = (event: RoutedResponseEvent) => ResponseBodyObserver | undefined;
+/** The outcome of resolving a request's target to a route. */
+export type RouteResolution = {
+    readonly ok: true;
+    readonly route: FrontDoorRoute;
+} | {
+    readonly ok: false;
+    readonly status: number;
+    readonly message: string;
+};
+/** Everything the ordered pipeline depends on, injected so it runs against fakes in tests. */
+export interface PipelineDeps {
+    /** Resolves the route a request's target names, reading whatever configuration the route needs. */
+    readonly resolveRoute: (request: RoutedRequest) => Promise<RouteResolution>;
+    /** The response middleware chain, run in order at each response head. This is where usage capture registers. */
+    readonly responseObservers: readonly ResponseObserver[];
+    /**
+     * The headroom hop, applied BEFORE a route whose declaration admits it whenever the session's launch resolved headroom on: headroom needs the Anthropic-shaped request, so it always sits in front of a translator, never behind one. Omitted by a listener that serves routes directly (the direct listener headroom forwards an in-process route back to), or when no headroom is wired.
+     */
+    readonly headroom?: HeadroomHopDeps;
+    /** The clock response middleware times requests by, in epoch milliseconds. */
+    readonly now: () => number;
+    readonly log: (line: string) => void;
+    /**
+     * The listener's admission step, run after identification and before anything is routed: it decides whether the request may be routed at all and with which headers. A client-facing listener admits a request carrying the per-launch capability of a live registered session, unchanged; the direct listener admits only what this process's own headroom hop sent back (the generation's hop secret plus a live custody id for the provider the path names) and swaps the hop's placeholder credentials for the real ones. A refused request is answered 401 without ever reaching a route, so a loopback process that never launched through agent-shim cannot spend a session's credentials or quota.
+     */
+    readonly admit: (request: AdmissionRequest) => Admission;
+}
+/** What the admission step sees of one request. */
+interface AdmissionRequest {
+    /** The request target exactly as received. */
+    readonly url: string;
+    /** Every header as received, internal ones included: the capability and hop headers live here. */
+    readonly headers: Readonly<IncomingHttpHeaders>;
+    /** The headers the identity step judged forwardable, internal ones stripped. */
+    readonly forwardable: Readonly<IncomingHttpHeaders>;
+}
+/** The admission step's verdict: route with these headers, or refuse with this message. */
+type Admission = {
+    readonly ok: true;
+    readonly headers: IncomingHttpHeaders;
+} | {
+    readonly ok: false;
+    readonly message: string;
+};
+/** One request as a transport hands it to the pipeline, before anything has been identified or routed. */
+export interface PipelineRequest {
+    readonly method: string;
+    /** The request target exactly as received, path and query together. */
+    readonly url: string;
+    readonly headers: IncomingHttpHeaders;
+    /** The request's body stream. */
+    readonly body: IncomingMessage;
+    /** Aborted the moment the client goes away. */
+    readonly signal: AbortSignal;
+    readonly response: ServerResponse;
+}
+/** What the response middleware learns about the request a routed response answers. */
+interface ObservedRequest {
+    readonly method: string;
+    /** The request target's path, without its query string. */
+    readonly path: string;
+    readonly receivedAt: number;
+}
+/**
+ * Builds the response half a route writes through. The head is what runs the response middleware: `start` invokes every observer, in order, with the session, the request and the route's name before a byte reaches the client, and keeps the body observers they return. Each body chunk reaches those observers only after it has been handed to the client's socket, and their `end` runs once when the response ends, is destroyed, or the client goes away first, so following the body never holds a byte back and never misses how it finished. Body writes apply backpressure by waiting for the socket to drain, and resolve without writing once the client is gone, so a route streaming to a dead client finishes promptly rather than filling a buffer.
+ */
+export declare function createRoutedResponse(response: ServerResponse, context: {
+    readonly deps: PipelineDeps;
+    readonly session: SessionIdentity;
+    readonly route: string;
+    readonly request: ObservedRequest;
+}): RoutedResponse;
+/**
+ * The ordered pipeline every routed session's request runs through: identify the session (splitting the launcher-injected headers out of what may leave the machine), then route, with the response middleware running at each response head. A route that cannot be resolved is answered as an Anthropic-shaped error, and the observers see that error like any other response, since quota and rate-limit state lives in exactly those.
+ */
+export declare function serveRouted(request: PipelineRequest, deps: PipelineDeps): Promise<void>;
+export {};

package/dist/types/frontdoor/server.d.ts

@@ -0,0 +1,44 @@
+import http from "node:http";
+import type { IncomingMessage } from "node:http";
+import https from "node:https";
+import type { LeafCert } from "./connect";
+import type { PipelineRequest } from "./pipeline";
+/** A front-door listener: plain HTTP for the direct listener only headroom reaches, HTTPS for the provider listener every provider session's child connects to. */
+export type FrontDoorServer = http.Server | https.Server;
+/**
+ * A front-door listener: the transport a routed session's requests arrive on. It turns each Node request into a `PipelineRequest` (the raw request plus an abort signal that fires the moment the client goes away before the response finished) and hands it to the pipeline; the pipeline owns identification, admission, middleware and routing.
+ *
+ * With `tls`, the listener serves HTTPS with that leaf, which is how the provider listener authenticates itself to the child: the leaf is signed by agent-shim's CA, whose key only the owning user can read, and the only CA the child trusts for a 127.0.0.1 certificate is that one (no public CA issues certificates for a loopback address), so a process that merely binds the port cannot complete a handshake the child accepts and never receives the request (credentials and capability included). Without `tls` it serves plain HTTP, which only the direct listener does: nothing that reaches it carries a real credential (see the credential custody).
+ *
+ * The disconnect is read from the response's `close` event, not the request's: the request emits `close` as soon as its body has been read, long before the response ends. `GET /healthz` is answered here, before the pipeline, because a readiness probe is not a routed session and carries no session headers or capability.
+ */
+export declare function createFrontDoorServer(pipeline: (request: PipelineRequest) => Promise<void>, log: (line: string) => void, tls?: LeafCert): FrontDoorServer;
+/**
+ * Probes a listener's health endpoint once: the check the supervisor's start and the tests use to know the door is actually serving, not merely bound. With `ca`, the probe speaks HTTPS and accepts only a certificate chaining to that CA for 127.0.0.1, so a healthy answer also proves who is answering; without it, plain HTTP. No capability is ever sent: the health endpoint needs none.
+ */
+export declare function frontDoorHealthy(port: number, ca?: string): Promise<boolean>;
+/** How a listener is bound. */
+interface ListenOptions {
+    /** The sticky port to try first; any free port is used when it is taken or absent. */
+    readonly preferredPort?: number;
+    /** Receives the actual port the moment the bind succeeds, before the health probe. */
+    readonly onBound?: (port: number) => void;
+    /** The CA a TLS listener's leaf chains to, so its own start-up probe verifies the handshake a child will make; omitted for a plain-HTTP listener. */
+    readonly ca?: string;
+    /**
+     * Called for any error the listener emits once it is bound and serving. Attached only after the bind has settled: a server emits the sticky port's EADDRINUSE as an ordinary `error` event, and a handler attached before the bind would treat the fallback the bind is about to make as fatal.
+     */
+    readonly onError?: (error: Error) => void;
+}
+/**
+ * Binds the listener on `preferredPort` when it is free and any free port otherwise (bind, do not probe: check-then-bind races), probing its own health endpoint before resolving.
+ */
+export declare function listenFrontDoor(server: FrontDoorServer, options?: Readonly<ListenOptions>): Promise<{
+    readonly port: number;
+    readonly close: () => Promise<void>;
+}>;
+/**
+ * Iterates a forwarded response's body as typed chunks. Node types the async iteration of an `IncomingMessage` as `any`, so every consumer narrows here once rather than each carrying its own assertion.
+ */
+export declare function upstreamChunks(stream: IncomingMessage): AsyncGenerator<Uint8Array>;
+export {};

package/dist/types/headroom/headers.d.ts

@@ -0,0 +1,11 @@
+/** One `ANTHROPIC_CUSTOM_HEADERS` entry as the child environment carries it. */
+export interface CustomHeaderEntry {
+    readonly name: string;
+    readonly value: string;
+}
+/**
+ * Merges `ANTHROPIC_CUSTOM_HEADERS` blocks: every string in `existing` (as Claude Code writes them, `Name: Value` entries separated by newlines) parsed in order, then every entry of `additions` set on top, so a later block replaces an earlier block's value for the same header name while leaving every other entry untouched. The result is re-serialised in first-seen order with additions updated in place.
+ *
+ * Blank lines are skipped on parse; a header name keeps its own case exactly as written, since header names are case-insensitive on the wire but a statusline or log reading this value back should see what was set.
+ */
+export declare function mergeAnthropicCustomHeaders(existing: readonly (string | undefined)[], additions: readonly CustomHeaderEntry[]): string;