agenticreplay 0.1.0 → 0.1.2

package/packages/cli/dist/args.d.ts

@@ -0,0 +1,57 @@
+/**
+ * Argument parsing.
+ *
+ * Hand-rolled on purpose: a debugger you install to diagnose a broken environment should not drag
+ * in a dependency tree of its own. The one rule worth stating is that everything after a bare
+ * `--` belongs to the child agent, never to us — `agenticreplay record claude -- -p "fix the test"` has to
+ * forward those bytes untouched.
+ */
+export type FlagValue = string | number | boolean;
+export interface ParsedArgs {
+    command: string;
+    positionals: string[];
+    flags: Record<string, FlagValue>;
+    /** Everything after a bare `--`, forwarded verbatim to the agent. */
+    passthrough: string[];
+    /**
+     * Flags that became `true` only because nothing followed them.
+     *
+     * Recorded rather than inferred from the value: `--model=true` is also `true`, and telling a
+     * person their value is missing when they typed one is its own kind of wrong.
+     */
+    missingValue: Set<string>;
+    /** Flags given more than once with values that disagree. The last one silently won. */
+    conflicting: Set<string>;
+    /** Read a flag as a comma-separated list. */
+    list(name: string): string[];
+    has(name: string): boolean;
+    str(name: string, fallback?: string): string | undefined;
+    num(name: string, fallback?: number): number | undefined;
+    bool(name: string, fallback?: boolean): boolean;
+}
+/**
+ * Flags that never take a value.
+ *
+ * Without this list any flag followed by a non-flag token swallowed it, so the flag read as false
+ * *and* the positional vanished. `agenticreplay replay --worktree last` then restored the recorded tree over
+ * the working directory — the exact opposite of what `--worktree` promises — and
+ * `agenticreplay record --tls-intercept codex` turned interception off while losing the agent name, so
+ * record auto-detected and could capture a different harness. Neither said anything.
+ *
+ * A list rather than a heuristic, because the alternative is guessing from the shape of the next
+ * token, and `agenticreplay compare --models last` would guess wrong. `--flag=value` and `--no-flag` still
+ * work for these; they are handled before this point.
+ */
+export declare const VALUELESS: Set<string>;
+/**
+ * Flags read as a number.
+ *
+ * The counterpart to `VALUELESS`, and needed for the same reason: `num()` returns its fallback for
+ * anything it cannot parse, so `--from four` replayed the whole run instead of forking at a
+ * checkpoint, and `--port eighty` bound a random port and printed it as though that were the
+ * request. Knowing which flags are numeric is what lets a value be checked once, up front, rather
+ * than nine times by hand — which is what `agenticreplay gc --keep` had been doing alone.
+ */
+export declare const NUMERIC: Set<string>;
+export declare function parseArgs(argv: string[]): ParsedArgs;
+//# sourceMappingURL=args.d.ts.map

package/packages/cli/dist/args.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"args.d.ts","sourceRoot":"","sources":["../src/args.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,MAAM,MAAM,SAAS,GAAG,MAAM,GAAG,MAAM,GAAG,OAAO,CAAC;AAElD,MAAM,WAAW,UAAU;IACzB,OAAO,EAAE,MAAM,CAAC;IAChB,WAAW,EAAE,MAAM,EAAE,CAAC;IACtB,KAAK,EAAE,MAAM,CAAC,MAAM,EAAE,SAAS,CAAC,CAAC;IACjC,qEAAqE;IACrE,WAAW,EAAE,MAAM,EAAE,CAAC;IACtB;;;;;OAKG;IACH,YAAY,EAAE,GAAG,CAAC,MAAM,CAAC,CAAC;IAC1B,uFAAuF;IACvF,WAAW,EAAE,GAAG,CAAC,MAAM,CAAC,CAAC;IACzB,6CAA6C;IAC7C,IAAI,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,EAAE,CAAC;IAC7B,GAAG,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC;IAC3B,GAAG,CAAC,IAAI,EAAE,MAAM,EAAE,QAAQ,CAAC,EAAE,MAAM,GAAG,MAAM,GAAG,SAAS,CAAC;IACzD,GAAG,CAAC,IAAI,EAAE,MAAM,EAAE,QAAQ,CAAC,EAAE,MAAM,GAAG,MAAM,GAAG,SAAS,CAAC;IACzD,IAAI,CAAC,IAAI,EAAE,MAAM,EAAE,QAAQ,CAAC,EAAE,OAAO,GAAG,OAAO,CAAC;CACjD;AAED;;;;;;;;;;;;GAYG;AACH,eAAO,MAAM,SAAS,aAqCpB,CAAC;AAEH;;;;;;;;GAQG;AACH,eAAO,MAAM,OAAO,aAQlB,CAAC;AAeH,wBAAgB,SAAS,CAAC,IAAI,EAAE,MAAM,EAAE,GAAG,UAAU,CAwFpD"}

