agenticreplay 0.1.0 → 0.1.2

package/packages/cli/src/api.ts

@@ -1,275 +0,0 @@
-import { resolve } from 'node:path';
-import {
-  TraceReader,
-  chainTo,
-  deriveCheckpoints,
-  listRuns,
-  resolveRunSelector,
-  runGraph,
-  type Checkpoint,
-  type RunGraph,
-  type RunRef,
-} from '@agenticreplay/core';
-import type { TraceEvent } from '@agenticreplay/schema';
-import { buildTimeline, detectLoops, exportTraceHtml, summarize } from '@agenticreplay/viewer';
-import { parseArgs } from './args.js';
-import { Output, type LogEntry } from './out.js';
-import { recordCommand, type RecordResult } from './commands/record.js';
-import { replayCommand, type ReplayResult } from './commands/replay.js';
-import { compareCommand, type CompareRow } from './commands/compare.js';
-
-/**
- * Driving agenticreplay from code.
- *
- * Everything agenticreplay knew was reachable only by running a command and reading a terminal: `agenticreplay show`
- * computed a timeline and formatted it away, `agenticreplay list` returned `void`. Anyone who wanted to ask
- * "what diverged when I replayed that run?" — a script, a CI job, an agent debugging its own
- * failure — had to parse `info replay.done reused=2/2 exact=2 divergences=0` out of stdout.
- *
- * This returns the same work as data. The commands render what it returns, so the terminal is a
- * view of one source of truth rather than the only place the truth exists. Two rules follow from
- * that and are asserted in the tests:
- *
- *   - Nothing here writes to the embedding process's stdout. A library that prints over its
- *     caller's output cannot be built on, and it breaks every JSON consumer downstream.
- *   - Nothing here calls `process.exit`. Failures throw errors that name the run.
- */
-
-export interface AgenticReplayOptions {
-  /** Project whose `.agenticreplay/runs` is being read. Defaults to the current directory. */
-  cwd?: string;
-  /** Receives agenticreplay's own log lines as structured records, for a caller that wants progress. */
-  onLog?: (entry: LogEntry) => void;
-}
-
-/** One row of `agenticreplay show`, as data rather than a formatted line. */
-export interface TimelineRow {
-  seq: number;
-  turn?: number;
-  kind: string;
-  label: string;
-  detail?: string;
-  meta?: string;
-}
-
-export interface Timeline {
-  runId: string;
-  adapter: string;
-  eventCount: number;
-  /** `null` where the run has no exit code — a trace cut short, not an exit of zero. */
-  exitCode: number | null;
-  /** Present when this run came from another — a fork, or an exact replay's own trace. */
-  parentRun?: string;
-  forkPoint?: number;
-  forkModel?: string;
-  usage: { input: number; output: number };
-  events: TimelineRow[];
-  /** Runs where the agent repeated itself rather than making progress. */
-  loops: {
-    turns: number[];
-    kind: 'repeated-action' | 'error-spin';
-    signature?: string;
-    repeats?: number;
-    tree?: string;
-  }[];
-}
-
-export interface RecordOptions {
-  /** Adapter id or alias, e.g. `claude`, `codex`, `node`, `generic-openai`. */
-  adapter: string;
-  /** The command to launch, for adapters that take one. */
-  command?: string[];
-  /** Origin overrides by dialect id, as `--upstream-anthropic` / `--upstream-openai` would set. */
-  upstream?: Record<string, string>;
-  /** Extra flags, passed through verbatim — the escape hatch for anything not modelled here. */
-  flags?: string[];
-}
-
-export interface RecordOutcome extends RecordResult {
-  /** Everything agenticreplay warned about during the run, so a caller with no terminal still sees it. */
-  warnings: LogEntry[];
-}
-
-export interface ReplayOptions {
-  /** Checkpoint to fork from. Omit for an exact replay. */
-  from?: number;
-  /** Model to run from the fork point onward. */
-  model?: string;
-  /** Run in a scratch worktree instead of over the working tree. */
-  worktree?: boolean;
-  flags?: string[];
-}
-
-export interface CompareOptions {
-  from?: number;
-  models: string[];
-  /** Command whose exit code is the verdict. */
-  verify?: string;
-  flags?: string[];
-}
-
-/**
- * What every command run through this API is told: agenticreplay's stdout belongs to someone else.
- *
- * `record`, `replay` and `compare` all spawn a real agent, and they spawn it with
- * `stdio: 'inherit'` — the file descriptor, which no in-process substitution can intercept. So an
- * embedded caller got the agent's output written over its own, and under `agenticreplay mcp` that
- * descriptor *is* the JSON-RPC transport: one line of agent chatter ends the session.
- *
- * `--json` is the existing spelling of "stdout is not a terminal here". The commands read it only
- * to route the child's stdout to stderr; the document itself is written by `jsonMain`, which this
- * path never reaches.
- */
-const QUIET = ['--json'] as const;
-
-export class AgenticReplay {
-  readonly cwd: string;
-  readonly #onLog: ((entry: LogEntry) => void) | undefined;
-
-  constructor(options: AgenticReplayOptions = {}) {
-    this.cwd = options.cwd ?? process.cwd();
-    this.#onLog = options.onLog;
-  }
-
-  // -------------------------------------------------------------------------
-  // reading
-  // -------------------------------------------------------------------------
-
-  /** Every run in this project, newest first. Empty rather than an error when there are none. */
-  async list(): Promise<RunRef[]> {
-    return listRuns(this.cwd);
-  }
-
-  /** The raw event stream. A rendered row is a view; this is the thing itself. */
-  async events(selector = 'last'): Promise<TraceEvent[]> {
-    return (await this.#reader(selector)).events();
-  }
-
-  /** What `agenticreplay show` prints, as objects. */
-  async show(selector = 'last'): Promise<Timeline> {
-    const reader = await this.#reader(selector);
-    const manifest = reader.manifest();
-    const events = await reader.events();
-    const summary = summarize(manifest, events);
-    return {
-      runId: summary.runId,
-      adapter: summary.adapter,
-      eventCount: summary.eventCount,
-      exitCode: summary.exitCode,
-      parentRun: manifest.parent_run,
-      forkPoint: manifest.fork_point,
-      forkModel: manifest.fork_model,
-      usage: { input: summary.totalUsage.input, output: summary.totalUsage.output },
-      events: buildTimeline(events).map((row) => ({
-        seq: row.seq,
-        turn: row.turn,
-        kind: row.kind,
-        label: row.label,
-        detail: row.detail,
-        meta: row.meta,
-      })),
-      loops: detectLoops(events).map((loop) => ({
-        turns: loop.turns,
-        kind: loop.kind,
-        signature: loop.signature,
-        repeats: loop.repeats,
-        tree: loop.tree,
-      })),
-    };
-  }
-
-  /** Where a fork can start: points whose conversation prefix is complete and tree was snapshotted. */
-  async checkpoints(selector = 'last'): Promise<Checkpoint[]> {
-    return deriveCheckpoints(await this.events(selector));
-  }
-
-  /**
-   * What caused what in a run, as nodes and typed edges.
-   *
-   * `to` narrows it to the chain that produced one event, which is the shape of an answer to
-   * "why did this fail" rather than "what happened". Every edge says whether the trace recorded
-   * it or this derived it, so a caller can weigh the two differently.
-   */
-  async graph(selector = 'last', options: { to?: number } = {}): Promise<RunGraph> {
-    const graph = runGraph(await this.events(selector));
-    return options.to === undefined ? graph : chainTo(graph, options.to);
-  }
-
-  /** The absolute path of a run's directory, for a caller that wants to read it directly. */
-  async runDir(selector = 'last'): Promise<string> {
-    return (await resolveRunSelector(this.cwd, selector)).dir;
-  }
-
-  // -------------------------------------------------------------------------
-  // doing
-  // -------------------------------------------------------------------------
-
-  async record(options: RecordOptions): Promise<RecordOutcome> {
-    const argv = ['record', options.adapter];
-    for (const [dialect, origin] of Object.entries(options.upstream ?? {})) {
-      // Flags are named for the provider, not the dialect: `openai-responses` shares
-      // `--upstream-openai` with chat completions, because it is one origin serving both.
-      argv.push(`--upstream-${dialect.replace(/-responses$/, '')}`, origin);
-    }
-    argv.push(...QUIET, ...(options.flags ?? []));
-    if (options.command && options.command.length > 0) argv.push('--', ...options.command);
-
-    const { out, entries } = this.#collect();
-    const result = await recordCommand(parseArgs(argv), out, this.cwd);
-    return {
-      ...result,
-      warnings: entries.filter((e) => e.level === 'warn' || e.level === 'error'),
-    };
-  }
-
-  async replay(selector = 'last', options: ReplayOptions = {}): Promise<ReplayResult> {
-    const argv = ['replay', selector];
-    if (options.from !== undefined) argv.push('--from', String(options.from));
-    if (options.model !== undefined) argv.push('--model', options.model);
-    if (options.worktree === true) argv.push('--worktree');
-    argv.push(...QUIET, ...(options.flags ?? []));
-    return replayCommand(parseArgs(argv), this.#collect().out, this.cwd);
-  }
-
-  async compare(selector = 'last', options: CompareOptions): Promise<CompareRow[]> {
-    const argv = ['compare', selector, '--models', options.models.join(',')];
-    if (options.from !== undefined) argv.push('--from', String(options.from));
-    if (options.verify !== undefined) argv.push('--verify', options.verify);
-    argv.push(...QUIET, ...(options.flags ?? []));
-    return compareCommand(parseArgs(argv), this.#collect().out, this.cwd);
-  }
-
-  /** Write the run as one self-contained HTML file. */
-  async export(
-    selector = 'last',
-    options: { out: string },
-  ): Promise<{ path: string; bytes: number }> {
-    return exportTraceHtml(await this.runDir(selector), resolve(this.cwd, options.out));
-  }
-
-  // -------------------------------------------------------------------------
-
-  async #reader(selector: string): Promise<TraceReader> {
-    return TraceReader.open((await resolveRunSelector(this.cwd, selector)).dir);
-  }
-
-  /**
-   * An `Output` that goes nowhere near a terminal.
-   *
-   * The commands were written to print, and rewriting all of them to return data instead would be
-   * a much larger change than the one that is actually needed — so the API gives them a sink that
-   * keeps the facts and drops the formatting.
-   */
-  #collect(): { out: Output; entries: LogEntry[] } {
-    const entries: LogEntry[] = [];
-    const onLog = this.#onLog;
-    const out = new Output({
-      write: () => {},
-      sink: (entry) => {
-        entries.push(entry);
-        onLog?.(entry);
-      },
-    });
-    return { out, entries };
-  }
-}

package/packages/cli/src/archive.ts

@@ -1,264 +0,0 @@
-import { deflateRawSync, inflateRawSync } from 'node:zlib';
-
-/**
- * The zip subset a trace archive needs, written by hand.
- *
- * The CLI takes no new runtime dependencies (CONTRIBUTING, "Rules of the road"), and a debugger
- * people install to diagnose a broken environment is the worst possible place to drag one in. zlib
- * is a node builtin, and what remains — a local header, a central directory and a trailer — is
- * about a hundred lines. `archive.test.ts` is what makes that defensible rather than merely brief.
- *
- * ONE PROPERTY GOVERNS EVERYTHING HERE: entry bytes round-trip EXACTLY. The gateway recomputes the
- * integrity root over `events.jsonl` and refuses a push whose root does not match the manifest, so
- * an archiver that re-serialised JSON, normalised a newline or reordered keys would produce a file
- * that looks equivalent and is rejected on arrival. Nothing in this file parses an entry's content.
- */
-export interface ArchiveEntry {
-  /** Path inside the archive, `<run_id>/manifest.json` and friends. */
-  name: string;
-  bytes: Uint8Array;
-}
-
-const LOCAL_SIG = 0x04034b50;
-const CENTRAL_SIG = 0x02014b50;
-const EOCD_SIG = 0x06054b50;
-const EOCD_LEN = 22;
-/** Zip64 puts this in a 32-bit field it cannot hold, and the real value in an extra record. */
-const ZIP32_SENTINEL = 0xffffffff;
-
-/**
- * CRC-32 (IEEE), computed here rather than taken from `zlib.crc32`.
- *
- * That builtin landed in Node 20.15, while the published CLI requires Node 24 — keeping the local
- * implementation avoids making archive support depend on a newer patch-level builtin detail.
- */
-const CRC_TABLE = (() => {
-  const table = new Uint32Array(256);
-  for (let i = 0; i < 256; i++) {
-    let c = i;
-    for (let k = 0; k < 8; k++) c = c & 1 ? 0xedb88320 ^ (c >>> 1) : c >>> 1;
-    table[i] = c >>> 0;
-  }
-  return table;
-})();
-
-export function crc32(bytes: Uint8Array): number {
-  let c = 0xffffffff;
-  for (let i = 0; i < bytes.length; i++) c = CRC_TABLE[(c ^ bytes[i]!) & 0xff]! ^ (c >>> 8);
-  return (c ^ 0xffffffff) >>> 0;
-}
-
-/**
- * Reject a name that would write outside the run directory when `agenticreplay pull` unpacks it.
- *
- * Checked where the name is PARSED rather than where it is used: pull is not the only future
- * caller, and a check in the caller is one a later caller forgets. A trace names its entries
- * `<run_id>/manifest.json` and `<run_id>/blobs/<ab>/<sha>`, so anything absolute, anything with a
- * `..` segment and anything carrying a backslash is either a bug upstream or an attack.
- */
-function assertSafeName(name: string): void {
-  if (name === '' || name.length > 512) throw new Error(`unsafe archive entry name: ${name}`);
-  if (name.startsWith('/') || /^[A-Za-z]:/.test(name) || name.includes('\\')) {
-    throw new Error(`unsafe archive entry name: ${name}`);
-  }
-  if (name.split('/').some((seg) => seg === '..')) {
-    throw new Error(`unsafe archive entry name: ${name}`);
-  }
-}
-
-/** Serialise entries as a zip. Deflated, unless deflating made the entry bigger. */
-export async function writeArchive(entries: ArchiveEntry[]): Promise<Uint8Array> {
-  /**
-   * REFUSE WHAT THE FORMAT CANNOT EXPRESS, RATHER THAN TRUNCATING IT.
-   *
-   * The trailer counts entries in 16 bits and records sizes and offsets in 32.
-   * Writing a larger value silently keeps its low bits, and the damage is
-   * graded — worst in the middle:
-   *
-   *   65535 entries  -> the count IS the zip64 sentinel, and readArchive
-   *                     refuses the file outright
-   *   65536          -> wraps to 0, and readArchive returns nothing
-   *   70000          -> wraps to 4464, and readArchive SUCCEEDS with 4464 of
-   *                     them
-   *
-   * That last band is the one that matters: `agenticreplay push` sends a structurally
-   * corrupt archive, and `agenticreplay pull` installs a fraction of the run and
-   * reports success. Silent partial loss is exactly what this file's governing
-   * property — entry bytes round-trip EXACTLY — exists to rule out, and a run
-   * directory holds one file per unique content-addressed blob, so a long
-   * session with heavy tool output reaches these counts without trying.
-   *
-   * Refusing rather than emitting zip64: readArchive refuses zip64 too, so
-   * writing it would produce archives this CLI cannot read back — trading a
-   * silent truncation for a confident file nothing here can open. A bound that
-   * says so is the honest answer until both halves learn the format.
-   */
-  const MAX_ENTRIES = 0xfffe; // 0xffff is the reader's zip64 sentinel
-  if (entries.length > MAX_ENTRIES) {
-    throw new Error(
-      `archive has too many entries: ${entries.length}, and a zip trailer counts at most ${MAX_ENTRIES}`,
-    );
-  }
-
-  const chunks: Uint8Array[] = [];
-  const central: Uint8Array[] = [];
-  let offset = 0;
-
-  for (const entry of entries) {
-    const name = new TextEncoder().encode(entry.name);
-    const crc = crc32(entry.bytes);
-    const deflated = entry.bytes.length === 0 ? new Uint8Array(0) : deflateRawSync(entry.bytes);
-    // An already-compressed blob (an image, a zip) inflates under deflate. Storing it then costs
-    // less than compressing it, and the reader handles both.
-    const stored = entry.bytes.length === 0 || deflated.length >= entry.bytes.length;
-    const payload = stored ? entry.bytes : deflated;
-    const method = stored ? 0 : 8;
-
-    // The same refusal for the 32-bit size and offset fields. Each is checked
-    // where it is about to be written rather than once at the end, so the
-    // message names the entry that overflows instead of the total.
-    if (payload.length >= ZIP32_SENTINEL || entry.bytes.length >= ZIP32_SENTINEL) {
-      throw new Error(`archive entry is too large for a 32-bit zip field: ${entry.name}`);
-    }
-    if (offset >= ZIP32_SENTINEL) {
-      throw new Error(`archive is too large for a 32-bit zip offset at entry: ${entry.name}`);
-    }
-
-    const local = new Uint8Array(30 + name.length);
-    const lv = new DataView(local.buffer);
-    lv.setUint32(0, LOCAL_SIG, true);
-    lv.setUint16(4, 20, true); // version needed
-    lv.setUint16(6, 0, true); // flags
-    lv.setUint16(8, method, true);
-    // A FIXED timestamp, so the same run produces the same bytes twice. A wall clock here would
-    // make every push a different archive and every digest comparison meaningless.
-    lv.setUint16(10, 0, true);
-    lv.setUint16(12, 0x21, true); // 1980-01-01, the DOS epoch
-    lv.setUint32(14, crc, true);
-    lv.setUint32(18, payload.length, true);
-    lv.setUint32(22, entry.bytes.length, true);
-    lv.setUint16(26, name.length, true);
-    lv.setUint16(28, 0, true);
-    local.set(name, 30);
-
-    const head = new Uint8Array(46 + name.length);
-    const cv = new DataView(head.buffer);
-    cv.setUint32(0, CENTRAL_SIG, true);
-    cv.setUint16(4, 20, true); // version made by
-    cv.setUint16(6, 20, true); // version needed
-    cv.setUint16(8, 0, true);
-    cv.setUint16(10, method, true);
-    cv.setUint16(12, 0, true);
-    cv.setUint16(14, 0x21, true);
-    cv.setUint32(16, crc, true);
-    cv.setUint32(20, payload.length, true);
-    cv.setUint32(24, entry.bytes.length, true);
-    cv.setUint16(28, name.length, true);
-    cv.setUint32(42, offset, true);
-    head.set(name, 46);
-
-    chunks.push(local, payload);
-    central.push(head);
-    offset += local.length + payload.length;
-  }
-
-  const centralSize = central.reduce((n, c) => n + c.length, 0);
-  if (centralSize >= ZIP32_SENTINEL || offset >= ZIP32_SENTINEL) {
-    throw new Error('archive is too large for a 32-bit zip trailer');
-  }
-  const eocd = new Uint8Array(EOCD_LEN);
-  const ev = new DataView(eocd.buffer);
-  ev.setUint32(0, EOCD_SIG, true);
-  ev.setUint16(8, entries.length, true);
-  ev.setUint16(10, entries.length, true);
-  ev.setUint32(12, centralSize, true);
-  ev.setUint32(16, offset, true);
-
-  const total = [...chunks, ...central, eocd];
-  const size = total.reduce((n, c) => n + c.length, 0);
-  const out = new Uint8Array(size);
-  let at = 0;
-  for (const c of total) {
-    out.set(c, at);
-    at += c.length;
-  }
-  return out;
-}
-
-/** Read a zip written by this file or by the gateway's Go writer. */
-export async function readArchive(bytes: Uint8Array): Promise<ArchiveEntry[]> {
-  const view = new DataView(bytes.buffer, bytes.byteOffset, bytes.byteLength);
-
-  // The trailer is last, but a zip may carry a comment after it, so scan back for the signature.
-  let eocd = -1;
-  for (let i = bytes.length - EOCD_LEN; i >= 0 && i >= bytes.length - EOCD_LEN - 0xffff; i--) {
-    if (view.getUint32(i, true) === EOCD_SIG) {
-      eocd = i;
-      break;
-    }
-  }
-  if (eocd < 0) throw new Error('not a zip archive: no end-of-central-directory record');
-
-  const count = view.getUint16(eocd + 10, true);
-  const centralSize = view.getUint32(eocd + 12, true);
-  const centralOffset = view.getUint32(eocd + 16, true);
-  if (count === 0xffff || centralSize === ZIP32_SENTINEL || centralOffset === ZIP32_SENTINEL) {
-    throw new Error('zip64 archives are not supported');
-  }
-
-  /**
-   * WHERE THE ENTRIES REALLY START.
-   *
-   * `centralOffset` is relative to the start of the archive, which is not necessarily the start of
-   * the FILE: a zip appended to something else (a self-extracting stub, a concatenated download)
-   * shifts every recorded offset by a constant. Recovering that constant from the trailer — whose
-   * own position is known — is what makes such an archive readable, and it is zero for an ordinary
-   * one, so the arithmetic costs nothing in the common case.
-   */
-  const base = eocd - centralSize - centralOffset;
-  if (base < 0) throw new Error('malformed zip: central directory does not fit before its trailer');
-
-  const out: ArchiveEntry[] = [];
-  let at = base + centralOffset;
-  for (let i = 0; i < count; i++) {
-    if (at + 46 > bytes.length || view.getUint32(at, true) !== CENTRAL_SIG) {
-      throw new Error('malformed zip: central directory entry is not where the trailer says');
-    }
-    const method = view.getUint16(at + 10, true);
-    const compressed = view.getUint32(at + 20, true);
-    const uncompressed = view.getUint32(at + 24, true);
-    const nameLen = view.getUint16(at + 28, true);
-    const extraLen = view.getUint16(at + 30, true);
-    const commentLen = view.getUint16(at + 32, true);
-    const localOffset = view.getUint32(at + 42, true);
-    if (compressed === ZIP32_SENTINEL || uncompressed === ZIP32_SENTINEL) {
-      throw new Error('zip64 archives are not supported');
-    }
-    const name = new TextDecoder().decode(bytes.subarray(at + 46, at + 46 + nameLen));
-    assertSafeName(name);
-
-    // The local header repeats the name and extra fields, and its lengths are the authority on
-    // where the data begins — a central-directory extra length does not have to match it.
-    const local = base + localOffset;
-    if (local + 30 > bytes.length || view.getUint32(local, true) !== LOCAL_SIG) {
-      throw new Error(`malformed zip: no local header for ${name}`);
-    }
-    const localName = view.getUint16(local + 26, true);
-    const localExtra = view.getUint16(local + 28, true);
-    const start = local + 30 + localName + localExtra;
-    if (start + compressed > bytes.length) {
-      throw new Error(`malformed zip: ${name} runs past the end of the archive`);
-    }
-    const payload = bytes.subarray(start, start + compressed);
-    const data = method === 0 ? new Uint8Array(payload) : new Uint8Array(inflateRawSync(payload));
-    if (data.length !== uncompressed) {
-      throw new Error(`malformed zip: ${name} is ${data.length} bytes, expected ${uncompressed}`);
-    }
-    if (crc32(data) !== view.getUint32(at + 16, true)) {
-      throw new Error(`malformed zip: ${name} failed its checksum`);
-    }
-    out.push({ name, bytes: data });
-    at += 46 + nameLen + extraLen + commentLen;
-  }
-  return out;
-}