agent-shim 7.6.1 → 7.8.0

package/dist/types/cli/bool.d.ts

@@ -0,0 +1,8 @@
+/**
+ * The one boolean vocabulary every agent-shim input shares, CLI flag values and environment variables alike: `true` and `1` mean true, `false` and `0` mean false, and nothing else is a boolean (no case folding, no `yes`/`no`).
+ *
+ * Lives in a module with no imports so both `src/cli/parsers.ts` (which raises on anything else) and `src/cliError.ts` (which must never raise while reporting another failure) can share it without an import cycle.
+ * @param input - The raw text.
+ * @returns The boolean it spells, or undefined when it spells none.
+ */
+export declare function parseBoolWord(input: string): boolean | undefined;

package/dist/types/cli/parsers.d.ts

@@ -0,0 +1,40 @@
+import { UsageError } from "../cliError";
+/** One `<key>=<value>` pair, as parsed by `parsePair`. */
+export interface ParsedPair {
+    readonly key: string;
+    readonly value: string;
+}
+/**
+ * Splits `input` on its *first* `=` into a key and a value. The value may itself contain further `=` characters (they stay part of the value); only the first `=` is treated as the separator.
+ *
+ * Throws when there is no `=` at all, or when the key half is empty (`=true`, or a leading `=`).
+ */
+export declare function parsePair(input: string): ParsedPair;
+/** Parses `input` as a boolean in the shared vocabulary (`true`/`1`, `false`/`0`); throws on anything else. */
+export declare function parseBool(input: string): boolean;
+/** Raised when a boolean environment variable holds something outside the shared vocabulary. */
+export declare class InvalidEnvBoolError extends UsageError {
+    readonly variable: string;
+    readonly value: string;
+    constructor(variable: string, value: string);
+}
+/**
+ * Reads a boolean environment variable with the same vocabulary a CLI flag value uses. Unset and the empty string both mean "not given" (undefined), consistent with how every other agent-shim environment variable treats the empty string; anything outside the vocabulary throws `InvalidEnvBoolError` rather than silently reading as false.
+ */
+export declare function parseEnvBool(variable: string, value: string | undefined): boolean | undefined;
+/**
+ * Parses a comma-separated list of `<key>=<bool>` pairs into a plain object, e.g. `"history=true,knowledge=false"` becomes `{ history: true, knowledge: false }`. Used only for the list-valued environment variables; flags repeat instead.
+ *
+ * An empty string parses to `{}`. A key repeated within the same list is not an error: the later occurrence wins, matching how a plain object literal with a repeated key behaves.
+ */
+export declare function parseBoolPairList(input: string): Record<string, boolean>;
+/**
+ * Commander repeatable-option collector for one `--flag <key>=<bool>` occurrence: parses `value` and merges it over `previous`, so `--category history=true --category knowledge=false` accumulates into one object, the later occurrence winning on key collision.
+ */
+export declare function collectBoolPair(value: string, previous?: Readonly<Record<string, boolean>>): Record<string, boolean>;
+/** Commander repeatable-option collector for one `--flag <KEY>=<VALUE>` occurrence with a free-text value, merged over `previous` the same way `collectBoolPair` merges. */
+export declare function collectStringPair(value: string, previous?: Readonly<Record<string, string>>): Record<string, string>;
+/** Commander repeatable-option collector for a plain repeated value (`--extends a --extends b`), preserving the order given. */
+export declare function collectRepeated(value: string, previous?: readonly string[]): string[];
+/** Commander option parser for a duration such as `30m`, `5h` or `7d` (a count followed by ms, s, m, h, d or w), returning milliseconds. A malformed value is a usage error naming the option. */
+export declare function parseDurationOption(value: string): number;

package/dist/types/configProfilesStore.d.ts

