@hraness/xcb 0.9.1

package/dist/codex-process.d.ts

@@ -0,0 +1,67 @@
+import type { ProviderProcessWriteResult } from "./process-port.ts";
+import { type Readable, type Writable } from "node:stream";
+import { type CodexParentRuntimeBinding } from "./codex-host.ts";
+export declare const CODEX_NATIVE_VERSION = "0.153.4";
+export declare const CODEX_NATIVE_SHA256 = "b973d440acac501fd2594a43e7ca9ce41e0a65b9dfb28d0d7a7837c99e1261e3";
+export type CodexProcessReceipt = Readonly<{
+    nativeVersion: string;
+    executableSha256: string;
+    runtimeSnapshotSha256: string;
+    configSha256: string;
+    profileSha256: string;
+    custodyPath: string;
+    parentRuntimeSha256: string;
+    scratchContentSha256: string;
+    scratchIdentitySha256: string;
+    pid: number | null;
+    pgid: number | null;
+    rootExited: boolean;
+    groupAbsent: boolean;
+    stdioJoined: boolean;
+    scratchRetained: boolean;
+    nativeExitCode: number | null;
+    nativeExitSignal: string | null;
+    runtimeErrors: readonly string[];
+    cleanupErrors: readonly string[];
+}>;
+export interface CodexProcessHandle {
+    readonly cwd: string;
+    readonly stdin?: Writable;
+    readonly stdout: Readable;
+    /** Full acceptance is distinct from the RPC result; never replay uncertain bytes. */
+    write(bytes: Uint8Array): Promise<ProviderProcessWriteResult>;
+    readonly exited: Promise<void>;
+    readonly ready: Promise<void>;
+    receipt(): CodexProcessReceipt;
+    stopAndJoin(): Promise<CodexProcessReceipt>;
+}
+export interface CodexProcessLauncher {
+    /** No contact path, credential, arbitrary executable, or caller-selected argv. */
+    launch(input: {
+        runId: string;
+        accountId: string;
+        workspaceId: string;
+        configuration: string;
+        relayPort: number;
+        signal: AbortSignal;
+    }): Promise<CodexProcessHandle>;
+}
+/** Journal decoding supplies recovery evidence, never process-stop authority. */
+export declare function parseCodexCustodyJournal(text: string): {
+    snapshot: Readonly<Record<string, unknown>>;
+    incompleteTail: boolean;
+};
+/** Inspect through one no-follow descriptor before copying any executable bytes. */
+export declare function inspectCodexExecutable(path: string): Promise<Buffer>;
+/** Experimental runtime policy; the launcher never issues a qualification. */
+export declare function codexMacSandbox(input: {
+    executable: string;
+    scratch: string;
+    relayPort: number;
+}): string;
+/** Internal host launcher. Account/API integration and production admission are separate. */
+export declare function createCodexProcessLauncher(options: {
+    executablePath: string;
+    stateRoot: string;
+    parentRuntime: CodexParentRuntimeBinding;
+}): CodexProcessLauncher;

package/dist/codex-protocol-manifest.d.ts

@@ -0,0 +1,27 @@
+/** Immutable identity emitted by a trusted host after it has inspected the
+ * exact Codex executable and generated protocol schema. A digest supplied by
+ * a caller is only an assertion until this manifest is host-produced. */
+export type CodexProtocolManifest = Readonly<{
+    protocol: "codex-app-server-experimental";
+    protocolVersion: string;
+    sourceVersion: string;
+    executableSha256: string;
+    schemaSha256: string;
+    manifestSha256: string;
+    generatedAtUnixMs: number;
+}>;
+export declare function buildCodexProtocolManifest(input: Readonly<{
+    protocolVersion: string;
+    sourceVersion: string;
+    executableSha256: string;
+    schemaSha256: string;
+    generatedAtUnixMs: number;
+}>): CodexProtocolManifest;
+/** Bind a trusted host manifest to the runtime selected for a task. This does
+ * not inspect files or execute Codex; those effects belong to the host that
+ * created the manifest. */
+export declare function assertCodexProtocolManifest(value: unknown, runtime: Readonly<{
+    version: string;
+    sha256: string;
+    schemaSha256: string;
+}>): CodexProtocolManifest;

package/dist/codex-relay.d.ts

