@provos/ironcurtain 0.11.0 → 0.13.0

package/dist/docker/trajectory-types.d.ts

@@ -0,0 +1,187 @@
+/**
+ * MITM token-trajectory capture: shared types.
+ *
+ * Types backing the on-disk JSONL schema (see
+ * docs/designs/mitm-token-trajectory-capture.md §4) and the dispatcher's
+ * internal state. The schema is the source of truth for the corpus
+ * downstream tooling consumes — keep field names byte-faithful with the
+ * design doc.
+ */
+import type { SessionId } from '../session/types.js';
+/**
+ * Provider identity. `unknown` is reserved for hosts the capture sees but
+ * cannot classify (and is captured raw). `'openai'` is the OpenAI Responses
+ * API stream Codex emits on `chatgpt.com`.
+ */
+export type CaptureProvider = 'anthropic' | 'openai' | 'unknown';
+/** Reason a session was poisoned. See §9 for the full taxonomy. */
+export type PoisonReason = 'reassembly-failure' | 'disk-error' | 'queue-overflow' | 'mid-stream-abort' | 'infrastructure-teardown' | 'unsupported-encoding' | 'unknown';
+/**
+ * Single HTTP exchange captured by the MITM proxy. One line per
+ * exchange in the on-disk JSONL.
+ */
+export interface ExchangeRecord {
+    readonly schemaVersion: 1;
+    readonly exchangeId: string;
+    readonly sessionId: string;
+    readonly persona?: string;
+    readonly workflowRunId?: string;
+    readonly bundleId?: string;
+    readonly recordedAgentName?: string;
+    readonly provider: CaptureProvider;
+    readonly method: string;
+    readonly host: string;
+    readonly path: string;
+    readonly requestStartedAt: number;
+    readonly requestFinishedAt: number;
+    readonly responseFinishedAt: number;
+    readonly request: {
+        readonly headers: Readonly<Record<string, string>>;
+        /** UTF-8 body when content-encoding is identity (or absent); empty otherwise. */
+        readonly bodyUtf8: string;
+        /** Present iff body is compressed or otherwise not valid UTF-8. */
+        readonly bodyBase64?: string;
+        readonly bodyBytes: number;
+        readonly contentEncoding?: string;
+    };
+    readonly response: {
+        readonly status: number;
+        readonly headers: Readonly<Record<string, string>>;
+        readonly streaming: boolean;
+        readonly providerRequestId?: string;
+        readonly stopReason?: string;
+        readonly modelFingerprint?: string;
+        readonly usage?: Readonly<Record<string, unknown>>;
+        readonly bodyUtf8: string;
+        readonly bodyBase64?: string;
+        readonly bodyBytes: number;
+        readonly streamRaw?: {
+            readonly events: ReadonlyArray<{
+                readonly eventType: string;
+                readonly dataUtf8: string;
+                readonly offsetMs: number;
+            }>;
+        };
+    };
+    readonly capture: {
+        readonly reassemblyOk: boolean;
+        readonly reassemblyDiagnostic?: string;
+        readonly retried?: boolean;
+    };
+}
+/**
+ * Single line in `manifest.jsonl`. Always one `session-start` paired
+ * with one `session-end` (modulo crash safety nets, where the start
+ * may exist without a matching end — see §9).
+ */
+export type ManifestEntry = {
+    readonly schemaVersion: 1;
+    readonly event: 'session-start';
+    readonly seq: number;
+    readonly sessionId: string;
+    readonly persona?: string;
+    readonly fsmState?: string;
+    readonly ts: string;
+} | {
+    readonly schemaVersion: 1;
+    readonly event: 'session-end';
+    readonly seq: number;
+    readonly sessionId: string;
+    readonly persona?: string;
+    readonly fsmState?: string;
+    readonly ts: string;
+    readonly exchanges: number;
+    readonly bytesWritten: number;
+    readonly poisoned: boolean;
+    readonly poisonReason?: PoisonReason;
+    readonly closedReason?: 'infrastructure-teardown';
+};
+/**
+ * Capture configuration. v0 surface is a single boolean — see §10 for
+ * the rationale (no knobs that would silently produce partial captures).
+ */
+export interface CaptureConfig {
+    readonly enabled: boolean;
+}
+/**
+ * Inputs to `beginSession` / `beginCaptureSession`.
+ */
+export interface BeginCaptureSessionOptions {
+    readonly sessionId: SessionId;
+    readonly persona?: string;
+    readonly fsmState?: string;
+}
+/**
+ * Aggregate dispatcher diagnostics.
+ */
+export interface CaptureStats {
+    /** Records successfully written to disk across all sessions. */
+    readonly written: number;
+    /**
+     * Records dropped before disk (poisoned session, missing beginSession,
+     * etc.). Individual records are never dropped on successful sessions;
+     * this is for diagnostic visibility only.
+     */
+    readonly dropped: number;
+    readonly queued: number;
+    readonly bytesWritten: number;
+    readonly openSessions: number;
+}
+/**
+ * Reassembler interface. Each provider has its own state machine; the
+ * dispatcher routes by host. See §5 for the byte-fidelity rules.
+ */
+export interface Reassembler {
+    /** Feed raw response chunk bytes (verbatim). */
+    push(chunk: Buffer): void;
+    /**
+     * Signal that the upstream response stream closed cleanly. Returns
+     * the reassembled body plus structured fields. Throws (or marks the
+     * reassembly as failed) if the stream did not finish in a well-formed
+     * state. After `finalize()`, the reassembler MUST NOT be reused.
+     */
+    finalize(): ReassemblyResult;
+    /**
+     * True once the provider's terminal event has been parsed
+     * (`message_stop` / `[DONE]` / `response.completed`). Lets the tap
+     * finalize a complete-but-socket-aborted stream (write a faithful
+     * record) instead of poisoning it as a mid-stream abort. When false,
+     * a close/error before the terminal event is a genuine truncation.
+     */
+    canFinalize(): boolean;
+}
+/**
+ * Output of a successful reassembly.
+ */
+export interface ReassemblyResult {
+    /**
+     * Reassembled body as a string. Constructed via raw substring
+     * concatenation of wire bytes — never JSON.parse → JSON.stringify
+     * on captured content. See §6 invariant #1.
+     */
+    readonly bodyUtf8: string;
+    readonly providerRequestId?: string;
+    readonly stopReason?: string;
+    readonly modelFingerprint?: string;
+    readonly usage?: Readonly<Record<string, unknown>>;
+    /** Raw event log for diagnostics (`streamRaw.events`). */
+    readonly events: ReadonlyArray<{
+        readonly eventType: string;
+        readonly dataUtf8: string;
+        readonly offsetMs: number;
+    }>;
+}
+/**
+ * Headers/body redaction is centralized so the writer-input unit test
+ * (§12 test #2(a)) can drive the redaction layer directly without a
+ * proxy.
+ */
+export declare const REDACTED_HEADER_NAMES: ReadonlySet<string>;
+export declare const REDACTED_VALUE = "<redacted>";
+/**
+ * Drop / replace any header in the redaction set. Case-insensitive on
+ * the name. Always emits the redaction sentinel so the schema shape is
+ * preserved (downstream tooling can see that a header was present and
+ * stripped, vs. truly absent).
+ */
+export declare function redactHeaders(headers: Readonly<Record<string, string | string[] | undefined>>): Record<string, string>;

