agenticreplay 0.1.0 → 0.1.2

package/packages/cli/dist/exchange-events.js

@@ -0,0 +1,296 @@
+import { createHash } from 'node:crypto';
+export class ExchangeEventDeriver {
+    #pending = new Map();
+    /**
+     * Tool results already turned into events. Necessary because the conversation is resent in
+     * full every turn: without this, a result would be re-emitted on every subsequent request and
+     * a long run would accumulate one duplicate per turn per tool call.
+     */
+    #closed = new Set();
+    /**
+     * Retrieval contexts already emitted, by fingerprint.
+     *
+     * A conversation is resent in full every turn, so without this a multi-turn RAG session would
+     * re-emit the first turn's passages on every request after it — the same duplication `#closed`
+     * prevents for tool results, one event type over.
+     */
+    #seenContext = new Set();
+    /** Tool calls that were issued but whose result never came back. */
+    unresolved() {
+        // A pending entry now outlives the result that answered it, so that the recorder can still
+        // resolve the call's seq for `causes` after derive has returned. `#closed` is the authority on
+        // whether a call was actually answered; "still in #pending" no longer means "unanswered".
+        return [...this.#pending.values()].filter((p) => !this.#closed.has(p.id));
+    }
+    /**
+     * Derive the events for one exchange. Returns them in the order they should be appended;
+     * `tool.result` events come first because they describe work that happened *before* this
+     * request was made.
+     */
+    derive(exchange, turn) {
+        const events = [];
+        /** Where the results this batch produced ended up, so the request can name them. */
+        const resultsAt = [];
+        // What the retriever found, before the request that carried it — same order and the same
+        // reason as a tool result: it describes work that happened before this call was made, and the
+        // request names it as a cause. Derived rather than captured, because it is already on the
+        // wire: the passages are in the prompt. See `retrievalContext`.
+        const retrieved = retrievalContext(exchange.canonicalRequest);
+        if (retrieved && !this.#seenContext.has(retrieved.fingerprint)) {
+            this.#seenContext.add(retrieved.fingerprint);
+            events.push({
+                type: 'retrieval.context',
+                // The harness retrieved these; agenticreplay only read them out of what it sent.
+                actor: 'harness',
+                attrs: {
+                    query: retrieved.query,
+                    passages: retrieved.passages.length,
+                    chars: retrieved.passages.reduce((n, p) => n + p.length, 0),
+                    // Named so a reader knows the boundaries are the prompt's, not the retriever's: this
+                    // is what was *used*, which `--context-docs` truncates out of what was *retrieved*.
+                    derived_from: 'prompt',
+                },
+                payload: { query: retrieved.query, passages: retrieved.passages },
+            });
+            resultsAt.push(events.length - 1);
+        }
+        for (const result of collectToolResults(exchange.canonicalRequest)) {
+            // Already accounted for on an earlier turn — the resent conversation is not new information.
+            if (this.#closed.has(result.tool_use_id))
+                continue;
+            // No pending call either: recording began mid-conversation, so this result is the first
+            // thing we know about that tool use. Record it rather than lose it.
+            const pending = this.#pending.get(result.tool_use_id);
+            events.push({
+                type: 'tool.result',
+                actor: 'harness',
+                attrs: {
+                    tool_use_id: result.tool_use_id,
+                    name: pending?.name ?? 'unknown',
+                    is_error: result.is_error ?? false,
+                    bytes: result.content.length,
+                },
+                payload: result.content,
+                causesToolId: result.tool_use_id,
+            });
+            resultsAt.push(events.length - 1);
+            // Deliberately not deleted here. The recorder resolves the call's seq *after* derive
+            // returns — it has to, since the seq only exists once the event is written — so dropping the
+            // entry in this loop meant `causes` came back empty on every tool result ever recorded, with
+            // no error to notice. `#closed` is what stops a resent result being re-emitted, so the
+            // pending entry can outlive the result it answered without any duplication.
+            this.#closed.add(result.tool_use_id);
+        }
+        events.push({
+            type: 'model.request',
+            actor: 'agent',
+            attrs: {
+                ...(exchange.requestId ? { request_id: exchange.requestId } : {}),
+                model: exchange.canonicalRequest.model,
+                dialect: exchange.dialect,
+                path: exchange.path,
+                messages: exchange.canonicalRequest.messages.length,
+                tools: exchange.canonicalRequest.tools?.length ?? 0,
+                // Only where agenticreplay established the connection and therefore knows. Absent reads as "not
+                // recorded" rather than as HTTP/1.1, which is why it is left off instead of defaulted.
+                ...(exchange.alpn === undefined ? {} : { alpn: exchange.alpn }),
+            },
+            payload: exchange.rawRequest,
+            // Absent rather than empty when nothing came back: an edge list naming nothing is noise a
+            // reader has to interpret, and `causes` is optional precisely so it can be left off.
+            ...(resultsAt.length > 0 ? { causesIndex: resultsAt } : {}),
+        });
+        const requestAt = events.length - 1;
+        const response = exchange.canonicalResponse;
+        events.push({
+            // The edge every other request/response pair already had. Without it `agenticreplay graph --to` on a
+            // model.response walks backwards, finds no incoming edge, and reports that the run has no
+            // causal edges at all -- on a run whose graph is otherwise full of them. `net.response`,
+            // `tool.result` and `shell.result` all name what they answered; this is the same fact about
+            // the pair the recorder watched most directly.
+            causesIndex: [requestAt],
+            type: 'model.response',
+            actor: 'model',
+            attrs: {
+                ...(exchange.requestId ? { request_id: exchange.requestId } : {}),
+                model: response?.model ?? exchange.canonicalRequest.model,
+                stop_reason: response?.stop_reason ?? 'unknown',
+                input_tokens: response?.usage.input_tokens ?? 0,
+                output_tokens: response?.usage.output_tokens ?? 0,
+                status: exchange.status,
+                duration_ms: exchange.durationMs ?? 0,
+                streamed: exchange.streamed,
+                // The payload below is the decoded body, so the encoding it arrived in is recorded here or
+                // nowhere: a promoted exchange keeps no response headers.
+                ...(exchange.responseDecodedFrom === undefined
+                    ? {}
+                    : { decoded_from: exchange.responseDecodedFrom }),
+                // Who answered. The trace said what was sent and what came back and never this, which is
+                // the first question asked of a recording that looks wrong — a gateway left behind in
+                // `~/.agenticreplay/config.json` redirects every run on the machine, and nothing in the run said so.
+                // On the response because it is a fact about the answer, and per exchange rather than in
+                // the manifest because the origin is chosen per request: a fork that changes provider
+                // changes it again mid-run. Absent means an older agenticreplay did not record it, never "the
+                // vendor's own API".
+                ...(exchange.upstream === undefined ? {} : { upstream: exchange.upstream }),
+            },
+            payload: exchange.rawResponse,
+        });
+        const responseAt = events.length - 1;
+        for (const use of collectToolUses(response)) {
+            events.push({
+                type: 'tool.call',
+                actor: 'model',
+                attrs: { tool_use_id: use.id, name: use.name, input: use.input },
+                causesIndex: [responseAt],
+            });
+            // seq is assigned by the writer; the caller patches it back in via markPending.
+            this.#pending.set(use.id, { id: use.id, name: use.name, input: use.input, seq: -1, turn });
+        }
+        return events;
+    }
+    markPending(toolUseId, seq) {
+        const p = this.#pending.get(toolUseId);
+        if (p)
+            p.seq = seq;
+    }
+    seqOf(toolUseId) {
+        const seq = this.#pending.get(toolUseId)?.seq;
+        return seq === undefined || seq < 0 ? undefined : seq;
+    }
+}
+/**
+ * The question a retriever was asked and the passages it came back with, read out of the prompt.
+ *
+ * The whole point is that this needs no new capture mechanism. A RAG system's retrieval runs
+ * in-process — FAISS is a library call, not an HTTP request — so a proxy cannot see it happen.
+ * What a proxy *can* see is the prompt the retrieval produced, and the passages are in it
+ * verbatim, because putting them there is what retrieval is for. Same standing as `tool.call`,
+ * which is likewise reconstructed from traffic rather than captured at the source.
+ *
+ * Two things are deliberately not here, and their absence is not an oversight. **Scores** and
+ * **top-k** never reach the wire: a prompt carries the passages that survived truncation, in the
+ * order they were pasted, with no numbers attached. Reporting a count as though it were `top-k`
+ * would be a fabricated measurement — `--context-docs` cuts the list before it is joined, so even
+ * "how many were retrieved" cannot be recovered. Getting those needs an instrument inside the
+ * Python process, which is a separate piece of work and honestly out of reach from here.
+ *
+ * Recognition is deliberately narrow. It fires on an explicit `Context:` … `Question:` structure,
+ * which is what a RAG template writes and what an ordinary chat turn does not. A looser rule —
+ * "the message is long and has paragraphs" — would file half the coding-agent traffic in the
+ * world as retrieval evidence, and a timeline that cries retrieval on every long prompt is worth
+ * less than no timeline at all.
+ */
+const CONTEXT_LABEL = /^[ \t]*(?:context|retrieved context|relevant context|retrieved documents|documents|passages|sources)[ \t]*:[ \t]*/im;
+const QUESTION_LABEL = /^[ \t]*(?:question|query|user question)[ \t]*:[ \t]*/im;
+/** How a template separates one passage from the next, most explicit first. */
+const PASSAGE_SEPARATORS = [/\n[ \t]*-{3,}[ \t]*\n/, /\n[ \t]*={3,}[ \t]*\n/, /\n\s*\n/];
+export function retrievalContext(req) {
+    const last = req.messages[req.messages.length - 1];
+    if (!last || last.role !== 'user')
+        return undefined;
+    const text = last.content
+        .filter((b) => b.type === 'text')
+        .map((b) => b.text)
+        .join('\n');
+    if (text === '')
+        return undefined;
+    const context = CONTEXT_LABEL.exec(text);
+    if (context === null)
+        return undefined;
+    const afterContext = context.index + context[0].length;
+    const question = QUESTION_LABEL.exec(text.slice(afterContext));
+    if (question === null)
+        return undefined;
+    const body = text.slice(afterContext, afterContext + question.index).trim();
+    if (body === '')
+        return undefined;
+    // What follows the question label, up to a blank line — a template's closing instruction
+    // ("Answer concisely:") sits after one, and folding it into the query would make two runs that
+    // asked the same thing look like they asked different things.
+    const rest = text.slice(afterContext + question.index + question[0].length);
+    const query = (rest.split(/\n\s*\n/)[0] ?? '').trim();
+    if (query === '')
+        return undefined;
+    const separator = PASSAGE_SEPARATORS.find((re) => re.test(body));
+    // `String.split` with a non-global pattern still splits on every occurrence, so the separator
+    // is used as found rather than recompiled.
+    const passages = (separator === undefined ? [body] : body.split(separator))
+        .map((p) => p.trim())
+        .filter((p) => p !== '');
+    if (passages.length === 0)
+        return undefined;
+    return {
+        query,
+        passages,
+        fingerprint: createHash('sha256')
+            .update(`${query}${passages.join('')}`)
+            .digest('hex'),
+    };
+}
+function collectToolResults(req) {
+    const out = [];
+    // Only the trailing user message can carry results for the calls we are still holding open;
+    // scanning the whole conversation would re-emit every earlier result on every turn.
+    const last = req.messages[req.messages.length - 1];
+    if (!last || last.role !== 'user')
+        return out;
+    for (const block of last.content) {
+        if (block.type === 'tool_result')
+            out.push(block);
+    }
+    return out;
+}
+function collectToolUses(res) {
+    if (!res)
+        return [];
+    return res.content.filter((b) => b.type === 'tool_use');
+}
+/**
+ * Derive one exchange's events, resolve their causal references, and write them.
+ *
+ * Shared because it has two callers — `agenticreplay record` and the live half of a fork — and they drifted:
+ * the fork wrote every model exchange with no `causes` at all, so a forked run could be replayed
+ * and forked again but not explained. The seq resolution is the part that is easy to leave out,
+ * since it cannot happen until the writer has appended, so it lives here rather than in either
+ * caller.
+ */
+export async function appendDerivedEvents(writer, deriver, exchange, turn, 
+/**
+ * Each derived event as it is written.
+ *
+ * The recorder needs to know whether the agent ran any commands, so it can say when the shell
+ * layer was on and saw none of them. That is only knowable from what the model asked for, and
+ * this is the one place the derived events exist.
+ */
+onDerived) {
+    /** `written[i]` is the seq of the i-th derived event, which is what `causesIndex` refers to. */
+    const written = [];
+    for (const derived of deriver.derive(exchange, turn)) {
+        const causes = [];
+        if (derived.causesToolId) {
+            const seq = deriver.seqOf(derived.causesToolId);
+            if (seq !== undefined)
+                causes.push(seq);
+        }
+        for (const index of derived.causesIndex ?? []) {
+            const seq = written[index];
+            if (seq !== undefined)
+                causes.push(seq);
+        }
+        const event = await writer.append({
+            type: derived.type,
+            actor: derived.actor,
+            turn,
+            attrs: derived.attrs,
+            payload: derived.payload,
+            ...(causes.length > 0 ? { causes } : {}),
+        });
+        written.push(event.seq);
+        onDerived?.(derived);
+        if (derived.type === 'tool.call') {
+            deriver.markPending(String(derived.attrs['tool_use_id']), event.seq);
+        }
+    }
+}
+//# sourceMappingURL=exchange-events.js.map

package/packages/cli/dist/exchange-events.js.map

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

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

@@ -0,0 +1,41 @@
+import type { ParsedArgs } from './args.js';
+/**
+ * Which flags each command accepts.
+ *
+ * The parser takes any flag it is given, which is right for parsing and wrong for a CLI: a
+ * mistyped or invented flag was accepted in silence and simply had no effect, so a run that did
+ * something other than what was asked reported success.
+ *
+ * Every entry below is a flag the code actually reads — collected from the `args.bool/str/num/list`
+ * calls in each command and in the helpers it shares — not from what the documentation describes.
+ * Building it the other way round is how a flag that never existed came to be recommended in the
+ * first place, and a list that allows more than the code understands would rebuild exactly that.
+ */
+export declare const GLOBAL: readonly ["ci", "json", "verbose", "color", "help", "version", "h"];
+export declare const BY_COMMAND: Record<string, readonly string[]>;
+/**
+ * Reject a flag this command does not have.
+ *
+ * Throws rather than warns. A flag is an instruction, and carrying on having ignored one produces
+ * a run that did something other than what was asked while reporting success — which is the
+ * failure this whole tool exists to make visible.
+ */
+export declare function assertKnownFlags(args: ParsedArgs): void;
+/** Exposed so a test can hold {@link POSITIONALS} against the source it mirrors. */
+export declare const POSITIONAL_COUNTS: Readonly<Record<string, number>>;
+/**
+ * Reject a positional argument the command does not read.
+ *
+ * The parser collects every token that is not a flag, and each command reads at most the first.
+ * Anything past that was dropped in silence — and for `record` that is the worst shape available:
+ * the arguments meant for the agent never reach it, the harness starts with none, and agenticreplay reports
+ * a successful recording of a run that was never asked to do anything.
+ *
+ *   agenticreplay record codex exec "fix auth.ts"    ->  manifest argv: ["codex"]
+ *
+ * The agent's own arguments go after `--`, which is the one thing that message has to say. Counting
+ * per command rather than allowing one everywhere matters for the seven that read none: `agenticreplay
+ * attach claude` looks like it names the agent, and `--for` is what actually does.
+ */
+export declare function assertNoStrayPositionals(args: ParsedArgs): void;
+//# sourceMappingURL=flags.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"flags.d.ts","sourceRoot":"","sources":["../src/flags.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,WAAW,CAAC;AAE5C;;;;;;;;;;;GAWG;AACH,eAAO,MAAM,MAAM,qEAAsE,CAAC;AAc1F,eAAO,MAAM,UAAU,EAAE,MAAM,CAAC,MAAM,EAAE,SAAS,MAAM,EAAE,CAsExD,CAAC;AA6CF;;;;;;GAMG;AACH,wBAAgB,gBAAgB,CAAC,IAAI,EAAE,UAAU,GAAG,IAAI,CAsBvD;AAqCD,oFAAoF;AACpF,eAAO,MAAM,iBAAiB,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAe,CAAC;AAE/E;;;;;;;;;;;;;GAaG;AACH,wBAAgB,wBAAwB,CAAC,IAAI,EAAE,UAAU,GAAG,IAAI,CAuB/D"}

package/packages/cli/dist/flags.js

@@ -0,0 +1,292 @@
+import { NUMERIC, VALUELESS } from './args.js';
+/**
+ * Which flags each command accepts.
+ *
+ * The parser takes any flag it is given, which is right for parsing and wrong for a CLI: a
+ * mistyped or invented flag was accepted in silence and simply had no effect, so a run that did
+ * something other than what was asked reported success.
+ *
+ * Every entry below is a flag the code actually reads — collected from the `args.bool/str/num/list`
+ * calls in each command and in the helpers it shares — not from what the documentation describes.
+ * Building it the other way round is how a flag that never existed came to be recommended in the
+ * first place, and a list that allows more than the code understands would rebuild exactly that.
+ */
+export const GLOBAL = ['ci', 'json', 'verbose', 'color', 'help', 'version', 'h'];
+/** Read by `config.ts` for any command that can reach a provider. */
+const UPSTREAM = ['upstream-anthropic', 'upstream-openai'];
+/** Read by `tls-capture.ts`, which record, replay and compare all set up. */
+const TLS = ['tls-intercept', 'tls-hosts', 'max-body-bytes', 'max-buffered-bytes'];
+/**
+ * How much of a retrieval call's answer to keep. Only the commands that *make* one have it:
+ * replay serves what a recording already holds, and cannot change what was stored then.
+ */
+const RETRIEVAL = ['retrieval-store'];
+export const BY_COMMAND = {
+    quickstart: ['dir', 'full'],
+    // push/pull reach a gateway the user names. `--force` means two different deliberate overrides:
+    // on push, store despite a secret-scan finding; on pull, replace a local run that already exists.
+    //
+    // `--fs` belongs here because `pushCommand` reads it (`args.bool('fs')`) and the help text
+    // offers it. Leaving it out did not make push ignore the flag — it made push REFUSE it, before
+    // the implementation ever saw it, and the refusal named only the two flags that were listed. So
+    // the workspace snapshots could not be shipped by any invocation, every run on the gateway came
+    // back with `blob_count: 0`, and forking a pulled run died in `git read-tree` on a tree object
+    // that had never been sent. This list is meant to be counted from the `args.*` call sites; that
+    // one was missed.
+    push: ['gateway', 'force', 'fs'],
+    pull: ['gateway', 'force'],
+    record: ['fs', 'shell', 'agent-spans', 'mcp-config', ...RETRIEVAL, ...TLS, ...UPSTREAM],
+    attach: [
+        'for',
+        'bind',
+        'advertise',
+        'port',
+        'remote-ca-path',
+        'replay',
+        'loose',
+        ...RETRIEVAL,
+        ...TLS,
+        ...UPSTREAM,
+    ],
+    replay: [
+        'from',
+        'model',
+        'fs',
+        'in-place',
+        'worktree',
+        'loose',
+        'trace',
+        'port',
+        'ui',
+        'mcp-config',
+        'serialize',
+        ...TLS,
+        ...UPSTREAM,
+        'quiet',
+    ],
+    // `fs` because compare forks through the same code replay does, and that path reads
+    // `args.bool('fs', true)` twice: once for the checkpoint restore, once for the fork's own
+    // capture. Without the entry `agenticreplay compare --no-fs` was refused while `agenticreplay replay --no-fs`
+    // worked, for two spellings of the same fork.
+    compare: ['from', 'models', 'verify', 'share', 'loose', 'fs', ...TLS, ...UPSTREAM],
+    show: [],
+    checkpoints: [],
+    events: [],
+    // `inspect.ts` serves graph, export and ui from one file, so the flags of all three are read
+    // there. Reading a file rather than a command is how the first version of this list came to
+    // give `export` two flags and lose the three it needs — `--card`, `--graph-card` and `--to`
+    // are the picture commands the README documents, and rejecting them broke a working feature.
+    graph: ['to'],
+    export: ['o', 'out', 'card', 'graph-card', 'to'],
+    ui: ['port'],
+    scrub: ['match', 'matches', 'dry-run', 'drop-fs'],
+    // `--remote` asks the gateway instead of this directory. `--gateway` stays what it is for
+    // push and pull — an optional override of which host — rather than doubling as the switch, so
+    // that a configured destination needs no url typed at it. `--source` and `--limit` are the
+    // listing's own parameters, passed through rather than reimplemented here.
+    list: ['remote', 'gateway', 'source', 'limit'],
+    gc: ['older-than', 'keep', 'dry-run'],
+    doctor: [],
+    setup: ['gateway', 'key', 'key-env', 'models'],
+    models: [],
+    mcp: [],
+    help: [],
+};
+/** The closest known flag, for a name that is probably a typo rather than an invention. */
+function nearest(name, known) {
+    let best;
+    for (const candidate of known) {
+        // Prefix and containment both catch the realistic slips: `--worktre`, `--model-s`.
+        const prefix = candidate.startsWith(name) || name.startsWith(candidate) ? 2 : 0;
+        const contains = candidate.includes(name) || name.includes(candidate) ? 1 : 0;
+        const score = Math.max(prefix, contains);
+        if (score > 0 && (best === undefined || score > best.score))
+            best = { name: candidate, score };
+    }
+    return best?.name;
+}
+/**
+ * Flags a command has only ALONGSIDE another.
+ *
+ * `agenticreplay list` lists this directory unless `--remote` asks the gateway, and `--gateway`, `--source`
+ * and `--limit` mean something only to the gateway. Being on the list above let them past
+ * `assertKnownFlags` unconditionally — and then the local listing ran and dropped every one of
+ * them without a word. `agenticreplay list --gateway <url>` printed THIS directory's runs to someone who
+ * had just named a host, which reads as that host's answer: the silently-ignored instruction this
+ * file exists to refuse, let back in by the entry that added the flags.
+ */
+const NEEDS = {
+    list: {
+        flags: ['gateway', 'source', 'limit'],
+        with: 'remote',
+        otherwise: 'without it, agenticreplay list shows the runs in this directory and asks no gateway anything',
+    },
+};
+function assertCompanions(args) {
+    const rule = NEEDS[args.command];
+    if (rule === undefined || args.bool(rule.with))
+        return;
+    const orphaned = rule.flags.filter((f) => args.has(f));
+    if (orphaned.length === 0)
+        return;
+    throw new Error(`${orphaned.map((f) => `--${f}`).join(', ')} ${orphaned.length === 1 ? 'asks' : 'ask'} ` +
+        `the gateway, and nothing here does: add --${rule.with}\n  ${rule.otherwise}`);
+}
+/**
+ * Reject a flag this command does not have.
+ *
+ * Throws rather than warns. A flag is an instruction, and carrying on having ignored one produces
+ * a run that did something other than what was asked while reporting success — which is the
+ * failure this whole tool exists to make visible.
+ */
+export function assertKnownFlags(args) {
+    const allowed = BY_COMMAND[args.command];
+    // An unknown command is reported by the dispatcher, which can say more about it than this can.
+    if (allowed === undefined)
+        return;
+    const known = [...allowed, ...GLOBAL];
+    const unknown = Object.keys(args.flags).filter((name) => !known.includes(name));
+    // Names first: "unknown flag --modle" is a better answer than "--modle needs a value".
+    if (unknown.length === 0) {
+        // Before the values: `--limit abc` without `--remote` is wrong for a reason that has nothing
+        // to do with `abc`, and that is the reason worth giving.
+        assertCompanions(args);
+        assertUsableValues(args, known);
+        return;
+    }
+    const [first] = unknown;
+    const suggestion = nearest(first, known);
+    throw new Error(`unknown flag ${dashed(first)} for "agenticreplay ${args.command}"` +
+        (suggestion === undefined ? '' : `\n  did you mean --${suggestion}?`) +
+        `\n  flags for this command: ${allowed.length === 0 ? '(none)' : allowed.map((f) => `--${f}`).join(' ')}`);
+}
+/**
+ * How many positional arguments each command reads.
+ *
+ * Counted from the `positionals[0]` call sites, the same way the flag list above is counted from
+ * the `args.*` ones. `record` reads an agent name and the run commands read a selector; the seven
+ * that read none genuinely take none — `attach` is configured entirely by flags, and `list`, `gc`,
+ * `doctor`, `setup`, `models` and `mcp` take nothing at all.
+ */
+const POSITIONALS = {
+    record: 1,
+    replay: 1,
+    compare: 1,
+    show: 1,
+    events: 1,
+    checkpoints: 1,
+    graph: 1,
+    export: 1,
+    // push defaults to the last run, like every other run-taking command; pull needs to be told
+    // which run to fetch, because "last" means nothing on a machine that has not seen it yet.
+    push: 1,
+    pull: 1,
+    ui: 1,
+    scrub: 1,
+    // Configured entirely by `--dir`, like `attach` below it.
+    quickstart: 0,
+    attach: 0,
+    list: 0,
+    gc: 0,
+    doctor: 0,
+    setup: 0,
+    models: 0,
+    mcp: 0,
+    help: 0,
+};
+/** Exposed so a test can hold {@link POSITIONALS} against the source it mirrors. */
+export const POSITIONAL_COUNTS = POSITIONALS;
+/**
+ * Reject a positional argument the command does not read.
+ *
+ * The parser collects every token that is not a flag, and each command reads at most the first.
+ * Anything past that was dropped in silence — and for `record` that is the worst shape available:
+ * the arguments meant for the agent never reach it, the harness starts with none, and agenticreplay reports
+ * a successful recording of a run that was never asked to do anything.
+ *
+ *   agenticreplay record codex exec "fix auth.ts"    ->  manifest argv: ["codex"]
+ *
+ * The agent's own arguments go after `--`, which is the one thing that message has to say. Counting
+ * per command rather than allowing one everywhere matters for the seven that read none: `agenticreplay
+ * attach claude` looks like it names the agent, and `--for` is what actually does.
+ */
+export function assertNoStrayPositionals(args) {
+    // An unknown command is the dispatcher's to report, as above.
+    const takes = POSITIONALS[args.command];
+    if (takes === undefined)
+        return;
+    const stray = args.positionals.slice(takes);
+    if (stray.length === 0)
+        return;
+    const quote = (a) => (/\s/.test(a) ? `"${a}"` : a);
+    const listed = stray.map(quote).join(' ');
+    const takesLine = takes === 0
+        ? `\n  "agenticreplay ${args.command}" takes no arguments; everything it needs is a flag`
+        : `\n  "agenticreplay ${args.command}" takes one: ${quote(args.positionals[0])}`;
+    // Only `record` hands its tail to something else, so only `record` can say where the tail goes.
+    const forAgent = args.command === 'record'
+        ? `\n  arguments for the agent go after --: agenticreplay record ${quote(args.positionals[0])} -- ${listed}`
+        : '';
+    throw new Error(`unexpected argument${stray.length > 1 ? 's' : ''} for "agenticreplay ${args.command}": ${listed}` +
+        takesLine +
+        forAgent);
+}
+/**
+ * A flag as the person would have typed it.
+ *
+ * Every short flag here is one character, so the count of dashes follows from the length. Telling
+ * someone `--o needs a value` when they typed `-o` sends them looking for a flag that does not
+ * exist.
+ */
+function dashed(name) {
+    return name.length === 1 ? `-${name}` : `--${name}`;
+}
+/**
+ * Reject a flag whose value cannot be honoured.
+ *
+ * `assertKnownFlags` settled the names; the values were still taken on trust. Every accessor falls
+ * back in silence when a value is missing or of the wrong shape, so the instruction vanished and
+ * the run reported success having done something else:
+ *
+ *   `--model` with nothing after it turned a fork into a plain replay, and the two models being
+ *   compared agreed because only one of them ever ran. `--match a --match b` redacted `b` alone and
+ *   reported its count as though that were the whole job. `--from four` replayed everything instead
+ *   of forking at a checkpoint. `--json=maybe` turned JSON output off while it was being asked for.
+ *
+ * Same reasoning as `assertNoStrayPositionals` beside it, third part of the command line: an
+ * instruction agenticreplay cannot carry out must not be carried past in silence.
+ *
+ * `agenticreplay gc --keep` checked its own by hand and was the only command that did. Doing it here is the
+ * same check for all of them, and one place to fix when it is wrong.
+ */
+function assertUsableValues(args, allowed) {
+    for (const name of Object.keys(args.flags)) {
+        const value = args.flags[name];
+        // Repeating a flag is how most CLIs take a list, so people write it. Say which form is one here
+        // rather than only saying no.
+        if (args.conflicting.has(name)) {
+            const listForm = [`${name}s`, `${name}es`].find((f) => allowed.includes(f));
+            throw new Error(`${dashed(name)} given more than once, and only the last would have counted` +
+                (listForm === undefined
+                    ? '\n  give it once'
+                    : `\n  for several, use one --${listForm}: --${listForm} a,b,c`));
+        }
+        if (NUMERIC.has(name)) {
+            if (args.missingValue.has(name) || typeof value === 'string') {
+                throw new Error(`${dashed(name)} needs a number, like ${dashed(name)} 4`);
+            }
+            continue;
+        }
+        // `--flag`, `--flag=true` and `--no-flag` all arrive as a boolean. Anything else is a value on
+        // a switch, and the switch would then have read as off.
+        if (VALUELESS.has(name)) {
+            if (typeof value === 'string') {
+                throw new Error(`${dashed(name)} takes no value; it is either given or it is not`);
+            }
+            continue;
+        }
+        if (args.missingValue.has(name))
+            throw new Error(`${dashed(name)} needs a value`);
+    }
+}
+//# sourceMappingURL=flags.js.map