@@ -0,0 +1,80 @@
+import type { BrokerToolName } from "./broker.ts";
+import { type CodexTool, type CodexCapabilityMapping, type CodexTaskSettings } from "./codex-config.ts";
+/** A trusted host port, deliberately without credential discovery or a live HTTP implementation.
+ * A paid implementation must separately reserve/account usage and impose its own output-token cap.
+ */
+export interface CodexResponsesUpstream {
+    request(body: Readonly<Record<string, unknown>>, signal: AbortSignal): Promise<Response>;
+}
+export type CodexLimits = Readonly<{
+    deadlineMs: number;
+    ioMs: number;
+    cleanupMs: number;
+    maxRequests: number;
+    maxRequestBytes: number;
+    maxResponseBytes: number;
+    maxFrameBytes: number;
+    maxFrames: number;
+}>;
+export declare function codexLimits(input?: Partial<CodexLimits>): CodexLimits;
+/** Application tasks have an explicit run/cleanup allocation. Keep the legacy
+ * contact limits and every IO/request/byte limit unchanged, and retain the
+ * task runtime's one-hour combined ceiling. */
+export declare function codexTaskLimits(input?: Partial<CodexLimits>): CodexLimits;
+export declare function codexAssert(value: unknown, code: string): asserts value;
+export declare function codexRecord(value: unknown): Record<string, unknown>;
+export declare function codexBounded<T>(promise: Promise<T>, ms: number, code: string): Promise<T>;
+export type CodexRelayReceipt = Readonly<{
+    requests: number;
+    calls: number;
+    started: number;
+    completed: number;
+    outputsObserved: number;
+    finalObserved: boolean;
+    joined: boolean;
+    failure: string | null;
+}>;
+export type CodexTaskRelayOptions = Readonly<{
+    mapping: CodexCapabilityMapping;
+    settings: CodexTaskSettings;
+    executionDeadlineUnixMs: number;
+    maxOutputBytes: number;
+    now?: () => number;
+}>;
+export interface CodexRelay {
+    readonly baseUrl: string;
+    readonly port: number;
+    bindTurn(threadId: string, turnId: string): void;
+    claimCall(params: Record<string, unknown>): {
+        id: string;
+        name: BrokerToolName;
+        input: Record<string, unknown>;
+    };
+    claimTaskCall(params: Record<string, unknown>): {
+        id: string;
+        name: string;
+        input: Record<string, unknown>;
+    };
+    completeCall(id: string, text: string, success: boolean, write: () => Promise<void>): Promise<void>;
+    observeTool(params: Record<string, unknown>, phase: "started" | "completed"): void;
+    observeFinal(text: unknown): void;
+    result(): unknown;
+    resultText(): string | null;
+    usage(): Readonly<{
+        inputTokens: number | null;
+        outputTokens: number | null;
+        totalTokens: number | null;
+    }>;
+    receipt(): CodexRelayReceipt;
+    close(): Promise<CodexRelayReceipt>;
+}
+export declare function startCodexRelay(options: {
+    model: string;
+    prompt: string;
+    tools: readonly CodexTool[];
+    upstream: CodexResponsesUpstream;
+    signal: AbortSignal;
+    limits: CodexLimits;
+    fail(code: string): void;
+    task?: CodexTaskRelayOptions;
+}): Promise<CodexRelay>;

package/dist/codex-scratch.d.ts

@@ -0,0 +1,36 @@
+declare const directories: readonly ["", "home", "state", "tmp", "work"];
+type Directory = typeof directories[number];
+type EntryPath = Directory | "state/config.toml";
+export type CodexScratchEntry = Readonly<{
+    path: EntryPath;
+    kind: "directory" | "file";
+    device: string;
+    inode: string;
+    uid: number;
+    mode: number;
+    links: number;
+    size: string;
+    modifiedNs: string;
+    changedNs: string;
+}>;
+export type CodexScratchInspection = Readonly<{
+    schema: "xcb.codex-scratch.v1";
+    configurationSha256: string;
+    configurationBytes: number;
+    /** Content/layout identity, independent of the newly allocated directory inodes. */
+    contentSha256: string;
+    /** Exact inspected physical root, relative entries, and stable filesystem metadata. */
+    identitySha256: string;
+    entries: readonly CodexScratchEntry[];
+}>;
+/** Inspect only a newly created host scratch tree, immediately before launch.
+ * Model/tool-written paths must never be supplied to this host-only function.
+ * No contact data, aliases, credentials, plugins, or extra files belong here.
+ * This is a checked snapshot, not a filesystem lease: a hostile same-UID host
+ * or root racing preparation is excluded. The launcher must retain that trust
+ * boundary after inspection; the result alone does not qualify a provider. */
+export declare function inspectCodexScratch(input: {
+    scratch: string;
+    configuration: string | Uint8Array;
+}): Promise<CodexScratchInspection>;
+export {};