@@ -0,0 +1,61 @@
+import { type ConfigProfile, type GlobalConfig, type LaunchFlags } from "./config/schema";
+import { CliError } from "./cliError";
+import type { LayoutPaths } from "./paths";
+/** Raised by any operation that requires a configuration profile to already exist, when it does not. */
+export declare class ProfileNotFoundError extends CliError {
+    readonly profileName: string;
+    constructor(profileName: string);
+}
+/** Raised by `createProfile` (`profile add`) when a profile with the given name already has a file. */
+export declare class ProfileAlreadyExistsError extends CliError {
+    readonly profileName: string;
+    constructor(profileName: string);
+}
+/** Raised when a `--category` patch names something other than one of the four overridable categories (e.g. `secret`, or a typo). */
+export declare class InvalidCategoryNameError extends CliError {
+    readonly categoryName: string;
+    constructor(categoryName: string);
+}
+/** True when a profile file exists for `name`, regardless of whether it validates. */
+export declare function profileExists(paths: LayoutPaths, name: string): boolean;
+export declare function requireProfileExists(paths: LayoutPaths, name: string): void;
+/** Reads and validates one configuration profile, or undefined when it does not exist. */
+export declare function readProfile(paths: LayoutPaths, name: string): ConfigProfile | undefined;
+/**
+ * Creates a new configuration profile, empty apart from the optional `extends` list and description. Throws `ProfileAlreadyExistsError` if a profile with this name already has a file, and `ConfigValidationError` when the result fails `ConfigProfileSchema` (e.g. an empty `--extends ""` name), rather than letting the underlying `ZodError` escape as an unhandled crash.
+ */
+export declare function createProfile(paths: LayoutPaths, name: string, extendsList?: readonly string[], description?: string): ConfigProfile;
+/** One profile as reported by `listProfiles`. */
+export interface ProfileListEntry {
+    readonly name: string;
+    readonly profile: ConfigProfile;
+}
+/** Lists every configuration profile under `configProfilesDir` that has a valid `<name>.json`. */
+export declare function listProfiles(paths: LayoutPaths): readonly ProfileListEntry[];
+/** Reads the user-global `~/.agent-shim/config.json`, or undefined when it does not exist. */
+export declare function readGlobalConfig(paths: LayoutPaths): GlobalConfig | undefined;
+/** Sets the user-global default configuration profile in `~/.agent-shim/config.json`, creating the file if it doesn't exist yet. Whether the profile exists is the caller's concern: `profile use` checks it first. */
+export declare function setGlobalDefaultProfile(paths: LayoutPaths, name: string): GlobalConfig;
+/**
+ * Merges `patch` (from one or more `--category cat=bool` flags) into `profile`'s own `categories` object and writes it back.
+ *
+ * Throws `InvalidCategoryNameError` for any key that isn't one of the four overridable categories — `secret` can never be toggled by any configuration layer, this included.
+ */
+export declare function setProfileCategories(paths: LayoutPaths, name: string, patch: Readonly<Record<string, boolean>>): ConfigProfile;
+/**
+ * Merges `patch` (from one or more `--entry "path"=bool` flags) into `profile`'s own `entries` object and writes it back.
+ *
+ * Key validity (the `<category>/<real-relative-path>` prefix requirement) is enforced by `ConfigProfileSchema`'s own `EntriesSchema` at write time — an invalid key surfaces as the usual `ConfigValidationError`.
+ */
+export declare function setProfileEntries(paths: LayoutPaths, name: string, patch: Readonly<Record<string, boolean>>): ConfigProfile;
+/**
+ * Merges `patch` into `profile`'s own `launch` object and writes it back. A key present in `patch` with the value `undefined` removes that setting outright (a `--no-launch-provider`, say) rather than overwriting it, and a `launch` object left with no settings is removed too.
+ */
+export declare function setProfileLaunchFlags(paths: LayoutPaths, name: string, patch: Readonly<LaunchFlags>): ConfigProfile;
+/** Replaces `profile`'s own `extends` list and/or description; an empty list or an undefined description removes the field. */
+export declare function setProfileMetadata(paths: LayoutPaths, name: string, patch: Readonly<{
+    extends?: readonly string[];
+    description?: string | false;
+}>): ConfigProfile;
+/** Deletes a configuration profile's file. Throws `ProfileNotFoundError` when it does not exist. Nothing that references it by name is rewritten; `agent-shim doctor` reports any identity default, directory rule or `extends` left pointing at it. */
+export declare function removeProfile(paths: LayoutPaths, name: string): void;

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/frontdoor/connect.d.ts