package/packages/cli/dist/args.js

@@ -0,0 +1,180 @@
+/**
+ * Argument parsing.
+ *
+ * Hand-rolled on purpose: a debugger you install to diagnose a broken environment should not drag
+ * in a dependency tree of its own. The one rule worth stating is that everything after a bare
+ * `--` belongs to the child agent, never to us — `agenticreplay record claude -- -p "fix the test"` has to
+ * forward those bytes untouched.
+ */
+/**
+ * Flags that never take a value.
+ *
+ * Without this list any flag followed by a non-flag token swallowed it, so the flag read as false
+ * *and* the positional vanished. `agenticreplay replay --worktree last` then restored the recorded tree over
+ * the working directory — the exact opposite of what `--worktree` promises — and
+ * `agenticreplay record --tls-intercept codex` turned interception off while losing the agent name, so
+ * record auto-detected and could capture a different harness. Neither said anything.
+ *
+ * A list rather than a heuristic, because the alternative is guessing from the shape of the next
+ * token, and `agenticreplay compare --models last` would guess wrong. `--flag=value` and `--no-flag` still
+ * work for these; they are handled before this point.
+ */
+export const VALUELESS = new Set([
+    'remote',
+    'ui',
+    'json',
+    'loose',
+    'in-place',
+    'worktree',
+    'trace',
+    'fs',
+    'shell',
+    'agent-spans',
+    'ci',
+    'verbose',
+    'color',
+    'dry-run',
+    'drop-fs',
+    'tls-intercept',
+    'version',
+    'help',
+    // Added with the flags themselves and, the first time, not: `agenticreplay replay --quiet run_a1b2c3`
+    // parsed as `quiet="run_a1b2c3"` with no positional left, so replay fell back to `last` and
+    // reproduced a different run than the one asked for, in silence. `flags.test.ts` now reads the
+    // source and holds this list to every flag the code treats as a boolean, so the next one added
+    // without an entry here fails a test rather than a user.
+    'quiet',
+    'full',
+    'serialize',
+    // `-h` parses to the body "h" (short flags take one dash), and main.ts reads it with
+    // args.bool('h'). Found by the derived invariant test the day it was written, which is the
+    // point of deriving it — the hand-written list had missed this one too.
+    'h',
+    // push / pull: "store this even though the scan found something", and "replace the local copy".
+    // Missing here it was VALUE-TAKING, so `agenticreplay push --force run_abc` ate the selector and pushed
+    // the workspace's NEWEST run to the gateway instead, without ?force=1, reporting success under
+    // the other run's name. See the invariant test below for why the list is now derived rather
+    // than trusted.
+    'force',
+]);
+/**
+ * Flags read as a number.
+ *
+ * The counterpart to `VALUELESS`, and needed for the same reason: `num()` returns its fallback for
+ * anything it cannot parse, so `--from four` replayed the whole run instead of forking at a
+ * checkpoint, and `--port eighty` bound a random port and printed it as though that were the
+ * request. Knowing which flags are numeric is what lets a value be checked once, up front, rather
+ * than nine times by hand — which is what `agenticreplay gc --keep` had been doing alone.
+ */
+export const NUMERIC = new Set([
+    'from',
+    'to',
+    'port',
+    'keep',
+    'limit',
+    'max-body-bytes',
+    'max-buffered-bytes',
+]);
+function coerce(raw) {
+    if (raw === 'true')
+        return true;
+    if (raw === 'false')
+        return false;
+    // Only a complete numeric literal becomes a number; "5.3-flash" must stay a string.
+    if (/^-?\d+(\.\d+)?$/.test(raw))
+        return Number(raw);
+    return raw;
+}
+/** A token is a flag only if it is not a negative number: `--from -1` passes -1 as a value. */
+function isFlag(token) {
+    return token.startsWith('-') && token !== '-' && !/^-?\d+(\.\d+)?$/.test(token);
+}
+export function parseArgs(argv) {
+    const flags = {};
+    const missingValue = new Set();
+    const conflicting = new Set();
+    /** Record an assignment, noticing when it silently overwrites a different one. */
+    const set = (name, value) => {
+        if (name in flags && flags[name] !== value)
+            conflicting.add(name);
+        flags[name] = value;
+    };
+    const positionals = [];
+    let passthrough = [];
+    const separator = argv.indexOf('--');
+    const own = separator === -1 ? argv.slice() : argv.slice(0, separator);
+    if (separator !== -1)
+        passthrough = argv.slice(separator + 1);
+    for (let i = 0; i < own.length; i += 1) {
+        const token = own[i];
+        if (!isFlag(token)) {
+            positionals.push(token);
+            continue;
+        }
+        const isLong = token.startsWith('--');
+        const body = isLong ? token.slice(2) : token.slice(1);
+        const eq = body.indexOf('=');
+        if (eq !== -1) {
+            const name = body.slice(0, eq);
+            set(name, coerce(body.slice(eq + 1)));
+            // An explicit value, however wrong its shape, was given. It is not missing.
+            missingValue.delete(name);
+            continue;
+        }
+        if (isLong && body.startsWith('no-')) {
+            const name = body.slice(3);
+            set(name, false);
+            missingValue.delete(name);
+            continue;
+        }
+        const next = own[i + 1];
+        if (!VALUELESS.has(body) && next !== undefined && !isFlag(next)) {
+            set(body, coerce(next));
+            missingValue.delete(body);
+            i += 1;
+        }
+        else {
+            set(body, true);
+            if (!VALUELESS.has(body))
+                missingValue.add(body);
+        }
+    }
+    const command = positionals.shift() ?? 'help';
+    return {
+        command,
+        positionals,
+        flags,
+        passthrough,
+        missingValue,
+        conflicting,
+        list(name) {
+            const v = flags[name];
+            if (v === undefined || typeof v === 'boolean')
+                return [];
+            return String(v)
+                .split(',')
+                .map((s) => s.trim())
+                .filter(Boolean);
+        },
+        has(name) {
+            return name in flags;
+        },
+        str(name, fallback) {
+            const v = flags[name];
+            return v === undefined || typeof v === 'boolean' ? fallback : String(v);
+        },
+        num(name, fallback) {
+            const v = flags[name];
+            if (typeof v === 'number')
+                return v;
+            if (typeof v === 'string' && /^-?\d+(\.\d+)?$/.test(v))
+                return Number(v);
+            return fallback;
+        },
+        bool(name, fallback = false) {
+            const v = flags[name];
+            return typeof v === 'boolean' ? v : fallback;
+        },
+    };
+}
+//# sourceMappingURL=args.js.map

