orcareplay 0.1.0

package/dist/commands/gc.js

@@ -0,0 +1,326 @@
+import { createReadStream } from 'node:fs';
+import { readFile, readdir, rm, rmdir, stat, unlink } from 'node:fs/promises';
+import { basename, dirname, join, resolve } from 'node:path';
+import { tmpdir } from 'node:os';
+import { createInterface } from 'node:readline';
+import { listRuns, runsDir } from '@orcareplay/core';
+const UNITS = {
+    s: 1_000,
+    m: 60_000,
+    h: 3_600_000,
+    d: 86_400_000,
+    w: 604_800_000,
+};
+const HEX64 = /^[0-9a-f]{64}$/;
+/** Any digest mentioned anywhere in an event line counts as a reference. See {@link inspectRun}. */
+const DIGEST_IN_LINE = /[0-9a-f]{64}/g;
+/** Milliseconds for `7d`, `24h`, `30m`; null for anything it will not guess at. */
+export function parseDuration(text) {
+    const match = /^(\d+(?:\.\d+)?)([smhdw])$/.exec(text.trim().toLowerCase());
+    if (!match)
+        return null;
+    const unit = UNITS[match[2]];
+    if (unit === undefined)
+        return null;
+    return Number(match[1]) * unit;
+}
+/**
+ * `orca gc` — reclaim the space a trace store grows into.
+ *
+ * A run is append-only and content-addressed, so nothing inside one grows unboundedly. What grows
+ * is the number of runs, and the blobs left behind when a run died between writing a payload and
+ * writing the event that referenced it. Removing runs is therefore opt-in: with no retention flag
+ * this only sweeps that debris and reports what it would take if asked.
+ */
+export async function gcCommand(args, out, cwd = process.cwd()) {
+    const dryRun = args.bool('dry-run');
+    const olderThanMs = readOlderThan(args);
+    const keep = readKeep(args);
+    const runs = await listRuns(cwd);
+    if (runs.length === 0) {
+        out.plain(`no runs in ${runsDir(cwd)} — nothing to reclaim`);
+        return { runsRemoved: 0, worktreesRemoved: 0, blobsRemoved: 0, bytesReclaimed: 0 };
+    }
+    const facts = [];
+    for (const run of runs)
+        facts.push(await inspectRun(run.runId, run.dir, run.createdAt));
+    // `facts` is newest first, so --keep is simply the first n entries.
+    const cutoff = olderThanMs === undefined ? undefined : Date.now() - olderThanMs;
+    const doomed = new Set();
+    facts.forEach((run, index) => {
+        if (cutoff === undefined && keep === undefined)
+            return;
+        // Both flags are constraints, not alternatives: --keep is a floor under --older-than.
+        if (cutoff !== undefined && run.createdMs >= cutoff)
+            return;
+        if (keep !== undefined && index < keep)
+            return;
+        doomed.add(run.runId);
+    });
+    // Forking is the point of this tool, and a fork's provenance is a pointer to a run that must
+    // still be there. Rescuing a parent can expose a grandparent, so this runs to a fixed point.
+    const rescued = new Map();
+    for (let changed = true; changed;) {
+        changed = false;
+        for (const run of facts) {
+            if (doomed.has(run.runId))
+                continue;
+            const parent = run.parentRun;
+            if (parent !== undefined && doomed.delete(parent)) {
+                rescued.set(parent, run.runId);
+                changed = true;
+            }
+        }
+    }
+    if (dryRun)
+        out.plain('dry run — nothing will be removed');
+    out.table(['RUN', 'CREATED', 'SIZE', 'ACTION'], facts.map((run) => [
+        run.runId,
+        run.createdAt,
+        formatBytes(run.bytes),
+        doomed.has(run.runId)
+            ? 'remove'
+            : rescued.has(run.runId)
+                ? `keep — parent of ${rescued.get(run.runId)}`
+                : 'keep',
+    ]));
+    for (const [parent, child] of rescued) {
+        out.warn('gc.parent_kept', { run: parent, child, why: 'a surviving run forked from it' });
+    }
+    let runsRemoved = 0;
+    let worktreesRemoved = 0;
+    let blobsRemoved = 0;
+    let bytesReclaimed = 0;
+    for (const run of facts) {
+        if (!doomed.has(run.runId))
+            continue;
+        runsRemoved += 1;
+        bytesReclaimed += run.bytes;
+        if (!dryRun)
+            await rm(run.dir, { recursive: true, force: true });
+        // The fork's scratch worktree goes with its run. It is deliberately *not* removed when the
+        // fork finishes — it holds what the model actually did, so deleting it then would destroy the
+        // thing you forked in order to look at — but nothing reclaimed it either, so a single
+        // `orca compare --models a,b,c,d` left four full copies of the workspace behind forever.
+        if (run.worktree !== undefined) {
+            worktreesRemoved += 1;
+            bytesReclaimed += await runDirBytes(run.worktree);
+            if (!dryRun)
+                await rm(run.worktree, { recursive: true, force: true });
+        }
+    }
+    for (const run of facts) {
+        if (doomed.has(run.runId))
+            continue;
+        if (run.skippedReason !== undefined) {
+            out.warn('gc.blobs_skipped', { run: run.runId, why: run.skippedReason });
+            continue;
+        }
+        if (run.orphans.length === 0)
+            continue;
+        const shards = new Set();
+        for (const orphan of run.orphans) {
+            blobsRemoved += 1;
+            bytesReclaimed += orphan.bytes;
+            shards.add(orphan.shard);
+            if (!dryRun)
+                await unlink(orphan.path).catch(() => undefined);
+        }
+        out.info('gc.orphans', {
+            run: run.runId,
+            blobs: run.orphans.length,
+            bytes: run.orphans.reduce((sum, o) => sum + o.bytes, 0),
+        });
+        // An empty shard directory is just clutter; a non-empty one refuses and that is fine.
+        if (!dryRun)
+            for (const shard of shards)
+                await rmdir(shard).catch(() => undefined);
+    }
+    if (olderThanMs === undefined && keep === undefined) {
+        out.plain('');
+        out.plain('  no run was removed — say which ones you mean:');
+        out.plain('    orca gc --older-than 7d      # by age');
+        out.plain('    orca gc --keep 10            # by count');
+        out.plain('    add --dry-run to see the plan first');
+    }
+    out.phase('gc', {
+        runs: runsRemoved,
+        worktrees: worktreesRemoved || undefined,
+        blobs: blobsRemoved,
+        bytes: bytesReclaimed,
+        dry_run: dryRun || undefined,
+    });
+    return { runsRemoved, worktreesRemoved, blobsRemoved, bytesReclaimed };
+}
+/**
+ * Does this path look like a directory orca made for a fork to run in?
+ *
+ * Deliberately narrow, and deliberately only half the test — the caller also requires the run to
+ * carry a `fork_point`. Directly inside the OS temp directory, with the prefix `replayFork` uses.
+ * Anything else is left alone, including a fork whose worktree someone moved somewhere they care
+ * about: an unreclaimed directory costs disk, and the alternative costs somebody's work.
+ *
+ * So `orca replay --worktree` is out of reach here, because an exact replay's trace has no fork
+ * point. That is the right way round: you asked for a scratch copy to look at, orca printed where
+ * it put it, and a garbage collector that deletes the thing you asked to keep is worse than one
+ * that leaves a directory behind. The pre-replay safety snapshot is not gc's problem either —
+ * replay owns that one and removes it once your files are back.
+ */
+function isScratchWorktree(dir) {
+    return resolve(dirname(dir)) === resolve(tmpdir()) && basename(dir).startsWith('orca-');
+}
+function readOlderThan(args) {
+    if (!args.has('older-than'))
+        return undefined;
+    const raw = args.str('older-than');
+    const ms = raw === undefined ? null : parseDuration(raw);
+    if (ms === null) {
+        throw new Error(`--older-than needs a duration like 7d, 24h or 30m${raw === undefined ? '' : ` — got ${JSON.stringify(raw)}`}\n` +
+            'units are s, m, h, d, w; for example: orca gc --older-than 7d --dry-run');
+    }
+    return ms;
+}
+function readKeep(args) {
+    if (!args.has('keep'))
+        return undefined;
+    const n = args.num('keep');
+    if (n === undefined || !Number.isInteger(n) || n < 0) {
+        throw new Error('--keep needs a whole number of runs to keep, like --keep 10\n' +
+            'it keeps the n most recent runs and removes the rest');
+    }
+    return n;
+}
+async function inspectRun(runId, dir, createdAt) {
+    const facts = {
+        runId,
+        dir,
+        createdAt,
+        createdMs: Date.parse(createdAt),
+        bytes: await runDirBytes(dir),
+        orphans: [],
+    };
+    if (Number.isNaN(facts.createdMs))
+        facts.createdMs = 0;
+    let sealed = false;
+    try {
+        const manifest = JSON.parse(await readFile(join(dir, 'manifest.json'), 'utf8'));
+        if (typeof manifest.parent_run === 'string')
+            facts.parentRun = manifest.parent_run;
+        // Only a fork's cwd is ever ours to delete. A plain recording runs in the user's project, and
+        // `gc` removing that would be the worst bug this tool could have — so the fork check is the
+        // load-bearing half of the guard, and the path check is the belt.
+        //
+        // The fork check is `fork_point`, not `parent_run`. It used to be the latter, back when the
+        // only run with a parent was a fork; an exact replay now writes a trace of its own findings
+        // that also names a parent, and it ran in the user's *own* directory. A project that happens
+        // to live at $TMPDIR/orca-something would have satisfied the belt on its own, and the run
+        // holding the evidence of what happened there is the one gc would have used to delete it.
+        if (typeof manifest.fork_point === 'number' &&
+            typeof manifest.cwd === 'string' &&
+            isScratchWorktree(manifest.cwd)) {
+            facts.worktree = manifest.cwd;
+        }
+        sealed = typeof manifest.ended_at === 'string';
+    }
+    catch {
+        // A run whose manifest is unreadable is still a directory with a size; it just cannot be
+        // proven finished, so the guards below leave its blobs alone.
+    }
+    const eventsPath = join(dir, 'events.jsonl');
+    const referenced = new Set();
+    let readable = false;
+    try {
+        const lines = createInterface({
+            input: createReadStream(eventsPath),
+            crlfDelay: Number.POSITIVE_INFINITY,
+        });
+        try {
+            for await (const line of lines) {
+                // Match digests in the raw line rather than walking parsed payloads: a blob referenced
+                // from somewhere this build does not know about must still count as referenced.
+                for (const digest of line.match(DIGEST_IN_LINE) ?? [])
+                    referenced.add(digest);
+                if (facts.parentRun === undefined && line.includes('"fork"')) {
+                    facts.parentRun = forkParentOf(line);
+                }
+            }
+        }
+        finally {
+            lines.close();
+        }
+        readable = true;
+    }
+    catch {
+        readable = false;
+    }
+    if (!sealed) {
+        facts.skippedReason = 'run is not sealed — it may still be recording';
+        return facts;
+    }
+    if (!readable) {
+        facts.skippedReason = 'events.jsonl is unreadable, so every blob would look unreferenced';
+        return facts;
+    }
+    facts.orphans = await orphanBlobs(join(dir, 'blobs'), referenced);
+    return facts;
+}
+/** The parent a forked run names in its own `fork` event — where replay records provenance. */
+function forkParentOf(line) {
+    try {
+        const event = JSON.parse(line);
+        if (event.type !== 'fork')
+            return undefined;
+        const parent = event.attrs?.parent_run;
+        return typeof parent === 'string' ? parent : undefined;
+    }
+    catch {
+        return undefined;
+    }
+}
+async function orphanBlobs(blobsRoot, referenced) {
+    const orphans = [];
+    for (const shard of await readdir(blobsRoot, { withFileTypes: true }).catch(() => [])) {
+        if (!shard.isDirectory())
+            continue;
+        const shardDir = join(blobsRoot, shard.name);
+        for (const name of await readdir(shardDir).catch(() => [])) {
+            // Only files named as a digest: a half-written `.tmp` belongs to whoever is writing it.
+            if (!HEX64.test(name) || referenced.has(name))
+                continue;
+            const path = join(shardDir, name);
+            const info = await stat(path).catch(() => null);
+            if (!info?.isFile())
+                continue;
+            orphans.push({ path, shard: shardDir, bytes: info.size });
+        }
+    }
+    return orphans;
+}
+/** Every byte of file content under a run directory. Shared with `orca doctor`. */
+export async function runDirBytes(dir) {
+    let total = 0;
+    for (const entry of await readdir(dir, { withFileTypes: true }).catch(() => [])) {
+        const path = join(dir, entry.name);
+        if (entry.isDirectory()) {
+            total += await runDirBytes(path);
+            continue;
+        }
+        const info = await stat(path).catch(() => null);
+        if (info?.isFile())
+            total += info.size;
+    }
+    return total;
+}
+export function formatBytes(bytes) {
+    if (bytes < 1024)
+        return `${bytes} B`;
+    const units = ['KB', 'MB', 'GB', 'TB'];
+    let value = bytes / 1024;
+    let unit = 0;
+    while (value >= 1024 && unit < units.length - 1) {
+        value /= 1024;
+        unit += 1;
+    }
+    return `${value.toFixed(1)} ${units[unit]}`;
+}
+//# sourceMappingURL=gc.js.map