package/dist/codex-session.d.ts

@@ -0,0 +1,44 @@
+import type { ToolBroker } from "./broker.ts";
+import type { CapabilityBroker } from "./capabilities.ts";
+import type { CodexProcessLauncher, CodexProcessReceipt } from "./codex-process.ts";
+import { type CodexLimits, type CodexRelayReceipt, type CodexResponsesUpstream, type CodexTaskRelayOptions } from "./codex-relay.ts";
+import type { AgentRunRequest } from "./runtime.ts";
+export type CodexSessionReceipt = Readonly<{
+    status: "completed" | "failed";
+    productionQualified: false;
+    initialized: boolean;
+    turnCompleted: boolean;
+    usage: Readonly<{
+        inputTokens: number | null;
+        outputTokens: number | null;
+        totalTokens: number | null;
+    }>;
+    process: CodexProcessReceipt | null;
+    relay: CodexRelayReceipt | null;
+    handlersJoined: boolean;
+    processStopped: boolean;
+    failures: readonly string[];
+    frames: number;
+    stdoutBytes: number;
+    unexpectedNotification: string | null;
+    failureStage: "prepare" | "initialize" | "thread/start" | "turn/start" | "turn" | "cleanup" | null;
+    deniedNativeRequest: string | null;
+}>;
+export declare class CodexSessionError extends Error {
+    readonly receipt: CodexSessionReceipt;
+    constructor(receipt: CodexSessionReceipt);
+}
+/** Low-level unqualified driver. Native ownership and upstream access are explicit trusted ports.
+ * No module import, account discovery, adapter registration or credential-bearing network operation.
+ */
+export declare function runCodexSession(options: {
+    request: AgentRunRequest;
+    broker: ToolBroker | CapabilityBroker;
+    upstream: CodexResponsesUpstream;
+    launcher: CodexProcessLauncher;
+    limits?: Partial<CodexLimits>;
+    task?: CodexTaskRelayOptions;
+}): Promise<{
+    output: unknown;
+    receipt: CodexSessionReceipt;
+}>;

package/dist/codex-task-adapter.d.ts

@@ -0,0 +1,24 @@
+import type { CodexProcessLauncher } from "./codex-process.ts";
+import { type CodexResponsesUpstream } from "./codex-relay.ts";
+import type { AgentTaskAdapter, AgentTaskRoute, TaskRuntimeQualification } from "./task-runtime.ts";
+export type CodexTaskAdapterOptions = Readonly<{
+    route: AgentTaskRoute;
+    runtime: Readonly<{
+        version: string;
+        digest: string;
+    }>;
+    qualification: TaskRuntimeQualification;
+    instructions: Readonly<{
+        base: string;
+        developer: string;
+    }>;
+    upstream: CodexResponsesUpstream;
+    launcher: CodexProcessLauncher;
+    now(): number;
+}>;
+/**
+ * Native Codex task adapter. It receives a capability broker from xcb,
+ * maps that exact profile into the relay, and retains the native stop receipt
+ * until the task runtime has joined the process and broker cleanup.
+ */
+export declare function createCodexTaskAdapter(options: CodexTaskAdapterOptions): AgentTaskAdapter;

package/dist/codex-task-process.d.ts

