agenticreplay 0.1.0 → 0.1.2

package/packages/cli/dist/mcp.js

@@ -0,0 +1,290 @@
+import { spawn } from 'node:child_process';
+import { readFile, stat, writeFile } from 'node:fs/promises';
+import { createRequire } from 'node:module';
+import { join } from 'node:path';
+import { rewriteMcpConfig } from '@agenticreplay/adapters';
+import { EARLIEST_TS_MS, LATEST_TS_MS } from '@agenticreplay/schema';
+import { isMcpFrameRecord, objectsOnLine, MCP_RECORD_START } from '@agenticreplay/mcp-shim';
+/**
+ * The recording's own copy of the config it was given, kept beside the frames it produced.
+ *
+ * A replay used to find the source by reading the path out of the `mcp_instrumented` note, and a
+ * path is a poor thing to depend on. It has to survive the trace's redactor — `mkdtemp` and every
+ * CI workspace end in a random segment, and `agenticreplay-int-mcp-stdio-feH8gJ` is 25 characters of
+ * mixed-case base62, so roughly one in seven cleared the entropy sweep's threshold and reached the
+ * trace as `<secret:high_entropy:…>`. `stat` then failed, MCP was dropped for the replay, and the
+ * agent was launched with no `MCP_CONFIG_PATH`: `KeyError` from a recording that was perfectly
+ * good, intermittently, according to what `mkdtemp` picked.
+ *
+ * It also has to still be there, and mean the same thing. Deleting the config, moving it, or
+ * editing a server's command between the recording and the replay all changed what the replay ran
+ * — for a file the operator has no reason to think of as part of the run.
+ *
+ * Keeping the bytes removes both. Nothing has to survive redaction, because this is not in the
+ * trace; nothing outside the run directory has to still exist. It carries the same material as the
+ * rewritten `mcp-config.json` written next to it — same directory, same `0600` — so it is not a
+ * new kind of thing to protect.
+ */
+export const MCP_SOURCE_FILENAME = 'mcp-source.json';
+/**
+ * The MCP config a *replay* should instrument: the flag if one was given, else whatever the
+ * recording itself used.
+ *
+ * Replay and fork launch the same agent the recording did, so they hit the same blind spot record
+ * had before `--mcp-config` existed: without a config the harness either talks to servers agenticreplay
+ * cannot see, or — for one that requires the variable — does not start at all. The recording knows
+ * the answer; it just had nowhere to write it down, since `manifest.argv` holds only the agent's
+ * own arguments and `--mcp-config` is agenticreplay's.
+ *
+ * The path is read back from the run's own `mcp_instrumented` note. Nothing is re-instrumented from
+ * the *rewritten* config in the parent run directory: its servers already point at the parent's
+ * frames file, so reusing it would append this replay's traffic to the recording it is replaying.
+ */
+export function mcpSourceFrom(flagValue, events) {
+    if (flagValue)
+        return flagValue;
+    for (const event of events) {
+        if (event.type !== 'note' || event.attrs?.rule !== 'mcp_instrumented')
+            continue;
+        const source = event.attrs.source;
+        if (typeof source === 'string' && source !== '')
+            return source;
+    }
+    return undefined;
+}
+/** Did this run capture MCP at all? Decides whether a replay without a config is worth warning about. */
+export function usedMcp(events) {
+    return events.some((e) => e.type === 'mcp.request' || e.type === 'mcp.response');
+}
+/**
+ * Set up MCP capture for a replay or a fork, from the flag or from what the recording used.
+ *
+ * Returns undefined — quietly — when the run never had MCP, which is most runs. When it did and the
+ * source config has since moved or been deleted, that is said out loud rather than silently
+ * dropping a capture layer: an absent `mcp.*` in the replay would otherwise read as "the agent made
+ * no MCP calls" instead of "agenticreplay was not looking".
+ */
+export async function mcpForReplay(args, events, writer, out, 
+/** The recording's own frames, so the servers are answered from rather than started. */
+recordedFrames, 
+/** The recording's directory, which holds its own copy of the config it was given. */
+recordedRunDir) {
+    // The recording's copy first, and only then the path it wrote down. The copy cannot have been
+    // redacted, moved or edited since; the path can have been all three.
+    const kept = recordedRunDir === undefined ? undefined : join(recordedRunDir, MCP_SOURCE_FILENAME);
+    if (kept !== undefined && (await stat(kept).catch(() => null))) {
+        return setupMcpCapture({
+            sourceConfigPath: kept,
+            runDir: writer.runDir,
+            out,
+            ...(recordedFrames === undefined ? {} : { replayFrames: recordedFrames }),
+        });
+    }
+    const source = mcpSourceFrom(args.str('mcp-config'), events);
+    if (source === undefined) {
+        if (usedMcp(events)) {
+            out.warn('mcp.not_instrumented', {
+                why: 'the recording captured MCP but did not record which config it came from',
+                next: 'pass --mcp-config <path> to capture it here too',
+            });
+        }
+        return undefined;
+    }
+    if (!(await stat(source).catch(() => null))) {
+        out.warn('mcp.source_missing', {
+            path: source,
+            note: 'the config the recording used is no longer there; MCP will not be captured',
+        });
+        return undefined;
+    }
+    return setupMcpCapture({
+        sourceConfigPath: source,
+        runDir: writer.runDir,
+        out,
+        // A replay that starts the real servers is not a replay of them: it is a second live run whose
+        // answers happen to be read back through the same shim. Answering from the recording is what
+        // makes an MCP run reproducible after the server it talked to is gone.
+        ...(recordedFrames === undefined ? {} : { replayFrames: recordedFrames }),
+    });
+}
+/**
+ * Point the launched agent at the instrumented config.
+ *
+ * Every target harness reads one of these; setting all three costs nothing and avoids making the
+ * user work out which one their agent uses.
+ */
+export function pointAtMcpConfig(env, configPath) {
+    env.MCP_CONFIG_PATH = configPath;
+    env.CLAUDE_MCP_CONFIG = configPath;
+    env.OPENCODE_MCP_CONFIG = configPath;
+}
+/**
+ * Drain captured frames into a trace as `mcp.request` / `mcp.response`.
+ *
+ * Frames are read off disk after the agent exits, so each carries the moment it passed through the
+ * shim and is stamped with that rather than with the drain — `mono_us` is authoritative for
+ * duration (spec §2.1), and a frame stamped at the drain can never interleave with the model turns
+ * it actually sat between.
+ */
+/**
+ * Whether a parsed capture line is something the drain can safely turn into an event.
+ *
+ * Several shims share one capture file — `createWriteStream(out, { flags: 'a' })`, whose own
+ * comment says "several servers in one run may share a capture file" — so this file is exposed to
+ * the same interleaved write as the shell frames, and the same two failures follow from it:
+ *
+ *   - a line that parses to `null` reaches `frame.ts` and throws `TypeError`
+ *   - a `ts` that parses to an instant outside the range a `date-time` can express becomes a `Date`
+ *     that `TraceWriter.append` cannot format, and `toISOString()` or `assertEvent` throws
+ *
+ * Both happen after the agent has exited, where the trace is being sealed. Being the right *type*
+ * is not enough for `ts`; the instant has to exist.
+ */
+function usableFrame(value) {
+    // The shape check belongs to the package that owns the format, so the two readers of this file
+    // cannot drift apart — they already had, and the one without it died on a `null` line.
+    if (!isMcpFrameRecord(value))
+        return false;
+    const ts = value.ts;
+    if (ts === undefined)
+        return true;
+    if (typeof ts !== 'string')
+        return false;
+    const at = Date.parse(ts);
+    // An unparseable `ts` is fine: the drain already falls back to the run's own turn for it.
+    return Number.isNaN(at) || (at >= EARLIEST_TS_MS && at <= LATEST_TS_MS);
+}
+export async function drainMcpFrames(mcp, writer, turnAt, fallbackTurn) {
+    for (const frame of await mcp.drain()) {
+        // Belt and braces with the filter in `drain`. This function is exported and reached from three
+        // call sites, and what it is handed comes off a file several processes append to.
+        if (!usableFrame(frame))
+            continue;
+        const at = frame.ts === undefined ? Number.NaN : Date.parse(frame.ts);
+        const when = Number.isNaN(at) ? undefined : new Date(at);
+        await writer.append({
+            type: frame.dir === 'in' ? 'mcp.request' : 'mcp.response',
+            actor: 'agent',
+            turn: when === undefined ? fallbackTurn : turnAt(at),
+            ...(when === undefined ? {} : { occurredAt: when }),
+            attrs: { server: frame.name, kind: frame.kind, method: frame.method, id: frame.id },
+            payload: frame.raw,
+        });
+    }
+}
+/**
+ * Set up MCP capture for a run.
+ *
+ * The mechanism is a config rewrite, not a patch: each stdio server is relaunched through
+ * `agenticreplay-mcp-shim`, a transparent JSON-RPC tee. The agent's own config file is never touched — a
+ * rewritten copy goes in the run directory, and the agent is pointed at that.
+ *
+ * HTTP and SSE servers are deliberately left alone and reported as skipped; they route through the
+ * HTTP proxy instead, and silently dropping them would be worse than not capturing them.
+ */
+export async function setupMcpCapture(opts) {
+    const raw = await readFile(opts.sourceConfigPath, 'utf8').catch(() => undefined);
+    if (raw === undefined) {
+        opts.out.warn('mcp.config_unreadable', { path: opts.sourceConfigPath });
+        return undefined;
+    }
+    // Kept before it is parsed, so a later run reads back what this run was handed — byte for byte,
+    // key order and all. See {@link MCP_SOURCE_FILENAME} for why a path was not good enough.
+    await writeFile(join(opts.runDir, MCP_SOURCE_FILENAME), raw, { mode: 0o600 }).catch(() => undefined);
+    let parsed;
+    try {
+        parsed = JSON.parse(raw);
+    }
+    catch (err) {
+        opts.out.warn('mcp.config_unparseable', { path: opts.sourceConfigPath, error: String(err) });
+        return undefined;
+    }
+    const framesPath = join(opts.runDir, 'mcp-frames.jsonl');
+    const shim = resolveShimEntry();
+    // Recording and replay are the same rewrite with a different flag: `--out` writes what the
+    // servers say, `--replay` says it back. Both keep `--out` so a replay records its own frames and
+    // is itself a run that can be read.
+    const shimArgs = opts.replayFrames === undefined
+        ? [shim, '--out', framesPath]
+        : [shim, '--out', framesPath, '--replay', opts.replayFrames];
+    const { config, rewritten, skipped } = rewriteMcpConfig(parsed, process.execPath, shimArgs);
+    const configPath = join(opts.runDir, 'mcp-config.json');
+    await writeFile(configPath, `${JSON.stringify(config, null, 2)}\n`, { mode: 0o600 });
+    opts.out.info('mcp.instrumented', {
+        servers: rewritten.length,
+        skipped: skipped.length,
+        mode: opts.replayFrames === undefined ? 'record' : 'replay',
+        config: configPath,
+    });
+    return {
+        configPath,
+        rewritten,
+        skipped,
+        async drain() {
+            const text = await readFile(framesPath, 'utf8').catch(() => '');
+            const records = [];
+            // A malformed capture line must never break the recorder; the agent's run matters more, and
+            // a line that a short write left holding a fragment and a record must still yield the record.
+            for (const parsed of text
+                .split('\n')
+                .flatMap((line) => objectsOnLine(line, MCP_RECORD_START))) {
+                if (usableFrame(parsed))
+                    records.push(parsed);
+            }
+            return records;
+        },
+    };
+}
+/**
+ * Locate the installed shim entry point, whether running from source or from a published dist.
+ *
+ * This used to ask for `@agenticreplay/mcp-shim/dist/cli.js` and fall back to `@agenticreplay/mcp-shim`
+ * when that threw. It always threw — the package declares an `exports` map, and an exports map
+ * blocks every subpath it does not list — so the fallback ran every time and resolved to
+ * `dist/index.js`, which is the library.
+ *
+ * The consequence was not a missing capture layer. Every stdio MCP server in the agent's config was
+ * rewritten to launch that module, which exports and exits: the real server was never started at
+ * all, so `--mcp-config` silently broke the agent's MCP servers *and* recorded nothing, while
+ * `agenticreplay doctor` reported the shim runnable because the wrong process exited 0.
+ *
+ * So: one declared subpath, and no fallback that can succeed with the wrong file. A resolution
+ * failure has to stay a failure — `setupMcpCapture` reports it, and the run continues without MCP
+ * capture, which is the honest outcome.
+ */
+function resolveShimEntry() {
+    const require = createRequire(import.meta.url);
+    return require.resolve('@agenticreplay/mcp-shim/cli');
+}
+/**
+ * Exposed for the doctor command: is the shim runnable at all?
+ *
+ * It checks that the thing it launched *is the shim*, not merely that a process started and
+ * stopped. Asking only for a clean exit is what let doctor vouch for a resolution that had landed
+ * on the library: that module exits 0 having done nothing, which is indistinguishable from success
+ * unless you look at what it said.
+ */
+export async function shimIsRunnable() {
+    let entry;
+    try {
+        entry = resolveShimEntry();
+    }
+    catch {
+        return false;
+    }
+    return new Promise((resolve) => {
+        const child = spawn(process.execPath, [entry, '--help'], {
+            stdio: ['ignore', 'ignore', 'pipe'],
+        });
+        let stderr = '';
+        child.stderr?.setEncoding('utf8');
+        child.stderr?.on('data', (chunk) => {
+            stderr += chunk;
+        });
+        child.on('error', () => resolve(false));
+        // `--help` is not a flag the shim takes, so it prints its usage and exits non-zero. That usage
+        // line is the identification: any other program is not this one.
+        child.on('close', () => resolve(stderr.includes('agenticreplay-mcp-shim --name')));
+    });
+}
+//# sourceMappingURL=mcp.js.map

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

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

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