package/dist/commands/gc.js.map

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

package/dist/commands/inspect.d.ts

@@ -0,0 +1,24 @@
+import type { RunGraph } from '@orcareplay/core';
+import type { Output } from '../out.js';
+import type { ParsedArgs } from '../args.js';
+/** `orca list` — what runs are here, newest first. */
+export declare function listCommand(args: ParsedArgs, out: Output, cwd?: string): Promise<void>;
+/** `orca show` — the timeline, in the terminal. */
+export declare function showCommand(args: ParsedArgs, out: Output, cwd?: string): Promise<void>;
+/** `orca checkpoints` — where can I fork from? */
+export declare function checkpointsCommand(args: ParsedArgs, out: Output, cwd?: string): Promise<void>;
+/**
+ * `orca graph` — what caused what.
+ *
+ * The timeline says what happened in what order; this says what produced what. Every row names
+ * both ends and, crucially, whether the trace vouches for the edge or a rule here worked it out —
+ * a reader who cannot tell the two apart has been handed a guess dressed as a fact.
+ */
+export declare function graphCommand(args: ParsedArgs, out: Output, cwd?: string): Promise<void>;
+/** The whole graph, or just the chain that produced `to`. */
+export declare function narrow(graph: RunGraph, to: number | undefined): RunGraph;
+/** `orca export` — the single self-contained file that makes a trace shareable. */
+export declare function exportCommand(args: ParsedArgs, out: Output, cwd?: string): Promise<void>;
+/** `orca ui` — the same viewer, served locally. */
+export declare function uiCommand(args: ParsedArgs, out: Output, cwd?: string): Promise<void>;
+//# sourceMappingURL=inspect.d.ts.map