@@ -0,0 +1,21 @@
+import { bindCodexAccountProcess } from "./codex-account-process.ts";
+import type { CodexAccountProcessCloseReceipt } from "./codex-account-transport.ts";
+import type { CodexProcessHandle, CodexProcessReceipt } from "./codex-process.ts";
+export type CodexTaskProcessOptions = Parameters<typeof bindCodexAccountProcess>[0] & Readonly<{
+    cwd: string;
+    joinTimeoutMs: number;
+    /** Application-owned policy, scratch and journal observations. */
+    receipt(): CodexProcessReceipt;
+    /** Called only after matching physical proof and settled local work. The host
+     * persists closure and handles its own scratch; native join supplies neither
+     * configuration qualification nor successful product finalization. */
+    finalize(observation: Readonly<{
+        physical: CodexAccountProcessCloseReceipt;
+        operationCompleted: boolean;
+    }>): Promise<CodexProcessReceipt>;
+}>;
+/** Bridge for a trusted CodexProcessLauncher or CodexManagedProcessLauncher.
+ * The application still prepares and binds its exact task/account/profile,
+ * admits the shared artifact, owns launch intent and returns an owned port even
+ * when readiness fails. No launcher or qualification is inferred here. */
+export declare function bindCodexTaskProcess(options: CodexTaskProcessOptions): CodexProcessHandle;

package/dist/devin-acp.d.ts

@@ -0,0 +1,105 @@
+import { Transform } from "node:stream";
+/** Bounded ACP v1 codec. Every inbound frame is withheld until its byte bound,
+ * UTF-8, JSON object and JSON-RPC envelope pass; malformed recognized frames
+ * close the client rather than being parsed hopefully. */
+export declare const DEVIN_ACP_MAX_FRAME_BYTES: number;
+export declare const DEVIN_ACP_MAX_PROMPT_BYTES: number;
+export declare const DEVIN_ACP_PROTOCOL_VERSION = 1;
+export type DevinAcpError = Readonly<{
+    code: number;
+    message: string;
+}>;
+export type DevinAcpInbound = Readonly<{
+    kind: "request";
+    id: string | number;
+    method: string;
+    params: unknown;
+}> | Readonly<{
+    kind: "notification";
+    method: string;
+    params: unknown;
+}> | Readonly<{
+    kind: "response";
+    id: string | number;
+    result: unknown;
+}> | Readonly<{
+    kind: "errorResponse";
+    id: string | number;
+    error: DevinAcpError;
+}>;
+export type DevinStopReason = "end_turn" | "max_tokens" | "max_turn_requests" | "refusal" | "cancelled";
+export type DevinPermissionOutcome = Readonly<{
+    outcome: "cancelled";
+}> | Readonly<{
+    outcome: "selected";
+    optionId: string;
+}>;
+export type DevinPermissionOption = Readonly<{
+    optionId: string;
+    name: string;
+    kind: "allow_once" | "allow_always" | "reject_once" | "reject_always";
+}>;
+export type DevinPermissionRequest = Readonly<{
+    requestId: string;
+    sessionId: string;
+    toolCall: Readonly<{
+        toolCallId: string;
+        title: string | null;
+        kind: string | null;
+        status: string | null;
+    }>;
+    options: readonly DevinPermissionOption[];
+}>;
+export type DevinFact = Readonly<{
+    type: "assistantDelta";
+    sessionId: string;
+    text: string;
+}> | Readonly<{
+    type: "usageUpdated";
+    sessionId: string;
+    used: number;
+    size: number;
+    inputTokens: number | null;
+    outputTokens: number | null;
+}> | Readonly<{
+    type: "protocolNotice";
+    sessionId: string | null;
+    method: string;
+}>;
+export type DevinSessionConfigOption = Readonly<{
+    id: string;
+    currentValue: string;
+}>;
+export type DevinNewSession = Readonly<{
+    sessionId: string;
+    currentMode: string | null;
+    configOptions: readonly DevinSessionConfigOption[];
+}>;
+export type DevinPromptUsage = Readonly<{
+    totalTokens: number | null;
+    inputTokens: number | null;
+    outputTokens: number | null;
+}>;
+export type DevinPromptResult = Readonly<{
+    stopReason: DevinStopReason;
+    usage: DevinPromptUsage | null;
+}>;
+/** Splits a provider byte stream into validated single-line ACP frames. The
+ * last partial line is still validated; a missing trailing LF is not evidence. */
+export declare function devinAcpFraming(maximumFrameBytes?: number): Transform;
+export declare function parseAcpInbound(value: unknown): DevinAcpInbound;
+export declare function parseInitializeResult(value: unknown): Readonly<{
+    protocolVersion: number;
+    loadSession: boolean;
+}>;
+export declare function parseNewSessionResult(value: unknown): DevinNewSession;
+export declare function parsePromptResult(value: unknown): DevinPromptResult;
+export declare function parseSessionUpdate(value: unknown): readonly DevinFact[];
+export declare function parsePermissionRequest(requestId: string | number, value: unknown): DevinPermissionRequest;
+export declare function validatePermissionOutcome(value: unknown, options: readonly DevinPermissionOption[]): DevinPermissionOutcome;
+/** Chooses the first reject option; absent one, cancels the request. The host's
+ * allow decision must come from its own policy callback, never from the frame. */
+export declare function denyPermissionOutcome(options: readonly DevinPermissionOption[]): DevinPermissionOutcome;
+export declare function boundedDevinPrompt(value: unknown): string;
+export declare function boundedDevinSessionId(value: unknown): string;
+export declare function devinModeId(value: unknown): string;

