@provos/ironcurtain 0.10.0 → 0.12.0

package/dist/docker/docker-probe.js

@@ -0,0 +1,86 @@
+/**
+ * Docker availability probe (leaf module).
+ *
+ * The single canonical "is Docker available?" check, extracted here so that
+ * runtime modules (`docker-manager.ts`, `container-runtime.ts`,
+ * `apple-container-manager.ts`) can depend on it without importing
+ * `session/preflight.ts` — which itself lazily reaches back into the
+ * container-runtime backends. Keeping the probe in a dependency-free leaf
+ * breaks that import cycle.
+ *
+ * This module must stay a leaf: it may import only Node built-ins and
+ * `utils/exec-error.js`. Do not add imports from `session/`, `docker/`
+ * runtime modules, or any layer that could reach back here.
+ */
+import { execFile as execFileCb } from 'node:child_process';
+import { promisify } from 'node:util';
+import { isExecError, isExecTimeout } from '../utils/exec-error.js';
+const execFile = promisify(execFileCb);
+/**
+ * Per-attempt timeout for `docker info`. The daemon call can be slow under
+ * load (cold daemon, busy machine), so we use a generous timeout and retry
+ * on timeout-class failures rather than tightening the bound.
+ */
+const DOCKER_PROBE_TIMEOUT_MS = 10_000;
+/** Maximum number of additional attempts after the first one. */
+const DOCKER_PROBE_MAX_RETRIES = 2;
+const DOCKER_UNAVAILABLE_REASON = 'Docker not available';
+function describeProbeFailure(err, fallback) {
+    if (!isExecError(err))
+        return fallback;
+    if (err.code === 'ENOENT') {
+        return 'The "docker" command was not found in your PATH. Is Docker installed?';
+    }
+    const stderr = err.stderr.trim();
+    if (stderr.length === 0)
+        return fallback;
+    if (stderr.includes('permission denied')) {
+        return 'Permission denied while connecting to the Docker daemon socket.\nIs your user in the "docker" group?';
+    }
+    if (stderr.includes('Cannot connect to the Docker daemon')) {
+        return ('Cannot connect to the Docker daemon.\n' +
+            'Is the Docker service running? On macOS/Windows, ensure Docker Desktop is started.');
+    }
+    return stderr;
+}
+/**
+ * Single canonical "is Docker available?" probe for the entire codebase. Other
+ * modules MUST call this rather than re-implementing `docker info`.
+ *
+ * `docker info` can blow past a tight timeout on a cold/busy daemon, so we use
+ * a generous 10s per attempt and retry on timeout-class failures. We do NOT
+ * retry on deterministic failures (ENOENT, permission denied, "Cannot connect
+ * to the Docker daemon") — those won't change between attempts and the
+ * user-visible failure path should be fast.
+ *
+ * @param execFileFn Optional `execFile` implementation for tests.
+ */
+export async function checkDockerAvailable(execFileFn = execFile) {
+    const totalAttempts = DOCKER_PROBE_MAX_RETRIES + 1;
+    let lastErr;
+    for (let attempt = 1; attempt <= totalAttempts; attempt++) {
+        try {
+            await execFileFn('docker', ['info'], { timeout: DOCKER_PROBE_TIMEOUT_MS });
+            return { available: true };
+        }
+        catch (err) {
+            lastErr = err;
+            if (!isExecError(err) || !isExecTimeout(err)) {
+                return {
+                    available: false,
+                    reason: DOCKER_UNAVAILABLE_REASON,
+                    detailedMessage: describeProbeFailure(err, err instanceof Error ? err.message : String(err)),
+                };
+            }
+        }
+    }
+    const baseMessage = lastErr instanceof Error ? lastErr.message : String(lastErr);
+    const timeoutSeconds = DOCKER_PROBE_TIMEOUT_MS / 1000;
+    return {
+        available: false,
+        reason: DOCKER_UNAVAILABLE_REASON,
+        detailedMessage: `Docker daemon did not respond within ${timeoutSeconds}s after ${totalAttempts} attempts. ` +
+            `The daemon may be overloaded or starting up. Original error: ${baseMessage}`,
+    };
+}
+//# sourceMappingURL=docker-probe.js.map

