agent-shim 8.8.0 → 8.9.0

package/dist/types/index.d.ts

@@ -1,7 +1,11 @@
+import * as zod from 'zod';
 import { z } from 'zod';
 import { IncomingHttpHeaders, IncomingMessage, ServerResponse } from 'node:http';
 import * as net from 'node:net';
 import { Duplex } from 'node:stream';
+import * as zod_v4_core from 'zod/v4/core';
+import * as _orpc_server from '@orpc/server';
+import { RouterClient } from '@orpc/server';
 
 /**
  * Every category a `~/.claude` entry can be classified into. `secret` is deliberately part of this list — it is a real classification the resolver acts on — but it is NOT part of `CategoryMapSchema`'s shape, because no configuration layer may ever toggle it. See OVERRIDABLE_CATEGORIES.
@@ -1602,6 +1606,44 @@ declare function realConnectCertStore(paths: {
     readonly frontdoorCaKeyFile: string;
 }): ConnectCertStore;
 
+/**
+ * The Zod schemas of the Remote Control surfaces: one definition each for the summaries, statuses and pending lists the tracker produces, the stream events the door's client attachment fans out, and every input and output the typed API accepts. The tracker's own TypeScript interfaces in `rcSessions.ts` stay the implementations' types; these schemas are what the oRPC contract validates through, and because the procedures wrap the very operations that produce those interfaces' values, a drift between a schema and its interface fails the API's own output validation (exercised by its tests) rather than shipping silently. This module deliberately imports nothing from oRPC: it is a plain Zod leaf, so the tracker and the stream half can share it without either depending on the API layer.
+ */
+/** The permission modes the SDK's own `set_permission_mode` control request accepts, as the input schema of the set-permission-mode operation and the subscribe-free vocabulary every surface narrows untrusted strings through. */
+declare const RcPermissionModeSchema: z.ZodEnum<{
+    default: "default";
+    acceptEdits: "acceptEdits";
+    bypassPermissions: "bypassPermissions";
+    plan: "plan";
+    dontAsk: "dontAsk";
+    auto: "auto";
+}>;
+/** One event off the client read stream, exactly as the door forwards it to subscribers: the envelope the API host sent, with the fields the door itself relies on typed and the rest (the payload above all) carried verbatim for the consumer to narrow. */
+declare const RcStreamEnvelopeSchema: z.ZodObject<{
+    event_id: z.ZodOptional<z.ZodString>;
+    event_type: z.ZodString;
+    sequence_num: z.ZodInt;
+    source: z.ZodString;
+    payload: z.ZodOptional<z.ZodUnknown>;
+    created_at: z.ZodOptional<z.ZodUnknown>;
+}, z.core.$loose>;
+/** One fan-out event: the session the stream it rode belongs to, beside the envelope itself. */
+declare const RcStreamEventSchema: z.ZodObject<{
+    session: z.ZodString;
+    envelope: z.ZodObject<{
+        event_id: z.ZodOptional<z.ZodString>;
+        event_type: z.ZodString;
+        sequence_num: z.ZodInt;
+        source: z.ZodString;
+        payload: z.ZodOptional<z.ZodUnknown>;
+        created_at: z.ZodOptional<z.ZodUnknown>;
+    }, z.core.$loose>;
+}, z.core.$strict>;
+/** One event off the client read stream, as the TypeScript every in-process consumer of the fan-out handles it (the schema's own inferred type, so the two cannot drift). */
+type RcStreamEnvelope = z.output<typeof RcStreamEnvelopeSchema>;
+/** One fan-out event, as the TypeScript every in-process consumer handles it. */
+type RcStreamEvent = z.output<typeof RcStreamEventSchema>;
+
 /** What the identity step learned about one request from the launcher-injected headers. */
 interface SessionIdentity {
     /** The identity name the launch resolved, when it resolved one. */
@@ -1750,6 +1792,14 @@ interface RcSessionTracker {
     readonly pendingOf: (sessionId?: string) => readonly RcPendingRequestSummary[];
     /** The observed credential and protocol headers for one session, the client-half writes' accessor: present only while the session is tracked, and never surfaced anywhere a summary, log or capture goes. */
     readonly credentialOf: (sessionId: string) => RcObservedCredential | undefined;
+    /** Advances the session's sequence cursor to the highest number named, which every confirmed client-half write calls with the numbers the real service assigned its events. */
+    readonly noteSequenceNums: (sessionId: string, sequenceNums: readonly number[]) => void;
+    /** The session's sequence cursor: the highest number the door has seen, from the client read stream's envelopes or from its own confirmed writes; undefined while neither has been seen. */
+    readonly sequenceNumOf: (sessionId: string) => number | undefined;
+    /**
+     * Files one client read stream envelope: advances the session's sequence cursor, and treats the payload exactly as an observed event-batch body's would be treated, which is how an approval reaches the pending list from the stream (the live finding behind the client attachment: the CLI routes `control_request`s only toward attached clients, so the stream, not the worker's own writes, is where a `can_use_tool` the door must answer becomes visible). A `control_request` whose envelope names the worker as its source births a pending entry; a `control_response` retires the request it answers, whoever answered it.
+     */
+    readonly fileStreamEvent: (sessionId: string, event: RcStreamEnvelope) => void;
     /** Retires one pending control request as answered: what a successful answer write calls, so the request stops being listed the moment it is answered. */
     readonly completePending: (sessionId: string, requestId: string) => void;
     /** Stops the idle sweep timer. The entries themselves are unreachable the moment the door drops them. */
@@ -1759,8 +1809,12 @@ interface RcSessionTracker {
 declare function createRcSessionTracker(deps: RcSessionTrackerDeps): RcSessionTracker;
 /**
  * Wraps one route so the tracker sees every exchange the route serves: the request's facts are handed over first, and when they are Remote Control facts the request's body chunks and the response the route writes are teed to the tracker's observer while flowing on unchanged. Used on the door's route resolution, so the bare `/v1/` pass-through an OAuth session's Remote Control calls ride is where observation happens.
+ *
+ * `onExchangeSettled`, when given, is called once the exchange's response has ended and the observer has filed whatever it filed: it is where the door re-pokes the client stream attachment, so a session becomes attached the moment its create's own response completes rather than at whatever exchange happens to follow.
  */
-declare function observingRoutedRoute(route: FrontDoorRoute, tracker: RcSessionTracker): FrontDoorRoute;
+declare function observingRoutedRoute(route: FrontDoorRoute, tracker: RcSessionTracker, hooks?: {
+    readonly onExchangeSettled?: () => void;
+}): FrontDoorRoute;
 /** Adapts the tracker's exchange observer to the passthrough forwarding's observer shape, so the connect test world (which forwards rather than routes) observes through the same tracker. */
 declare function rcObserverAsPassthrough(observer: RcExchangeObserver): PassthroughObserver;
 /**
@@ -1800,6 +1854,8 @@ type RcObservedCredential = RcWriteHeaders;
 interface RcInjectDeps {
     /** Reads the observed credential for a session: the tracker's accessor, in production. */
     readonly credentialOf: (sessionId: string) => RcObservedCredential | undefined;
+    /** Advances the session's sequence cursor: the tracker's accessor, in production, so a delivered write's numbers are what a stream resume continues after. */
+    readonly noteSequenceNums: (sessionId: string, sequenceNums: readonly number[]) => void;
     /** The dial to the real API host. */
     readonly dial: RcEventDial;
     /** Mints the payload event's uuid: a v4 UUID or better in production. */
@@ -1847,6 +1903,8 @@ interface RcAnswerDeps {
     readonly pendingOf: (sessionId: string) => readonly RcPendingRequestSummary[];
     /** Retires a pending request as answered: the tracker's accessor, in production, called only once the write is confirmed delivered. */
     readonly completePending: (sessionId: string, requestId: string) => void;
+    /** Advances the session's sequence cursor: the tracker's accessor, in production, so a delivered write's numbers are what a stream resume continues after. */
+    readonly noteSequenceNums: (sessionId: string, sequenceNums: readonly number[]) => void;
     /** The dial to the real API host. */
     readonly dial: RcEventDial;
 }
@@ -1858,6 +1916,8 @@ declare function answerRcControlRequest(deps: RcAnswerDeps, sessionId: string, r
 interface RcControlRequestDeps {
     /** Reads the observed credential for a session: the tracker's accessor, in production. */
     readonly credentialOf: (sessionId: string) => RcObservedCredential | undefined;
+    /** Advances the session's sequence cursor: the tracker's accessor, in production, so a delivered write's numbers are what a stream resume continues after. */
+    readonly noteSequenceNums: (sessionId: string, sequenceNums: readonly number[]) => void;
     /** The dial to the real API host. */
     readonly dial: RcEventDial;
     /** Mints the request's id: a v4 UUID or better in production, the id the worker's `control_response` echoes. */
@@ -1876,6 +1936,88 @@ declare function setRcSessionModel(deps: RcControlRequestDeps, sessionId: string
  */
 declare function setRcSessionPermissionMode(deps: RcControlRequestDeps, sessionId: string, mode: RcPermissionMode): Promise<RcEventWriteResult>;
 
+/**
+ * How long a failed attachment backs off before retrying. Not a fresh number: it is the session's own liveness bound (`RC_IDLE_EXPIRY_MS`, the 45 s stream timeout the tracker's idle expiry already derives from), so an attachment that cannot be re-established retries at exactly the cadence the protocol itself gives up on a quiet session at. Production passes that constant; tests pass small values so a backoff is reached in milliseconds.
+ */
+declare const RC_STREAM_BACKOFF_MS = 45000;
+/** One event the SSE parser completed: the fields the wire's own framing carried, before any protocol interpretation. */
+interface SseParsedEvent {
+    /** The `event:` field's value, when the block carried one; the protocol's own events always do. */
+    readonly event: string | undefined;
+    /** The `id:` field's value in force at dispatch (the most recent one the connection saw, per the SSE framing rules); on this stream it carries the event's sequence number. */
+    readonly id: string | undefined;
+    /** The `data:` lines joined with newlines, exactly as the SSE framing defines. */
+    readonly data: string;
+}
+/**
+ * An incremental Server-Sent Events parser: feed it the stream's text chunks as they arrive and it returns the events each write completed. Chunks may split lines, fields and even a CRLF pair anywhere; the parser buffers until a line ending is certain, so a `\r` at a chunk's end waits for the byte that decides whether it is `\r\n`. Comments (`:`-prefixed lines, the protocol's 15 s keepalives) complete nothing, an event with no `data:` line dispatches nothing (the framing's own rule), and the `id:` value persists to the next dispatched event the same way, which is what carries the sequence number of an id-only block forward.
+ */
+declare function createSseParser(): {
+    readonly write: (text: string) => readonly SseParsedEvent[];
+};
+/**
+ * One parsed SSE event as the protocol's envelope, or undefined when the event is not a client event this half reads: a block under any other event name, or data that is not one JSON object carrying the fields the door relies on (`event_type`, `sequence_num`, `source`). An envelope the door cannot read is one it knows nothing about, never a failure: the stream stays up and the next event is read on its own merits.
+ */
+declare function parseRcStreamEnvelope(parsed: SseParsedEvent): RcStreamEnvelope | undefined;
+/** One answer from the API host the presence call dials: the status and the whole body. Presence answers one small JSON object, never a stream, so the body needs no cap of its own. */
+interface RcPresenceAnswer {
+    readonly status: number;
+    readonly body: string;
+}
+/** One answer from the API host the stream dial opens: the status and the body's chunks as they arrive. On a success the chunks are the live stream (consumed incrementally, never buffered); the production dial returns an already-drained empty iterable for any non-2xx answer, whose body is one small error document. */
+interface RcStreamAnswer {
+    readonly status: number;
+    readonly chunks: AsyncIterable<Uint8Array>;
+}
+/**
+ * The one network effect the client read stream performs, injected so the attachment logic runs against fakes: announce a client's presence, and open the read stream. Production dials the real API host over the door's interception-proof agent; tests redirect to a local stand-in. `resume` names the documented resume pair's value: present only when the door has seen events for the session already, it sends `from_sequence_num` as a query parameter and `Last-Event-ID` as a header together.
+ */
+interface RcStreamDial {
+    readonly announcePresence: (sessionId: string, headers: Readonly<Record<string, string>>, clientId: string) => Promise<RcPresenceAnswer>;
+    readonly openStream: (sessionId: string, headers: Readonly<Record<string, string>>, resume: {
+        readonly fromSequenceNum: number;
+    } | undefined, signal: AbortSignal) => Promise<RcStreamAnswer>;
+}
+/** The fan-out every stream event is handed to: the tracker files what it recognises, and each subscriber receives the event beside it. */
+interface RcEventFanout {
+    /** Delivers one event to every subscriber listening for its session (or for every session), synchronously, in publication order. */
+    readonly publish: (event: RcStreamEvent) => void;
+    /** Adds one listener, told every event whose session it matches; `undefined` listens to every session. Returns the detach function. */
+    readonly subscribe: (session: string | undefined, listener: (event: RcStreamEvent) => void) => () => void;
+}
+/** Creates the fan-out: plain synchronous listener sets, one per session plus one for every-session listeners. Delivery is synchronous so the tracker's filing (which rides the same publish) and every subscriber observe the same order; a subscriber that cannot keep up is bounded where it is bridged to a pull (the typed API's subscription), not here. */
+declare function createRcEventFanout(): RcEventFanout;
+/** Everything the attachment hub needs, injected so its decisions run against fakes in unit tests. */
+interface RcStreamHubDeps {
+    readonly now: () => number;
+    /** The tracker's credential accessor: the OAuth-kind bearer and protocol headers the attachment replays, exactly as the write path does. */
+    readonly credentialOf: (sessionId: string) => RcObservedCredential | undefined;
+    /** The tracker's swept session list: an attachment whose session has expired is dropped, exactly when the tracker itself gives up on it. */
+    readonly trackedSessions: () => readonly string[];
+    /** Files one envelope with the tracker: advances the session's sequence cursor and births or retires pending control requests, exactly as an observed event-batch body does. */
+    readonly fileStreamEvent: (sessionId: string, event: RcStreamEnvelope) => void;
+    /** Reads the session's sequence cursor: the highest number the door has seen, from the stream or from its own confirmed writes. */
+    readonly sequenceNumOf: (sessionId: string) => number | undefined;
+    readonly dial: RcStreamDial;
+    readonly fanout: RcEventFanout;
+    /** Mints the stable client id one session's attachment announces: a v4 UUID or better in production. Stable means it survives reconnects, so the host sees one client, not a new one per drop. */
+    readonly newClientId: () => string;
+    /** How long a failed attachment backs off; production passes `RC_STREAM_BACKOFF_MS`, tests pass small values so a backoff is reached in milliseconds. */
+    readonly backoffMs: number;
+    readonly sleep: (ms: number) => Promise<void>;
+    /** The door's log, for attachment lifecycle lines only: never an event payload, never a credential. */
+    readonly log?: (line: string) => void;
+}
+/** The door's client read stream attachment: one stream per tracked session, fanned out to every subscriber. */
+interface RcStreamHub {
+    /** Reconciles the attachments against the tracker: attaches a stream to every tracked session whose OAuth credential is known, and drops an attachment whose session has expired or lost its credential. Idempotent, synchronous and total (never throws): the door calls it after every observed Remote Control exchange, so an attachment follows the session it belongs to without any polling of its own. */
+    readonly reconcile: () => void;
+    /** Stops every attachment and frees their dials. */
+    readonly close: () => void;
+}
+/** Creates the attachment hub. One per door process; everything it holds dies with it. */
+declare function createRcStreamHub(deps: RcStreamHubDeps): RcStreamHub;
+
 /** Where the Remote Control inject path dials: the API host's own address by default, over TLS with the door's interception-proof agent (real-name DNS resolution and the pf-exempt source-port range), so an injected event cannot be looped back into the door's own transparent surface. A test redirects the dial at a local stand-in presenting the host's name, exactly as the forwarding targets are redirected. */
 interface RcDialTarget {
     readonly host: string;
@@ -1891,6 +2033,7 @@ interface RcDialTarget {
  * The real `RcEventDial`: one keep-alive TLS agent of the door's own exempt kind, so every injected event rides the same interception-proof dials the door's forwarded traffic does. The dial only ever reads small JSON answers (an event write's result, or an error), never a stream.
  */
 declare function realRcEventDial(target?: RcDialTarget): RcEventDial;
+declare function realRcStreamDial(target?: RcDialTarget): RcStreamDial;
 declare function realConnectEffects(): ConnectEffects;
 
 /**
@@ -1966,6 +2109,225 @@ declare function frontDoorRcControl(transport: RcControlTransport, token: string
 /** The filesystem operations headroom coordination needs: the same shape as `FarmFs`, injected so every decision over state, sessions, and the start lock runs against an in-memory fake in tests. */
 type HeadroomFs = Pick<FarmFs, "mkdirp" | "mkdirPrivate" | "readFileUtf8" | "writeFileUtf8" | "writeFilePrivate" | "writeFileExclusive" | "readdir" | "removeRecursive">;
 
+/** What an `lstat` (which never follows symlinks) reports about one path, narrowed to what authenticating the socket needs. */
+interface SocketPathStat {
+    readonly kind: "dir" | "socket" | "symlink" | "other";
+    /** The owning user id. */
+    readonly uid: number;
+    /** The permission bits, without the file type bits. */
+    readonly mode: number;
+}
+/** The platform facts and the one filesystem call the socket checks need, injected so every refusal is unit-testable without a real socket, directory or second user. */
+interface HeadroomSocketTrustPorts {
+    /** `process.platform` in the real implementation. */
+    readonly platform: string;
+    /** This process's user id. Only called on a platform with unix sockets, which all have POSIX user ids. */
+    readonly currentUid: () => number;
+    /** Stats one path without following symlinks, or returns undefined when nothing is there. */
+    readonly lstat: (target: string) => SocketPathStat | undefined;
+}
+
+/**
+ * A secondary pre-pipeline surface the listener answers under one path prefix: the typed Remote Control API. The listener owns only the dispatch (the prefix and the not-matched 404); the handle itself is whatever the door built, so this file stays independent of the API framework behind it.
+ */
+interface PrePipelineApi {
+    /** The path prefix every request of this surface arrives under, outside the routed URL space. */
+    readonly pathPrefix: string;
+    /** Serves one request, resolving with whether a procedure under the prefix matched; the listener answers the 404 itself when one did not. */
+    readonly handle: (request: IncomingMessage, response: ServerResponse) => Promise<{
+        readonly matched: boolean;
+    }>;
+}
+
+/**
+ * The Remote Control operations as a typed oRPC API, so programmatic consumers (automation, a mobile or web client, another of this user's tools) get a generated type-safe client instead of hand-rolled HTTP. One procedure per existing operation, each wrapping the same operation the bespoke token-gated routes wrap (the routes stay: the CLI uses them), with inputs and outputs validating through the Zod schemas of `rcSchemas.ts`, which the operations' own values must satisfy, so contract and behaviour share one schema source and cannot drift apart silently.
+ *
+ * Mounted on the provider listener beside the bespoke namespace, authenticated by the same per-generation owner-only control token as a Bearer credential: a fresh random value per door start, written owner-only under the front door's state directory, and checked in constant time like every other capability the door accepts. `rc.subscribe` streams the client attachment's fan-out: every event the door's held stream produced, SSE-framed by oRPC's event iterator, each carrying its sequence number as the SSE event id so a consumer's own reconnect can resume exactly as the door's does.
+ */
+/** The one path prefix the typed API is mounted under, answered before the routed pipeline like the bespoke control routes are. */
+declare const RC_ORPC_PATH_PREFIX = "/__agent-shim/orpc";
+/** Everything the typed API needs: the same operations the bespoke control routes take, the fan-out its subscription reads, and the token both surfaces demand. */
+interface RcApiDeps {
+    /** This generation's control token: the value the door wrote owner-only for its callers to present. */
+    readonly expectedToken: string;
+    /** The observed sessions as the tracker lists them. */
+    readonly list: () => readonly RcSessionSummary[];
+    /** The observed sessions as the tracker reports their status, filtered to one when named. */
+    readonly statusOf: (sessionId?: string) => readonly RcSessionStatus[];
+    /** The control requests awaiting an answer, filtered to one session when named. */
+    readonly pendingOf: (sessionId?: string) => readonly RcPendingRequestSummary[];
+    /** The inject operation, already wired to the tracker and the door's API-host dial. */
+    readonly inject: (sessionId: string, text: string) => Promise<RcEventWriteResult>;
+    /** The answer operation, already wired to the tracker and the door's API-host dial. */
+    readonly answer: (sessionId: string, requestId: string, decision: RcAnswerDecision) => Promise<RcEventWriteResult>;
+    /** The interrupt operation, already wired to the tracker and the door's API-host dial. */
+    readonly interrupt: (sessionId: string) => Promise<RcEventWriteResult>;
+    /** The set-model operation, already wired to the tracker and the door's API-host dial. */
+    readonly setModel: (sessionId: string, model: string) => Promise<RcEventWriteResult>;
+    /** The set-permission-mode operation, already wired to the tracker and the door's API-host dial. */
+    readonly setPermissionMode: (sessionId: string, mode: RcPermissionMode) => Promise<RcEventWriteResult>;
+    /** The client attachment's fan-out, whose events the subscription yields. */
+    readonly fanout: RcEventFanout;
+}
+/** Builds the typed API's router: one procedure per operation, every one behind the control-token middleware. */
+declare function createRcApiRouter(deps: RcApiDeps): {
+    rc: {
+        list: _orpc_server.DecoratedProcedure<_orpc_server.MergedInitialContext<{
+            readonly headers: IncomingHttpHeaders;
+        } & Record<never, never>, {
+            readonly headers: IncomingHttpHeaders;
+        }, {
+            readonly headers: IncomingHttpHeaders;
+        }>, any, Schema<unknown, unknown>, zod.ZodObject<{
+            sessions: zod.ZodReadonly<zod.ZodArray<zod.ZodObject<{
+                id: zod.ZodString;
+                createdAt: zod.ZodNumber;
+                lastSeenAt: zod.ZodNumber;
+            }, zod_v4_core.$strict>>>;
+        }, zod_v4_core.$strict>, Record<never, never>, Record<never, never>>;
+        status: _orpc_server.DecoratedProcedure<_orpc_server.MergedInitialContext<{
+            readonly headers: IncomingHttpHeaders;
+        } & Record<never, never>, {
+            readonly headers: IncomingHttpHeaders;
+        }, {
+            readonly headers: IncomingHttpHeaders;
+        }>, any, zod.ZodObject<{
+            session: zod.ZodOptional<zod.ZodString>;
+        }, zod_v4_core.$strict>, zod.ZodObject<{
+            statuses: zod.ZodReadonly<zod.ZodArray<zod.ZodObject<{
+                workerState: zod.ZodOptional<zod.ZodObject<{
+                    value: zod.ZodString;
+                    observedAt: zod.ZodNumber;
+                }, zod_v4_core.$strict>>;
+                workerIdleSeconds: zod.ZodOptional<zod.ZodObject<{
+                    value: zod.ZodNumber;
+                    observedAt: zod.ZodNumber;
+                }, zod_v4_core.$strict>>;
+                pending: zod.ZodReadonly<zod.ZodArray<zod.ZodObject<{
+                    sessionId: zod.ZodString;
+                    requestId: zod.ZodString;
+                    type: zod.ZodString;
+                    summary: zod.ZodString;
+                    observedAt: zod.ZodNumber;
+                }, zod_v4_core.$strict>>>;
+                id: zod.ZodString;
+                createdAt: zod.ZodNumber;
+                lastSeenAt: zod.ZodNumber;
+            }, zod_v4_core.$strict>>>;
+        }, zod_v4_core.$strict>, Record<never, never>, Record<never, never>>;
+        pending: _orpc_server.DecoratedProcedure<_orpc_server.MergedInitialContext<{
+            readonly headers: IncomingHttpHeaders;
+        } & Record<never, never>, {
+            readonly headers: IncomingHttpHeaders;
+        }, {
+            readonly headers: IncomingHttpHeaders;
+        }>, any, zod.ZodObject<{
+            session: zod.ZodOptional<zod.ZodString>;
+        }, zod_v4_core.$strict>, zod.ZodObject<{
+            pending: zod.ZodReadonly<zod.ZodArray<zod.ZodObject<{
+                sessionId: zod.ZodString;
+                requestId: zod.ZodString;
+                type: zod.ZodString;
+                summary: zod.ZodString;
+                observedAt: zod.ZodNumber;
+            }, zod_v4_core.$strict>>>;
+        }, zod_v4_core.$strict>, Record<never, never>, Record<never, never>>;
+        send: _orpc_server.DecoratedProcedure<_orpc_server.MergedInitialContext<{
+            readonly headers: IncomingHttpHeaders;
+        } & Record<never, never>, {
+            readonly headers: IncomingHttpHeaders;
+        }, {
+            readonly headers: IncomingHttpHeaders;
+        }>, any, zod.ZodObject<{
+            session: zod.ZodString;
+            text: zod.ZodString;
+        }, zod_v4_core.$strict>, zod.ZodObject<{
+            session: zod.ZodString;
+            sequenceNums: zod.ZodReadonly<zod.ZodArray<zod.ZodNumber>>;
+        }, zod_v4_core.$strict>, Record<never, never>, Record<never, never>>;
+        answer: _orpc_server.DecoratedProcedure<_orpc_server.MergedInitialContext<{
+            readonly headers: IncomingHttpHeaders;
+        } & Record<never, never>, {
+            readonly headers: IncomingHttpHeaders;
+        }, {
+            readonly headers: IncomingHttpHeaders;
+        }>, any, zod.ZodObject<{
+            session: zod.ZodString;
+            request: zod.ZodString;
+            approve: zod.ZodBoolean;
+            text: zod.ZodOptional<zod.ZodString>;
+        }, zod_v4_core.$strict>, zod.ZodObject<{
+            session: zod.ZodString;
+            request: zod.ZodString;
+            sequenceNums: zod.ZodReadonly<zod.ZodArray<zod.ZodNumber>>;
+        }, zod_v4_core.$strict>, Record<never, never>, Record<never, never>>;
+        interrupt: _orpc_server.DecoratedProcedure<_orpc_server.MergedInitialContext<{
+            readonly headers: IncomingHttpHeaders;
+        } & Record<never, never>, {
+            readonly headers: IncomingHttpHeaders;
+        }, {
+            readonly headers: IncomingHttpHeaders;
+        }>, any, zod.ZodObject<{
+            session: zod.ZodString;
+        }, zod_v4_core.$strict>, zod.ZodObject<{
+            session: zod.ZodString;
+            sequenceNums: zod.ZodReadonly<zod.ZodArray<zod.ZodNumber>>;
+        }, zod_v4_core.$strict>, Record<never, never>, Record<never, never>>;
+        setModel: _orpc_server.DecoratedProcedure<_orpc_server.MergedInitialContext<{
+            readonly headers: IncomingHttpHeaders;
+        } & Record<never, never>, {
+            readonly headers: IncomingHttpHeaders;
+        }, {
+            readonly headers: IncomingHttpHeaders;
+        }>, any, zod.ZodObject<{
+            session: zod.ZodString;
+            model: zod.ZodString;
+        }, zod_v4_core.$strict>, zod.ZodObject<{
+            session: zod.ZodString;
+            sequenceNums: zod.ZodReadonly<zod.ZodArray<zod.ZodNumber>>;
+        }, zod_v4_core.$strict>, Record<never, never>, Record<never, never>>;
+        setPermissionMode: _orpc_server.DecoratedProcedure<_orpc_server.MergedInitialContext<{
+            readonly headers: IncomingHttpHeaders;
+        } & Record<never, never>, {
+            readonly headers: IncomingHttpHeaders;
+        }, {
+            readonly headers: IncomingHttpHeaders;
+        }>, any, zod.ZodObject<{
+            session: zod.ZodString;
+            mode: zod.ZodEnum<{
+                default: "default";
+                acceptEdits: "acceptEdits";
+                bypassPermissions: "bypassPermissions";
+                plan: "plan";
+                dontAsk: "dontAsk";
+                auto: "auto";
+            }>;
+        }, zod_v4_core.$strict>, zod.ZodObject<{
+            session: zod.ZodString;
+            sequenceNums: zod.ZodReadonly<zod.ZodArray<zod.ZodNumber>>;
+        }, zod_v4_core.$strict>, Record<never, never>, Record<never, never>>;
+        subscribe: _orpc_server.DecoratedProcedure<_orpc_server.MergedInitialContext<{
+            readonly headers: IncomingHttpHeaders;
+        } & Record<never, never>, {
+            readonly headers: IncomingHttpHeaders;
+        }, {
+            readonly headers: IncomingHttpHeaders;
+        }>, any, zod.ZodObject<{
+            session: zod.ZodOptional<zod.ZodString>;
+        }, zod_v4_core.$strict>, any, Record<never, never>, Record<never, never>>;
+    };
+};
+/** The typed API's router, as the CLI-side client's own type is derived from it. */
+type RcApiRouter = ReturnType<typeof createRcApiRouter>;
+/**
+ * Builds the typed API's node handler, already bound to its mount prefix and context: the pre-pipeline surface the provider listener hands every request under `RC_ORPC_PATH_PREFIX`, answering with `matched: false` for a path under the prefix that names no procedure (which the listener itself answers as a 404). Request bodies are bounded by the same protocol cap the bespoke routes apply.
+ */
+declare function createRcApiNodeHandler(deps: RcApiDeps): PrePipelineApi;
+/** The typed API's client as the `frontdoor rc` verbs use it: every call presents the control token, over TLS trusting only the CA file the door's own state names. */
+type RcApiClient = RouterClient<RcApiRouter>;
+/** Builds the typed API's client for the door's provider listener: the same address, CA and per-generation control token the bespoke control client uses. */
+declare function frontDoorRcApiClient(port: number, ca: string, token: string): RcApiClient;
+
 /** The outcome of authenticating the listener a front-door state file names. */
 type ListenerVerdict = {
     readonly ok: true;
@@ -2417,24 +2779,6 @@ declare function ensureHeadroom(params: {
 /** The token-saving settings of the `headroom` config block, without its install and lifecycle fields (`source`, `idleShutdownMinutes`). */
 type HeadroomSettings = Pick<HeadroomGlobalConfig, "mode" | "targetRatio" | "ccr" | "rolloutChannel" | "interceptToolResults" | "readMaturation">;
 
-/** What an `lstat` (which never follows symlinks) reports about one path, narrowed to what authenticating the socket needs. */
-interface SocketPathStat {
-    readonly kind: "dir" | "socket" | "symlink" | "other";
-    /** The owning user id. */
-    readonly uid: number;
-    /** The permission bits, without the file type bits. */
-    readonly mode: number;
-}
-/** The platform facts and the one filesystem call the socket checks need, injected so every refusal is unit-testable without a real socket, directory or second user. */
-interface HeadroomSocketTrustPorts {
-    /** `process.platform` in the real implementation. */
-    readonly platform: string;
-    /** This process's user id. Only called on a platform with unix sockets, which all have POSIX user ids. */
-    readonly currentUid: () => number;
-    /** Stats one path without following symlinks, or returns undefined when nothing is there. */
-    readonly lstat: (target: string) => SocketPathStat | undefined;
-}
-
 /** Everything the supervisor needs to run the daemon, resolved from the global config and the filesystem before it starts. */
 interface HeadroomSupervisorConfig {
     /** The install spec as configured (`headroom.source`), already defaulted. */
@@ -3387,5 +3731,5 @@ interface PrepareClaudeLaunchOptions {
  */
 declare function prepareClaudeLaunch(options: PrepareClaudeLaunchOptions): LaunchPlan;
 
-export { AMBIENT_CREDENTIAL_VARS, CONNECT_INTERCEPT_HOST, CONNECT_INTERCEPT_HOSTS, CONNECT_LIMITS, CONTROL_PATH_PREFIX, CategoryClassificationOverlaySchema, CategoryClassificationSchema, CategoryMapSchema, CliError, ConfigProfileSchema, CredentialCacheSchema, CredentialSchema, CredentialSourceSchema, DirectoryRuleAlreadyExistsError, DirectoryRuleMissingTargetError, DirectoryRuleNotFoundError, DirectoryRuleSchema, DirectoryRulesSchema, EXIT_FAILURE, EXIT_USAGE, EntryValueSchema, FARM_MANIFEST_FILENAME, FrontDoorStartError, GlobalConfigSchema, HeadroomStartError, IdentityAlreadyExistsError, IdentityNotFoundError, IdentitySchema, InvalidCategoryNameError, InvalidIdentityNameError, InvalidProviderNameError, LaunchRefusedError, LegacyProviderFileError, PROMPT_CACHE_TTL_MS, PlanClassSchema, PoolNameSchema, PoolNotFoundError, PoolPickReportSchema, PoolSchema, PortableConfigSchema, ProfileAlreadyExistsError, ProfileNotFoundError, ProviderAlreadyExistsError, ProviderKindMismatchError, ProviderNotFoundError, ProviderSchema, RC_IDLE_EXPIRY_MS, RC_PENDING_DEADLINE_MS, RC_PERMISSION_MODES, RC_REQUEST_PARSE_CAP_BYTES, RC_SESSIONS_PATH_PREFIX, ROUTED_PATH_PREFIX, UsageError, UsageSnapshotError, UsageSnapshotSchema, WhenSchema, addDirectoryRule, addIdentity, addPool, addProvider, answerRcControlRequest, buildEntryFacts, buildLayoutPaths, buildRcControlResponsePayload, buildRcEventWriteBody, buildRcInterruptPayload, buildRcSetModelPayload, buildRcSetPermissionModePayload, buildRcUserMessagePayload, carryOver, checkReportHasWarnings, checkReportToJson, collectCheckReport, collectDoctorReport, collectPoolPick, createLeafCache, createProfile, createRcControlHandler, createRcSessionTracker, describeProviderEndpoint, detectAmbientCredential, effectiveWindow, ensureCa, ensureFrontDoor, ensureHeadroom, evaluateAmbientCredentialGuard, evaluateWhen, formatAmbientCredentialGuardMessage, formatCheckReport, formatDoctorReport, forwardableHeaders, frontDoorRcControl, generateCa, identityExists, injectRcUserMessage, interruptRcSession, isIdentityDirectoryName, isInterceptedHost, isRcPermissionMode, listDirectoryRules, listIdentities, listProfiles, listProviders, listUsageSnapshots, matchBranch, mintLeaf, observingRoutedRoute, parseConnectTarget, planOf, prepareClaudeLaunch, prepareLaunch, profileExists, providerExists, rankPool, rcEventWriteResultFromAnswer, rcObserverAsPassthrough, readActiveIdentity, readDirectoryRules, readFarmManifest, readGlobalConfig, readIdentity, readPools, readProfile, readProvider, readUsageSnapshot, realConnectCertStore, realConnectEffects, realRcControlTransport, realRcEventDial, recoverFarm, recoveryDiagnostics, removeDirectoryRule, removeIdentity, removePool, removeProfile, removeProvider, requirePool, resolveAgentShimHome, resolveClaudeHome, resolveDecisions, resolveLayoutPaths, resolveSupervisorConfig, resyncFarm, runCheck, runDoctor, runFrontDoorSupervisor, runSupervisor, servedByPipeline, setAllowAmbientCredential, setDefaultConfigProfile, setGlobalDefaultProfile, setIdentityCredential, setPool, setProfileCategories, setProfileEntries, setProfileLaunchFlags, setProfileMetadata, setRcSessionModel, setRcSessionPermissionMode, snapshotPath, startConnectServer, topLevelNames, updateDirectoryRule, updateProvider, useIdentity, writeDirectoryRules };
-export type { AddDirectoryRuleOptions, AddProviderInput, AmbientCredentialDetection, AmbientCredentialGuardResult, AmbientCredentialVar, BuildEntryFactsParams, CaMaterial, Candidate, CarryOverParams, CarryOverResult, CategoryMap, CheckReport, CollectCheckReportParams, CollectDoctorReportParams, CompiledRule, ConditionContext, ConfigProfile, ConnectCertStore, ConnectEffects, ConnectLimits, ConnectServerConfig, ConnectServerHandle, ConnectTarget, Credential, CredentialSource, Decision, Diagnostic, DirectoryRule, DirectoryRules, DoctorReport, EffectiveWindow, EliminatedRule, EnsureFrontDoorPorts, EnsureHeadroomPorts, EntryFact, EntryFacts, EntryValue, EvaluateAmbientCredentialGuardParams, FlattenedCascade, FrontDoorRcControl, FrontDoorSupervisorPorts, GlobalConfig, HeadroomSupervisorConfig, Identity, IdentityCredentialChange, IdentityListEntry, IdentityListing, InjectedCredential, LaunchPlan, Layer, LayerId, LayoutPaths, LeafCert, PlanClass, Pool, PoolMember, PoolPickReport, PoolRanking, PortableConfig, PrepareClaudeLaunchOptions, PrepareLaunchParams, ProfileListEntry, Provider, ProviderListEntry, RankPoolInput, RcAnswerDecision, RcAnswerDeps, RcControlAnswer, RcControlHandlerDeps, RcControlRequestDeps, RcControlTransport, RcDialAnswer, RcDialTarget, RcEventDial, RcEventWriteResult, RcExchangeObserver, RcInjectDeps, RcObservedCredential, RcObservedRequest, RcPendingRequestSummary, RcPermissionMode, RcSessionStatus, RcSessionSummary, RcSessionTracker, RcSessionTrackerDeps, RcWorkerFact, RcWriteHeaders, RecoverFarmParams, RecoveryResult, ResolveDecisionsInput, ResolvedState, ResyncFarmParams, ResyncFarmResult, RunCheckParams, RunDoctorParams, RunFrontDoorSupervisorOptions, RunSupervisorOptions, StickyPick, SupervisorPorts, UnreadableIdentityListEntry, UpdateDirectoryRuleOptions, UpdateProviderInput, UsageReadFs, UsageSnapshot, WhenCondition, WhenEvaluation };
+export { AMBIENT_CREDENTIAL_VARS, CONNECT_INTERCEPT_HOST, CONNECT_INTERCEPT_HOSTS, CONNECT_LIMITS, CONTROL_PATH_PREFIX, CategoryClassificationOverlaySchema, CategoryClassificationSchema, CategoryMapSchema, CliError, ConfigProfileSchema, CredentialCacheSchema, CredentialSchema, CredentialSourceSchema, DirectoryRuleAlreadyExistsError, DirectoryRuleMissingTargetError, DirectoryRuleNotFoundError, DirectoryRuleSchema, DirectoryRulesSchema, EXIT_FAILURE, EXIT_USAGE, EntryValueSchema, FARM_MANIFEST_FILENAME, FrontDoorStartError, GlobalConfigSchema, HeadroomStartError, IdentityAlreadyExistsError, IdentityNotFoundError, IdentitySchema, InvalidCategoryNameError, InvalidIdentityNameError, InvalidProviderNameError, LaunchRefusedError, LegacyProviderFileError, PROMPT_CACHE_TTL_MS, PlanClassSchema, PoolNameSchema, PoolNotFoundError, PoolPickReportSchema, PoolSchema, PortableConfigSchema, ProfileAlreadyExistsError, ProfileNotFoundError, ProviderAlreadyExistsError, ProviderKindMismatchError, ProviderNotFoundError, ProviderSchema, RC_IDLE_EXPIRY_MS, RC_ORPC_PATH_PREFIX, RC_PENDING_DEADLINE_MS, RC_PERMISSION_MODES, RC_REQUEST_PARSE_CAP_BYTES, RC_SESSIONS_PATH_PREFIX, RC_STREAM_BACKOFF_MS, ROUTED_PATH_PREFIX, RcPermissionModeSchema, RcStreamEnvelopeSchema, RcStreamEventSchema, UsageError, UsageSnapshotError, UsageSnapshotSchema, WhenSchema, addDirectoryRule, addIdentity, addPool, addProvider, answerRcControlRequest, buildEntryFacts, buildLayoutPaths, buildRcControlResponsePayload, buildRcEventWriteBody, buildRcInterruptPayload, buildRcSetModelPayload, buildRcSetPermissionModePayload, buildRcUserMessagePayload, carryOver, checkReportHasWarnings, checkReportToJson, collectCheckReport, collectDoctorReport, collectPoolPick, createLeafCache, createProfile, createRcApiNodeHandler, createRcApiRouter, createRcControlHandler, createRcEventFanout, createRcSessionTracker, createRcStreamHub, createSseParser, describeProviderEndpoint, detectAmbientCredential, effectiveWindow, ensureCa, ensureFrontDoor, ensureHeadroom, evaluateAmbientCredentialGuard, evaluateWhen, formatAmbientCredentialGuardMessage, formatCheckReport, formatDoctorReport, forwardableHeaders, frontDoorRcApiClient, frontDoorRcControl, generateCa, identityExists, injectRcUserMessage, interruptRcSession, isIdentityDirectoryName, isInterceptedHost, isRcPermissionMode, listDirectoryRules, listIdentities, listProfiles, listProviders, listUsageSnapshots, matchBranch, mintLeaf, observingRoutedRoute, parseConnectTarget, parseRcStreamEnvelope, planOf, prepareClaudeLaunch, prepareLaunch, profileExists, providerExists, rankPool, rcEventWriteResultFromAnswer, rcObserverAsPassthrough, readActiveIdentity, readDirectoryRules, readFarmManifest, readGlobalConfig, readIdentity, readPools, readProfile, readProvider, readUsageSnapshot, realConnectCertStore, realConnectEffects, realRcControlTransport, realRcEventDial, realRcStreamDial, recoverFarm, recoveryDiagnostics, removeDirectoryRule, removeIdentity, removePool, removeProfile, removeProvider, requirePool, resolveAgentShimHome, resolveClaudeHome, resolveDecisions, resolveLayoutPaths, resolveSupervisorConfig, resyncFarm, runCheck, runDoctor, runFrontDoorSupervisor, runSupervisor, servedByPipeline, setAllowAmbientCredential, setDefaultConfigProfile, setGlobalDefaultProfile, setIdentityCredential, setPool, setProfileCategories, setProfileEntries, setProfileLaunchFlags, setProfileMetadata, setRcSessionModel, setRcSessionPermissionMode, snapshotPath, startConnectServer, topLevelNames, updateDirectoryRule, updateProvider, useIdentity, writeDirectoryRules };
+export type { AddDirectoryRuleOptions, AddProviderInput, AmbientCredentialDetection, AmbientCredentialGuardResult, AmbientCredentialVar, BuildEntryFactsParams, CaMaterial, Candidate, CarryOverParams, CarryOverResult, CategoryMap, CheckReport, CollectCheckReportParams, CollectDoctorReportParams, CompiledRule, ConditionContext, ConfigProfile, ConnectCertStore, ConnectEffects, ConnectLimits, ConnectServerConfig, ConnectServerHandle, ConnectTarget, Credential, CredentialSource, Decision, Diagnostic, DirectoryRule, DirectoryRules, DoctorReport, EffectiveWindow, EliminatedRule, EnsureFrontDoorPorts, EnsureHeadroomPorts, EntryFact, EntryFacts, EntryValue, EvaluateAmbientCredentialGuardParams, FlattenedCascade, FrontDoorRcControl, FrontDoorSupervisorPorts, GlobalConfig, HeadroomSupervisorConfig, Identity, IdentityCredentialChange, IdentityListEntry, IdentityListing, InjectedCredential, LaunchPlan, Layer, LayerId, LayoutPaths, LeafCert, PlanClass, Pool, PoolMember, PoolPickReport, PoolRanking, PortableConfig, PrepareClaudeLaunchOptions, PrepareLaunchParams, ProfileListEntry, Provider, ProviderListEntry, RankPoolInput, RcAnswerDecision, RcAnswerDeps, RcApiClient, RcApiDeps, RcApiRouter, RcControlAnswer, RcControlHandlerDeps, RcControlRequestDeps, RcControlTransport, RcDialAnswer, RcDialTarget, RcEventDial, RcEventFanout, RcEventWriteResult, RcExchangeObserver, RcInjectDeps, RcObservedCredential, RcObservedRequest, RcPendingRequestSummary, RcPermissionMode, RcPresenceAnswer, RcSessionStatus, RcSessionSummary, RcSessionTracker, RcSessionTrackerDeps, RcStreamAnswer, RcStreamDial, RcStreamEnvelope, RcStreamEvent, RcStreamHub, RcStreamHubDeps, RcWorkerFact, RcWriteHeaders, RecoverFarmParams, RecoveryResult, ResolveDecisionsInput, ResolvedState, ResyncFarmParams, ResyncFarmResult, RunCheckParams, RunDoctorParams, RunFrontDoorSupervisorOptions, RunSupervisorOptions, SseParsedEvent, StickyPick, SupervisorPorts, UnreadableIdentityListEntry, UpdateDirectoryRuleOptions, UpdateProviderInput, UsageReadFs, UsageSnapshot, WhenCondition, WhenEvaluation };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "agent-shim",
-  "version": "8.8.0",
+  "version": "8.9.0",
   "description": "A profile manager and launcher for Claude Code that lets one person run multiple logins from one machine while controlling what gets shared between them.",
   "license": "MIT",
   "author": "Joseph Mearman <joseph@mearman.co.uk>",
@@ -50,6 +50,8 @@
   },
   "dependencies": {
     "@clack/prompts": "^1.8.0",
+    "@orpc/client": "1.15.4",
+    "@orpc/server": "1.15.4",
     "commander": "^15.0.0",
     "cosmiconfig": "^10.0.1",
     "picomatch": "^4.0.7",