agenticreplay 0.1.0 → 0.1.2

package/node_modules/@agenticreplay/proxy/dist/intercept.js

@@ -0,0 +1,1258 @@
+import { createServer as createHttpServer, } from 'node:http';
+import { connect as http2Connect, createSecureServer as createHttp2SecureServer, constants as H2, } from 'node:http2';
+import { Agent, request as httpsRequest } from 'node:https';
+import { connect as netConnect, isIP } from 'node:net';
+import { createSecureContext, rootCertificates, TLSSocket } from 'node:tls';
+import { randomUUID } from 'node:crypto';
+import * as zlib from 'node:zlib';
+import { AUTH_REQUEST_HEADERS, AUTH_RESPONSE_HEADERS, BINARY_BODY_PREFIX, } from '@agenticreplay/core';
+import { HostPolicy } from './tls-hosts.js';
+/**
+ * HTTP CONNECT: tunnel it, or terminate it and look inside.
+ *
+ * Capture is normally base-URL injection — point an environment variable at a local origin server
+ * and the agent's traffic arrives in plaintext. A harness that reads no such variable (a Codex CLI
+ * signed in with a ChatGPT subscription is the case that forced this) is invisible to that
+ * mechanism, because it talks to its own backend over TLS it established itself.
+ *
+ * So: a proxy the child is pointed at with `HTTPS_PROXY`, a CA minted for this run alone, and a
+ * certificate for exactly the hosts the operator named. Everything else is copied byte for byte
+ * between two sockets, which is the difference between a debugger and a wiretap.
+ */
+/** Described by this connection rather than by the message, so never forwarded. */
+const HOP_BY_HOP = new Set([
+    'connection',
+    'proxy-connection',
+    'keep-alive',
+    'transfer-encoding',
+    'upgrade',
+    'te',
+    'trailer',
+    // Stripped so the origin answers in plaintext. A recorded gzip frame is a recording nobody can
+    // read, and the agent is no worse off for receiving the bytes uncompressed.
+    'accept-encoding',
+]);
+/**
+ * Forwarded upstream, never written down. Same rule the origin-server path already applies: an
+ * agent that cannot authenticate cannot run, and spec §7 forbids writing auth material, which is
+ * a different requirement from relaying it.
+ */
+const SECRET_REQUEST_HEADERS = new Set(AUTH_REQUEST_HEADERS);
+/** A response can hand out credentials too. `set-cookie` is a session, not metadata. */
+const SECRET_RESPONSE_HEADERS = new Set(AUTH_RESPONSE_HEADERS);
+/**
+ * Enough to hold any model exchange; short of enough to hold somebody's video download.
+ *
+ * Exported because a run that hits it has to be able to say so in the number the operator will
+ * measure their conversation against. A warning that says "too large" without saying how large is
+ * a warning nobody can act on.
+ */
+export const DEFAULT_MAX_CAPTURED_BYTES = 64 * 1024 * 1024;
+export const DEFAULT_MAX_BUFFERED_BYTES = 256 * 1024 * 1024;
+export function isInterceptResponse(decision) {
+    return 'status' in decision;
+}
+/**
+ * A rewritten body is uncompressed JSON even when the client sent gzip/zstd. The origin must not
+ * be told the old encoding, or it will try to inflate plaintext and the substitution is lost.
+ */
+function applyRewrittenBody(headers, body) {
+    delete headers['content-encoding'];
+    delete headers['content-length'];
+    headers['content-length'] = String(body.length);
+}
+/** Decode a recorded body, whichever of the two forms it was stored in. */
+export function readRecordedBody(body) {
+    return body.startsWith(BINARY_BODY_PREFIX)
+        ? Buffer.from(body.slice(BINARY_BODY_PREFIX.length), 'base64')
+        : Buffer.from(body, 'utf8');
+}
+/**
+ * Decode a body for reading while forwarding stays byte-for-byte.
+ *
+ * Named for the body, not for the half of the exchange: responses arrive compressed too, and a
+ * function called `decodeRequestBody` decoding one would be a name that has to be read past.
+ */
+export function decodeBody(bytes, contentEncoding, maxOutputBytes) {
+    const encodings = (contentEncoding ?? '')
+        .split(',')
+        .map((value) => value.trim().toLowerCase())
+        .filter((value) => value !== '' && value !== 'identity');
+    let decoded = bytes;
+    for (const encoding of encodings.reverse()) {
+        const limits = maxOutputBytes === undefined ? undefined : { maxOutputLength: maxOutputBytes };
+        if (encoding === 'gzip')
+            decoded = zlib.gunzipSync(decoded, limits);
+        else if (encoding === 'deflate')
+            decoded = zlib.inflateSync(decoded, limits);
+        else if (encoding === 'br')
+            decoded = zlib.brotliDecompressSync(decoded, limits);
+        else if (encoding === 'zstd') {
+            const decompress = zlib.zstdDecompressSync;
+            if (!decompress)
+                throw new Error('zstd request encoding requires a Node runtime with zstd support');
+            decoded = decompress(decoded, maxOutputBytes === undefined ? undefined : { maxOutputLength: maxOutputBytes });
+        }
+        else {
+            throw new Error(`unsupported content encoding: ${encoding}`);
+        }
+    }
+    return recordableBody(decoded);
+}
+/**
+ * The response body as the client saw it, plus the encoding agenticreplay took off to get there.
+ *
+ * Not attempted on a capture that is a prefix rather than the whole stream: half a deflate member
+ * cannot be inflated, and `truncated` / `abandoned` already say the record is incomplete. Nor on a
+ * response that carried no body -- RFC 7232 asks a 304 to send the header fields a 200 would have
+ * sent, `content-encoding` among them, and 204 and HEAD arrive the same way; every decoder throws
+ * "unexpected end of file" on an empty buffer, which would have reported an opaque body where
+ * there was no body at all. Failing to decode a body that *is* there is not fatal either -- the
+ * wire bytes are kept and the reason is reported, the same way an undecodable request body is.
+ */
+function recordableResponseBody(captured, contentEncoding, whole) {
+    const encoding = contentEncoding
+        ?.split(',')
+        .map((value) => value.trim().toLowerCase())
+        .filter((value) => value !== '' && value !== 'identity')
+        .join(', ');
+    if (encoding === undefined ||
+        encoding === '' ||
+        encoding === 'identity' ||
+        captured.bytes === 0 ||
+        !whole) {
+        return { body: captured.text() };
+    }
+    try {
+        return {
+            body: decodeBody(captured.buffer(), contentEncoding, captured.limit),
+            decodedFrom: encoding,
+        };
+    }
+    catch (err) {
+        return { body: captured.text(), error: String(err) };
+    }
+}
+/**
+ * The headers that describe the body actually recorded.
+ *
+ * `content-encoding: gzip` beside a decoded body is a claim the recording no longer supports, and
+ * a `content-length` counting compressed bytes is another. Neither fact is lost: the wire size is
+ * already on the event as `bytes`, and what agenticreplay removed is recorded as `decoded_from`. Only the
+ * recorded copy is touched -- the client is served the origin's own header set, from `outHeaders`
+ * on HTTP/1.1 and `downstream` on h2.
+ */
+function normalizeHeaderValue(value) {
+    if (typeof value === 'string')
+        return value;
+    if (Array.isArray(value))
+        return value.slice();
+    if (typeof value === 'number')
+        return String(value);
+    return undefined;
+}
+function headerText(value) {
+    if (value === undefined)
+        return undefined;
+    return Array.isArray(value) ? value.join(', ') : value;
+}
+function headersWithoutEncoding(headers) {
+    const out = {};
+    for (const [key, value] of Object.entries(headers)) {
+        if (key === 'content-encoding' || key === 'content-length')
+            continue;
+        out[key] = value;
+    }
+    return out;
+}
+/** Text when the bytes are text, base64 behind a marker when they are not. */
+function recordableBody(bytes) {
+    const asText = bytes.toString('utf8');
+    if (Buffer.compare(Buffer.from(asText, 'utf8'), bytes) === 0)
+        return asText;
+    return `${BINARY_BODY_PREFIX}${bytes.toString('base64')}`;
+}
+function binaryBodyTransformation(location, body) {
+    if (!body.startsWith(BINARY_BODY_PREFIX))
+        return [];
+    return [
+        {
+            kind: 'encoding',
+            location,
+            rule: 'binary-body-base64-persistence',
+            count: 1,
+            reason: 'invalid UTF-8 preserved as base64 because the transport body is binary',
+        },
+    ];
+}
+function normalizeLimit(value, fallback) {
+    return value !== undefined && Number.isSafeInteger(value) && value > 0 ? value : fallback;
+}
+class CaptureBudget {
+    limit;
+    #used = 0;
+    constructor(limit) {
+        this.limit = limit;
+    }
+    reserve(requested) {
+        const available = Math.max(0, this.limit - this.#used);
+        const reserved = Math.min(requested, available);
+        this.#used += reserved;
+        return reserved;
+    }
+    release(bytes) {
+        this.#used = Math.max(0, this.#used - bytes);
+    }
+}
+/** `host:port` from a CONNECT request line, with the default HTTPS port when it is omitted. */
+function parseTarget(authority) {
+    const trimmed = authority.trim();
+    const colon = trimmed.lastIndexOf(':');
+    // A colon inside brackets belongs to an IPv6 literal, not to a port.
+    const hasPort = colon > trimmed.lastIndexOf(']');
+    const hostText = hasPort ? trimmed.slice(0, colon) : trimmed;
+    const host = hostText.replace(/^\[|\]$/g, '');
+    if (host.length === 0)
+        return undefined;
+    if (!hasPort)
+        return { host, port: 443 };
+    const port = Number(trimmed.slice(colon + 1));
+    if (!Number.isInteger(port) || port <= 0 || port > 65535)
+        return undefined;
+    return { host, port };
+}
+/**
+ * Attach CONNECT handling to an existing origin server.
+ *
+ * Only ever called when interception was asked for. With no `'connect'` listener Node destroys
+ * the socket, which is the right answer for a proxy that was not asked to be one — so "off" is
+ * the absence of this function, not a branch inside it.
+ */
+export function attachTlsIntercept(server, options, counters) {
+    const policy = HostPolicy.from(options.hosts ?? []);
+    const maxCaptured = normalizeLimit(options.maxCapturedBytes, DEFAULT_MAX_CAPTURED_BYTES);
+    const budget = new CaptureBudget(normalizeLimit(options.maxBufferedBytes, DEFAULT_MAX_BUFFERED_BYTES));
+    const extraRoots = options.trustedOriginCerts ?? [];
+    // `ca` replaces the default store rather than adding to it, so an extra root has to be supplied
+    // alongside the whole bundle or the proxy would stop trusting the public web.
+    const originTrust = extraRoots.length > 0 ? [...rootCertificates, ...extraRoots] : undefined;
+    const agent = new Agent({ keepAlive: true, maxSockets: 64 });
+    /** One secure context per intercepted host; minting is cheap but not free. */
+    const contexts = new Map();
+    /**
+     * Which origin a decrypted request was destined for, keyed by the socket we created for it.
+     *
+     * Keyed on `object` rather than `TLSSocket` so a lookup from `req.socket` needs no cast: a
+     * socket this map does not know is simply a miss, which is exactly the answer wanted.
+     */
+    const targets = new WeakMap();
+    /**
+     * The same answer as `targets`, reachable from an h2 session.
+     *
+     * `session.socket` is a Proxy standing in for the real socket, so it is never a key `targets`
+     * knows -- the lookup silently missed and every h2 stream was rejected as arriving on an unknown
+     * connection. A property on the socket survives the Proxy, which forwards unknown reads through.
+     */
+    const TARGET = Symbol('agenticreplay.intercept.target');
+    /**
+     * Which origin a decrypted request was destined for.
+     *
+     * Two indirections to get through, both of them somebody else's wrapper. The h2 server hands out
+     * a Proxy in place of the socket, which forwards unknown property reads to the real one; and the
+     * socket it terminated is a `TLSSocket` wrapping the socket we tagged, reachable as `_parent`.
+     */
+    const targetOf = (socket) => {
+        let cursor = socket;
+        for (let depth = 0; depth < 4 && typeof cursor === 'object' && cursor !== null; depth += 1) {
+            const own = cursor[TARGET] ?? targets.get(cursor);
+            if (own)
+                return own;
+            cursor = cursor._parent;
+        }
+        return undefined;
+    };
+    const open = new Set();
+    /**
+     * A protocol switch inside a session we decrypted — a WebSocket, usually.
+     *
+     * Not relayed: this proxy understands request/response exchanges and nothing else, and a
+     * half-implemented WebSocket relay would drop frames rather than fail. Refusing outright and
+     * saying so leaves the operator with a message instead of a hang, and the remedy is to take the
+     * host off the allowlist so the whole connection is tunnelled untouched instead.
+     */
+    const onUpgrade = (req, socket) => {
+        const target = targetOf(req.socket);
+        options.onFailure?.({
+            host: target?.host ?? 'unknown',
+            port: target?.port ?? 0,
+            reason: `agenticreplay cannot relay an ${String(req.headers.upgrade)} upgrade through an intercepted connection`,
+            kind: 'upgrade_refused',
+        });
+        socket.end('HTTP/1.1 501 Not Implemented\r\nconnection: close\r\n\r\n');
+    };
+    /**
+     * One upstream h2 session per origin, reused across streams the way `Agent` is for HTTP/1.1.
+     *
+     * `ALPNProtocols: ['h2']` on purpose: this session exists only because the client asked for h2,
+     * and an origin answering `http/1.1` here would leave us holding a session that cannot carry the
+     * request. Failing loudly beats forwarding into a protocol mismatch.
+     */
+    const h2Upstreams = new Map();
+    function upstreamH2(target) {
+        const key = `${target.host}:${target.port}`;
+        const existing = h2Upstreams.get(key);
+        if (existing && !existing.closed && !existing.destroyed)
+            return existing;
+        const session = http2Connect(`https://${target.host}:${target.port}`, {
+            ALPNProtocols: ['h2'],
+            ...(originTrust ? { ca: originTrust } : {}),
+        });
+        session.on('error', (err) => {
+            options.onFailure?.({
+                host: target.host,
+                port: target.port,
+                reason: String(err),
+                kind: 'upstream_session',
+            });
+            h2Upstreams.delete(key);
+        });
+        session.on('close', () => h2Upstreams.delete(key));
+        h2Upstreams.set(key, session);
+        return session;
+    }
+    /**
+     * One TLS-terminating server per intercepted host, and the reason it is a server rather than a
+     * socket we terminate ourselves.
+     *
+     * The obvious shape -- `new TLSSocket({ isServer: true })`, then hand the decrypted socket to an
+     * HTTP server -- works for HTTP/1.1 and silently does not for h2. An `Http2Session` takes over
+     * the socket's handle rather than reading the stream, so the client's connection preface and its
+     * first PING, already buffered by the time the handshake callback runs, are never seen: the
+     * session establishes, nothing flows, and the client gives up with a keepalive timeout. Verified
+     * on a loopback with no agent involved. Letting the h2 server do the TLS itself is what fixes
+     * it, and `allowHTTP1` keeps one server able to serve both.
+     *
+     * Per host rather than one server with `SNICallback`, so the certificate is still chosen by the
+     * CONNECT target exactly as before. SNI would work for every client that sends it and quietly
+     * pick the wrong certificate for one that does not.
+     */
+    const h2Servers = new Map();
+    function serverFor(host) {
+        const cached = h2Servers.get(host);
+        if (cached)
+            return cached;
+        const issued = options.ca.issue(host);
+        const server = createHttp2SecureServer({
+            key: issued.keyPem,
+            cert: issued.certPem,
+            allowHTTP1: true,
+            ALPNProtocols: ['h2', 'http/1.1'],
+        });
+        // An h2 request emits both `stream` and `request` when `allowHTTP1` is set, so `request` has
+        // to serve HTTP/1.1 only or the same exchange is answered twice and the second attempt throws
+        // ERR_HTTP2_HEADERS_SENT.
+        server.on('request', (req, res) => {
+            // The event is typed for h2 because the server can serve it, but `allowHTTP1` means an
+            // HTTP/1.1 session delivers the node:http pair instead. The version check above is what
+            // makes the cast true rather than hopeful.
+            if (req.httpVersionMajor >= 2)
+                return;
+            const req1 = req;
+            const res1 = res;
+            void forward(req1, res1).catch((err) => {
+                if (!res.headersSent)
+                    res.writeHead(502, { 'content-type': 'application/json' });
+                res.end(JSON.stringify({ error: { message: `agenticreplay tls-intercept: ${String(err)}` } }));
+            });
+        });
+        server.on('stream', (stream, headers) => {
+            void forwardH2(stream, headers).catch((err) => {
+                // Reported as well as answered, because the guard below returns without writing anything
+                // when the client has already gone -- and a failure nobody is left to receive is exactly
+                // the one worth having in the run's failure list.
+                reportH2(stream.session?.socket, err, 'forward');
+                // Guarded for the same reason as the response path: by the time a failure surfaces the
+                // client may be gone, and respond/end would then throw out of a rejection handler.
+                if (stream.destroyed)
+                    return;
+                try {
+                    if (!stream.headersSent)
+                        stream.respond({ ':status': 502 });
+                    stream.end(JSON.stringify({
+                        error: { message: `agenticreplay tls-intercept h2: ${String(err)}` },
+                    }));
+                }
+                catch {
+                    stream.destroy();
+                }
+            });
+        });
+        server.on('upgrade', onUpgrade);
+        // The one that was worth telling apart: the client refused OUR certificate.
+        server.on('tlsClientError', (err, socket) => reportH2(socket, err, 'handshake', 'client_handshake'));
+        server.on('sessionError', (err, session) => reportH2(session?.socket, err));
+        server.on('clientError', (err, socket) => reportH2(socket, err));
+        server.on('error', (err) => reportH2(undefined, err));
+        server.on('session', (session) => {
+            session.on('error', (err) => reportH2(session.socket, err));
+        });
+        h2Servers.set(host, server);
+        return server;
+    }
+    /**
+     * Errors inside an h2 session, reported rather than swallowed.
+     *
+     * Without these the only symptom of a session that never became usable was the *client*
+     * complaining -- "HTTP/2 keepalive ping timed out" -- with nothing on this side saying why, which
+     * is the same blindness the HTTP/1.1 path avoids by reporting handshake failures.
+     */
+    const reportH2 = (socket, reason, what = 'session', kind = 'session') => {
+        const target = targetOf(socket);
+        options.onFailure?.({
+            host: target?.host ?? 'unknown',
+            port: target?.port ?? 0,
+            reason: `h2 ${what}: ${String(reason)}`,
+            kind,
+        });
+    };
+    /**
+     * The h2 twin of `forward`, recording the same exchange.
+     *
+     * Two differences from HTTP/1.1, both protocol rules rather than choices: the method, path and
+     * authority arrive as `:`-prefixed pseudo-headers and have to be rebuilt rather than copied, and
+     * h2 forbids the hop-by-hop headers outright, so passing one through is an error rather than
+     * merely being wrong.
+     */
+    async function forwardH2(stream, headers) {
+        // `session` is optional on the type because a stream outlives a destroyed session; a stream
+        // being served cannot have lost it, but the lookup needs a socket either way.
+        const target = stream.session ? targetOf(stream.session.socket) : undefined;
+        if (!target)
+            throw new Error('decrypted h2 stream arrived on an unknown connection');
+        const startedAt = Date.now();
+        const requestId = randomUUID();
+        const method = String(headers[H2.HTTP2_HEADER_METHOD] ?? 'GET');
+        const path = String(headers[H2.HTTP2_HEADER_PATH] ?? '/');
+        const outbound = {
+            [H2.HTTP2_HEADER_METHOD]: method,
+            [H2.HTTP2_HEADER_PATH]: path,
+            [H2.HTTP2_HEADER_SCHEME]: 'https',
+            [H2.HTTP2_HEADER_AUTHORITY]: String(headers[H2.HTTP2_HEADER_AUTHORITY] ?? `${target.host}:${target.port}`),
+        };
+        const recordableHeaders = {};
+        for (const [name, value] of Object.entries(headers)) {
+            const key = name.toLowerCase();
+            if (key.startsWith(':') || HOP_BY_HOP.has(key) || value === undefined)
+                continue;
+            outbound[key] = value;
+            const recorded = normalizeHeaderValue(value);
+            if (!SECRET_REQUEST_HEADERS.has(key) && recorded !== undefined) {
+                recordableHeaders[key] = recorded;
+            }
+        }
+        const requestBody = new Capture(maxCaptured, budget);
+        const responseBody = new Capture(maxCaptured, budget);
+        const contentEncoding = headerText(normalizeHeaderValue(headers['content-encoding']));
+        let rewrittenBody;
+        const requestStart = {
+            requestId,
+            requestStartedAt: startedAt,
+            host: target.host,
+            port: target.port,
+            method,
+            path,
+            requestHeaders: recordableHeaders,
+            requestBytes: Buffer.alloc(0),
+            requestTruncated: false,
+        };
+        try {
+            await options.onRequestStart?.(requestStart);
+        }
+        catch (err) {
+            // A recorder failure happens before dispatch. Preserve that fact as an incomplete terminal
+            // attempt so a failed append cannot look like a missing request or a successful capture.
+            try {
+                options.onNetExchange?.({
+                    ...requestStart,
+                    requestBody: '',
+                    requestBytes: 0,
+                    status: 0,
+                    responseHeaders: {},
+                    responseBody: '',
+                    responseTruncated: false,
+                    responseComplete: false,
+                    responseError: `request-start recorder failed: ${String(err)}`,
+                    responseBytes: 0,
+                    durationMs: Date.now() - startedAt,
+                });
+            }
+            catch {
+                // The persistence callback failed too; the original failure remains the one surfaced.
+            }
+            throw err;
+        }
+        // Replay answers from the recording and must never reach the origin. The HTTP/1.1 twin has
+        // consulted this hook since interception existed; without the same call here, a run recorded
+        // over HTTP/1.1 and replayed by a client that now negotiates h2 would be forwarded live --
+        // real model calls, on the caller's own credential, during what the operator ran offline.
+        if (options.onRequest) {
+            try {
+                for await (const chunk of stream)
+                    requestBody.add(Buffer.from(chunk));
+            }
+            catch (err) {
+                requestBody.release();
+                responseBody.release();
+                throw err;
+            }
+            const request = {
+                requestId,
+                requestStartedAt: startedAt,
+                host: target.host,
+                port: target.port,
+                method,
+                path,
+                requestHeaders: recordableHeaders,
+                requestBytes: requestBody.buffer(),
+                requestTruncated: requestBody.truncated,
+            };
+            const decision = await options.onRequest(request);
+            if (decision && isInterceptResponse(decision)) {
+                requestBody.release();
+                if (stream.destroyed)
+                    return;
+                stream.respond({ ':status': decision.status, ...(decision.headers ?? {}) });
+                stream.end(decision.body);
+                counters.intercepted += 1;
+                return;
+            }
+            if (decision) {
+                rewrittenBody = decision.outboundBody;
+                applyRewrittenBody(outbound, rewrittenBody);
+            }
+            // The bounded capture size is also the maximum replayable request size: forwarding a
+            // truncated body upstream is worse than refusing clearly, which is what HTTP/1.1 does.
+            if (requestBody.truncated) {
+                requestBody.release();
+                throw new Error(`request exceeded capture limit of ${maxCaptured} bytes`);
+            }
+        }
+        await new Promise((resolve, reject) => {
+            const upstream = upstreamH2(target).request(outbound);
+            let settled = false;
+            const finish = () => {
+                if (settled)
+                    return;
+                settled = true;
+                resolve();
+            };
+            /**
+             * Response state, hoisted so an abandoned exchange is still recorded.
+             *
+             * Same gap the HTTP/1.1 path had: recording happened only in `upstream.on('end')`, so a
+             * client that stopped reading a streaming reply mid-flight left no trace of a request agenticreplay
+             * had already decrypted. `status` stays 0 until the origin answers, which is what tells
+             * `onDecrypted` this one has no response to replay.
+             */
+            let status = 0;
+            let recorded = false;
+            let responseError;
+            const recordableResponse = {};
+            const emit = (abandoned) => {
+                if (recorded)
+                    return;
+                recorded = true;
+                counters.intercepted += 1;
+                // A body agenticreplay cannot decode is still an exchange worth having. `decodeBody` throws
+                // for zstd on a runtime without it -- inside `engines`, and why the repo's own zstd test is
+                // skipped there -- and an exception in this callback would take the process down with the
+                // exchange unrecorded. server.ts already decodes inside a try/catch for the same reason.
+                let recordedRequest;
+                if (rewrittenBody) {
+                    recordedRequest = recordableBody(rewrittenBody);
+                }
+                else {
+                    try {
+                        recordedRequest = decodeBody(requestBody.buffer(), contentEncoding, requestBody.limit);
+                    }
+                    catch (err) {
+                        options.onFailure?.({
+                            host: target.host,
+                            port: target.port,
+                            reason: `request body left opaque: ${String(err)}`,
+                            kind: 'body_opaque',
+                        });
+                        recordedRequest = requestBody.text();
+                    }
+                }
+                const decoded = recordableResponseBody(responseBody, headerText(recordableResponse['content-encoding']), !abandoned);
+                if (decoded.error !== undefined) {
+                    options.onFailure?.({
+                        host: target.host,
+                        port: target.port,
+                        reason: `response body left opaque: ${decoded.error}`,
+                        kind: 'body_opaque',
+                    });
+                }
+                const transformations = [];
+                if (decoded.decodedFrom !== undefined) {
+                    transformations.push({
+                        kind: 'decompression',
+                        location: 'response.body',
+                        rule: 'content-encoding',
+                        count: decoded.decodedFrom.split(',').length,
+                        reason: decoded.decodedFrom,
+                    });
+                }
+                if (contentEncoding !== undefined) {
+                    transformations.push({
+                        kind: 'decompression',
+                        location: 'request.body',
+                        rule: 'content-encoding',
+                        count: contentEncoding.split(',').length,
+                        reason: contentEncoding,
+                    });
+                }
+                transformations.push(...binaryBodyTransformation('request.body', recordedRequest));
+                transformations.push(...binaryBodyTransformation('response.body', decoded.body));
+                try {
+                    options.onNetExchange?.({
+                        requestId,
+                        requestStartedAt: startedAt,
+                        host: target.host,
+                        port: target.port,
+                        method,
+                        path,
+                        requestHeaders: recordableHeaders,
+                        requestBody: recordedRequest,
+                        requestBytes: requestBody.bytes,
+                        requestTruncated: requestBody.truncated,
+                        status,
+                        alpn: 'h2',
+                        responseHeaders: decoded.decodedFrom === undefined
+                            ? recordableResponse
+                            : headersWithoutEncoding(recordableResponse),
+                        responseBody: decoded.body,
+                        ...(decoded.decodedFrom === undefined
+                            ? {}
+                            : { responseDecodedFrom: decoded.decodedFrom }),
+                        responseTruncated: responseBody.truncated,
+                        responseComplete: !abandoned && responseError === undefined && !responseBody.truncated,
+                        ...(responseError === undefined ? {} : { responseError }),
+                        ...(transformations.length === 0 ? {} : { transformations }),
+                        responseBytes: responseBody.bytes,
+                        abandoned,
+                        durationMs: Date.now() - startedAt,
+                    });
+                }
+                finally {
+                    requestBody.release();
+                    responseBody.release();
+                }
+            };
+            /**
+             * The client can go at any point, and every write after that throws.
+             *
+             * `stream.respond` on a destroyed stream raises ERR_HTTP2_INVALID_STREAM synchronously from
+             * inside an upstream event callback, where nothing catches it: the promise is already
+             * constructed, so the throw is an uncaught exception and the proxy exits. Reproduced against
+             * Node 22 with a client RST at 60 ms and an origin answering at 400 ms.
+             */
+            const abandon = () => {
+                emit(true);
+                upstream.destroy();
+                finish();
+            };
+            stream.on('aborted', abandon);
+            stream.on('close', abandon);
+            if (options.onRequest) {
+                // The hook above consumed the body, so replay the bytes it read rather than the stream.
+                upstream.end(rewrittenBody ?? requestBody.buffer());
+            }
+            else {
+                stream.on('data', (chunk) => {
+                    requestBody.add(chunk);
+                    if (!upstream.write(chunk)) {
+                        stream.pause();
+                        upstream.once('drain', () => stream.resume());
+                    }
+                });
+                // Without this, a client that aborts mid-upload never emits `end`, `upstream.end()` is
+                // never called, and the origin waits for a body that will not arrive.
+                stream.on('end', () => upstream.end());
+            }
+            stream.on('error', (err) => {
+                responseError = String(err);
+                emit(false);
+                reject(err);
+            });
+            upstream.on('error', (err) => {
+                responseError = String(err);
+                emit(false);
+                reject(err);
+            });
+            upstream.on('response', (responseHeaders) => {
+                status = Number(responseHeaders[H2.HTTP2_HEADER_STATUS] ?? 0);
+                const downstream = { ':status': status };
+                for (const [name, value] of Object.entries(responseHeaders)) {
+                    const key = name.toLowerCase();
+                    if (key.startsWith(':') || HOP_BY_HOP.has(key) || value === undefined)
+                        continue;
+                    downstream[key] = value;
+                    const recorded = normalizeHeaderValue(value);
+                    if (!SECRET_RESPONSE_HEADERS.has(key) && recorded !== undefined) {
+                        recordableResponse[key] = recorded;
+                    }
+                }
+                if (stream.destroyed) {
+                    abandon();
+                    return;
+                }
+                stream.respond(downstream);
+                // Tee, never buffer, for the same reason as HTTP/1.1: a model reply arrives over seconds
+                // and the agent renders it as it lands.
+                upstream.on('data', (chunk) => {
+                    responseBody.add(chunk);
+                    if (stream.destroyed) {
+                        abandon();
+                        return;
+                    }
+                    if (!stream.write(chunk)) {
+                        // `drain` never fires on a destroyed stream, so a client that goes mid-response would
+                        // otherwise leave upstream paused for good and the exchange never recorded.
+                        upstream.pause();
+                        stream.once('drain', () => upstream.resume());
+                    }
+                });
+                upstream.on('end', () => {
+                    if (settled)
+                        return;
+                    // Recorded before the stream is closed out, so the `close` listener above cannot win the
+                    // race and file the same exchange as abandoned.
+                    emit(false);
+                    if (!stream.destroyed)
+                        stream.end();
+                    finish();
+                });
+            });
+        });
+    }
+    /** The negotiated protocol, looked up through the TLS wrapper the server put in place. */
+    const alpnOf = (socket) => {
+        let cursor = socket;
+        for (let depth = 0; depth < 4 && typeof cursor === 'object' && cursor !== null; depth += 1) {
+            const value = cursor.alpnProtocol;
+            if (typeof value === 'string')
+                return value;
+            cursor = cursor._parent;
+        }
+        return undefined;
+    };
+    function contextFor(host) {
+        const cached = contexts.get(host);
+        if (cached)
+            return cached;
+        const issued = options.ca.issue(host);
+        const context = createSecureContext({ key: issued.keyPem, cert: issued.certPem });
+        contexts.set(host, context);
+        return context;
+    }
+    async function forward(req, res) {
+        const target = targetOf(req.socket);
+        if (!target)
+            throw new Error('decrypted request arrived on an unknown connection');
+        const startedAt = Date.now();
+        const requestId = randomUUID();
+        const path = req.url ?? '/';
+        const outboundHeaders = {};
+        const recordableHeaders = {};
+        for (const [name, value] of Object.entries(req.headers)) {
+            const key = name.toLowerCase();
+            if (HOP_BY_HOP.has(key) || value === undefined)
+                continue;
+            outboundHeaders[name] = value;
+            const recorded = normalizeHeaderValue(value);
+            if (!SECRET_REQUEST_HEADERS.has(key) && recorded !== undefined) {
+                recordableHeaders[key] = recorded;
+            }
+        }
+        // Node lower-cases every incoming header name, so this replaces the client's own `host`
+        // rather than adding a second one. Forwarded as the client wrote it, because virtual hosting
+        // depends on it; the CONNECT target is the fallback for an HTTP/1.0 client that sent none.
+        outboundHeaders.host = req.headers.host ?? target.host;
+        const requestBody = new Capture(maxCaptured, budget);
+        let rewrittenBody;
+        const requestStart = {
+            requestId,
+            requestStartedAt: startedAt,
+            host: target.host,
+            port: target.port,
+            method: req.method ?? 'GET',
+            path,
+            requestHeaders: recordableHeaders,
+            requestBytes: Buffer.alloc(0),
+            requestTruncated: false,
+        };
+        try {
+            await options.onRequestStart?.(requestStart);
+        }
+        catch (err) {
+            try {
+                options.onNetExchange?.({
+                    ...requestStart,
+                    requestBody: '',
+                    requestBytes: 0,
+                    status: 0,
+                    responseHeaders: {},
+                    responseBody: '',
+                    responseTruncated: false,
+                    responseComplete: false,
+                    responseError: `request-start recorder failed: ${String(err)}`,
+                    responseBytes: 0,
+                    durationMs: Date.now() - startedAt,
+                });
+            }
+            catch {
+                // Preserve the recorder failure when terminal evidence cannot itself be persisted.
+            }
+            throw err;
+        }
+        // Replay has to decide before opening an origin connection. Buffer only when that hook is in
+        // use; the recording path below retains the original streaming behaviour and bounded capture.
+        if (options.onRequest) {
+            try {
+                for await (const chunk of req)
+                    requestBody.add(Buffer.from(chunk));
+            }
+            catch (err) {
+                requestBody.release();
+                throw err;
+            }
+            const request = {
+                requestId,
+                requestStartedAt: startedAt,
+                host: target.host,
+                port: target.port,
+                method: req.method ?? 'GET',
+                path,
+                requestHeaders: recordableHeaders,
+                requestBytes: requestBody.buffer(),
+                requestTruncated: requestBody.truncated,
+            };
+            const decision = await options.onRequest(request);
+            if (decision && isInterceptResponse(decision)) {
+                res.writeHead(decision.status, decision.headers ?? {});
+                res.end(decision.body);
+                counters.intercepted += 1;
+                requestBody.release();
+                return;
+            }
+            if (decision) {
+                rewrittenBody = decision.outboundBody;
+                applyRewrittenBody(outboundHeaders, rewrittenBody);
+            }
+        }
+        const upstream = httpsRequest({
+            host: target.host,
+            port: target.port,
+            method: req.method ?? 'GET',
+            path,
+            headers: outboundHeaders,
+            agent,
+            // SNI is a name, never an address.
+            ...(isIP(target.host) === 0 ? { servername: target.host } : {}),
+            ...(originTrust ? { ca: originTrust } : {}),
+        });
+        if (options.onRequest) {
+            // The hook consumed the request. The bounded size is deliberately also the maximum replay
+            // request size; sending a truncated body upstream would be worse than a clear failure.
+            if (requestBody.truncated) {
+                upstream.destroy(new Error(`request exceeded capture limit of ${maxCaptured} bytes`));
+            }
+            else {
+                upstream.end(rewrittenBody ?? requestBody.buffer());
+            }
+        }
+        else {
+            req.on('data', (chunk) => requestBody.add(chunk));
+            req.pipe(upstream);
+        }
+        const finished = new Promise((resolve, reject) => {
+            /**
+             * What has been read so far, hoisted out of the response handler so that an exchange the
+             * client walks away from is still recorded.
+             *
+             * Streaming is the normal case for a model API, and a harness that stops reading the moment
+             * it has what it needs leaves the rest of the stream on the floor. `onNetExchange` used to
+             * fire only from `end`, so those runs recorded nothing at all: the request had been
+             * decrypted and the response headers were in hand, and the run still reported
+             * `capture.empty` with "the agent never called the proxy" -- the opposite of what happened.
+             * Hermes is the harness that showed it; the shape is not specific to Hermes.
+             */
+            let recorded = false;
+            let status = 0;
+            let responseError;
+            const responseHeaders = {};
+            const responseBody = new Capture(maxCaptured, budget);
+            const emit = (abandoned) => {
+                if (recorded)
+                    return;
+                recorded = true;
+                counters.intercepted += 1;
+                // A body agenticreplay cannot decode is still an exchange worth having, and an exception thrown in
+                // this callback would take the process down with it. Same guard, same reason, as h2.
+                let recordedRequest;
+                if (rewrittenBody) {
+                    recordedRequest = recordableBody(rewrittenBody);
+                }
+                else {
+                    try {
+                        recordedRequest = decodeBody(requestBody.buffer(), typeof req.headers['content-encoding'] === 'string'
+                            ? req.headers['content-encoding']
+                            : undefined, requestBody.limit);
+                    }
+                    catch (err) {
+                        options.onFailure?.({
+                            host: target.host,
+                            port: target.port,
+                            reason: `request body left opaque: ${String(err)}`,
+                            kind: 'body_opaque',
+                        });
+                        recordedRequest = requestBody.text();
+                    }
+                }
+                const decoded = recordableResponseBody(responseBody, headerText(responseHeaders['content-encoding']), !abandoned);
+                if (decoded.error !== undefined) {
+                    options.onFailure?.({
+                        host: target.host,
+                        port: target.port,
+                        reason: `response body left opaque: ${decoded.error}`,
+                        kind: 'body_opaque',
+                    });
+                }
+                const transformations = [];
+                const requestEncoding = typeof req.headers['content-encoding'] === 'string'
+                    ? req.headers['content-encoding']
+                    : undefined;
+                if (decoded.decodedFrom !== undefined) {
+                    transformations.push({
+                        kind: 'decompression',
+                        location: 'response.body',
+                        rule: 'content-encoding',
+                        count: decoded.decodedFrom.split(',').length,
+                        reason: decoded.decodedFrom,
+                    });
+                }
+                if (requestEncoding !== undefined) {
+                    transformations.push({
+                        kind: 'decompression',
+                        location: 'request.body',
+                        rule: 'content-encoding',
+                        count: requestEncoding.split(',').length,
+                        reason: requestEncoding,
+                    });
+                }
+                transformations.push(...binaryBodyTransformation('request.body', recordedRequest));
+                transformations.push(...binaryBodyTransformation('response.body', decoded.body));
+                try {
+                    options.onNetExchange?.({
+                        requestId,
+                        requestStartedAt: startedAt,
+                        host: target.host,
+                        port: target.port,
+                        method: req.method ?? 'GET',
+                        path,
+                        requestHeaders: recordableHeaders,
+                        requestBody: recordedRequest,
+                        requestBytes: requestBody.bytes,
+                        requestTruncated: requestBody.truncated,
+                        status,
+                        alpn: alpnOf(req.socket),
+                        responseHeaders: decoded.decodedFrom === undefined
+                            ? responseHeaders
+                            : headersWithoutEncoding(responseHeaders),
+                        responseBody: decoded.body,
+                        ...(decoded.decodedFrom === undefined
+                            ? {}
+                            : { responseDecodedFrom: decoded.decodedFrom }),
+                        responseTruncated: responseBody.truncated,
+                        responseComplete: !abandoned && responseError === undefined && !responseBody.truncated,
+                        ...(responseError === undefined ? {} : { responseError }),
+                        ...(transformations.length === 0 ? {} : { transformations }),
+                        responseBytes: responseBody.bytes,
+                        abandoned,
+                        durationMs: Date.now() - startedAt,
+                    });
+                }
+                finally {
+                    requestBody.release();
+                    responseBody.release();
+                }
+            };
+            /** The client is gone: keep what was read, stop pulling from the origin, and settle. */
+            const abandon = () => {
+                emit(true);
+                upstream.destroy();
+                resolve();
+            };
+            res.on('close', () => {
+                if (!recorded)
+                    abandon();
+            });
+            upstream.on('error', (err) => {
+                // A client that has already left is not an upstream failure to report. Asked of `res`
+                // only: `req` destroys itself once its body has been read, so a request with no body has
+                // `req.destroyed` set long before anything went wrong, and reading it here turned every
+                // upstream failure -- an origin certificate agenticreplay refuses to trust, most of all -- into a
+                // silent abandonment with no 502 for the client to see.
+                if (res.destroyed) {
+                    responseError = String(err);
+                    abandon();
+                    return;
+                }
+                responseError = String(err);
+                emit(false);
+                reject(err);
+            });
+            upstream.on('response', (originRes) => {
+                const outHeaders = {};
+                const responseHeaderPairs = originRes.rawHeaders;
+                for (let index = 0; index < responseHeaderPairs.length; index += 2) {
+                    const name = responseHeaderPairs[index];
+                    const value = responseHeaderPairs[index + 1];
+                    const key = name.toLowerCase();
+                    if (HOP_BY_HOP.has(key))
+                        continue;
+                    const previousForwarded = outHeaders[name];
+                    outHeaders[name] =
+                        previousForwarded === undefined
+                            ? value
+                            : Array.isArray(previousForwarded)
+                                ? [...previousForwarded, value]
+                                : [previousForwarded, value];
+                    if (!SECRET_RESPONSE_HEADERS.has(key)) {
+                        const previousRecorded = responseHeaders[key];
+                        responseHeaders[key] =
+                            previousRecorded === undefined
+                                ? value
+                                : Array.isArray(previousRecorded)
+                                    ? [...previousRecorded, value]
+                                    : [previousRecorded, value];
+                    }
+                }
+                status = originRes.statusCode ?? 0;
+                if (res.destroyed) {
+                    abandon();
+                    return;
+                }
+                res.writeHead(originRes.statusCode ?? 502, outHeaders);
+                // Tee, never buffer. A model reply arrives over seconds and the agent renders it as it
+                // lands; reading it to completion first would make every turn appear to hang.
+                originRes.on('data', (chunk) => {
+                    responseBody.add(chunk);
+                    if (res.destroyed) {
+                        abandon();
+                        return;
+                    }
+                    if (!res.write(chunk)) {
+                        originRes.pause();
+                        // `drain` never fires on a destroyed response, so a client that goes mid-stream would
+                        // otherwise leave the origin paused for good and the exchange unrecorded.
+                        res.once('drain', () => originRes.resume());
+                    }
+                });
+                /**
+                 * The origin going away and the client going away arrive on the same two events here, and
+                 * they need opposite handling.
+                 *
+                 * If the client left, this is abandonment: keep the prefix, stop pulling from the origin,
+                 * settle. If the *origin* died, the client is still connected and waiting for a stream
+                 * agenticreplay has already started forwarding -- and abandoning there settles this promise, so the
+                 * caller's `.catch`, the only thing that ends the client's response, never runs. The agent
+                 * then waits for a continuation that will never come. `originRes.on('aborted', abandon)`
+                 * did exactly that: a crashing origin or a dropped network hung every in-flight call on
+                 * this path, where before it produced a prompt answer.
+                 *
+                 * Both are recorded, because a response the origin cut short is still evidence. Only the
+                 * first is `abandoned`: that field says the agent stopped reading, and here it did not.
+                 *
+                 * The h2 path needs none of this -- there `aborted` is on the client's own stream and the
+                 * origin reports through `upstream.on('error')`, so the two are already separate objects.
+                 */
+                const originGone = (err) => {
+                    if (res.destroyed) {
+                        abandon();
+                        return;
+                    }
+                    responseError = String(err);
+                    emit(false);
+                    reject(err);
+                };
+                originRes.on('aborted', () => originGone(new Error('origin aborted mid-response')));
+                originRes.on('error', originGone);
+                originRes.on('end', () => {
+                    if (recorded)
+                        return;
+                    // Recorded before the response is closed out, so that the `close` listener above cannot
+                    // win the race and file the same exchange as abandoned.
+                    emit(false);
+                    res.end();
+                    resolve();
+                });
+            });
+        });
+        await finished;
+    }
+    function intercept(clientSocket, head, target) {
+        clientSocket.write('HTTP/1.1 200 Connection Established\r\n\r\n');
+        if (head.length > 0)
+            clientSocket.unshift(head);
+        // Tagged before the handover, because the server wraps this socket in a TLSSocket of its own
+        // and the request that comes back out carries the wrapper, not this.
+        clientSocket[TARGET] = target;
+        serverFor(target.host).emit('connection', clientSocket);
+    }
+    function tunnel(clientSocket, head, target) {
+        const startedAt = Date.now();
+        let bytesToOrigin = head.length;
+        let bytesToClient = 0;
+        let settled = false;
+        // Counted at the decision, not at the close. The number an operator wants is "how many
+        // connections did agenticreplay refuse to look inside", and a connection still open when the run ends
+        // was refused just as firmly as one that closed.
+        counters.tunnelled += 1;
+        const origin = netConnect(target.port, target.host);
+        open.add(origin);
+        const finish = (error) => {
+            if (settled)
+                return;
+            settled = true;
+            options.onTunnel?.({
+                host: target.host,
+                port: target.port,
+                bytesToOrigin,
+                bytesToClient,
+                durationMs: Date.now() - startedAt,
+                ...(error === undefined ? {} : { error }),
+            });
+        };
+        origin.on('connect', () => {
+            clientSocket.write('HTTP/1.1 200 Connection Established\r\n\r\n');
+            if (head.length > 0)
+                origin.write(head);
+            // Byte counts only. Nothing here inspects, decodes or stores what passes through — that is
+            // the entire promise a tunnel makes.
+            clientSocket.on('data', (chunk) => void (bytesToOrigin += chunk.length));
+            origin.on('data', (chunk) => void (bytesToClient += chunk.length));
+            clientSocket.pipe(origin);
+            origin.pipe(clientSocket);
+        });
+        origin.on('error', (err) => {
+            if (!clientSocket.destroyed && !settled) {
+                clientSocket.write('HTTP/1.1 502 Bad Gateway\r\n\r\n');
+            }
+            finish(String(err));
+            clientSocket.destroy();
+            origin.destroy();
+        });
+        origin.on('close', () => {
+            open.delete(origin);
+            finish();
+            clientSocket.destroy();
+        });
+        clientSocket.on('error', () => origin.destroy());
+        clientSocket.on('close', () => origin.destroy());
+    }
+    server.on('connect', (req, clientSocket, head) => {
+        open.add(clientSocket);
+        clientSocket.on('close', () => open.delete(clientSocket));
+        clientSocket.on('error', () => clientSocket.destroy());
+        const target = parseTarget(req.url ?? '');
+        if (!target) {
+            clientSocket.write('HTTP/1.1 400 Bad Request\r\n\r\n');
+            clientSocket.destroy();
+            return;
+        }
+        if (policy.allows(target.host, target.port)) {
+            intercept(clientSocket, head, target);
+        }
+        else {
+            tunnel(clientSocket, head, target);
+        }
+    });
+    return {
+        policy,
+        close: () => {
+            agent.destroy();
+            for (const session of h2Upstreams.values())
+                session.destroy();
+            h2Upstreams.clear();
+            for (const server of h2Servers.values())
+                server.close();
+            h2Servers.clear();
+            for (const socket of open)
+                socket.destroy();
+            open.clear();
+        },
+    };
+}
+/** A bounded copy of a stream, so recording a large upload cannot exhaust memory. */
+class Capture {
+    limit;
+    budget;
+    #chunks = [];
+    #captured = 0;
+    #total = 0;
+    #truncated = false;
+    #released = false;
+    constructor(limit, budget) {
+        this.limit = limit;
+        this.budget = budget;
+    }
+    add(chunk) {
+        this.#total += chunk.length;
+        const room = this.limit - this.#captured;
+        if (room <= 0) {
+            this.#truncated = true;
+            return;
+        }
+        const reserved = this.budget.reserve(Math.min(chunk.length, room));
+        if (reserved < chunk.length) {
+            if (reserved > 0)
+                this.#chunks.push(chunk.subarray(0, reserved));
+            this.#captured += reserved;
+            this.#truncated = true;
+            return;
+        }
+        this.#chunks.push(chunk);
+        this.#captured += chunk.length;
+    }
+    /**
+     * The captured bytes as something a trace can hold.
+     *
+     * Text when the bytes are text, and base64 behind a marker when they are not. `toString('utf8')`
+     * on a binary body replaces every invalid sequence with U+FFFD and is not reversible: a Connect
+     * protobuf body came back with 974 replacement characters in 8,459 bytes, which is enough to
+     * make the payload undecodable while still looking like it was captured. The round-trip test is
+     * what tells the two cases apart.
+     */
+    text() {
+        return recordableBody(Buffer.concat(this.#chunks));
+    }
+    buffer() {
+        return Buffer.concat(this.#chunks);
+    }
+    get truncated() {
+        return this.#truncated;
+    }
+    get bytes() {
+        return this.#total;
+    }
+    release() {
+        if (this.#released)
+            return;
+        this.#released = true;
+        this.budget.release(this.#captured);
+    }
+}
+//# sourceMappingURL=intercept.js.map