package/dist/docker/trajectory-types.js

@@ -0,0 +1,43 @@
+/**
+ * MITM token-trajectory capture: shared types.
+ *
+ * Types backing the on-disk JSONL schema (see
+ * docs/designs/mitm-token-trajectory-capture.md §4) and the dispatcher's
+ * internal state. The schema is the source of truth for the corpus
+ * downstream tooling consumes — keep field names byte-faithful with the
+ * design doc.
+ */
+/**
+ * Headers/body redaction is centralized so the writer-input unit test
+ * (§12 test #2(a)) can drive the redaction layer directly without a
+ * proxy.
+ */
+export const REDACTED_HEADER_NAMES = new Set([
+    'authorization',
+    'x-api-key',
+    'proxy-authorization',
+    'cookie',
+    'set-cookie',
+]);
+export const REDACTED_VALUE = '<redacted>';
+/**
+ * Drop / replace any header in the redaction set. Case-insensitive on
+ * the name. Always emits the redaction sentinel so the schema shape is
+ * preserved (downstream tooling can see that a header was present and
+ * stripped, vs. truly absent).
+ */
+export function redactHeaders(headers) {
+    const out = {};
+    for (const [name, value] of Object.entries(headers)) {
+        if (value === undefined)
+            continue;
+        const lower = name.toLowerCase();
+        if (REDACTED_HEADER_NAMES.has(lower)) {
+            out[lower] = REDACTED_VALUE;
+            continue;
+        }
+        out[lower] = Array.isArray(value) ? value.join(', ') : value;
+    }
+    return out;
+}
+//# sourceMappingURL=trajectory-types.js.map

