agenticreplay 0.1.0 → 0.1.2

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

@@ -0,0 +1,350 @@
+import { once } from 'node:events';
+import { TraceReader, TraceWriter, ensureRunsDir, resolveRunSelector } from '@agenticreplay/core';
+import { createProxy, } from '@agenticreplay/proxy';
+import { defaultAdapters } from '@agenticreplay/adapters';
+import { advertisedUrl, attachExports, attachInstructions } from '../attach.js';
+import { ExchangeEventDeriver, appendDerivedEvents } from '../exchange-events.js';
+import { SerialQueue } from '../serial.js';
+import { planTlsCapture, recordedTlsHosts, setupTlsCapture, persistNetRequestStart, persistNetExchange, } from '../tls-capture.js';
+import { loadExchanges } from './replay.js';
+import { upstreamPlan } from '../upstream.js';
+import { AGENTICREPLAY_VERSION } from '../version.js';
+export async function attachCommand(args, out, cwd = process.cwd(), options = {}) {
+    const minted = [];
+    try {
+        return await runAttached(args, out, cwd, options, minted);
+    }
+    catch (err) {
+        for (const ca of minted)
+            await ca.dispose().catch(() => undefined);
+        throw err;
+    }
+}
+async function runAttached(args, out, cwd, options, minted) {
+    const registry = defaultAdapters();
+    const bind = args.str('bind') ?? '127.0.0.1';
+    const advertise = args.str('advertise');
+    const requestedPort = args.num('port') ?? 0;
+    // Resolved before the run directory is made, so an invocation that cannot work — a wildcard bind
+    // with nothing to advertise — leaves nothing behind to clean up. The port is not known yet when
+    // agenticreplay is choosing one, and does not need to be: only the host can make this fail.
+    advertisedUrl({
+        bind,
+        port: requestedPort === 0 ? 1 : requestedPort,
+        ...(advertise === undefined ? {} : { advertise }),
+    });
+    /**
+     * Serving a recording back instead of recording a new one.
+     *
+     * `agenticreplay replay` launches the agent, which is right for a run agenticreplay recorded by launching it and
+     * impossible for one that came from a sandbox — the agent may not exist on this machine at all.
+     * So replay attaches too: same proxy, same matcher, same blocked egress, and the operator points
+     * the same remote agent at it.
+     */
+    // The parser turns a flag with no value into `true`, so a bare `--replay` — or `--replay
+    // --tls-intercept`, where the next token is itself a flag — would read as absent and start a
+    // *recording* session against the live provider. That is the worst direction to fail in.
+    if (args.has('replay') && args.str('replay') === undefined) {
+        throw new Error('--replay needs the run to serve: agenticreplay attach --replay <run>, or --replay last');
+    }
+    const replaySelector = args.str('replay');
+    const replaying = replaySelector
+        ? await (async () => {
+            const runDir = (await resolveRunSelector(cwd, replaySelector)).dir;
+            const reader = await TraceReader.open(runDir);
+            return {
+                exchanges: await loadExchanges(reader),
+                hosts: recordedTlsHosts(await reader.events()),
+                // Which harness made the recording. It will be the one connecting again, so it is the
+                // right default for the block the operator pastes.
+                adapter: reader.manifest().adapter?.id,
+            };
+        })()
+        : undefined;
+    /**
+     * `exec` is the honest default for a fresh session: agenticreplay does not know what will connect, and
+     * detecting an agent from this directory would be a guess about a machine it cannot see. For a
+     * replay it is the wrong default and a useless one — `exec` sets no variables, so the block the
+     * operator is meant to paste comes out empty. The recording names the harness, so use it.
+     */
+    const adapterName = args.str('for') ?? replaying?.adapter ?? 'exec';
+    const adapter = registry.get(adapterName);
+    // The last thing that can refuse the run, and it runs before the trace exists: a writer created
+    // first and abandoned by a throw leaves an unsealed run directory behind, which then wins `last`
+    // — so the next command someone types operates on the session that never happened. Awaited
+    // since it grew the one refusal that needs the disk, an `AGENTICREPLAY_TLS_UPSTREAM_CA` that cannot be
+    // read; the guarantee here is unchanged, it just covers one more way to fail.
+    await planTlsCapture(args, replaying?.hosts);
+    // Before the run directory exists, because this refuses an upstream that is not an origin: resolved after it, a
+    // typo in `--upstream-*` left an empty run behind for `agenticreplay list` to show. It depends on nothing
+    // but the arguments and the environment, so there is no reason for it to run any later.
+    const plan = await upstreamPlan(args);
+    const dir = await ensureRunsDir(cwd);
+    const writer = await TraceWriter.create(dir, {
+        adapter: {
+            id: adapter.id,
+            version: AGENTICREPLAY_VERSION,
+            harness_version: adapter.harnessVersions,
+        },
+        argv: [adapterName],
+        cwd,
+        agenticreplayVersion: AGENTICREPLAY_VERSION,
+    });
+    let modelExchanges = 0;
+    let turn = 0;
+    let unmatched = 0;
+    const writes = new SerialQueue();
+    const attempts = new Map();
+    let terminalAttempts = 0;
+    async function start(request) {
+        attempts.set(request.requestId, ++turn);
+        await persistNetRequestStart(writer, turn, request);
+    }
+    function finish(exchange) {
+        terminalAttempts++;
+        const at = attempts.get(exchange.requestId);
+        if (at === undefined)
+            writer.markCaptureIncomplete('missing_request_correlation');
+        writes.push(() => persistNetExchange(writer, at ?? 0, exchange));
+    }
+    const tls = await setupTlsCapture({
+        args,
+        out,
+        ...(replaying ? { recordedHosts: replaying.hosts } : {}),
+        writer,
+        writes,
+        // Out-of-band traffic belongs to whichever turn was in progress when it happened, exactly as in
+        // a launched recording. A fixed 0 filed every net.* event against the start of the session.
+        turn: () => turn,
+        onRequestStart: start,
+        onNetExchange: finish,
+    });
+    if (tls.ca)
+        minted.push(tls.ca);
+    // Read before the proxy closes: `stats()` is a snapshot of a live object, and the teardown in
+    // `finally` is the last moment it is still meaningful.
+    let stats = {
+        matchedExact: 0,
+        matchedInexact: 0,
+        unmatched: 0,
+    };
+    const deriver = new ExchangeEventDeriver();
+    // BEFORE THE PROXY, NOT AFTER: `createProxy` is listening by the time it returns, and the first
+    // thing a remote agent sends becomes an event. `attach` wrote no run.start at all, so every
+    // session it recorded opened on `model.request` and the gateway refused the push — "0 run.start
+    // and 1 run.end events". The proxy URL that `record`'s run.start carries is not known yet and is
+    // not read by anything; the adapter and the cwd are what a reader needs.
+    await writer.append({
+        type: 'run.start',
+        actor: 'agenticreplay',
+        turn: 0,
+        attrs: { adapter: adapter.id, cwd, attached: true },
+    });
+    const proxy = await createProxy({
+        // A replay session serves the recording and blocks egress, exactly as `agenticreplay replay` does. The
+        // only difference is which side starts the agent, and that is not a difference the proxy has.
+        mode: replaying ? 'replay' : 'record',
+        ...(replaying ? { exchanges: replaying.exchanges, loose: args.bool('loose') } : {}),
+        host: bind,
+        port: requestedPort,
+        upstream: plan.upstream,
+        upstreamHeaders: plan.headers,
+        upstreamHeadersOrigin: plan.headersOrigin,
+        ...tls.proxyOptions,
+        onRequestStart: start,
+        onNetExchange: finish,
+        onUnmatched: () => {
+            unmatched += 1;
+        },
+        onExchange: (exchange) => {
+            modelExchanges += 1;
+            const at = exchange.requestId ? (attempts.get(exchange.requestId) ?? 0) : 0;
+            writes.push(() => appendDerivedEvents(writer, deriver, exchange, at));
+        },
+    });
+    const advertised = advertisedUrl({
+        bind,
+        port: proxy.port,
+        ...(advertise === undefined ? {} : { advertise }),
+    });
+    try {
+        const proxyUrl = advertised;
+        // What the adapter would have put into a child's environment, pointed at the reachable
+        // address rather than a loopback one. `runDir` is this machine's, and is only ever used by
+        // adapters that write a scratch file — none of which a remote agent would read, which is why
+        // `--for` is documented as the variables rather than as full instrumentation.
+        const launch = await adapter.prepare({
+            runId: writer.runId,
+            cwd,
+            runDir: writer.runDir,
+            proxyUrl,
+            userArgs: ['<your agent>'],
+            env: process.env,
+        });
+        const remoteCaPath = args.str('remote-ca-path') ?? '/tmp/agenticreplay-ca.crt';
+        const instructions = attachInstructions({
+            proxyUrl,
+            adapterEnv: launch.env,
+            ...(proxy.tls
+                ? {
+                    ca: { certPath: proxy.tls.caCertPath, bundlePath: proxy.tls.caBundlePath },
+                    remoteCaPath,
+                }
+                : {}),
+        });
+        out.phase('attached', {
+            run: writer.runId,
+            proxy: proxyUrl,
+            for: adapter.id,
+            ...(replaying
+                ? {
+                    serving: replaySelector,
+                    exchanges: replaying.exchanges.length,
+                    // Same flag, same reason as `agenticreplay replay`: attach takes `--loose` too and passes it
+                    // to the same proxy, so the label has to come from it rather than be assumed.
+                    egress: args.bool('loose') ? 'live-on-unmatched' : 'blocked',
+                }
+                : {}),
+        });
+        if (proxy.tls) {
+            out.warn('tls.intercepting', {
+                hosts: proxy.tls.hosts,
+                ca_sha256: proxy.tls.fingerprint,
+            });
+            await writer.append({
+                type: 'note',
+                actor: 'agenticreplay',
+                turn: 0,
+                attrs: {
+                    rule: 'tls_intercept',
+                    hosts: proxy.tls.hosts,
+                    ca_sha256: proxy.tls.fingerprint,
+                },
+            });
+        }
+        /**
+         * An instruction the operator cannot act on is worse than none: the block pastes cleanly, the
+         * session waits, and nothing ever connects. Both shapes of that are visible from here.
+         */
+        const exported = attachExports({
+            proxyUrl,
+            adapterEnv: launch.env,
+            ...(proxy.tls
+                ? {
+                    ca: { certPath: proxy.tls.caCertPath, bundlePath: proxy.tls.caBundlePath },
+                    remoteCaPath,
+                }
+                : {}),
+        });
+        if (Object.keys(exported).length === 0) {
+            out.warn('attach.nothing_to_set', {
+                for: adapter.id,
+                cause: `${adapter.id} redirects nothing, and this session is not intercepting`,
+                next: 'name the harness with --for <agent>, or add --tls-intercept',
+            });
+        }
+        // A path under the run directory exists on this machine and nowhere else. The fetch hook is
+        // the live example: `--for node` names a preload agenticreplay just wrote here, so the block would
+        // instrument nothing over there while looking exactly as though it had.
+        const local = Object.entries(exported)
+            .filter(([, value]) => value.includes(writer.runDir))
+            .map(([name]) => name);
+        if (local.length > 0) {
+            out.warn('attach.local_path', {
+                vars: local.join(','),
+                cause: `${adapter.id} instruments by writing a file here and naming it in the environment`,
+                effect: 'those paths do not exist in the sandbox, so that half of the capture will not run',
+                next: 'copy the named files across, or use --tls-intercept instead',
+            });
+        }
+        out.plain('');
+        for (const line of instructions)
+            out.plain(`  ${line}`);
+        out.plain('');
+        out.plain(replaying
+            ? '  Serving the recording. Press ctrl-C when the agent is done.'
+            : '  Recording. Press ctrl-C when the agent is done.');
+        options.onReady?.({ proxyUrl, runId: writer.runId });
+        await (options.until ?? firstInterrupt());
+    }
+    finally {
+        stats = proxy.stats();
+        await proxy.close();
+        await writes.drain().catch(() => writer.markCaptureIncomplete('storage_failure'));
+        await tls.ca?.dispose();
+    }
+    /**
+     * The same warning a launched run gets, and it matters more here. A remote agent that was never
+     * given the block — or was given it in a shell that had already started the agent — produces a
+     * session that ends cleanly and records nothing, and there is no exit code to hint at it.
+     */
+    if (modelExchanges === 0 && !replaying) {
+        out.warn('capture.empty', {
+            exchanges: 0,
+            cause: 'nothing connected to the proxy while the session was open',
+            next: 'check the sandbox can reach the advertised address, and that the exports were set',
+        });
+    }
+    if (!replaying)
+        writer.setCaptureSummary({
+            status: terminalAttempts > 0 && terminalAttempts === attempts.size ? 'complete' : 'incomplete',
+            issues: terminalAttempts === 0
+                ? ['no_requests_observed']
+                : terminalAttempts !== attempts.size
+                    ? ['unfinalized_request']
+                    : [],
+            requests: attempts.size,
+            responses: terminalAttempts,
+        });
+    // The other half of the bracket. `close` seals the manifest; it does not write the event.
+    await writer.append({
+        type: 'run.end',
+        actor: 'agenticreplay',
+        turn,
+        attrs: { exchanges: modelExchanges },
+    });
+    const manifest = await writer.close(0);
+    // A replay session did not record a run, and saying it did would send someone looking for turns
+    // in a trace that holds none. It reports what it actually did: how much of the recording the
+    // agent asked for, and what it asked for that the recording could not answer.
+    if (replaying) {
+        out.info('served', {
+            serving: replaySelector,
+            reused: `${stats.matchedExact + stats.matchedInexact}/${replaying.exchanges.length}`,
+            unmatched: stats.unmatched,
+        });
+    }
+    else {
+        out.info('recorded', {
+            run: writer.runId,
+            events: manifest.counts?.events ?? 0,
+            exchanges: modelExchanges,
+            dir: writer.runDir,
+        });
+    }
+    return {
+        runId: writer.runId,
+        runDir: writer.runDir,
+        modelExchanges,
+        events: manifest.counts?.events ?? 0,
+        // The address the agent should use, not the one agenticreplay bound — a caller reading this from
+        // `--json` needs something it can connect to, which a wildcard bind is not.
+        proxyUrl: advertised,
+        // Exact plus inexact: both were served from the recording, which is what "reused" means here.
+        // The distinction between them is a divergence, and divergences are reported on their own.
+        reused: replaying ? stats.matchedExact + stats.matchedInexact : 0,
+        unmatched: replaying ? stats.unmatched : unmatched,
+        exitCode: replaying
+            ? stats.unmatched > 0
+                ? 1
+                : 0
+            : manifest.capture?.status === 'incomplete'
+                ? 2
+                : 0,
+    };
+}
+/** Ctrl-C, which is the only way an operator ends a session with no child process to wait on. */
+async function firstInterrupt() {
+    await once(process, 'SIGINT');
+}
+//# sourceMappingURL=attach.js.map

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

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

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