package/dist/devin-adapter.d.ts

@@ -0,0 +1,44 @@
+import type { BoundedProviderProcessFactory } from "./provider-process.ts";
+import type { DevinPermissionOutcome, DevinPermissionRequest } from "./devin-acp.ts";
+import type { AgentTaskAdapter, AgentTaskRoute, TaskRuntimeQualification } from "./task-runtime.ts";
+/**
+ * Devin task adapter over ACP v1 (`devin acp`). One bounded child per run:
+ * initialize -> session/new (host cwd, stdio MCP bridge when the profile has
+ * tools) -> optional mode/model selection -> session/prompt -> join. The
+ * profile's tools are exposed only through the host-owned loopback relay; fs
+ * and terminal client capabilities stay unimplemented. This adapter is
+ * admission-only: the supplied qualification decides whether tasks may run.
+ */
+export type DevinAcpAdapterOptions = Readonly<{
+    route: AgentTaskRoute;
+    runtime: Readonly<{
+        version: string;
+        digest: string;
+    }>;
+    qualification: TaskRuntimeQualification;
+    /** Host-admitted Devin CLI executable; an absolute pinned artifact path. */
+    executable: string;
+    /** Exact child environment; the host owns credential and HOME isolation. */
+    env: Readonly<Record<string, string>>;
+    factory: BoundedProviderProcessFactory;
+    /** Runtime executable that runs the stdio MCP bridge (`-e` source), e.g. a
+     * pinned bun/node path. Required when a task profile declares tools. */
+    bridgeExecutable?: string;
+    /** Where the tool relay listens: default is an ephemeral host TCP port.
+     * On Linux the provider runs inside a private net namespace, so the relay
+     * binds `socketPath` (mounted into the namespace) and the in-namespace
+     * forwarder re-publishes it at `127.0.0.1:port` — the advertised bridge
+     * URL uses that port either way. */
+    relayListen?: Readonly<{
+        socketPath: string;
+        port: number;
+    }>;
+    /** Canonical absolute cwd for the Devin session's workspace. */
+    workspaceCwd: (workspaceId: string) => string;
+    /** Session mode pinned for every task, e.g. "plan" or "ask". */
+    mode?: string;
+    /** Host permission policy for provider tool gates; default denies all. */
+    permission?: (request: DevinPermissionRequest) => DevinPermissionOutcome | Promise<DevinPermissionOutcome>;
+    now(): number;
+}>;
+export declare function createDevinAcpAdapter(options: DevinAcpAdapterOptions): AgentTaskAdapter;

package/dist/devin-client.d.ts