package/dist/commands/inspect.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"inspect.d.ts","sourceRoot":"","sources":["../../src/commands/inspect.ts"],"names":[],"mappings":"AAWA,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,kBAAkB,CAAC;AASjD,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,WAAW,CAAC;AACxC,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,YAAY,CAAC;AAK7C,sDAAsD;AACtD,wBAAsB,WAAW,CAC/B,IAAI,EAAE,UAAU,EAChB,GAAG,EAAE,MAAM,EACX,GAAG,SAAgB,GAClB,OAAO,CAAC,IAAI,CAAC,CAyBf;AAED,mDAAmD;AACnD,wBAAsB,WAAW,CAC/B,IAAI,EAAE,UAAU,EAChB,GAAG,EAAE,MAAM,EACX,GAAG,SAAgB,GAClB,OAAO,CAAC,IAAI,CAAC,CAsEf;AAED,kDAAkD;AAClD,wBAAsB,kBAAkB,CACtC,IAAI,EAAE,UAAU,EAChB,GAAG,EAAE,MAAM,EACX,GAAG,SAAgB,GAClB,OAAO,CAAC,IAAI,CAAC,CAmBf;AAED;;;;;;GAMG;AACH,wBAAsB,YAAY,CAChC,IAAI,EAAE,UAAU,EAChB,GAAG,EAAE,MAAM,EACX,GAAG,SAAgB,GAClB,OAAO,CAAC,IAAI,CAAC,CAgCf;AAED,6DAA6D;AAC7D,wBAAgB,MAAM,CAAC,KAAK,EAAE,QAAQ,EAAE,EAAE,EAAE,MAAM,GAAG,SAAS,GAAG,QAAQ,CAExE;AAyBD,mFAAmF;AACnF,wBAAsB,aAAa,CACjC,IAAI,EAAE,UAAU,EAChB,GAAG,EAAE,MAAM,EACX,GAAG,SAAgB,GAClB,OAAO,CAAC,IAAI,CAAC,CA+Ef;AAED,mDAAmD;AACnD,wBAAsB,SAAS,CAAC,IAAI,EAAE,UAAU,EAAE,GAAG,EAAE,MAAM,EAAE,GAAG,SAAgB,GAAG,OAAO,CAAC,IAAI,CAAC,CAQjG"}