@@ -0,0 +1,27 @@
+import { type ParsedArgs } from '../args.js';
+import type { Output } from '../out.js';
+export interface CompareRow {
+    /** Exit code of --verify, when one was given. This, not the agent's exit code, is the verdict. */
+    verifyExitCode?: number;
+    model: string;
+    verdict: 'pass' | 'fail';
+    exitCode: number;
+    divergences: number;
+    inputTokens: number;
+    outputTokens: number;
+    cost: number | null;
+    wallMs: number;
+    forkRunId?: string;
+    error?: string;
+}
+/**
+ * `agenticreplay compare <run> --models a,b,c`
+ *
+ * N forks from one checkpoint. The comparison only means anything because every branch starts
+ * from an identical filesystem tree and conversation prefix — the model is the only variable, so
+ * the difference in outcome is attributable to it rather than to drift.
+ */
+export declare function compareCommand(args: ParsedArgs, out: Output, cwd?: string): Promise<CompareRow[]>;
+/** Dash for unknown. Otherwise enough precision that a genuinely cheap model does not read $0. */
+export declare function formatCost(amount: number | null): string;
+//# sourceMappingURL=compare.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"compare.d.ts","sourceRoot":"","sources":["../../src/commands/compare.ts"],"names":[],"mappings":"AAEA,OAAO,EAAa,KAAK,UAAU,EAAE,MAAM,YAAY,CAAC;AACxD,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,WAAW,CAAC;AA6BxC,MAAM,WAAW,UAAU;IACzB,kGAAkG;IAClG,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB,KAAK,EAAE,MAAM,CAAC;IACd,OAAO,EAAE,MAAM,GAAG,MAAM,CAAC;IACzB,QAAQ,EAAE,MAAM,CAAC;IACjB,WAAW,EAAE,MAAM,CAAC;IACpB,WAAW,EAAE,MAAM,CAAC;IACpB,YAAY,EAAE,MAAM,CAAC;IACrB,IAAI,EAAE,MAAM,GAAG,IAAI,CAAC;IACpB,MAAM,EAAE,MAAM,CAAC;IACf,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,KAAK,CAAC,EAAE,MAAM,CAAC;CAChB;AAED;;;;;;GAMG;AACH,wBAAsB,cAAc,CAClC,IAAI,EAAE,UAAU,EAChB,GAAG,EAAE,MAAM,EACX,GAAG,SAAgB,GAClB,OAAO,CAAC,UAAU,EAAE,CAAC,CA0IvB;AAED,kGAAkG;AAClG,wBAAgB,UAAU,CAAC,MAAM,EAAE,MAAM,GAAG,IAAI,GAAG,MAAM,CAMxD"}