@@ -1,5 +1,6 @@
 import type { IncomingHttpHeaders, IncomingMessage, ServerResponse } from "node:http";
 import type * as net from "node:net";
+import type { Duplex } from "node:stream";
 import type { ConnectCapture, PassthroughObserver } from "./capture";
 /**
  * The front door's CONNECT surface, so an OAuth session can have agent-shim's routing AND Claude Code's Remote Control at once: Remote Control refuses any `ANTHROPIC_BASE_URL` other than the real API, but happily honours `HTTPS_PROXY`, so OAuth launches route at the proxy layer instead.
@@ -125,8 +126,8 @@ export interface ConnectListenerHandle {
 }
 /** Presents one leaf's server-side TLS on CONNECTed sockets. */
 interface TlsAcceptor {
-    /** Starts the TLS handshake on a socket that has just received its CONNECT response. */
-    readonly accept: (socket: net.Socket) => void;
+    /** Starts the TLS handshake on a socket that has just received its CONNECT response, carrying `context` to the handshake's completion untouched: whatever the caller knows about this connection (its tunnel's capability) reaches `onSecure` without the acceptor interpreting it. */
+    readonly accept: (socket: net.Socket, context: string) => void;
     /** Drops every session this acceptor is terminating. */
     readonly close: () => void;
 }