@@ -0,0 +1,36 @@
+import type { BoundedProviderProcess } from "./provider-process.ts";
+import { type DevinFact, type DevinNewSession, type DevinPermissionOutcome, type DevinPermissionRequest, type DevinPromptResult } from "./devin-acp.ts";
+/** One owned `devin acp` child behind the bounded-process custody contract. The
+ * client serializes writes, correlates requests, routes inbound fs/permission
+ * requests to host handlers and refuses concurrent prompts. */
+export type DevinAcpClientOptions = Readonly<{
+    process: BoundedProviderProcess;
+    onFact?: (fact: DevinFact) => void;
+    onPermission?: (request: DevinPermissionRequest) => DevinPermissionOutcome | Promise<DevinPermissionOutcome>;
+    maximumPendingRequests?: number;
+    shutdownGraceMs?: number;
+    shutdownForceJoinMs?: number;
+}>;
+export declare class DevinAcpClient {
+    #private;
+    constructor(options: DevinAcpClientOptions);
+    get closed(): Promise<void>;
+    initialize(signal?: AbortSignal): Promise<Readonly<{
+        protocolVersion: number;
+        loadSession: boolean;
+    }>>;
+    /** mcpServers entries are stdio transports only — Devin advertises no
+     * http/sse MCP capability; the caller must not pass other transports. */
+    newSession(input: {
+        cwd: string;
+        mcpServers?: readonly Record<string, unknown>[];
+        signal?: AbortSignal;
+    }): Promise<DevinNewSession>;
+    setMode(sessionIdInput: string, mode: string, signal?: AbortSignal): Promise<void>;
+    setConfigOption(sessionIdInput: string, configId: string, value: string, signal?: AbortSignal): Promise<void>;
+    prompt(sessionIdInput: string, text: string, signal?: AbortSignal): Promise<DevinPromptResult>;
+    cancel(sessionIdInput: string): Promise<void>;
+    resolvePermission(requestId: string, outcome: DevinPermissionOutcome): void;
+    close(): Promise<void>;
+}
+export type { DevinFact, DevinPermissionRequest, DevinPermissionOutcome, DevinPromptResult, DevinNewSession };

package/dist/devin-mcp.d.ts

@@ -0,0 +1,28 @@
+import type { CapabilityBroker } from "./capabilities.ts";
+export type DevinToolRelay = Readonly<{
+    /** Closed loopback origin carrying the relay token; only the bridge sees it. */
+    bridgeEnv(): Readonly<Record<string, string>>;
+    mcpServerEntry(): Readonly<Record<string, unknown>>;
+    stop(): Promise<void>;
+}>;
+export type DevinToolRelayOptions = Readonly<{
+    broker: CapabilityBroker;
+    /** Runtime executable that runs DEVIN_MCP_BRIDGE_SOURCE, e.g. an exact
+     * host-pinned `bun`/`node` path. Required when the profile has tools. */
+    bridgeExecutable: string;
+    /** Default is an ephemeral TCP listener on host loopback. On Linux the
+     * provider runs inside a private network namespace, so the relay instead
+     * listens on `socketPath` (bound into the namespace) and the in-namespace
+     * forwarder re-publishes it at 127.0.0.1:`port` — the bridge env URL uses
+     * that advertised port in both modes. */
+    listen?: Readonly<{
+        socketPath: string;
+        port: number;
+    }>;
+    signal?: AbortSignal;
+}>;
+export declare function startDevinToolRelay(options: DevinToolRelayOptions): Promise<DevinToolRelay>;
+/** Self-contained MCP-over-stdio server that proxies `tools/list`/`tools/call`
+ * to the host relay. Spawned as `executable -e <this source>` by the Devin ACP
+ * agent; uses only the runtime's own stdio/fetch surface. */
+export declare const DEVIN_MCP_BRIDGE_SOURCE: string;

package/dist/egress-bridge.d.ts

@@ -0,0 +1,35 @@
+import type { Duplex } from "node:stream";
+/** The only network authority the bridge uses; supplied by the trusted host. */
+export interface EgressBridgeDialer {
+    connect(host: string, port: number): Promise<Duplex>;
+}
+export type EgressBridgeOptions = Readonly<{
+    /** Canonical absolute socket path inside a private 0700 directory. */
+    socketPath: string;
+    /** Exact hostnames admitted for CONNECT; absent admits any host on :443,
+     * matching the seatbelt `remote tcp "*:443"` candidate semantics. */
+    allowlist?: readonly string[];
+    maxConnections?: number;
+    idleTimeoutMs?: number;
+    dialer: EgressBridgeDialer;
+}>;
+export type EgressBridgeReceipt = Readonly<{
+    socketPath: string;
+    productionQualified: false;
+    connectionsAccepted: number;
+    connectionsRefused: number;
+    bytesIn: number;
+    bytesOut: number;
+    listenerClosed: boolean;
+    socketsJoined: boolean;
+    socketRemoved: boolean;
+}>;
+export interface EgressBridge {
+    readonly socketPath: string;
+    readonly connections: number;
+    close(): Promise<EgressBridgeReceipt>;
+}
+/** Default dialer for the real host seam: a bounded plain TCP connect whose
+ * resolver runs host-side. The in-sandbox process never performs DNS. */
+export declare const egressBridgeDialer: EgressBridgeDialer;
+export declare function createEgressBridge(options: EgressBridgeOptions): Promise<EgressBridge>;