package/dist/docker/docker-probe.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"docker-probe.js","sourceRoot":"","sources":["../../src/docker/docker-probe.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAEH,OAAO,EAAE,QAAQ,IAAI,UAAU,EAAE,MAAM,oBAAoB,CAAC;AAC5D,OAAO,EAAE,SAAS,EAAE,MAAM,WAAW,CAAC;AACtC,OAAO,EAAE,WAAW,EAAE,aAAa,EAAE,MAAM,wBAAwB,CAAC;AAEpE,MAAM,QAAQ,GAAG,SAAS,CAAC,UAAU,CAAC,CAAC;AAEvC;;;;GAIG;AACH,MAAM,uBAAuB,GAAG,MAAM,CAAC;AAEvC,iEAAiE;AACjE,MAAM,wBAAwB,GAAG,CAAC,CAAC;AAEnC,MAAM,yBAAyB,GAAG,sBAAsB,CAAC;AAezD,SAAS,oBAAoB,CAAC,GAAY,EAAE,QAAgB;IAC1D,IAAI,CAAC,WAAW,CAAC,GAAG,CAAC;QAAE,OAAO,QAAQ,CAAC;IAEvC,IAAI,GAAG,CAAC,IAAI,KAAK,QAAQ,EAAE,CAAC;QAC1B,OAAO,uEAAuE,CAAC;IACjF,CAAC;IAED,MAAM,MAAM,GAAG,GAAG,CAAC,MAAM,CAAC,IAAI,EAAE,CAAC;IACjC,IAAI,MAAM,CAAC,MAAM,KAAK,CAAC;QAAE,OAAO,QAAQ,CAAC;IACzC,IAAI,MAAM,CAAC,QAAQ,CAAC,mBAAmB,CAAC,EAAE,CAAC;QACzC,OAAO,sGAAsG,CAAC;IAChH,CAAC;IACD,IAAI,MAAM,CAAC,QAAQ,CAAC,qCAAqC,CAAC,EAAE,CAAC;QAC3D,OAAO,CACL,wCAAwC;YACxC,oFAAoF,CACrF,CAAC;IACJ,CAAC;IACD,OAAO,MAAM,CAAC;AAChB,CAAC;AAED;;;;;;;;;;;GAWG;AACH,MAAM,CAAC,KAAK,UAAU,oBAAoB,CAAC,aAA8B,QAAQ;IAC/E,MAAM,aAAa,GAAG,wBAAwB,GAAG,CAAC,CAAC;IACnD,IAAI,OAAgB,CAAC;IAErB,KAAK,IAAI,OAAO,GAAG,CAAC,EAAE,OAAO,IAAI,aAAa,EAAE,OAAO,EAAE,EAAE,CAAC;QAC1D,IAAI,CAAC;YACH,MAAM,UAAU,CAAC,QAAQ,EAAE,CAAC,MAAM,CAAC,EAAE,EAAE,OAAO,EAAE,uBAAuB,EAAE,CAAC,CAAC;YAC3E,OAAO,EAAE,SAAS,EAAE,IAAI,EAAE,CAAC;QAC7B,CAAC;QAAC,OAAO,GAAY,EAAE,CAAC;YACtB,OAAO,GAAG,GAAG,CAAC;YACd,IAAI,CAAC,WAAW,CAAC,GAAG,CAAC,IAAI,CAAC,aAAa,CAAC,GAAG,CAAC,EAAE,CAAC;gBAC7C,OAAO;oBACL,SAAS,EAAE,KAAK;oBAChB,MAAM,EAAE,yBAAyB;oBACjC,eAAe,EAAE,oBAAoB,CAAC,GAAG,EAAE,GAAG,YAAY,KAAK,CAAC,CAAC,CAAC,GAAG,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC;iBAC7F,CAAC;YACJ,CAAC;QACH,CAAC;IACH,CAAC;IAED,MAAM,WAAW,GAAG,OAAO,YAAY,KAAK,CAAC,CAAC,CAAC,OAAO,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,OAAO,CAAC,CAAC;IACjF,MAAM,cAAc,GAAG,uBAAuB,GAAG,IAAI,CAAC;IACtD,OAAO;QACL,SAAS,EAAE,KAAK;QAChB,MAAM,EAAE,yBAAyB;QACjC,eAAe,EACb,wCAAwC,cAAc,WAAW,aAAa,aAAa;YAC3F,gEAAgE,WAAW,EAAE;KAChF,CAAC;AACJ,CAAC"}