package/packages/cli/dist/args.js.map

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

package/packages/cli/dist/attach.d.ts

@@ -0,0 +1,48 @@
+export interface AdvertiseRequest {
+    /** The address the proxy is listening on. */
+    bind: string;
+    /** The port it actually bound, which is not the advertised one behind a port mapping. */
+    port: number;
+    /** An explicit host, optionally with its own `:port`, overriding both of the above. */
+    advertise?: string;
+}
+/**
+ * The origin a remote agent should be pointed at.
+ *
+ * `0.0.0.0` is a statement about listening, not an address: an agent handed `http://0.0.0.0:8080`
+ * fails in a way that looks like agenticreplay is broken rather than like the invocation was incomplete. So
+ * a wildcard bind must be paired with the name the sandbox actually reaches this machine by, and
+ * refusing is the only honest option — agenticreplay cannot discover that name, and guessing one produces a
+ * run that records nothing.
+ */
+export declare function advertisedUrl(req: AdvertiseRequest): string;
+export interface AttachRequest {
+    /** Where the remote agent should send its model traffic. */
+    proxyUrl: string;
+    /** Variables the named adapter would have set, already pointed at `proxyUrl`. */
+    adapterEnv: Record<string, string>;
+    /** Present only when the run is intercepting. Paths are local, and are only for the copy step. */
+    ca?: {
+        certPath: string;
+        bundlePath: string;
+    };
+    /** Where the CA will live *in the sandbox* once copied. Every printed path uses this. */
+    remoteCaPath?: string;
+}
+/**
+ * The variables to set on the far side.
+ *
+ * The CA paths are the remote ones throughout. Printing this machine's path is the subtle failure
+ * this function exists to prevent: the block runs cleanly, every variable is set, and the agent
+ * trusts nothing — because the file those variables name is not there.
+ */
+export declare function attachExports(req: AttachRequest): Record<string, string>;
+/**
+ * The block the operator pastes into the sandbox.
+ *
+ * The copy step comes first because the export block references a file that has to exist by the
+ * time the agent starts, and an operator who pastes the second half alone gets an agent that
+ * cannot verify the proxy it was just told to trust.
+ */
+export declare function attachInstructions(req: AttachRequest): string[];
+//# sourceMappingURL=attach.d.ts.map