package/packages/cli/dist/commands/compare.js

@@ -0,0 +1,187 @@
+import { TraceReader, deriveCheckpoints, resolveRunSelector } from '@agenticreplay/core';
+import { priceFor } from '@agenticreplay/providers';
+import { parseArgs } from '../args.js';
+import { writeFile } from 'node:fs/promises';
+import { resolve } from 'node:path';
+import { renderCompareCard } from '../share-card.js';
+import { cardTarget, svgToPng } from '../rasterize.js';
+import { replayCommand } from './replay.js';
+import { readConfig } from '../config.js';
+/** Run the verdict command inside the fork's worktree. Shell so `npm test -- auth` just works. */
+async function runVerify(command, cwd) {
+    const { spawn } = await import('node:child_process');
+    return new Promise((resolve) => {
+        const child = spawn(command, { cwd, shell: true, stdio: 'ignore' });
+        // A verify command that cannot even start is a failed verdict, not a crashed comparison.
+        child.on('error', () => resolve(127));
+        child.on('close', (code) => resolve(code ?? 1));
+    });
+}
+/** Each fork is a fresh argv, so upstream overrides have to be forwarded explicitly. */
+function upstreamFlags(args) {
+    const out = [];
+    const a = args.str('upstream-anthropic');
+    const o = args.str('upstream-openai');
+    if (a)
+        out.push('--upstream-anthropic', a);
+    if (o)
+        out.push('--upstream-openai', o);
+    return out;
+}
+/**
+ * `agenticreplay compare <run> --models a,b,c`
+ *
+ * N forks from one checkpoint. The comparison only means anything because every branch starts
+ * from an identical filesystem tree and conversation prefix — the model is the only variable, so
+ * the difference in outcome is attributable to it rather than to drift.
+ */
+export async function compareCommand(args, out, cwd = process.cwd()) {
+    // Fall back to what `agenticreplay setup` recorded, so the common case needs no flags at all. An explicit
+    // --models still wins: the config is a default, not a policy.
+    const models = args.list('models').length > 0 ? args.list('models') : ((await readConfig()).models ?? []);
+    if (models.length === 0) {
+        throw new Error('compare needs models to compare\n' +
+            // Not two example ids: they are gateway-specific — OrcaRouter namespaces by provider,
+            // a direct provider does not — so a copyable pair here fails against half of them.
+            '  agenticreplay models to see what your gateway serves, then: agenticreplay compare last --models a,b\n' +
+            '  or run agenticreplay setup once — it stores your explicit gateway and a model list');
+    }
+    const selector = args.positionals[0] ?? 'last';
+    const runDir = (await resolveRunSelector(cwd, selector)).dir;
+    const reader = await TraceReader.open(runDir);
+    const events = await reader.events();
+    const checkpoints = deriveCheckpoints(events);
+    if (checkpoints.length === 0) {
+        throw new Error('this run has no checkpoints, so there is nothing to fork from');
+    }
+    const from = args.num('from') ?? checkpoints[checkpoints.length - 1].seq;
+    const runId = reader.manifest().run_id;
+    out.phase('compare', { run: runId, from, models: models.join(',') });
+    const rows = [];
+    // Sequential rather than parallel: each fork spawns a real agent against a real worktree, and
+    // running four of those concurrently on one machine measures the machine, not the models.
+    for (const model of models) {
+        const startedAt = Date.now();
+        try {
+            const forkArgs = parseArgs([
+                'replay',
+                // The concrete run id, never the caller's selector. "last" is re-resolved on every fork,
+                // so after the first branch it would point at the child we just created — which has no
+                // checkpoints — and every later model would fail for a reason that is not about the model.
+                runId,
+                '--from',
+                String(from),
+                '--model',
+                model,
+                ...(args.bool('loose') ? ['--loose'] : []),
+                // The same silent-no-op this list already warns about twice. `--no-fs` is what a run
+                // fetched with `agenticreplay pull` needs — it has no snapshots to restore from — and dropping it
+                // here would accept the flag and then fork with the restore still on, which is the one
+                // thing it was passed to prevent.
+                ...(args.bool('fs', true) ? [] : ['--no-fs']),
+                // Every fork this makes runs a live agent, so interception has to reach them: accepting
+                // the flag here and dropping it before the fork is exactly the silent-no-op the flag was
+                // fixed for one layer up.
+                ...(args.bool('tls-intercept') ? ['--tls-intercept'] : []),
+                // Same reasoning, and the same silent-no-op if dropped: every fork launches a live agent,
+                // and under --json agenticreplay's stdout is the result document. A fork that inherits it prints
+                // the agent's output into the middle of the JSON.
+                ...(args.bool('json') ? ['--json'] : []),
+                ...args.list('tls-hosts').flatMap((h) => ['--tls-hosts', h]),
+                ...upstreamFlags(args),
+            ]);
+            const result = await replayCommand(forkArgs, out, cwd);
+            // The agent exiting 0 only means it did not crash. "Did the task actually get done" needs
+            // a command that answers it — otherwise the verdict column is a number nobody should act on.
+            const verify = args.str('verify');
+            const verifyExitCode = verify && result.worktree ? await runVerify(verify, result.worktree) : undefined;
+            const failed = verifyExitCode === undefined ? result.exitCode !== 0 : verifyExitCode !== 0;
+            const usage = result.forkRunId
+                ? await usageOf(cwd, result.forkRunId)
+                : { input: 0, output: 0 };
+            const money = priceFor({ input_tokens: usage.input, output_tokens: usage.output }, model);
+            rows.push({
+                model,
+                verdict: failed ? 'fail' : 'pass',
+                verifyExitCode,
+                exitCode: result.exitCode,
+                divergences: result.divergences,
+                inputTokens: usage.input,
+                outputTokens: usage.output,
+                cost: money ? money.amount : null,
+                wallMs: Date.now() - startedAt,
+                forkRunId: result.forkRunId,
+            });
+        }
+        catch (err) {
+            rows.push({
+                model,
+                verdict: 'fail',
+                exitCode: -1,
+                divergences: 0,
+                inputTokens: 0,
+                outputTokens: 0,
+                cost: null,
+                wallMs: Date.now() - startedAt,
+                error: err instanceof Error ? err.message.split('\n')[0] : String(err),
+            });
+        }
+    }
+    out.plain('');
+    out.table(['MODEL', 'VERDICT', 'TOKENS', 'COST', 'WALL', 'RUN'], rows.map((r) => [
+        r.model,
+        r.verdict,
+        `${r.inputTokens}/${r.outputTokens}`,
+        // An unknown model prices as a dash, never as $0.00 — a confidently wrong cost is worse
+        // than an absent one when it lands in a table someone decides from. And a real cost too
+        // small for four decimals still gets shown: "cheaper" is the whole reason for this column.
+        formatCost(r.cost),
+        `${(r.wallMs / 1000).toFixed(1)}s`,
+        r.forkRunId ?? r.error ?? '',
+    ]));
+    if (args.has('share')) {
+        const picked = cardTarget(args.str('share') ?? 'compare.svg', '--share');
+        if (picked.format === 'gif') {
+            throw new Error('--share draws one table, so it has no animation. Use .svg or .png.');
+        }
+        const target = resolve(cwd, picked.path);
+        const svg = renderCompareCard(rows, {
+            runId,
+            forkPoint: from,
+            verify: args.str('verify'),
+        });
+        const body = picked.format === 'png' ? await svgToPng(svg) : svg;
+        await writeFile(target, body, { mode: 0o644 });
+        out.phase('shared', {
+            path: target,
+            bytes: typeof body === 'string' ? Buffer.byteLength(body) : body.length,
+            format: picked.format,
+        });
+    }
+    return rows;
+}
+/** Dash for unknown. Otherwise enough precision that a genuinely cheap model does not read $0. */
+export function formatCost(amount) {
+    if (amount === null)
+        return '—';
+    if (amount === 0)
+        return '$0';
+    if (amount < 0.0001)
+        return `$${amount.toExponential(2)}`;
+    if (amount < 0.01)
+        return `$${amount.toFixed(6)}`;
+    return `$${amount.toFixed(4)}`;
+}
+async function usageOf(cwd, runId) {
+    const reader = await TraceReader.open((await resolveRunSelector(cwd, runId)).dir);
+    let input = 0;
+    let output = 0;
+    for (const e of await reader.events()) {
+        if (e.type !== 'model.response')
+            continue;
+        input += Number(e.attrs?.input_tokens ?? 0);
+        output += Number(e.attrs?.output_tokens ?? 0);
+    }
+    return { input, output };
+}
+//# sourceMappingURL=compare.js.map

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

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

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