package/dist/docker/trajectory-types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"trajectory-types.js","sourceRoot":"","sources":["../../src/docker/trajectory-types.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AA6LH;;;;GAIG;AACH,MAAM,CAAC,MAAM,qBAAqB,GAAwB,IAAI,GAAG,CAAC;IAChE,eAAe;IACf,WAAW;IACX,qBAAqB;IACrB,QAAQ;IACR,YAAY;CACb,CAAC,CAAC;AAEH,MAAM,CAAC,MAAM,cAAc,GAAG,YAAY,CAAC;AAE3C;;;;;GAKG;AACH,MAAM,UAAU,aAAa,CAC3B,OAAgE;IAEhE,MAAM,GAAG,GAA2B,EAAE,CAAC;IACvC,KAAK,MAAM,CAAC,IAAI,EAAE,KAAK,CAAC,IAAI,MAAM,CAAC,OAAO,CAAC,OAAO,CAAC,EAAE,CAAC;QACpD,IAAI,KAAK,KAAK,SAAS;YAAE,SAAS;QAClC,MAAM,KAAK,GAAG,IAAI,CAAC,WAAW,EAAE,CAAC;QACjC,IAAI,qBAAqB,CAAC,GAAG,CAAC,KAAK,CAAC,EAAE,CAAC;YACrC,GAAG,CAAC,KAAK,CAAC,GAAG,cAAc,CAAC;YAC5B,SAAS;QACX,CAAC;QACD,GAAG,CAAC,KAAK,CAAC,GAAG,KAAK,CAAC,OAAO,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,KAAK,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,KAAK,CAAC;IAC/D,CAAC;IACD,OAAO,GAAG,CAAC;AACb,CAAC"}

package/dist/docker/types.d.ts