package/packages/cli/dist/attach.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"attach.d.ts","sourceRoot":"","sources":["../src/attach.ts"],"names":[],"mappings":"AAsCA,MAAM,WAAW,gBAAgB;IAC/B,6CAA6C;IAC7C,IAAI,EAAE,MAAM,CAAC;IACb,yFAAyF;IACzF,IAAI,EAAE,MAAM,CAAC;IACb,uFAAuF;IACvF,SAAS,CAAC,EAAE,MAAM,CAAC;CACpB;AAED;;;;;;;;GAQG;AACH,wBAAgB,aAAa,CAAC,GAAG,EAAE,gBAAgB,GAAG,MAAM,CAkB3D;AA2BD,MAAM,WAAW,aAAa;IAC5B,4DAA4D;IAC5D,QAAQ,EAAE,MAAM,CAAC;IACjB,iFAAiF;IACjF,UAAU,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IACnC,kGAAkG;IAClG,EAAE,CAAC,EAAE;QAAE,QAAQ,EAAE,MAAM,CAAC;QAAC,UAAU,EAAE,MAAM,CAAA;KAAE,CAAC;IAC9C,yFAAyF;IACzF,YAAY,CAAC,EAAE,MAAM,CAAC;CACvB;AAED;;;;;;GAMG;AACH,wBAAgB,aAAa,CAAC,GAAG,EAAE,aAAa,GAAG,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CA4BxE;AAOD;;;;;;GAMG;AACH,wBAAgB,kBAAkB,CAAC,GAAG,EAAE,aAAa,GAAG,MAAM,EAAE,CAgB/D"}

package/packages/cli/dist/attach.js