@@ -0,0 +1,24 @@
+import type { ParsedArgs } from '../args.js';
+import type { Output } from '../out.js';
+export interface DoctorCheck {
+    name: string;
+    status: 'ok' | 'warn' | 'fail';
+    detail: string;
+    /** What to do about it. Mandatory in spirit for anything that is not ok. */
+    fix?: string;
+}
+export interface DoctorResult {
+    checks: DoctorCheck[];
+    ok: boolean;
+}
+/**
+ * `agenticreplay doctor` — will recording actually work here?
+ *
+ * AgenticReplay instruments an agent by putting environment variables in front of someone else's process
+ * and shelling out to git. When that goes wrong the symptom appears inside the agent, minutes
+ * later, as something that looks like the agent's fault. Every check here is one of those failure
+ * modes, answered before the user spends an hour on it — so each is exercised for real (a port is
+ * actually bound, a file is actually written) rather than inferred.
+ */
+export declare function doctorCommand(args: ParsedArgs, out: Output, cwd?: string): Promise<DoctorResult>;
+//# sourceMappingURL=doctor.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"doctor.d.ts","sourceRoot":"","sources":["../../src/commands/doctor.ts"],"names":[],"mappings":"AAcA,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,YAAY,CAAC;AAE7C,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,WAAW,CAAC;AAMxC,MAAM,WAAW,WAAW;IAC1B,IAAI,EAAE,MAAM,CAAC;IACb,MAAM,EAAE,IAAI,GAAG,MAAM,GAAG,MAAM,CAAC;IAC/B,MAAM,EAAE,MAAM,CAAC;IACf,4EAA4E;IAC5E,GAAG,CAAC,EAAE,MAAM,CAAC;CACd;AAED,MAAM,WAAW,YAAY;IAC3B,MAAM,EAAE,WAAW,EAAE,CAAC;IACtB,EAAE,EAAE,OAAO,CAAC;CACb;AAMD;;;;;;;;GAQG;AACH,wBAAsB,aAAa,CACjC,IAAI,EAAE,UAAU,EAChB,GAAG,EAAE,MAAM,EACX,GAAG,SAAgB,GAClB,OAAO,CAAC,YAAY,CAAC,CAuCvB"}