package/dist/commands/inspect.js

@@ -0,0 +1,262 @@
+import { resolve } from 'node:path';
+import { writeFile } from 'node:fs/promises';
+import { TraceReader, chainTo, deriveCheckpoints, listRuns, pickChainTarget, resolveRunSelector, runGraph, } from '@orcareplay/core';
+import { buildTimeline, detectLoops, exportTraceHtml, serveViewer, summarize, } from '@orcareplay/viewer';
+import { priceFor } from '@orcareplay/providers';
+import { formatCost } from './compare.js';
+import { renderChainCard, renderGraphCard, scopeForCard } from '../share-card.js';
+import { cardTarget, gifFrames, svgToPng, svgsToGif } from '../rasterize.js';
+/** `orca list` — what runs are here, newest first. */
+export async function listCommand(args, out, cwd = process.cwd()) {
+    const runs = await listRuns(cwd);
+    if (runs.length === 0) {
+        out.plain('no runs recorded yet');
+        out.plain('');
+        out.plain('  orca record claude      # record one');
+        return;
+    }
+    // FROM is what makes a directory full of `orca compare` output readable: four runs with no
+    // stated relationship are four mysteries, and the relationship is already in every manifest.
+    out.table(['RUN', 'CREATED', 'FROM', 'DIR'], runs.map((r) => [
+        r.runId,
+        r.createdAt,
+        // `@<seq>` only where there is a fork point. A replay trace has a parent and no checkpoint,
+        // and `run_x@?` reads as missing data rather than as the different thing it is.
+        r.parentRun === undefined
+            ? ''
+            : r.forkPoint === undefined
+                ? r.parentRun
+                : `${r.parentRun}@${r.forkPoint}`,
+        r.dir,
+    ]));
+}
+/** `orca show` — the timeline, in the terminal. */
+export async function showCommand(args, out, cwd = process.cwd()) {
+    const reader = await TraceReader.open((await resolveRunSelector(cwd, args.positionals[0] ?? 'last')).dir);
+    const manifest = reader.manifest();
+    const events = await reader.events();
+    const summary = summarize(manifest, events);
+    out.plain(`${summary.runId}  ${summary.adapter}  ${summary.eventCount} events  exit ${summary.exitCode ?? 0}`);
+    // A forked run's timeline opens mid-conversation in a worktree that no longer exists. Without
+    // this line the only way to learn where it came from is to cat the manifest — for the feature
+    // the tool is named after.
+    if (manifest.parent_run !== undefined) {
+        // `parent_run` no longer implies a fork. An exact replay writes its own run with a parent and
+        // deliberately no `fork_point`, so keying the wording on that field is what tells the two
+        // apart — and stops the line reading "at checkpoint undefined", which looks like a corrupt
+        // trace rather than the different thing it actually is.
+        if (manifest.fork_point === undefined) {
+            out.plain(`  replay of ${manifest.parent_run}`);
+        }
+        else {
+            const model = manifest.fork_model === undefined ? '' : ` on ${manifest.fork_model}`;
+            out.plain(`  forked from ${manifest.parent_run} at checkpoint ${manifest.fork_point}${model}`);
+        }
+    }
+    out.plain('');
+    // Both halves of the row. Rendering only `meta` showed token counts for a model response and an
+    // empty cell for everything else — which quietly dropped a shell command's exit code, a tool
+    // result's success or failure, and the stop reason, leaving a call and its result looking like
+    // the same row printed twice.
+    // Indented by delegation depth, so a sub-agent's model and tool calls read as its work rather
+    // than as more of the parent's. `└─` on the first nested row marks where the delegation begins.
+    const timeline = buildTimeline(events);
+    const rows = timeline.map((r, i) => [
+        String(r.seq),
+        r.kind,
+        `${nestPrefix(r.depth, timeline[i - 1]?.depth ?? 0)}${r.label}`,
+        [r.detail, r.meta].filter((part) => part !== undefined && part !== '').join(' · '),
+    ]);
+    out.table(['SEQ', 'KIND', 'WHAT', 'DETAIL'], rows);
+    const loops = detectLoops(events);
+    for (const loop of loops) {
+        out.plain('');
+        // The signature is the point of the warning: "the same grep, four times" is something an
+        // operator can act on, where a list of turn numbers is something they have to go and look up.
+        out.warn('loop.detected', {
+            kind: loop.kind,
+            turns: loop.turns.join(','),
+            repeats: loop.repeats,
+            action: loop.signature,
+            tree: loop.tree?.slice(0, 8),
+        });
+    }
+    const cost = totalCost(events);
+    if (cost !== null) {
+        out.plain('');
+        out.info('usage', {
+            input: summary.totalUsage.input,
+            output: summary.totalUsage.output,
+            // Same scaling as the compare table: four fixed decimals render a genuinely cheap run as
+            // `$0.0000`, which reads as free rather than as small.
+            cost: formatCost(cost),
+        });
+    }
+}
+/** `orca checkpoints` — where can I fork from? */
+export async function checkpointsCommand(args, out, cwd = process.cwd()) {
+    const reader = await TraceReader.open((await resolveRunSelector(cwd, args.positionals[0] ?? 'last')).dir);
+    const events = await reader.events();
+    const checkpoints = deriveCheckpoints(events);
+    if (checkpoints.length === 0) {
+        out.plain('no checkpoints in this run');
+        out.plain('  checkpoints need a filesystem snapshot; was this recorded with --no-fs?');
+        return;
+    }
+    out.table(['SEQ', 'TURN', 'TREE'], checkpoints.map((c) => [String(c.seq), String(c.turn), (c.fsTree ?? '').slice(0, 12)]));
+    out.plain('');
+    out.plain(`  orca replay last --from ${checkpoints.at(-1).seq} --model <other-model>`);
+}
+/**
+ * `orca graph` — what caused what.
+ *
+ * The timeline says what happened in what order; this says what produced what. Every row names
+ * both ends and, crucially, whether the trace vouches for the edge or a rule here worked it out —
+ * a reader who cannot tell the two apart has been handed a guess dressed as a fact.
+ */
+export async function graphCommand(args, out, cwd = process.cwd()) {
+    const reader = await TraceReader.open((await resolveRunSelector(cwd, args.positionals[0] ?? 'last')).dir);
+    const events = await reader.events();
+    const graph = narrow(runGraph(events), args.num('to'));
+    const label = new Map(graph.nodes.map((n) => [n.seq, n.type]));
+    if (graph.edges.length === 0) {
+        out.plain('no causal edges in this run');
+        // Naming the likely cause beats leaving someone to wonder whether the feature works at all.
+        out.plain('  a run with no tool calls has nothing to connect; try `orca show` for the timeline');
+        return;
+    }
+    out.table(['FROM', 'TO', 'KIND', 'WHY'], graph.edges.map((e) => [
+        `${e.from} ${label.get(e.from) ?? ''}`.trim(),
+        `${e.to} ${label.get(e.to) ?? ''}`.trim(),
+        e.kind,
+        e.rule,
+    ]));
+    const inferred = graph.edges.filter((e) => e.kind === 'inferred').length;
+    if (inferred > 0) {
+        out.plain('');
+        out.plain(`  ${inferred} inferred — derived from this trace, not recorded in it`);
+    }
+}
+/** The whole graph, or just the chain that produced `to`. */
+export function narrow(graph, to) {
+    return to === undefined ? graph : chainTo(graph, to);
+}
+/**
+ * Write a card in whichever format was asked for.
+ *
+ * SVG is the source and never needs anything; PNG and GIF go through the optional raster path,
+ * which explains itself when its packages are absent rather than failing obscurely.
+ */
+async function writeCard(path, format, svgs, delays) {
+    if (format === 'svg') {
+        const svg = svgs[svgs.length - 1] ?? '';
+        await writeFile(path, svg, 'utf8');
+        return Buffer.byteLength(svg);
+    }
+    const buffer = format === 'png' ? await svgToPng(svgs[svgs.length - 1] ?? '') : await svgsToGif(svgs, delays);
+    await writeFile(path, buffer);
+    return buffer.length;
+}
+/** `orca export` — the single self-contained file that makes a trace shareable. */
+export async function exportCommand(args, out, cwd = process.cwd()) {
+    const runDir = (await resolveRunSelector(cwd, args.positionals[0] ?? 'last')).dir;
+    const reader = await TraceReader.open(runDir);
+    const manifest = reader.manifest();
+    // `--card` is a different artefact from `--out`, not a variation on it: one chain as a picture
+    // rather than the whole trace as a page. It leaks far less too — a card carries the events on
+    // one chain and none of the payloads — so it does not print the disclosure the page needs.
+    // The graph card shows the shape of a run; the chain card follows one path through it. Two
+    // different pictures, so two flags rather than a mode switch on one.
+    if (args.has('graph-card')) {
+        const target = cardTarget(args.str('graph-card') ?? 'graph.svg', '--graph-card');
+        const cardPath = resolve(cwd, target.path);
+        const events = await reader.events();
+        const graph = runGraph(events);
+        const to = args.num('to') ?? pickChainTarget(events);
+        const highlight = new Set(to === undefined ? [] : chainTo(graph, to).nodes.map((n) => n.seq));
+        const svg = renderGraphCard(scopeForCard(graph, highlight), {
+            runId: manifest.run_id,
+            highlight,
+        });
+        // A graph is one picture: there is no sequence to animate, so a .gif of it would be a
+        // one-frame file pretending to be a clip.
+        if (target.format === 'gif') {
+            throw new Error('--graph-card draws one picture, so it has no animation. Use .svg or .png.');
+        }
+        const bytes = await writeCard(cardPath, target.format, [svg], []);
+        out.phase('carded', { path: cardPath, bytes, kind: 'graph', format: target.format });
+        return;
+    }
+    if (args.has('card')) {
+        const target = cardTarget(args.str('card') ?? 'chain.svg', '--card');
+        const cardPath = resolve(cwd, target.path);
+        const events = await reader.events();
+        const to = args.num('to') ?? pickChainTarget(events);
+        if (to === undefined) {
+            // Refusing beats drawing something arbitrary: a card gets screenshotted whether or not it
+            // happens to be the interesting one, so a bad pick travels further than no card at all.
+            throw new Error(`nothing in ${manifest.run_id} stands out as the subject of a card — ` +
+                'no failing command, no tool error and no file change. ' +
+                'Name the event yourself with `--to <seq>`, or `orca show` to find one.');
+        }
+        const chain = chainTo(runGraph(events), to);
+        const frames = gifFrames(chain.nodes.length);
+        const svgs = target.format === 'gif'
+            ? frames.map((f) => renderChainCard(chain, { runId: manifest.run_id, reveal: f.reveal }))
+            : [renderChainCard(chain, { runId: manifest.run_id })];
+        const bytes = await writeCard(cardPath, target.format, svgs, frames.map((f) => f.delayMs));
+        out.phase('carded', { path: cardPath, bytes, to, format: target.format });
+        return;
+    }
+    const target = resolve(cwd, args.str('o') ?? args.str('out') ?? 'trace.html');
+    // Say what is about to leave the machine before it does. A trace can contain file contents and
+    // shell output, and the person exporting it is usually about to attach it to a public issue.
+    out.plain('about to write a single self-contained file containing:');
+    out.plain(`  run          ${manifest.run_id}`);
+    out.plain(`  events       ${manifest.counts?.events ?? '?'}`);
+    out.plain(`  blobs        ${manifest.counts?.blobs ?? '?'} (model requests, tool output, diffs)`);
+    out.plain(`  redactions   ${Object.values(manifest.redaction?.rules_fired ?? {}).reduce((a, b) => a + b, 0)} applied`);
+    out.plain(`  cwd          ${manifest.cwd}`);
+    out.plain('');
+    out.plain('  redaction is best-effort. skim the file before sharing it.');
+    out.plain('');
+    const result = await exportTraceHtml(runDir, target);
+    out.phase('exported', { path: result.path, bytes: result.bytes });
+}
+/** `orca ui` — the same viewer, served locally. */
+export async function uiCommand(args, out, cwd = process.cwd()) {
+    const runDir = (await resolveRunSelector(cwd, args.positionals[0] ?? 'last')).dir;
+    const server = await serveViewer({ runDir, port: args.num('port') ?? 0 });
+    out.phase('viewer', { url: server.url });
+    out.plain('  ctrl-c to stop');
+    await new Promise((resolve) => {
+        process.on('SIGINT', () => void server.close().then(resolve));
+    });
+}
+function totalCost(events) {
+    let total = 0;
+    let priced = false;
+    for (const e of events) {
+        if (e.type !== 'model.response')
+            continue;
+        const model = String(e.attrs?.model ?? '');
+        const money = priceFor({
+            input_tokens: Number(e.attrs?.input_tokens ?? 0),
+            output_tokens: Number(e.attrs?.output_tokens ?? 0),
+        }, model);
+        // An unknown model prices as null rather than zero: a confidently wrong cost is worse than an
+        // absent one, because it ends up in a comparison someone makes a decision from.
+        if (money) {
+            total += money.amount;
+            priced = true;
+        }
+    }
+    return priced ? total : null;
+}
+/** `  `-per-level indent, with `└─` on the row where a delegation's work starts. */
+function nestPrefix(depth, previousDepth) {
+    if (depth === 0)
+        return '';
+    return '  '.repeat(depth - 1) + (depth > previousDepth ? '└─ ' : '   ');
+}
+//# sourceMappingURL=inspect.js.map