@@ -0,0 +1,153 @@
+import { isIP } from 'node:net';
+/**
+ * Recording an agent agenticreplay does not launch.
+ *
+ * Every other capture path here ends in a child process: an adapter builds an environment and agenticreplay
+ * spawns the agent inside it. That is the design, and it has exactly one boundary it cannot cross
+ * — an agent that is not on this machine. A bot on a VPS, an agent inside a dev container or a
+ * cloud sandbox, a harness someone else's CI runs: there is no process to spawn, so there is no
+ * environment to build.
+ *
+ * AgenticReplay can still be reachable, and can still say precisely what to set. The proxy already accepts
+ * a bind address. What was missing is this half: the block of variables the operator pastes on the
+ * far side, which has to be right or the run comes back empty with nothing to explain why.
+ *
+ * Everything here is pure and returns data rather than printing, because the failure mode being
+ * guarded against is a *wrong instruction* — a path that exists here and not there, a wildcard
+ * address nothing can dial — and those are only testable if the strings are values.
+ */
+/**
+ * Variable names whose values must never be printed.
+ *
+ * The block goes to a terminal, and a terminal is scrollback, a screen share, a pasted ticket and
+ * a CI log. Over-matching here costs a line the operator did not need; under-matching prints
+ * somebody's API key, so the pattern is deliberately broad.
+ *
+ * Omitting them is also simply correct. The agent in the sandbox already holds whatever credential
+ * it authenticates with, and agenticreplay forwards it upstream untouched. Exporting the local machine's
+ * key would leak it; exporting the `agenticreplay-recorded` placeholder an adapter substitutes when the
+ * local environment has none would be worse — it would overwrite a working key over there and turn
+ * a functioning setup into a 401.
+ */
+const CREDENTIAL_LIKE = /(?:KEY|TOKEN|SECRET|PASSWORD|CREDENTIALS?)$/;
+/** Bind addresses that mean "every interface", and so mean nothing as a destination. */
+const WILDCARD_BINDS = new Set(['0.0.0.0', '::', '[::]', '*']);
+/**
+ * The origin a remote agent should be pointed at.
+ *
+ * `0.0.0.0` is a statement about listening, not an address: an agent handed `http://0.0.0.0:8080`
+ * fails in a way that looks like agenticreplay is broken rather than like the invocation was incomplete. So
+ * a wildcard bind must be paired with the name the sandbox actually reaches this machine by, and
+ * refusing is the only honest option — agenticreplay cannot discover that name, and guessing one produces a
+ * run that records nothing.
+ */
+export function advertisedUrl(req) {
+    if (req.advertise !== undefined && req.advertise.trim() !== '') {
+        const host = req.advertise
+            .trim()
+            .replace(/^https?:\/\//, '')
+            .replace(/\/+$/, '');
+        // A host the operator wrote a port into is used as-is: behind a port-mapped container the
+        // reachable port is not the one agenticreplay bound, and agenticreplay has no way to learn the mapping.
+        return `http://${hasPort(host) ? host : `${bracketed(host)}:${req.port}`}`;
+    }
+    if (WILDCARD_BINDS.has(req.bind)) {
+        throw new Error(`--bind ${req.bind} listens on every interface, which is not an address an agent can ` +
+            'connect to. Add --advertise <host> naming how the sandbox reaches this machine, ' +
+            'e.g. --advertise 10.0.0.5 or --advertise host.docker.internal.');
+    }
+    return `http://${bracketed(req.bind)}:${req.port}`;
+}
+/** A bare IPv6 literal is not a URL host until it is bracketed. */
+function bracketed(host) {
+    if (host.startsWith('['))
+        return host;
+    return isIP(host) === 6 ? `[${host}]` : host;
+}
+/**
+ * Does this host already carry its own port?
+ *
+ * An IPv6 literal is mostly colons, so the last one says nothing on its own: `fd00::1` ends in
+ * `:1`, which reads as a port and is not one. Answering wrongly drops the real port and hands the
+ * sandbox `http://fd00::1`, which means port 80 and connects to nothing.
+ *
+ * A bracketed host is unambiguous — anything after the `]` is a port. An unbracketed one carries a
+ * port only if it has exactly one colon, because more than one makes it an address rather than a
+ * host-and-port.
+ */
+function hasPort(host) {
+    const close = host.lastIndexOf(']');
+    if (close !== -1)
+        return /^:\d+$/.test(host.slice(close + 1));
+    const first = host.indexOf(':');
+    if (first === -1 || first !== host.lastIndexOf(':'))
+        return false;
+    return /^\d+$/.test(host.slice(first + 1));
+}
+/**
+ * The variables to set on the far side.
+ *
+ * The CA paths are the remote ones throughout. Printing this machine's path is the subtle failure
+ * this function exists to prevent: the block runs cleanly, every variable is set, and the agent
+ * trusts nothing — because the file those variables name is not there.
+ */
+export function attachExports(req) {
+    const env = {};
+    for (const [name, value] of Object.entries(req.adapterEnv)) {
+        if (CREDENTIAL_LIKE.test(name))
+            continue;
+        env[name] = value;
+    }
+    if (!req.ca || !req.remoteCaPath)
+        return env;
+    env.HTTPS_PROXY = req.proxyUrl;
+    env.https_proxy = req.proxyUrl;
+    // One path for all of them, unlike a local run. The bundle exists so an intercepted child keeps
+    // reaching the hosts agenticreplay deliberately does not decrypt; a sandbox that already trusts the
+    // public roots needs only the run CA added, and shipping one file is what makes the copy step a
+    // single line the operator will actually run.
+    for (const name of [
+        'NODE_EXTRA_CA_CERTS',
+        'SSL_CERT_FILE',
+        'REQUESTS_CA_BUNDLE',
+        'CURL_CA_BUNDLE',
+        'AWS_CA_BUNDLE',
+        'DENO_CERT',
+    ]) {
+        env[name] = req.remoteCaPath;
+    }
+    // Deliberately not carried across. `NO_PROXY` is set for a local run so the agent's plaintext
+    // calls to the proxy do not loop back through it; inherited into a sandbox it is just a list of
+    // hosts that machine will refuse to proxy, which is a silent way to record nothing.
+    return env;
+}
+/** Single-quote a value so no shell can reinterpret it, however it was spelled. */
+function shellQuote(value) {
+    return `'${value.replace(/'/g, `'\\''`)}'`;
+}
+/**
+ * The block the operator pastes into the sandbox.
+ *
+ * The copy step comes first because the export block references a file that has to exist by the
+ * time the agent starts, and an operator who pastes the second half alone gets an agent that
+ * cannot verify the proxy it was just told to trust.
+ */
+export function attachInstructions(req) {
+    const lines = [];
+    if (req.ca && req.remoteCaPath) {
+        lines.push(`# 1. copy the run's certificate authority into the sandbox:`);
+        lines.push(`#    scp ${req.ca.bundlePath} <sandbox>:${req.remoteCaPath}`);
+        lines.push(`#    (or: docker cp ${req.ca.bundlePath} <container>:${req.remoteCaPath})`);
+        lines.push(`# 2. then, in the sandbox, before starting your agent:`);
+    }
+    else {
+        lines.push(`# in the sandbox, before starting your agent:`);
+    }
+    for (const [name, value] of Object.entries(attachExports(req))) {
+        lines.push(`export ${name}=${shellQuote(value)}`);
+    }
+    // Said out loud, because a block with no key in it reads as an incomplete one.
+    lines.push(`# your agent's own credential is unchanged — agenticreplay forwards it upstream`);
+    return lines;
+}
+//# sourceMappingURL=attach.js.map