package/dist/docker/docker-progress-sink.d.ts

@@ -0,0 +1,43 @@
+/**
+ * Single-line progress renderer for `docker pull` / `docker build` streams.
+ *
+ * `spawnWithIdleTimeout` (PR #250) restored real-time visibility into image
+ * pulls/builds by piping the child's stdout/stderr verbatim to the parent's
+ * terminal — fixing silent hangs but flooding the user with thousands of
+ * lines of BuildKit / per-layer chatter. This sink replaces that verbatim
+ * dump in the interactive (TTY) case with a single status line that
+ * updates in place, while still feeding every chunk to the watchdog (the
+ * heartbeat detection in `spawnWithIdleTimeout` runs before the chunk
+ * reaches the sink — see `forward()` in that file).
+ *
+ * On non-TTY stderr (CI, redirected logs) the sink passes chunks through
+ * verbatim, matching the pre-existing behavior and keeping CI logs useful.
+ *
+ * On failure, `dumpRecent()` flushes the last ~200 raw lines so the user
+ * gets a real diagnostic — the 4 KB stderr-tail quoted in the rejection
+ * message from `spawnWithIdleTimeout` is often too short to capture an
+ * earlier RUN step that actually went wrong.
+ */
+export type DockerProgressOperation = 'docker pull' | 'docker build' | 'container pull' | 'container build';
+export interface DockerProgressSink {
+    /** Writable that the child's stdout pipes into. */
+    stdout: NodeJS.WritableStream;
+    /** Writable that the child's stderr pipes into. */
+    stderr: NodeJS.WritableStream;
+    /** Commit the in-place line (TTY) or emit a final summary (non-TTY). */
+    finish(success: boolean): void;
+    /** Flush the rolling raw-line buffer; intended for the failure path. */
+    dumpRecent(): void;
+}
+export interface CreateDockerProgressSinkOptions {
+    operation: DockerProgressOperation;
+    /** Underlying writable. Defaults to `process.stderr`. */
+    output?: NodeJS.WritableStream;
+    /** Override TTY detection (used by tests). */
+    isTTY?: boolean;
+    /** Max raw lines retained for failure dump. Defaults to 200. */
+    bufferSize?: number;
+    /** Override clock for elapsed timers (used by tests). */
+    now?: () => number;
+}
+export declare function createDockerProgressSink(opts: CreateDockerProgressSinkOptions): DockerProgressSink;

package/dist/docker/docker-progress-sink.js