@@ -141,12 +142,12 @@ interface HttpParserSession {
 export interface ConnectEffects {
     /** Binds a loopback TCP listener; `preferredPort` is tried first and any free port used when it is taken (bind, do not probe: check-then-bind races). Resolves with the bound port and a close handle. */
     readonly listenLoopback: (preferredPort: number | undefined, onSocket: (socket: net.Socket) => void) => Promise<ConnectListenerHandle>;
-    /** Builds the TLS terminator for one leaf, handing each successfully handshaked session to `onSecure`. `alpnProtocols`, when given, is advertised during the handshake, which is how a tap host's session can offer HTTP/2 the way its real server does. */
-    readonly createTlsAcceptor: (leaf: LeafCert, onSecure: (secure: net.Socket) => void, alpnProtocols?: readonly string[]) => TlsAcceptor;
+    /** Builds the TLS terminator for one leaf, handing each successfully handshaked session to `onSecure` together with the context its `accept` call carried. `alpnProtocols`, when given, is advertised during the handshake, which is how a tap host's session can offer HTTP/2 the way its real server does. */
+    readonly createTlsAcceptor: (leaf: LeafCert, onSecure: (secure: net.Socket, context: string) => void, alpnProtocols?: readonly string[]) => TlsAcceptor;
     /** Opens a TLS connection to a real host, presenting its name as SNI, for a tap session's upstream half. `clientAlpn`, when given, is the protocol the client negotiated with the surface and the only one offered upstream, so the tap never changes the channel's protocol. */
     readonly connectTlsUpstream: (host: string, port: number, clientAlpn: string | undefined) => Promise<net.Socket>;
-    /** Builds the HTTP parser bound to one request handler. `onUpgrade`, when given, sees every HTTP upgrade request arriving on a terminated session; the session destroys the socket afterwards either way, with or without one, matching Node's own no-listener behaviour. */
-    readonly createHttpSession: (handler: ConnectRequestHandler, onUpgrade?: (request: IncomingMessage) => void) => HttpParserSession;
+    /** Builds the HTTP parser bound to one request handler. `onUpgrade`, when given, owns every HTTP upgrade request arriving on a terminated session, socket and already-read bytes included; a session without one lets Node destroy the upgrade, its own no-listener behaviour. */
+    readonly createHttpSession: (handler: ConnectRequestHandler, onUpgrade?: (request: IncomingMessage, socket: Duplex, head: Buffer) => void) => HttpParserSession;
     /** Opens a raw TCP connection for a blind tunnel. */
     readonly connectTcp: (host: string, port: number) => Promise<net.Socket>;
     /** Streams one request to `target` and the response back, never buffering a body. When `observer` is given, the forwarding drives it with additive listeners (request and response chunks arrive to both the pipe and the observer) so capturing never changes the forwarding's own flow control. */

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

@@ -0,0 +1,112 @@
+import type { IncomingHttpHeaders, IncomingMessage } from "node:http";
+/**
+ * The agent-shim-internal headers the launcher injects through `ANTHROPIC_CUSTOM_HEADERS` so the front door can identify and route a request's session. None of them may ever leave the machine: the identity step strips every one before a route sees the request, so no upstream, and not even the headroom hop, learns what they say.
+ */
+export declare const INTERNAL_HEADER_NAMES: readonly ["x-agent-shim-identity", "x-agent-shim-session", "x-agent-shim-headroom", "x-agent-shim-auth", "x-agent-shim-hop", "x-agent-shim-hop-id", "x-headroom-project-id", "x-headroom-base-url"];
+/** Carries the launching identity's name (the `@name` the launch resolved), set by the launcher and stripped at the door. */
+export declare const IDENTITY_HEADER = "x-agent-shim-identity";
+/** Carries one launch's session id, generated by the launcher and stripped at the door; response middleware keys its observations by it. */
+export declare const SESSION_HEADER = "x-agent-shim-session";
+/** Set to `1` when the launch resolved headroom on, so the front door knows this session's requests must take the headroom hop; stripped at the door. */
+export declare const HEADROOM_FLAG_HEADER = "x-agent-shim-headroom";
+/**
+ * Carries the project identity headroom scopes its memory state to (the git repository root of the launch directory). Also injected by the launcher and stripped at the door: the headroom hop re-sets it on its own request, so it reaches headroom and nowhere else.
+ */
+export declare const PROJECT_ID_HEADER = "x-headroom-project-id";
+/**
+ * Headroom's per-request upstream selector, which the child used to carry and the door now owns: the door strips any inbound copy (a leftover from an older launcher's environment would otherwise redirect the daemon behind the door's back) and its hop sets it fresh when a route names an upstream.
+ */
+export declare const HEADROOM_BASE_URL_HEADER = "x-headroom-base-url";
+/**
+ * The per-launch capability a client-facing listener requires before it routes anything: a random token the launcher generates, hands the child through `ANTHROPIC_CUSTOM_HEADERS`, and records in the door's session registry, so a loopback process that never launched through agent-shim cannot spend the session's credentials or quota. Stripped at the door like every internal header.
+ */
+export declare const AUTH_HEADER = "x-agent-shim-auth";
+/**
+ * The capability the direct listener requires: a per-generation random secret held only in the door process's memory, set by the headroom hop on the requests it forwards back. A loopback process that finds the direct port still cannot use it, and nothing on disk ever holds the secret.
+ */
+export declare const HOP_SECRET_HEADER = "x-agent-shim-hop";
+/**
+ * Names the credential custody record one headroom hop holds: a random id the hop sets on the request it hands headroom, alongside placeholders where the real credential headers were. The direct listener exchanges a live id (and only for the provider the record was made for) for the real headers before routing, so the credential itself never crosses headroom or the plain-HTTP leg back.
+ */
+export declare const HOP_ID_HEADER = "x-agent-shim-hop-id";
+/** What the identity step learned about one request from the launcher-injected headers. */
+export interface SessionIdentity {
+    /** The identity name the launch resolved, when it resolved one. */
+    readonly identity: string | undefined;
+    /** The per-launch session id, when the launcher injected one. */
+    readonly sessionId: string | undefined;
+    /** Whether this launch resolved headroom on, so its requests must pass through the headroom hop before their route. */
+    readonly headroom: boolean;
+    /** The project identity headroom scopes memory to, re-set on the headroom hop and sent nowhere else. */
+    readonly projectId: string | undefined;
+}
+/** The outcome of the pipeline's first step: what the session is, and the headers that may actually leave the machine. */
+export interface IdentifiedRequest {
+    readonly session: SessionIdentity;
+    /**
+     * The request's headers with every internal header removed. A route forwards these, and only these, onwards: the identity and session headers are for the front door alone and must never reach an upstream, the headroom hop, or a translator's backend call.
+     */
+    readonly forwardableHeaders: IncomingHttpHeaders;
+}
+/**
+ * The identity step: splits a request's headers into what the front door may learn (the session) and what may leave the machine (everything else). Internal header names are matched case-insensitively, which is how the transport already normalises them.
+ */
+export declare function identifyRequest(headers: Readonly<IncomingHttpHeaders>): IdentifiedRequest;
+/** The path prefix every provider-scoped request sits under: a routed session's base URL is the front door's address plus `/providers/<name>`, so one listener serves any number of providers, each with its own credential and translation settings. */
+export declare const PROVIDER_PATH_PREFIX = "/providers/";
+/** The base URL a provider's sessions are pointed at: HTTPS, because the child sends its provider credential on every request and only a listener presenting a leaf signed by agent-shim's CA may receive it. */
+export declare function providerBaseUrl(port: number, provider: string): string;
+/** The bare origin of a loopback listener, which is what a headroom hop is told to forward to: headroom appends the client's own request path to it. */
+export declare function directOrigin(port: number): string;
+/** Splits `/providers/<name>/<rest>` into the provider name and the rest, or undefined for any other path. */
+export declare function parseProviderPath(path: string): {
+    readonly provider: string;
+    readonly rest: string;
+} | undefined;
+/** One request as a route sees it: the transport's own request and abort signal, plus what the identity step resolved. */
+export interface RoutedRequest {
+    readonly method: string;
+    /** The request target exactly as received, path and query together. */
+    readonly url: string;
+    /** The request's headers with every internal header already stripped: exactly what a route may forward onwards. */
+    readonly headers: IncomingHttpHeaders;
+    /** The request's body stream: a route either pipes it onward untouched or reads it whole, never both. */
+    readonly body: IncomingMessage;
+    /** Aborted the moment the client goes away; a route aborts its own upstream work with it. */
+    readonly signal: AbortSignal;
+    readonly session: SessionIdentity;
+}
+/** The response half a route writes through, so the pipeline can run response middleware at the head and apply backpressure uniformly. */
+export interface RoutedResponse {
+    /** Whether the head has already been written. */
+    readonly headersSent: boolean;
+    /** Writes the response head, running every response observer first. Must be called exactly once, before any write. */
+    readonly start: (status: number, headers: Readonly<Record<string, string>>) => void;
+    /** Sends the head on its way before any body chunk exists: a streaming response's client should see its headers the moment they are known. */
+    readonly flush: () => void;
+    /**
+     * Writes one body chunk, waiting for the socket to take it when the client is slow (backpressure: a slow client slows the route, and its upstream, instead of growing a buffer without bound). Resolves early, without writing, once the client is gone.
+     */
+    readonly write: (chunk: string | Uint8Array) => Promise<void>;
+    /** Ends the response. */
+    readonly end: () => void;
+    /** Drops the connection: an upstream failure after the head went out, where no status can be sent any more. */
+    readonly destroy: () => void;
+}
+/** One pluggable destination the front door routes a request to. */
+export interface FrontDoorRoute {
+    /** The route's name, for logs and for response middleware context. */
+    readonly name: string;
+    /**
+     * Whether the headroom hop may sit in front of this route. Headroom needs the Anthropic-shaped request, so a protocol translator built on an Anthropic-compatible surface opts in, and a route whose request shape headroom could not understand opts out.
+     */
+    readonly headroomEligible: boolean;
+    /**
+     * The upstream headroom is told to use (its per-request base URL header) when the hop sits in front of this route. When defined it is always this door's direct listener, which is what lets the hop keep the route's credential in custody and the direct listener restore it; a route must never name any other address here. Undefined leaves headroom's own default upstream in charge, which is Claude Code's API.
+     */
+    readonly headroomUpstream: string | undefined;
+    /**
+     * Serves the request directly: headroom has already been applied, or does not apply to this route. Writes the response through `response` and resolves once the response has ended.
+     */
+    readonly serve: (request: RoutedRequest, response: RoutedResponse) => Promise<void>;
+}

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

@@ -1,8 +1,9 @@
 import type * as net from "node:net";
+import type { Duplex } from "node:stream";
 import type { StreamTap } from "./capture";
 /**
  * Pumps one already-TLS-terminated stream byte for byte to its real host over a fresh TLS connection, teeing every chunk in both directions into `tap` when one is given. This is the instrumentation for a host whose protocol the surface does not parse: the claude.ai control plane carries Remote Control on a channel that mixes shapes (observed under capture: an HTTP/1.1-shaped token request first, then binary HTTP/2 frames around it), so parsing it as either protocol would destroy or distort it. Pass everything through unchanged and record, never interpret: the frames are decoded offline, and a protocol the door does not understand keeps working exactly as the blind tunnel served it.
  *
  * Lifecycle mirrors `blindTunnel`: whoever goes away first takes the other side with it, so neither half of a tap session ever outlives its peer. The tap's listeners ride beside the pipes, additive like every other observer in this surface, so a recording failure fails loudly rather than silently stopping a diagnostic.
  */
-export declare function pumpTapSession(secure: net.Socket, openUpstream: (clientAlpn: string | undefined) => Promise<net.Socket>, tap: StreamTap | undefined): void;
+export declare function pumpTapSession(secure: Duplex, openUpstream: (clientAlpn: string | undefined) => Promise<net.Socket>, tap: StreamTap | undefined, prefix?: Readonly<Buffer>): void;

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;

package/dist/types/identityStore.d.ts

@@ -0,0 +1,85 @@
+import { type CredentialCache, type CredentialSource, type CredentialTarget, type Identity } from "./config/schema";
+import { CliError } from "./cliError";
+import type { LayoutPaths } from "./paths";
+/** Raised by any operation that requires an identity to already exist, when it does not. */
+export declare class IdentityNotFoundError extends CliError {
+    readonly name: string;
+    constructor(name: string);
+}
+/** Raised by `addIdentity` when an identity with the given name already has an `identity.json`. */
+export declare class IdentityAlreadyExistsError extends CliError {
+    readonly identityName: string;
+    constructor(identityName: string);
+}
+/** Raised by `addIdentity` when `name` fails `IdentitySchema`'s own naming rule — it must start with a letter or number and may then contain letters, numbers, dots, hyphens, underscores, and at signs, so an email address names an identity directly while a *leading* `@` stays invalid (it would collide with the `@name` selector syntax's first-`@` split). */
+export declare class InvalidIdentityNameError extends CliError {
+    readonly attemptedName: string;
+    constructor(attemptedName: string);
+}
+export declare function identityExists(paths: LayoutPaths, name: string): boolean;
+/** Reads and validates one identity's `identity.json`, or undefined when it does not exist. */
+export declare function readIdentity(paths: LayoutPaths, name: string): Identity | undefined;
+/**
+ * Creates a new identity: validates `name` against `IdentitySchema`'s own naming rule and writes a fresh `identity.json` with `allowAmbientCredential: false` and no `defaultConfigProfile`.
+ *
+ * Throws `IdentityAlreadyExistsError` if an identity with this name already has an `identity.json` — `add` never silently overwrites an existing identity. Throws `InvalidIdentityNameError` when `name` fails `IdentitySchema`'s naming rule, rather than letting the underlying `ZodError` escape as an unhandled crash.
+ */
+export declare function addIdentity(paths: LayoutPaths, name: string): Identity;
+/**
+ * Persists `name` as the active identity, written atomically as plain text (not JSON — this file is read by `decideIdentity` in `src/launcher/identity.ts` via a simple UTF-8 read-and-trim, matching the README's documented `~/.agent-shim/active-identity` file).
+ *
+ * `name` may be a `pool:<name>` selector, which makes launches pick a member of that pool. Throws `IdentityNotFoundError` when no identity with this name exists yet, and `PoolNotFoundError` for a pool that is not defined: selecting either would silently persist a name nothing else can ever load.
+ */
+export declare function useIdentity(paths: LayoutPaths, name: string): void;
+/** Reads the persisted active-identity file, or undefined when none is set. */
+export declare function readActiveIdentity(paths: LayoutPaths): string | undefined;
+/**
+ * Whether a directory name directly under `identitiesDir` names an actual identity, rather than one of agent-shim's own farm directories.
+ *
+ * `IdentitySchema` requires an identity name to start with a letter or digit, so a leading `.` can only be a resync's own bookkeeping: a `.<identity>.scratch.<suffix>` tree still being built, or a `.<identity>.previous.<suffix>` superseded farm retained for `agent-shim identity resolve-conflicts`. Neither is an identity, and neither should be reported as a broken one for lacking an `identity.json` a resync never put there.
+ */
+export declare function isIdentityDirectoryName(name: string): boolean;
+/** One identity as reported by `listIdentities`, whose `identity.json` parsed and validated cleanly. */
+export interface IdentityListEntry {
+    readonly name: string;
+    readonly identity: Identity;
+    readonly isActive: boolean;
+    readonly problem?: never;
+}
+/** One identity whose `identity.json` is present but unreadable — malformed JSON, or valid JSON this version's `IdentitySchema` rejects. `problem` carries the reason, already flattened onto a single line. */
+export interface UnreadableIdentityListEntry {
+    readonly name: string;
+    readonly identity?: never;
+    readonly isActive: boolean;
+    readonly problem: string;
+}
+/** Either shape `listIdentities` can report, discriminated by which of `identity`/`problem` is present rather than by a tag field — the two are never simultaneously satisfiable. */
+export type IdentityListing = IdentityListEntry | UnreadableIdentityListEntry;
+/**
+ * Lists every identity under `identitiesDir`, marking which one (if any) is currently active.
+ *
+ * One identity whose `identity.json` cannot be read is reported as its own `UnreadableIdentityListEntry` rather than aborting the whole listing. A single bad file blocking `identity list` outright is exactly the failure mode that hides every *other* identity from view at the moment the user most needs to see them — and the file need not even be corrupt to land here, since a name written by a newer agent-shim whose naming rule has since widened is rejected outright by an older binary's own copy of `IdentitySchema`.
+ */
+export declare function listIdentities(paths: LayoutPaths): readonly IdentityListing[];
+/**
+ * Sets `identity`'s `defaultConfigProfile` field, or clears it when `profileName` is undefined. Throws `IdentityNotFoundError` when the identity does not exist. Whether the profile exists is the caller's concern: `identity set --default-profile` checks it first.
+ */
+export declare function setDefaultConfigProfile(paths: LayoutPaths, identityName: string, profileName: string | undefined): Identity;
+/**
+ * Patches `identity`'s `allowAmbientCredential` field. Throws `IdentityNotFoundError` when the identity does not exist.
+ */
+export declare function setAllowAmbientCredential(paths: LayoutPaths, identityName: string, allow: boolean): Identity;
+/** The change `setIdentityCredential` makes: new sources and/or a new target for the credential block, or `false` to remove the block and return the identity to its stored login. */
+export type IdentityCredentialChange = {
+    readonly sources?: readonly CredentialSource[];
+    readonly target?: CredentialTarget;
+    readonly cache?: CredentialCache | false;
+} | false;
+/**
+ * Sets, changes or removes `identityName`'s credential block. New `sources` replace the whole ordered list (the order is the meaning); a `target` alone keeps the existing sources, and so needs a credential block to exist already. Throws `IdentityNotFoundError` when the identity does not exist, and `UsageError` when only a target is given for an identity with no credential yet.
+ */
+export declare function setIdentityCredential(paths: LayoutPaths, identityName: string, change: IdentityCredentialChange): Identity;
+/**
+ * Deletes identity `name` entirely: its directory under `identitiesDir` (the farm, its `identity.json`, and whatever that farm holds unshared, credentials included), its resync lock, any scratch or superseded farm a resync left behind, and the active-identity selection when it names this identity. Data shared into `~/.claude` stays there, since the farm only ever symlinks to it. Throws `IdentityNotFoundError` when the identity does not exist.
+ */
+export declare function removeIdentity(paths: LayoutPaths, name: string): void;