package/packages/cli/dist/attach.js.map

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

package/packages/cli/dist/capture-limits.d.ts

@@ -0,0 +1,7 @@
+import type { ParsedArgs } from './args.js';
+/** Limits bound retained bytes, independently of the live stream forwarded to the client. */
+export declare function captureLimits(args: ParsedArgs): {
+    maxCapturedBytes: number;
+    maxBufferedBytes: number;
+};
+//# sourceMappingURL=capture-limits.d.ts.map

package/packages/cli/dist/capture-limits.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"capture-limits.d.ts","sourceRoot":"","sources":["../src/capture-limits.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,WAAW,CAAC;AAE5C,6FAA6F;AAC7F,wBAAgB,aAAa,CAAC,IAAI,EAAE,UAAU,GAAG;IAC/C,gBAAgB,EAAE,MAAM,CAAC;IACzB,gBAAgB,EAAE,MAAM,CAAC;CAC1B,CAcA"}

package/packages/cli/dist/capture-limits.js

@@ -0,0 +1,13 @@
+/** Limits bound retained bytes, independently of the live stream forwarded to the client. */
+export function captureLimits(args) {
+    const maxCapturedBytes = args.num('max-body-bytes', 64 * 1024 * 1024);
+    const maxBufferedBytes = args.num('max-buffered-bytes', 256 * 1024 * 1024);
+    if (!Number.isSafeInteger(maxCapturedBytes) ||
+        maxCapturedBytes < 1 ||
+        !Number.isSafeInteger(maxBufferedBytes) ||
+        maxBufferedBytes < maxCapturedBytes) {
+        throw new Error('capture limits must be positive safe integers; --max-buffered-bytes must be at least --max-body-bytes');
+    }
+    return { maxCapturedBytes, maxBufferedBytes };
+}
+//# sourceMappingURL=capture-limits.js.map