@@ -42,6 +42,8 @@ export interface DockerContainerConfig {
      * on standalone CLI / PTY sessions (which have no scope concept).
      */
     readonly scopeLabel?: string;
+    /** Additional runtime ownership/housekeeping labels. */
+    readonly labels?: Readonly<Record<string, string>>;
     /** Extra --add-host entries (e.g. ["host.docker.internal:172.30.0.3"]). When set, suppresses the default host-gateway mapping. */
     readonly extraHosts?: readonly string[];
     /** Optional resource limits. */
@@ -83,6 +85,23 @@ export interface DockerContainerConfig {
      * Optional. Defaults to false (no TTY allocated).
      */
     readonly tty?: boolean;
+    /**
+     * Guest-listens / host-connects Unix-domain-socket bridges
+     * (`container create --publish-socket <hostPath>:<containerPath>`).
+     *
+     * Apple `container` only — the runtime creates a vsock relay so a
+     * socket the guest `bind()`s at `containerPath` becomes reachable on
+     * the host at `hostPath`. Used by PTY mode on the `uds` topology to
+     * expose the in-container PTY listener without any network interface.
+     * The host-side socket materializes when the guest binds, so
+     * existence-polling is a valid readiness signal.
+     *
+     * Docker has no equivalent; `buildCreateArgs` throws when this is set.
+     */
+    readonly publishSockets?: readonly {
+        readonly hostPath: string;
+        readonly containerPath: string;
+    }[];
     /**
      * Override the container's effective user at creation time.
      * Maps to `docker create --user <value>` (formats: `uid`, `uid:gid`,
@@ -117,15 +136,67 @@ export interface DockerExecResult {
     readonly stdout: string;
     readonly stderr: string;
 }
+export interface DockerCommitOptions {
+    readonly tag?: string;
+    readonly changes?: readonly string[];
+    readonly pause?: boolean;
+    readonly timeoutMs?: number;
+    /**
+     * When true, snapshot through docker export/import instead of docker commit
+     * so the resulting image is flattened and does not retain the source image
+     * as an inspectable parent (a superseded snapshot digest can then be
+     * force-removed without a dependent-child-image conflict). Intended for
+     * workflow resume snapshots. The image Config that export/import would
+     * otherwise drop (ENTRYPOINT/CMD/WORKDIR/USER/ENV) is re-baked from the
+     * source container, so a flattened image still behaves like its source.
+     */
+    readonly flatten?: boolean;
+}
+export interface DockerImageInfo {
+    readonly id: string;
+    readonly repoTags: readonly string[];
+    readonly labels: Readonly<Record<string, string>>;
+    readonly created: string;
+}
+/** Docker network state used by crash reconciliation and subnet allocation. */
+export interface DockerNetworkInfo {
+    readonly id: string;
+    readonly name: string;
+    readonly created: string;
+    readonly labels: Readonly<Record<string, string>>;
+    readonly subnets: readonly string[];
+    readonly containerIds: readonly string[];
+}
+/** Docker container state used by crash reconciliation. */
+export interface DockerContainerInfo {
+    readonly id: string;
+    readonly name: string;
+    readonly created: string;
+    readonly running: boolean;
+    readonly labels: Readonly<Record<string, string>>;
+}
+export interface DockerNetworkCreateOptions {
+    readonly internal?: boolean;
+    readonly subnet?: string;
+    readonly gateway?: string;
+    readonly labels?: Readonly<Record<string, string>>;
+}
 /**
- * Manages Docker container lifecycle for agent sessions.
+ * Manages container lifecycle for agent sessions.
+ *
+ * Implementations wrap a specific container runtime CLI -- Docker today
+ * (`createDockerManager()` in docker-manager.ts), Apple `container` planned
+ * (see docs/designs/apple-container-runtime.md). Select via
+ * `createContainerRuntime()` in container-runtime.ts.
  *
- * Uses the Docker CLI (not the Docker API) for simplicity.
- * The Docker socket is only accessed from the host process,
- * never from inside agent containers.
+ * Implementations use the runtime's CLI (not an engine API) for simplicity.
+ * The runtime is only invoked from the host process, never from inside
+ * agent containers.
  */
-export interface DockerManager {
-    /** Check that Docker is available and the image exists. */
+export interface ContainerRuntime {
+    /** True when this runtime can commit containers to images and manage snapshot images. */
+    readonly supportsImageSnapshots: boolean;
+    /** Check that the runtime is available and the image exists. */
     preflight(image: string): Promise<void>;
     /** Create a container with the given configuration. Returns container ID. */
     create(config: DockerContainerConfig): Promise<string>;
@@ -145,8 +216,10 @@ export interface DockerManager {
      *   - `null`: skip the `--user` flag entirely. Required for non-agent
      *     containers that have no `codespace` account (e.g. the
      *     `bbernhard/signal-cli-rest-api` image).
+     * @param workdir - optional working directory passed via
+     *   `docker exec --workdir <dir>`.
      */
-    exec(nameOrId: string, command: readonly string[], timeoutMs?: number, execUser?: string | null): Promise<DockerExecResult>;
+    exec(nameOrId: string, command: readonly string[], timeoutMs?: number, execUser?: string | null, workdir?: string): Promise<DockerExecResult>;
     /** Stop a running container (SIGTERM, then SIGKILL after grace period). */
     stop(nameOrId: string): Promise<void>;
     /** Remove a container (must be stopped). */
@@ -155,18 +228,42 @@ export interface DockerManager {
     isRunning(nameOrId: string): Promise<boolean>;
     /** Check if a Docker image exists locally. */
     imageExists(image: string): Promise<boolean>;
+    /** Commit a container writable layer to an image and return its immutable sha256 image ID. */
+    commit(containerId: string, options?: DockerCommitOptions): Promise<string>;
+    /** Remove a Docker image by digest or tag. Returns true when a removal was attempted successfully. */
+    removeImage(ref: string): Promise<boolean>;
+    /** List local Docker images, optionally filtered by label. */
+    listImages(options?: {
+        readonly labelFilter?: string;
+    }): Promise<readonly DockerImageInfo[]>;
+    /** Inspect one local Docker image. Returns undefined when the image does not exist. */
+    inspectImage(ref: string): Promise<DockerImageInfo | undefined>;
     /** Build a Docker image from a Dockerfile. Optional labels are stamped on the image. */
     buildImage(tag: string, dockerfilePath: string, contextDir: string, labels?: Record<string, string>): Promise<void>;
     /** Read a label value from a Docker image. Returns undefined if image or label doesn't exist. */
     getImageLabel(image: string, label: string): Promise<string | undefined>;
+    /**
+     * Probe the version string of an agent binary baked into an image by running
+     * a throwaway, network-isolated container (`run --rm --network none
+     * --entrypoint <command[0]> <image> <command[1..]>`) and returning its trimmed
+     * stdout. Network isolation is required — the probe executes an agent binary
+     * that may attempt update-check/telemetry egress. Best-effort: returns
+     * undefined on any failure. Optional — runtimes that cannot cheaply run an
+     * ephemeral container may omit it, in which case callers skip version logging.
+     */
+    probeImageVersion?(image: string, command: readonly string[]): Promise<string | undefined>;
     /** Create a Docker network. No-op if it already exists. */
-    createNetwork(name: string, options?: {
-        internal?: boolean;
-        subnet?: string;
-        gateway?: string;
-    }): Promise<void>;
+    createNetwork(name: string, options?: DockerNetworkCreateOptions): Promise<void>;
+    /** Enumerate Docker networks. Optional for non-Docker runtimes. */
+    listNetworks?(): Promise<readonly DockerNetworkInfo[]>;
+    /** Enumerate Docker containers, including stopped containers. Optional for non-Docker runtimes. */
+    listContainers?(options?: {
+        readonly labelFilter?: string;
+    }): Promise<readonly DockerContainerInfo[]>;
     /** Remove a Docker network. Ignores errors (e.g., already removed). */
     removeNetwork(name: string): Promise<void>;
+    /** Check whether a named network still exists. Optional for non-Docker runtimes. */
+    networkExists?(name: string): Promise<boolean>;
     /** Pull a Docker image from a registry. */
     pullImage(image: string): Promise<void>;
     /**
@@ -186,6 +283,13 @@ export interface DockerManager {
     getImageId(nameOrId: string): Promise<string | undefined>;
     /** Connect an existing container to a Docker network. */
     connectNetwork(networkName: string, containerId: string): Promise<void>;
+    /**
+     * Returns the host-side IPv4 gateway address of a network, or undefined
+     * if the network does not exist or has no gateway. Optional: only the
+     * tcp-hostonly topology consumes it (see network-topology.ts), and it
+     * falls back to deriving the gateway from the subnet when absent.
+     */
+    getNetworkGateway?(name: string): Promise<string | undefined>;
     /** Get a container's IP address on a specific network. */
     getContainerIp(containerId: string, network: string): Promise<string>;
 }

package/dist/doctor/checks.d.ts

@@ -6,7 +6,8 @@
  * responsible for translating results into an exit code so unit tests
  * can call check functions directly without short-circuits.
  */
-import { type DockerAvailability } from '../session/preflight.js';
+import { type DockerAvailability } from '../docker/docker-probe.js';
+import { type ContainerRuntimeKind } from '../docker/container-runtime.js';
 import { type ExecFileFn } from '../docker/resource-limits.js';
 import type { AgentId } from '../docker/agent-adapter.js';
 import { loadGeneratedPolicy, findAnnotationServerDrift } from '../config/index.js';
@@ -29,19 +30,51 @@ export declare function checkSandbox(): Promise<CheckResult>;
  * be reused in contexts that don't care about preferred mode.
  */
 export declare function checkDocker(probe?: () => Promise<DockerAvailability>): Promise<CheckResult>;
+/**
+ * Reports Apple `container` runtime status. `skip` on platforms where the
+ * backend is structurally unavailable (non-macOS, Intel, pre-macOS-26);
+ * `warn` when the platform qualifies but the CLI/services are not ready —
+ * `checkActiveRuntime` upgrades that to a fail when this backend is the
+ * one sessions will actually use.
+ */
+export declare function checkAppleContainer(probe?: () => Promise<DockerAvailability>, hostPlatform?: string, hostArch?: string): Promise<CheckResult>;
+/**
+ * Reports whether Rosetta is installed. Only meaningful when the Apple
+ * container backend is in play: its BuildKit builder VM requires Rosetta,
+ * so agent-image builds fail without it. Probed by running an x86_64
+ * binary under `arch` — exits 0 iff Rosetta can translate it.
+ */
+export declare function checkRosetta(runX86?: () => boolean): CheckResult;
+/** Output of checkActiveRuntime: the resolved backend plus its availability. */
+export interface ActiveRuntime {
+    readonly result: CheckResult;
+    readonly kind: ContainerRuntimeKind;
+    /** Human label for messages ("Docker" / "Apple container"). */
+    readonly label: string;
+    /** The availability CheckResult of the backend sessions will use. */
+    readonly availability: CheckResult;
+}
+/**
+ * Resolves which container runtime sessions will use (env override >
+ * `containerRuntime` config > auto probe) and pairs it with the matching
+ * availability result from the Environment section, so downstream checks
+ * (preferred mode, resource limits) evaluate the backend that actually
+ * runs — not unconditionally Docker.
+ */
+export declare function checkActiveRuntime(config: IronCurtainConfig, dockerResult: CheckResult, appleResult: CheckResult): Promise<ActiveRuntime>;
 /**
  * Reports whether the user's `preferredMode` is satisfiable on this host.
  *
  * Reuses the prior `dockerResult` from `checkDocker` so Docker is probed
- * exactly once per `doctor` run. Maps the (preferredMode × dockerResult ×
+ * exactly once per `doctor` run. Maps the (preferredMode × runtime availability ×
  * api-key-presence) tuple to a status:
  *
- *   - preferredMode: 'docker' + Docker ok          -> ok
- *   - preferredMode: 'docker' + Docker unavailable -> fail (sessions will refuse to start)
+ *   - preferredMode: 'container' + active runtime ok          -> ok
+ *   - preferredMode: 'container' + active runtime unavailable -> fail (sessions will refuse to start)
  *   - preferredMode: 'builtin' + API key present   -> ok
  *   - preferredMode: 'builtin' + no API key        -> warn (sessions will fail to start by default)
  */
-export declare function checkPreferredMode(config: IronCurtainConfig, dockerResult: CheckResult): CheckResult;
+export declare function checkPreferredMode(config: IronCurtainConfig, dockerResult: CheckResult, runtimeLabel?: string): CheckResult;
 /**
  * Reports whether the user's Docker resource ceilings (after clamping)
  * are accepted by Docker. Two-step:
@@ -63,7 +96,7 @@ export interface CheckDockerResourcesDeps {
     readonly execFile?: ExecFileFn;
     readonly resolveImage?: (agentId: AgentId) => Promise<string>;
 }
-export declare function checkDockerResources(config: IronCurtainConfig, deps?: CheckDockerResourcesDeps): Promise<CheckResult>;
+export declare function checkDockerResources(config: IronCurtainConfig, deps?: CheckDockerResourcesDeps, runtimeKind?: ContainerRuntimeKind): Promise<CheckResult>;
 export interface ConfigLoadOk {
     readonly result: CheckResult;
     readonly config: IronCurtainConfig;