package/dist/egress-client.d.ts

@@ -0,0 +1,66 @@
+import { type Socket } from "node:net";
+import { type TLSSocket } from "node:tls";
+import { Agent as HttpsAgent } from "node:https";
+import type { Duplex } from "node:stream";
+/** In-sandbox consumer for the egress-bridge contract — the reverse seam of
+ * `egress-bridge.ts`. A confined process reads `XCB_EGRESS_SOCKET`,
+ * speaks `CONNECT host:443` over that unix socket, and receives a raw tunnel
+ * to layer TLS or HTTP onto. The bridge owns DNS and dialing; this module
+ * never resolves names and never opens a direct socket. Works under Node ≥ 20
+ * and Bun; no dependencies beyond node: builtins.
+ *
+ * Nothing here widens the sandbox: if the bridge refuses (allowlist miss,
+ * port, malformed head) the failure surfaces as a typed error and the process
+ * keeps whatever isolation it already had. */
+export declare const EGRESS_SOCKET_ENV = "XCB_EGRESS_SOCKET";
+/** Read the bridge socket path from an environment map (defaults to
+ * `process.env`). Absent → null; present but malformed → typed failure. */
+export declare function egressSocketFromEnv(env?: Readonly<Record<string, string | undefined>>): string | null;
+export type EgressConnectOptions = Readonly<{
+    /** Bridge socket path; defaults to `XCB_EGRESS_SOCKET`. */
+    socketPath?: string;
+    timeoutMs?: number;
+}>;
+/** One `CONNECT host:443` over the bridge socket. The returned socket is
+ * positioned past the `200` head — bytes after it are tunnel traffic. Any
+ * non-200 head, timeout, or socket failure destroys the socket and throws. */
+export declare function connectEgress(host: string, options?: EgressConnectOptions): Promise<Socket>;
+/** CONNECT plus a TLS handshake over the tunnel. `servername` defaults to the
+ * CONNECT host so SNI and verification match the requested origin. Extra
+ * `tls.connect` options (ALPN, ca, checkServerIdentity) pass through. */
+export declare function connectEgressTls(host: string, options?: EgressConnectOptions & Readonly<{
+    alpnProtocols?: readonly string[];
+    rejectUnauthorized?: boolean;
+    ca?: string | readonly string[];
+    servername?: string;
+}>): Promise<TLSSocket>;
+/** `https.Agent` whose connections arrive over the egress bridge. Plug into
+ * `https.request`/`https.get` via `{ agent }`; keepAlive stays off because the
+ * bridge meters each CONNECT. Only :443 origins are reachable — the bridge
+ * refuses everything else. */
+export declare function createEgressHttpsAgent(options?: EgressConnectOptions): HttpsAgent;
+export type EgressFetchInput = Readonly<{
+    method?: string;
+    headers?: Readonly<Record<string, string>>;
+    body?: string | Uint8Array;
+    maxBodyBytes?: number;
+    signal?: AbortSignal;
+    /** Injectable transport for tests; default is CONNECT + TLS to the host. */
+    transport?: (host: string, options: {
+        socketPath: string;
+        timeoutMs: number;
+    }) => Promise<Duplex>;
+}>;
+export type EgressFetchResponse = Readonly<{
+    status: number;
+    statusText: string;
+    headers: Readonly<Record<string, readonly string[]>>;
+    body: Uint8Array;
+    text(): string;
+    json(): unknown;
+}>;
+/** Minimal `fetch`-shaped HTTPS client over the egress bridge: https URLs on
+ * :443 only, bounded redirects and body. This is a request primitive, not a
+ * full fetch implementation — no cookies, cache, streaming request bodies or
+ * HTTP/2. */
+export declare function fetchViaEgress(rawUrl: string, input?: EgressFetchInput & EgressConnectOptions): Promise<EgressFetchResponse>;