package/packages/cli/dist/capture-limits.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"capture-limits.js","sourceRoot":"","sources":["../src/capture-limits.ts"],"names":[],"mappings":"AAEA,6FAA6F;AAC7F,MAAM,UAAU,aAAa,CAAC,IAAgB;IAI5C,MAAM,gBAAgB,GAAG,IAAI,CAAC,GAAG,CAAC,gBAAgB,EAAE,EAAE,GAAG,IAAI,GAAG,IAAI,CAAE,CAAC;IACvE,MAAM,gBAAgB,GAAG,IAAI,CAAC,GAAG,CAAC,oBAAoB,EAAE,GAAG,GAAG,IAAI,GAAG,IAAI,CAAE,CAAC;IAC5E,IACE,CAAC,MAAM,CAAC,aAAa,CAAC,gBAAgB,CAAC;QACvC,gBAAgB,GAAG,CAAC;QACpB,CAAC,MAAM,CAAC,aAAa,CAAC,gBAAgB,CAAC;QACvC,gBAAgB,GAAG,gBAAgB,EACnC,CAAC;QACD,MAAM,IAAI,KAAK,CACb,uGAAuG,CACxG,CAAC;IACJ,CAAC;IACD,OAAO,EAAE,gBAAgB,EAAE,gBAAgB,EAAE,CAAC;AAChD,CAAC"}

package/packages/cli/dist/cli.d.ts

@@ -0,0 +1,3 @@
+#!/usr/bin/env node
+export {};
+//# sourceMappingURL=cli.d.ts.map

package/packages/cli/dist/cli.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"cli.d.ts","sourceRoot":"","sources":["../src/cli.ts"],"names":[],"mappings":""}

package/packages/cli/dist/cli.js

@@ -0,0 +1,4 @@
+#!/usr/bin/env node
+import { main } from './main.js';
+process.exitCode = await main(process.argv.slice(2));
+//# sourceMappingURL=cli.js.map

package/packages/cli/dist/cli.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"cli.js","sourceRoot":"","sources":["../src/cli.ts"],"names":[],"mappings":";AACA,OAAO,EAAE,IAAI,EAAE,MAAM,WAAW,CAAC;AAEjC,OAAO,CAAC,QAAQ,GAAG,MAAM,IAAI,CAAC,OAAO,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,CAAC"}

package/packages/cli/dist/commands/attach.d.ts