@@ -0,0 +1,107 @@
+/**
+ * Terminal output.
+ *
+ * The CLI is most of this product's surface, and most of its output ends up somewhere that is not
+ * a terminal — a CI log, a pipe into grep, a pasted GitHub issue. So: colour only on a real TTY,
+ * no animation that corrupts a log, one greppable `level event key=value` line per fact, and
+ * errors that say what happened, what it means, and what to run next.
+ */
+export declare function stripAnsi(s: string): string;
+export declare function tame(text: string): string;
+/**
+ * A PATH AS SOMETHING A PERSON CAN PASTE.
+ *
+ * Several hints hand the reader a command with a path in it — `rm -rf <run>`, `cd <dir>` — and
+ * interpolated it bare. A path with a space in it then pastes as two arguments. Driven against a
+ * sandbox with the directory layout a Linux user named John Smith would have, the scrub hint
+ * `rm -rf /home/…/John Smith/proj/.agenticreplay/runs/run_x` deleted `/home/…/John` — someone else's
+ * directory — without a word, and left the run it was meant to delete exactly where it was.
+ *
+ * Left bare when nothing in it means anything to a shell, so an ordinary path prints as before.
+ * Otherwise POSIX gets single quotes, the one quoting in which nothing is special. Windows gets
+ * double quotes, which cmd, PowerShell and Git Bash all accept for a path — a Windows path cannot
+ * contain `"` — except when the path holds `$` or a backtick, which PowerShell expands inside
+ * double quotes; then it gets PowerShell's literal single quotes, because PowerShell is what a
+ * Windows terminal opens by default.
+ */
+export declare function shellArg(value: string, platform?: NodeJS.Platform): string;
+/**
+ * A command that deletes a directory, in the shell a person on this platform is most likely typing
+ * into. `rm -rf` is not a command there on Windows: PowerShell's `rm` is Remove-Item, which has
+ * `-Recurse` and no `-rf`, and cmd has no `rm` at all.
+ *
+ * `-LiteralPath`, because quoting stops the SHELL from globbing and Remove-Item globs by itself:
+ * its default `-Path` reads `[dev]` as a character class. In a sandbox holding `John [dev]\run_x`
+ * and a neighbour `John d\run_x`, the hint without it deleted the neighbour and left the run it
+ * named — the wrong-directory deletion this function exists to prevent, one layer further in.
+ */
+export declare function removeDirCommand(dir: string, platform?: NodeJS.Platform): string;
+/**
+ * `cd` to a directory, as a line a person can paste.
+ *
+ * PowerShell's `cd` is Set-Location, whose `-Path` also reads `[` and `]` as a wildcard class: the
+ * same sandbox took `cd "…\John [dev]"` to `John d`, and the replay hint follows that `cd` with
+ * `--in-place`. `-LiteralPath` is PowerShell's alone — cmd and Git Bash reject it — so it is used
+ * only for a path with a bracket in it, the one kind the three shells read differently.
+ */
+export declare function cdCommand(dir: string, platform?: NodeJS.Platform): string;
+export type Scalar = string | number | boolean | null | undefined;
+export type Fields = Record<string, Scalar>;
+/**
+ * One structured fact, before it is turned into a line of text.
+ *
+ * The same record that becomes `warn capture.empty exchanges=0 …` on a terminal. A caller that
+ * embedded agenticreplay has no stdout to read, and an agent asking for `--json` should not be handed
+ * prose to parse — so every fact is available as data at the point it is emitted, and the line is
+ * a rendering of it rather than the only form it ever takes.
+ *
+ * Fields arrive redacted, exactly as the terminal would show them: a key must not reach a JSON
+ * consumer just because it took a different route out.
+ */
+export interface LogEntry {
+    level: 'info' | 'warn' | 'error' | 'debug';
+    event: string;
+    fields: Record<string, Scalar>;
+}
+export interface OutputOptions {
+    write: (s: string) => void;
+    /** Receives every fact as data, in the order it was emitted. */
+    sink?: (entry: LogEntry) => void;
+    isTTY?: boolean;
+    env?: Record<string, string | undefined>;
+    verbose?: boolean;
+    ci?: boolean;
+    /** Explicit override from `--no-color`. Wins over TTY detection and NO_COLOR alike. */
+    color?: boolean;
+}
+export interface Failure {
+    event: string;
+    /** What happened. */
+    what: string;
+    /** What it means — the part that turns a message into an explanation. */
+    why?: string;
+    /** The next command to run. An error without this is a bug report we will receive instead. */
+    next?: string;
+}
+export declare class Output {
+    #private;
+    constructor(opts: OutputOptions);
+    get isVerbose(): boolean;
+    info(event: string, fields?: Fields): void;
+    warn(event: string, fields?: Fields): void;
+    error(event: string, fields?: Fields): void;
+    debug(event: string, fields?: Fields): void;
+    /** One line per phase. Always printed, including under --ci. */
+    phase(event: string, fields?: Fields): void;
+    /**
+     * Transient status. Printed only on an interactive TTY: in a pipe it is noise, and in CI it
+     * turns a log into thousands of lines of escape codes.
+     */
+    progress(message: string): void;
+    /** Free-form text for help and reports, where key=value would be worse than prose. */
+    plain(message?: string): void;
+    failure(f: Failure): void;
+    /** Aligned columns, no box drawing — a table people can pipe into awk. */
+    table(headers: string[], rows: string[][]): void;
+}
+//# sourceMappingURL=out.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"out.d.ts","sourceRoot":"","sources":["../src/out.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAgBH,wBAAgB,SAAS,CAAC,CAAC,EAAE,MAAM,GAAG,MAAM,CAE3C;AAuCD,wBAAgB,IAAI,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAQzC;AAED;;;;;;;;;;;;;;;GAeG;AACH,wBAAgB,QAAQ,CAAC,KAAK,EAAE,MAAM,EAAE,QAAQ,GAAE,MAAM,CAAC,QAA2B,GAAG,MAAM,CAO5F;AAED;;;;;;;;;GASG;AACH,wBAAgB,gBAAgB,CAC9B,GAAG,EAAE,MAAM,EACX,QAAQ,GAAE,MAAM,CAAC,QAA2B,GAC3C,MAAM,CAIR;AAED;;;;;;;GAOG;AACH,wBAAgB,SAAS,CAAC,GAAG,EAAE,MAAM,EAAE,QAAQ,GAAE,MAAM,CAAC,QAA2B,GAAG,MAAM,CAG3F;AAkBD,MAAM,MAAM,MAAM,GAAG,MAAM,GAAG,MAAM,GAAG,OAAO,GAAG,IAAI,GAAG,SAAS,CAAC;AAClE,MAAM,MAAM,MAAM,GAAG,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;AAE5C;;;;;;;;;;GAUG;AACH,MAAM,WAAW,QAAQ;IACvB,KAAK,EAAE,MAAM,GAAG,MAAM,GAAG,OAAO,GAAG,OAAO,CAAC;IAC3C,KAAK,EAAE,MAAM,CAAC;IACd,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;CAChC;AAED,MAAM,WAAW,aAAa;IAC5B,KAAK,EAAE,CAAC,CAAC,EAAE,MAAM,KAAK,IAAI,CAAC;IAC3B,gEAAgE;IAChE,IAAI,CAAC,EAAE,CAAC,KAAK,EAAE,QAAQ,KAAK,IAAI,CAAC;IACjC,KAAK,CAAC,EAAE,OAAO,CAAC;IAChB,GAAG,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,SAAS,CAAC,CAAC;IACzC,OAAO,CAAC,EAAE,OAAO,CAAC;IAClB,EAAE,CAAC,EAAE,OAAO,CAAC;IACb,uFAAuF;IACvF,KAAK,CAAC,EAAE,OAAO,CAAC;CACjB;AAED,MAAM,WAAW,OAAO;IACtB,KAAK,EAAE,MAAM,CAAC;IACd,qBAAqB;IACrB,IAAI,EAAE,MAAM,CAAC;IACb,yEAAyE;IACzE,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,8FAA8F;IAC9F,IAAI,CAAC,EAAE,MAAM,CAAC;CACf;AAED,qBAAa,MAAM;;gBAQL,IAAI,EAAE,aAAa;IAa/B,IAAI,SAAS,IAAI,OAAO,CAEvB;IAED,IAAI,CAAC,KAAK,EAAE,MAAM,EAAE,MAAM,GAAE,MAAW,GAAG,IAAI;IAI9C,IAAI,CAAC,KAAK,EAAE,MAAM,EAAE,MAAM,GAAE,MAAW,GAAG,IAAI;IAI9C,KAAK,CAAC,KAAK,EAAE,MAAM,EAAE,MAAM,GAAE,MAAW,GAAG,IAAI;IAI/C,KAAK,CAAC,KAAK,EAAE,MAAM,EAAE,MAAM,GAAE,MAAW,GAAG,IAAI;IAK/C,gEAAgE;IAChE,KAAK,CAAC,KAAK,EAAE,MAAM,EAAE,MAAM,GAAE,MAAW,GAAG,IAAI;IAI/C;;;OAGG;IACH,QAAQ,CAAC,OAAO,EAAE,MAAM,GAAG,IAAI;IAK/B,sFAAsF;IACtF,KAAK,CAAC,OAAO,SAAK,GAAG,IAAI;IAIzB,OAAO,CAAC,CAAC,EAAE,OAAO,GAAG,IAAI;IAkBzB,0EAA0E;IAC1E,KAAK,CAAC,OAAO,EAAE,MAAM,EAAE,EAAE,IAAI,EAAE,MAAM,EAAE,EAAE,GAAG,IAAI;CA6CjD"}