@@ -0,0 +1,299 @@
+/**
+ * Single-line progress renderer for `docker pull` / `docker build` streams.
+ *
+ * `spawnWithIdleTimeout` (PR #250) restored real-time visibility into image
+ * pulls/builds by piping the child's stdout/stderr verbatim to the parent's
+ * terminal — fixing silent hangs but flooding the user with thousands of
+ * lines of BuildKit / per-layer chatter. This sink replaces that verbatim
+ * dump in the interactive (TTY) case with a single status line that
+ * updates in place, while still feeding every chunk to the watchdog (the
+ * heartbeat detection in `spawnWithIdleTimeout` runs before the chunk
+ * reaches the sink — see `forward()` in that file).
+ *
+ * On non-TTY stderr (CI, redirected logs) the sink passes chunks through
+ * verbatim, matching the pre-existing behavior and keeping CI logs useful.
+ *
+ * On failure, `dumpRecent()` flushes the last ~200 raw lines so the user
+ * gets a real diagnostic — the 4 KB stderr-tail quoted in the rejection
+ * message from `spawnWithIdleTimeout` is often too short to capture an
+ * earlier RUN step that actually went wrong.
+ */
+import { Writable } from 'node:stream';
+import chalk from 'chalk';
+const DEFAULT_BUFFER_LINES = 200;
+const PENDING_BUFFER_HARD_CAP = 8 * 1024;
+export function createDockerProgressSink(opts) {
+    const output = opts.output ?? process.stderr;
+    // `process.stderr` is typed as `WriteStream` (with `isTTY: true | undefined`);
+    // a generic `WritableStream` may not have the property at all. Cast to a
+    // shape that admits either so ESLint does not flag the comparison.
+    const isTTY = opts.isTTY ?? output.isTTY === true;
+    const bufferSize = opts.bufferSize ?? DEFAULT_BUFFER_LINES;
+    const now = opts.now ?? Date.now;
+    // Non-TTY fast path: behave like the pre-sink `process.stderr` so CI logs
+    // keep their full transcript. finish/dumpRecent are no-ops because the
+    // raw transcript is already on screen.
+    if (!isTTY) {
+        const makeStream = () => new Writable({
+            write(chunk, _encoding, cb) {
+                output.write(typeof chunk === 'string' ? chunk : chunk.toString('utf-8'));
+                cb();
+            },
+        });
+        return {
+            stdout: makeStream(),
+            stderr: makeStream(),
+            finish: () => { },
+            dumpRecent: () => { },
+        };
+    }
+    const parser = opts.operation === 'docker pull' ? createPullParser(now) : createBuildParser(now);
+    const ringBuffer = [];
+    const startTime = now();
+    let pendingStdout = '';
+    let pendingStderr = '';
+    // Empty string means no in-place line is currently on screen.
+    let lastRendered = '';
+    let finished = false;
+    const record = (line) => {
+        if (!line)
+            return;
+        ringBuffer.push(line);
+        if (ringBuffer.length > bufferSize)
+            ringBuffer.shift();
+    };
+    const render = () => {
+        if (finished)
+            return;
+        const summary = parser.summary();
+        if (summary === lastRendered)
+            return;
+        lastRendered = summary;
+        output.write(`\r\x1B[2K${summary}`);
+    };
+    const processChunk = (chunk, isStderr) => {
+        const text = typeof chunk === 'string' ? chunk : chunk.toString('utf-8');
+        let pending = (isStderr ? pendingStderr : pendingStdout) + text;
+        // Docker pull uses `\r` (not `\n`) to update its progress meter in place;
+        // we treat both as line boundaries so each transient state is parsed.
+        const splitter = /[^\r\n]*[\r\n]/g;
+        let lastIdx = 0;
+        let match;
+        while ((match = splitter.exec(pending)) !== null) {
+            const segment = match[0];
+            const line = segment.replace(/[\r\n]+$/, '').trimEnd();
+            if (line) {
+                record(line);
+                try {
+                    parser.feed(line);
+                }
+                catch {
+                    // Parser bugs MUST NOT propagate — the streaming pipeline relies
+                    // on the sink consuming bytes without error so the watchdog stays
+                    // armed.
+                }
+            }
+            lastIdx = splitter.lastIndex;
+        }
+        pending = pending.slice(lastIdx);
+        // Guard against pathological no-newline output (e.g. a malicious image
+        // streaming a giant binary blob to stderr). Keep only the trailing half
+        // of the cap so we don't OOM on the pending buffer.
+        if (pending.length > PENDING_BUFFER_HARD_CAP) {
+            pending = pending.slice(-PENDING_BUFFER_HARD_CAP / 2);
+        }
+        if (isStderr)
+            pendingStderr = pending;
+        else
+            pendingStdout = pending;
+        render();
+    };
+    const makeWritable = (isStderr) => new Writable({
+        write(chunk, _encoding, cb) {
+            try {
+                processChunk(chunk, isStderr);
+            }
+            catch {
+                // see comment above — never throw from the write path
+            }
+            cb();
+        },
+    });
+    const flushPending = () => {
+        for (const pending of [pendingStdout, pendingStderr]) {
+            const trimmed = pending.replace(/[\r\n]+$/, '').trimEnd();
+            if (!trimmed)
+                continue;
+            record(trimmed);
+            try {
+                parser.feed(trimmed);
+            }
+            catch {
+                /* swallow */
+            }
+        }
+        pendingStdout = '';
+        pendingStderr = '';
+    };
+    return {
+        stdout: makeWritable(false),
+        stderr: makeWritable(true),
+        finish(success) {
+            if (finished)
+                return;
+            finished = true;
+            flushPending();
+            const elapsed = ((now() - startTime) / 1000).toFixed(1);
+            const summary = parser.summary();
+            const tag = success ? chalk.green(`${opts.operation} done`) : chalk.red(`${opts.operation} failed`);
+            const line = `${tag}  ${chalk.dim(`(${elapsed}s)`)}  ${chalk.dim(summary)}`;
+            if (lastRendered) {
+                output.write(`\r\x1B[2K${line}\n`);
+            }
+            else {
+                output.write(`${line}\n`);
+            }
+            lastRendered = '';
+        },
+        dumpRecent() {
+            if (ringBuffer.length === 0)
+                return;
+            if (lastRendered) {
+                // Make sure our dump starts on a fresh line.
+                output.write('\r\x1B[2K');
+                lastRendered = '';
+            }
+            output.write(chalk.dim(`--- last ${ringBuffer.length} lines from ${opts.operation} ---`) + '\n');
+            for (const line of ringBuffer) {
+                output.write(line + '\n');
+            }
+        },
+    };
+}
+function createPullParser(now) {
+    const layers = new Map();
+    let statusLine = '';
+    const startTime = now();
+    return {
+        feed(line) {
+            const clean = stripAnsi(line).trim();
+            // Layer-scoped messages: `<id>: <message>` where id is a short hex
+            // digest or a tag name in the case of the first line.
+            const layerMatch = clean.match(/^([0-9a-f]{8,}|[A-Za-z][\w.-]*):\s+(.+?)\s*$/);
+            if (layerMatch) {
+                const [, id, msg] = layerMatch;
+                if (/^Pulling fs layer$/i.test(msg) || /^Waiting$/i.test(msg)) {
+                    if (!layers.has(id))
+                        layers.set(id, 'pending');
+                }
+                else if (/^Downloading/i.test(msg)) {
+                    layers.set(id, 'downloading');
+                }
+                else if (/^Verifying Checksum/i.test(msg)) {
+                    layers.set(id, 'verifying');
+                }
+                else if (/^Download complete/i.test(msg)) {
+                    layers.set(id, 'downloaded');
+                }
+                else if (/^Extracting/i.test(msg)) {
+                    layers.set(id, 'extracting');
+                }
+                else if (/^Pull complete/i.test(msg)) {
+                    layers.set(id, 'done');
+                }
+                else if (/^Already exists/i.test(msg)) {
+                    layers.set(id, 'exists');
+                }
+                else if (/^Pulling from /i.test(msg)) {
+                    statusLine = clean;
+                }
+                return;
+            }
+            if (/^Status:|^Digest:/i.test(clean) || /Pulling from /i.test(clean)) {
+                statusLine = clean;
+            }
+        },
+        summary() {
+            const total = layers.size;
+            const phases = [...layers.values()];
+            const done = phases.filter((p) => p === 'done' || p === 'exists').length;
+            const downloading = phases.filter((p) => p === 'downloading').length;
+            const extracting = phases.filter((p) => p === 'extracting').length;
+            const elapsed = ((now() - startTime) / 1000).toFixed(0);
+            const parts = [chalk.cyan('docker pull')];
+            if (total === 0) {
+                parts.push(chalk.dim(statusLine || 'starting...'));
+            }
+            else {
+                parts.push(chalk.dim(`${done}/${total} layers`));
+                if (downloading > 0)
+                    parts.push(chalk.yellow(`${downloading} downloading`));
+                if (extracting > 0)
+                    parts.push(chalk.blue(`${extracting} extracting`));
+            }
+            parts.push(chalk.dim(`(${elapsed}s)`));
+            return parts.join('  ');
+        },
+    };
+}
+function createBuildParser(now) {
+    let currentStep;
+    let totalSteps;
+    let currentDesc;
+    let lastBracket;
+    const startTime = now();
+    return {
+        feed(line) {
+            const clean = stripAnsi(line);
+            // BuildKit `--progress=plain` format. Step headers look like:
+            //   #5 [stage 2/8] RUN apt-get install -y curl
+            //   #4 [internal] load build definition from Dockerfile
+            //   #6 [build 3/5] COPY . /workspace
+            // We pull the `N/M` out of the bracket when present so the summary
+            // can show progress; otherwise we fall back to the bracket label.
+            const stepHeader = clean.match(/^#\d+\s+\[([^\]]+)\]\s+(.+?)\s*$/);
+            if (stepHeader) {
+                const [, bracket, desc] = stepHeader;
+                const numbered = bracket.match(/(\d+)\/(\d+)/);
+                if (numbered) {
+                    currentStep = Number.parseInt(numbered[1], 10);
+                    totalSteps = Number.parseInt(numbered[2], 10);
+                }
+                lastBracket = bracket;
+                currentDesc = truncate(desc, 80);
+            }
+            // Step continuation lines (`#5 0.234 ...output...`) and DONE markers
+            // intentionally don't update the summary — they'd just flicker the
+            // line. Their job is to advance the watchdog, which already happens
+            // before the sink is reached.
+        },
+        summary() {
+            const elapsed = ((now() - startTime) / 1000).toFixed(0);
+            const parts = [chalk.cyan('docker build')];
+            if (currentStep !== undefined && totalSteps !== undefined) {
+                parts.push(chalk.dim(`step ${currentStep}/${totalSteps}`));
+            }
+            else if (lastBracket) {
+                parts.push(chalk.dim(lastBracket));
+            }
+            else {
+                parts.push(chalk.dim('starting...'));
+            }
+            if (currentDesc)
+                parts.push(currentDesc);
+            parts.push(chalk.dim(`(${elapsed}s)`));
+            return parts.join('  ');
+        },
+    };
+}
+function truncate(s, max) {
+    return s.length > max ? s.slice(0, max - 1) + '…' : s;
+}
+// CSI sequence: ESC [ <params> <intermediate> <final>. Strips colors and
+// cursor-control codes BuildKit/docker may embed in line output.
+// eslint-disable-next-line no-control-regex
+const ANSI_PATTERN = /\u001B\[[0-?]*[ -/]*[@-~]/g;
+function stripAnsi(s) {
+    return s.replace(ANSI_PATTERN, '');
+}
+//# sourceMappingURL=docker-progress-sink.js.map

package/dist/docker/docker-progress-sink.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"docker-progress-sink.js","sourceRoot":"","sources":["../../src/docker/docker-progress-sink.ts"],"names":[],"mappings":"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"}

package/dist/docker/mitm-proxy.d.ts

@@ -14,10 +14,12 @@
  */
 import * as http from 'node:http';
 import { type CertificateAuthority } from './ca.js';
-import { type ProviderConfig } from './provider-config.js';
+import { type AgentKind, type ProviderConfig } from './provider-config.js';
 import type { OAuthTokenManager } from './oauth-token-manager.js';
 import type { RegistryConfig, PackageValidator } from './package-types.js';
 import { type DomainListing } from './proxy-tools.js';
+import type { SseProvider } from './token-stream-types.js';
+import type { TrajectoryCaptureWriter } from './trajectory-capture.js';
 /**
  * Runtime control surface for the MITM proxy's host allowlist.
  *
@@ -65,6 +67,41 @@ export interface MitmProxy {
     stop(): Promise<void>;
     /** Runtime control for the dynamic host allowlist. */
     readonly hosts: DynamicHostController;
+    /**
+     * Set (or clear) the session ID that token-stream events extracted from
+     * LLM API responses are routed under.
+     *
+     * The MITM proxy is long-lived in shared-container workflow mode, where
+     * multiple per-state agent sessions share a single proxy instance. Token
+     * events for the active agent must be labeled with that agent's session
+     * ID, not with any static workflow-wide ID. Callers flip this value
+     * around each agent run: set to the session's ID before the agent runs,
+     * reset to `undefined` when the session ends.
+     *
+     * When the current session ID is `undefined`, extraction sites skip the
+     * `bus.push()` entirely — no events are emitted under a sentinel value.
+     */
+    setTokenSessionId(id: import('../session/types.js').SessionId | undefined): void;
+    /**
+     * Internal capture-attribution setter. Sets the session ID stamped on
+     * subsequent captured ExchangeRecords. Decoupled from
+     * `setTokenSessionId` because token-stream-bus and capture are
+     * different code paths that must not corrupt each other.
+     *
+     * Not called directly by orchestrator code — wrapped by
+     * `DockerInfrastructure.beginCaptureSession()` / `endCaptureSession()`.
+     * Exposed for unit-testing the proxy in isolation.
+     *
+     * When `undefined`, no capture record is produced for incoming
+     * exchanges (the per-handler snapshot is `undefined`).
+     */
+    setCaptureSessionId(id: import('../session/types.js').SessionId | undefined): void;
+    /**
+     * Internal capture-attribution setter. Sets the persona stamped on
+     * subsequent captured ExchangeRecords. Wrapped by
+     * `DockerInfrastructure.beginCaptureSession()`.
+     */
+    setCapturePersona(persona: string | undefined): void;
 }
 export interface MitmProxyOptions {
     /** Absolute path for the Unix domain socket (UDS mode). Omit for TCP mode. */
@@ -107,6 +144,56 @@ export interface MitmProxyOptions {
      * Used in tests to avoid real DNS resolution.
      */
     readonly dnsLookup?: http.RequestOptions['lookup'];
+    /**
+     * Connection-source filter for TCP mode. When set, sockets whose
+     * remote address fails the predicate are destroyed before any request
+     * parsing. Used by the tcp-hostonly topology, where the proxy listens
+     * on 0.0.0.0 and only the agent VM's host-only subnet may connect
+     * (see src/docker/network-topology.ts). No effect in UDS mode.
+     */
+    readonly allowRemoteAddress?: (remoteAddress: string | undefined) => boolean;
+    /**
+     * Initial session ID for token stream routing. When provided, token
+     * events extracted from LLM API endpoints are published into the
+     * module-scoped singleton bus (see `getTokenStreamBus`) under this ID.
+     *
+     * The value is mutable at runtime via `MitmProxy.setTokenSessionId()`:
+     * long-lived proxies (shared-container workflows) flip this around each
+     * agent so the active agent's session ID is used. When no session ID
+     * is set (initial value `undefined` AND no subsequent `setTokenSessionId`
+     * call), extraction sites skip publishing entirely.
+     *
+     * Routinely stale in workflow shared-container mode where the
+     * orchestrator overrides via `setTokenSessionId`; the seed is only
+     * meaningful in single-session standalone mode.
+     */
+    readonly initialTokenSessionId?: import('../session/types.js').SessionId;
+    /**
+     * Kind of agent driving this proxy, used by request-body rewriters to
+     * apply agent-kind-conditional transforms (currently: stripping the
+     * schedule built-in skill's tools when set to `'workflow'`). Immutable
+     * over the proxy's lifetime — a single bundle serves a single agent kind.
+     * `undefined` means rewriters fall back to the most conservative behavior.
+     */
+    readonly agentKind?: AgentKind;
+    /**
+     * Trajectory-capture dispatcher. When set, the proxy taps decrypted
+     * request and response bytes on allowed LLM API endpoints and hands
+     * complete `ExchangeRecord`s to the writer. When `undefined`, no taps
+     * are installed and capture is zero-cost. See
+     * docs/designs/mitm-token-trajectory-capture.md.
+     */
+    readonly capture?: TrajectoryCaptureWriter;
+    /**
+     * Human-readable agent name (e.g. `'claude-code'`) stamped onto every
+     * captured ExchangeRecord. Distinct from `agentKind` (which is the
+     * closed `'workflow' | undefined` enum used by the request rewriter).
+     */
+    readonly recordedAgentName?: string;
+    /** Workflow-run ID stamped onto every captured ExchangeRecord (when present). */
+    readonly workflowRunId?: string;
+    /** Bundle ID stamped onto every captured ExchangeRecord (when present). */
+    readonly bundleId?: string;
 }
 export interface ProviderKeyMapping {
     readonly config: ProviderConfig;
@@ -117,4 +204,51 @@ export interface ProviderKeyMapping {
     /** Optional token manager for OAuth providers — enables proactive refresh and 401 retry. */
     readonly tokenManager?: OAuthTokenManager;
 }
+/**
+ * Max bytes buffered from a non-streaming JSON response body for token stream
+ * extraction. The response is still streamed to the client unchanged; only
+ * the extraction side stops capturing once the cap is hit. This protects the
+ * proxy from unbounded memory growth on very large completions.
+ */
+export declare const MAX_JSON_RESPONSE_CAPTURE_BYTES: number;
+/**
+ * Output of `createBoundedJsonResponseCapture` -- the stateful hooks used to
+ * drive a bounded capture over a chunked response stream.
+ *
+ * Exposed primarily for unit testing the OOM guard without standing up the
+ * full mitm proxy pipeline.
+ */
+export interface BoundedJsonResponseCapture {
+    /** Feed a chunk into the capture buffer. Always safe to call. */
+    onData(chunk: Buffer): void;
+    /**
+     * Signal end-of-stream. The callback receives the concatenated buffer,
+     * or `null` if the capture overflowed and was discarded.
+     */
+    onEnd(onComplete: (body: Buffer | null) => void): void;
+}
+/**
+ * Create a size-bounded capture for a JSON response body.
+ *
+ * Up to `maxBytes` of data is accumulated into an internal chunk array.
+ * Once that threshold is crossed, any already-buffered chunks are released
+ * (so large responses do not pin memory) and further chunks are ignored.
+ * The caller is still responsible for piping the stream through to the
+ * client -- this helper only manages the extraction-side buffer.
+ */
+export declare function createBoundedJsonResponseCapture(maxBytes?: number): BoundedJsonResponseCapture;
+/**
+ * Maps a target hostname to the SSE provider for token stream parsing.
+ * Only Anthropic and OpenAI hosts are recognized; everything else
+ * falls back to 'unknown'.
+ */
+export declare function resolveSseProvider(hostname: string): SseProvider;
+export declare function extractToolResults(parsed: Record<string, unknown>, sessionId: import('../session/types.js').SessionId): void;
+/**
+ * Extract token stream events from a non-streaming JSON response body.
+ * Used when the upstream returns application/json instead of text/event-stream.
+ *
+ * Emits message_start (model), text_delta (content), and message_end (usage).
+ */
+export declare function extractFromJsonResponse(body: Buffer, sessionId: import('../session/types.js').SessionId): void;
 export declare function createMitmProxy(options: MitmProxyOptions): MitmProxy;