@@ -0,0 +1,49 @@
+import type { ParsedArgs } from '../args.js';
+import type { Output } from '../out.js';
+/**
+ * `agenticreplay attach` — record an agent this machine did not start.
+ *
+ * Everything else here launches the agent: an adapter builds an environment, agenticreplay spawns the
+ * process, and capture follows from that. It is a good design with one boundary it cannot cross —
+ * an agent that is not on this machine. A bot on a VPS, an agent inside a dev container or a cloud
+ * sandbox, a harness in someone else's CI: there is no process to spawn, so there is no
+ * environment to build and no way to say `agenticreplay record` at all.
+ *
+ * So this inverts it. AgenticReplay holds the proxy open, prints exactly what to export on the far side,
+ * and records whatever arrives until it is stopped. The recording that comes out is not a lesser
+ * one: same matcher, same events, same `agenticreplay replay`.
+ *
+ * The adapters are still what produce the variables — `--for claude` prints what the Claude Code
+ * adapter would have set, pointed at the advertised address instead of a loopback one. That keeps
+ * one source of truth for "which variable does this harness read", so a sandbox recording cannot
+ * drift from a local one.
+ */
+export interface AttachResult {
+    runId: string;
+    runDir: string;
+    modelExchanges: number;
+    events: number;
+    proxyUrl: string;
+    /** Replay sessions only: recorded exchanges served back, and requests nothing matched. */
+    reused: number;
+    unmatched: number;
+    /**
+     * Non-zero when replay cannot answer a request or recording coverage is incomplete.
+     * An operator stopping the session is normal; missing transport evidence still returns exit 2.
+     */
+    exitCode: number;
+}
+export interface AttachOptions {
+    /**
+     * Resolves when the session should stop. Defaults to SIGINT — the operator pressing ctrl-C,
+     * which is how a session with no child process to wait on ends.
+     */
+    until?: Promise<void>;
+    /** Called once the proxy is listening, with the address a remote agent should use. */
+    onReady?: (info: {
+        proxyUrl: string;
+        runId: string;
+    }) => void;
+}
+export declare function attachCommand(args: ParsedArgs, out: Output, cwd?: string, options?: AttachOptions): Promise<AttachResult>;
+//# sourceMappingURL=attach.d.ts.map

package/packages/cli/dist/commands/attach.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"attach.d.ts","sourceRoot":"","sources":["../../src/commands/attach.ts"],"names":[],"mappings":"AAUA,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,YAAY,CAAC;AAC7C,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,WAAW,CAAC;AAexC;;;;;;;;;;;;;;;;;GAiBG;AAEH,MAAM,WAAW,YAAY;IAC3B,KAAK,EAAE,MAAM,CAAC;IACd,MAAM,EAAE,MAAM,CAAC;IACf,cAAc,EAAE,MAAM,CAAC;IACvB,MAAM,EAAE,MAAM,CAAC;IACf,QAAQ,EAAE,MAAM,CAAC;IACjB,0FAA0F;IAC1F,MAAM,EAAE,MAAM,CAAC;IACf,SAAS,EAAE,MAAM,CAAC;IAClB;;;OAGG;IACH,QAAQ,EAAE,MAAM,CAAC;CAClB;AAED,MAAM,WAAW,aAAa;IAC5B;;;OAGG;IACH,KAAK,CAAC,EAAE,OAAO,CAAC,IAAI,CAAC,CAAC;IACtB,sFAAsF;IACtF,OAAO,CAAC,EAAE,CAAC,IAAI,EAAE;QAAE,QAAQ,EAAE,MAAM,CAAC;QAAC,KAAK,EAAE,MAAM,CAAA;KAAE,KAAK,IAAI,CAAC;CAC/D;AAED,wBAAsB,aAAa,CACjC,IAAI,EAAE,UAAU,EAChB,GAAG,EAAE,MAAM,EACX,GAAG,SAAgB,EACnB,OAAO,GAAE,aAAkB,GAC1B,OAAO,CAAC,YAAY,CAAC,CAQvB"}