agenticreplay 0.1.0 → 0.1.2

package/packages/cli/src/mcp-server.ts

@@ -1,314 +0,0 @@
-import type { Readable, Writable } from 'node:stream';
-import { JsonRpcFramer } from '@agenticreplay/mcp-shim';
-import { AgenticReplay } from './api.js';
-import { AGENTICREPLAY_VERSION } from './version.js';
-
-/**
- * AgenticReplay as tools an agent can call.
- *
- * `@agenticreplay/mcp-shim` records an agent's *own* MCP traffic — it is a tee, so nothing has ever
- * let an agent ask agenticreplay a question. That is backwards for this product in particular: "replay my
- * last run and tell me what diverged" is the most useful thing an agent could ask a replay
- * debugger, and it is a question no observability tool can answer, because a trace is a file.
- *
- * Written against the framer the shim already has rather than an SDK. The stdio transport is
- * newline-delimited JSON-RPC and the surface is four method names, so a runtime dependency here
- * would cost more than it carries — and this package has none.
- *
- * The tool set is deliberately narrow and read-mostly. `agenticreplay_replay` costs nothing and touches no
- * network; `agenticreplay_compare` spends real tokens, and says so in its own description, because an
- * agent choosing a tool reads that string and nothing else.
- */
-
-/** The version of the MCP spec these messages are shaped for. */
-const PROTOCOL_VERSION = '2025-06-18';
-
-const METHOD_NOT_FOUND = -32601;
-
-export interface McpTool {
-  name: string;
-  description: string;
-  inputSchema: {
-    type: 'object';
-    properties: Record<string, unknown>;
-    required?: string[];
-  };
-}
-
-/** Every tool takes `run`, because "which run" is the only question all of them share. */
-const RUN_ARG = {
-  run: {
-    type: 'string',
-    description:
-      'Run id, or "last" for the newest recording. Defaults to "last". Replay traces are ' +
-      'skipped when resolving "last", so it means the newest run you actually recorded.',
-  },
-} as const;
-
-export const MCP_TOOLS: McpTool[] = [
-  {
-    name: 'agenticreplay_list_runs',
-    description:
-      'List every agent run recorded in this project, newest first, with the run it was forked ' +
-      'from where there is one. Start here when you do not already know which run to look at.',
-    inputSchema: { type: 'object', properties: {} },
-  },
-  {
-    name: 'agenticreplay_show_run',
-    description:
-      'The full timeline of one run: every model turn with its token counts and stop reason, ' +
-      'every tool call with its arguments and result, every shell command with its exit code, ' +
-      'and every file the run changed. This is what tells you why an agent did something, ' +
-      'rather than what it cost.',
-    inputSchema: { type: 'object', properties: { ...RUN_ARG } },
-  },
-  {
-    name: 'agenticreplay_checkpoints',
-    description:
-      'The points in a run a fork can start from — where the conversation prefix is complete and ' +
-      'the workspace was snapshotted. Use before agenticreplay_compare to pick a fork point.',
-    inputSchema: { type: 'object', properties: { ...RUN_ARG } },
-  },
-  {
-    name: 'agenticreplay_graph',
-    description:
-      'What caused what in a run, as a list of edges. Each edge says which event produced which, ' +
-      'and whether it is `recorded` — the recorder watched it happen and wrote it into the trace ' +
-      '— or `inferred`, meaning this derived it just now from the rule it names and the trace ' +
-      'does not vouch for it. Pass `to` to get only the chain that produced one event, which is ' +
-      'the shape of an answer to "why did this fail" rather than "what happened".',
-    inputSchema: {
-      type: 'object',
-      properties: {
-        ...RUN_ARG,
-        to: {
-          type: 'number',
-          description: 'Narrow to the chain that produced this event seq. Omit for the whole run.',
-        },
-      },
-    },
-  },
-  {
-    name: 'agenticreplay_replay',
-    description:
-      'Re-run a recording exactly, with the network blocked and no tokens spent, and report what ' +
-      'could not be reproduced: divergences, and requests the recording could not serve. Free ' +
-      'and repeatable. It shows the recorded decisions still reproduce; it cannot show a fresh ' +
-      'run would fail the same way, because the model is not asked again — its recorded ' +
-      'responses are served back.',
-    inputSchema: {
-      type: 'object',
-      properties: {
-        ...RUN_ARG,
-        worktree: {
-          type: 'boolean',
-          description:
-            'Replay in a scratch copy instead of over the working tree. Slower, and leaves the ' +
-            'files you are looking at untouched.',
-        },
-      },
-    },
-  },
-  {
-    name: 'agenticreplay_compare',
-    description:
-      'Fork one recorded run onto several models from the same checkpoint — same files, same ' +
-      'conversation prefix — and grade each with a command you choose. SPENDS REAL TOKENS and ' +
-      'reaches the network: every model named is actually called. Ask before using it.',
-    inputSchema: {
-      type: 'object',
-      properties: {
-        ...RUN_ARG,
-        models: {
-          type: 'array',
-          items: { type: 'string' },
-          description: 'Model ids to compare. Required.',
-        },
-        from: {
-          type: 'number',
-          description: 'Checkpoint seq to fork at, from agenticreplay_checkpoints.',
-        },
-        verify: {
-          type: 'string',
-          description: 'Shell command whose exit code is the verdict, e.g. "npm test".',
-        },
-      },
-      required: ['models'],
-    },
-  },
-];
-
-type JsonRpcId = string | number;
-
-interface JsonRpcRequest {
-  jsonrpc?: string;
-  id?: JsonRpcId;
-  method?: string;
-  params?: unknown;
-}
-
-interface JsonRpcResponse {
-  jsonrpc: '2.0';
-  id: JsonRpcId;
-  result?: unknown;
-  error?: { code: number; message: string };
-}
-
-function asRecord(value: unknown): Record<string, unknown> {
-  return typeof value === 'object' && value !== null && !Array.isArray(value)
-    ? (value as Record<string, unknown>)
-    : {};
-}
-
-/** A tool result in MCP's shape: text content, plus the flag that says it failed. */
-function content(text: string, isError = false): Record<string, unknown> {
-  return { content: [{ type: 'text', text }], ...(isError ? { isError: true } : {}) };
-}
-
-function ok(json: unknown): Record<string, unknown> {
-  return content(JSON.stringify(json, null, 2));
-}
-
-/**
- * Handle one message.
- *
- * Returns `undefined` for a notification, which by definition has no id to answer — replying to
- * one is a protocol error that some clients treat as fatal.
- */
-export async function handleMcpMessage(
-  agenticreplay: AgenticReplay,
-  message: unknown,
-): Promise<JsonRpcResponse | undefined> {
-  const req = asRecord(message) as JsonRpcRequest;
-  const { id, method } = req;
-  if (id === undefined) return undefined;
-
-  const reply = (result: unknown): JsonRpcResponse => ({ jsonrpc: '2.0', id, result });
-  const fail = (code: number, message: string): JsonRpcResponse => ({
-    jsonrpc: '2.0',
-    id,
-    error: { code, message },
-  });
-
-  switch (method) {
-    case 'initialize':
-      return reply({
-        protocolVersion: PROTOCOL_VERSION,
-        capabilities: { tools: { listChanged: false } },
-        serverInfo: { name: 'agenticreplay', version: AGENTICREPLAY_VERSION },
-      });
-    case 'ping':
-      return reply({});
-    case 'tools/list':
-      return reply({ tools: MCP_TOOLS });
-    case 'tools/call':
-      return reply(await callTool(agenticreplay, asRecord(req.params)));
-    default:
-      return fail(
-        METHOD_NOT_FOUND,
-        `agenticreplay's MCP server does not implement '${method ?? '(none)'}'`,
-      );
-  }
-}
-
-/**
- * Run one tool.
- *
- * Every failure comes back as `isError` content rather than a JSON-RPC error: the spec draws that
- * line so a model can read what went wrong and try something else, where a transport error ends
- * the session. A bad run id is an ordinary answer here, not a crash.
- */
-async function callTool(
-  agenticreplay: AgenticReplay,
-  params: Record<string, unknown>,
-): Promise<unknown> {
-  const name = typeof params['name'] === 'string' ? params['name'] : '';
-  const args = asRecord(params['arguments']);
-  const run = typeof args['run'] === 'string' && args['run'] !== '' ? args['run'] : 'last';
-
-  const tool = MCP_TOOLS.find((t) => t.name === name);
-  if (!tool) {
-    return content(
-      `no such tool '${name}'. agenticreplay serves: ${MCP_TOOLS.map((t) => t.name).join(', ')}`,
-      true,
-    );
-  }
-
-  try {
-    switch (name) {
-      case 'agenticreplay_list_runs':
-        return ok(await agenticreplay.list());
-      case 'agenticreplay_show_run':
-        return ok(await agenticreplay.show(run));
-      case 'agenticreplay_checkpoints':
-        return ok(await agenticreplay.checkpoints(run));
-      case 'agenticreplay_graph': {
-        const to = args['to'];
-        if (to !== undefined && typeof to !== 'number') {
-          return content('to must be a number', true);
-        }
-        return ok(await agenticreplay.graph(run, to === undefined ? {} : { to }));
-      }
-      case 'agenticreplay_replay': {
-        const worktree = args['worktree'];
-        if (worktree !== undefined && typeof worktree !== 'boolean') {
-          return content('worktree must be a boolean', true);
-        }
-        return ok(await agenticreplay.replay(run, worktree === true ? { worktree: true } : {}));
-      }
-      case 'agenticreplay_compare': {
-        const models = Array.isArray(args['models'])
-          ? args['models'].filter((m): m is string => typeof m === 'string')
-          : [];
-        if (models.length === 0) return content('compare needs at least one model id', true);
-        const from = args['from'];
-        // Coercing a string here would silently fork from checkpoint 0 and produce a comparison
-        // whose one variable was not the model.
-        if (from !== undefined && typeof from !== 'number') {
-          return content(`from must be a number, got ${JSON.stringify(from)}`, true);
-        }
-        const verify = args['verify'];
-        if (verify !== undefined && typeof verify !== 'string') {
-          return content('verify must be a string', true);
-        }
-        return ok(
-          await agenticreplay.compare(run, {
-            models,
-            ...(typeof from === 'number' ? { from } : {}),
-            ...(typeof verify === 'string' ? { verify } : {}),
-          }),
-        );
-      }
-      default:
-        return content(`no such tool '${name}'`, true);
-    }
-  } catch (err) {
-    return content(err instanceof Error ? err.message : String(err), true);
-  }
-}
-
-export interface ServeMcpOptions {
-  agenticreplay: AgenticReplay;
-  input: Readable;
-  output: Writable;
-}
-
-/**
- * Serve MCP over a stream pair until the input ends.
- *
- * Messages are handled one at a time. Concurrency would buy nothing — every tool here is either a
- * file read or a subprocess that owns the working tree — and it would let two replays fight over
- * the same checkout.
- */
-export async function serveMcp({ agenticreplay, input, output }: ServeMcpOptions): Promise<void> {
-  const framer = new JsonRpcFramer();
-  for await (const chunk of input) {
-    for (const frame of framer.push(chunk as Uint8Array)) {
-      // A line that is not JSON is a stray log from something upstream, not a message. Dropping it
-      // is the only safe answer: there is no id to report an error against.
-      if (frame.message === undefined) continue;
-      const response = await handleMcpMessage(agenticreplay, frame.message);
-      if (response !== undefined) output.write(`${JSON.stringify(response)}\n`);
-    }
-  }
-}

package/packages/cli/src/mcp.ts

@@ -1,350 +0,0 @@
-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 type { TraceWriter } from '@agenticreplay/core';
-import { isMcpFrameRecord, objectsOnLine, MCP_RECORD_START } from '@agenticreplay/mcp-shim';
-import type { McpFrameRecord } from '@agenticreplay/mcp-shim';
-import type { Output } from './out.js';
-
-export interface McpCapture {
-  /** Path to the rewritten config the agent should be pointed at. */
-  configPath: string;
-  rewritten: string[];
-  skipped: string[];
-  /** Frames observed so far, drained by the recorder. */
-  drain(): Promise<McpFrameRecord[]>;
-}
-
-/**
- * A captured frame, as the shim writes it.
- *
- * Re-exported rather than redeclared. The version that used to live here named two of the same
- * fields differently — `server` for `name`, `direction` for `dir` — and since `JSON.parse` casts to
- * whatever the call site claims, nothing anywhere disagreed: every MCP event went into the trace
- * with an undefined server, and `direction === 'in'` was false for all of them, so every request
- * was recorded as a response. A format has one owner, and it is the thing that writes it.
- */
-export type { McpFrameRecord };
-
-/**
- * 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: string | undefined,
-  events: { type: string; attrs?: Record<string, unknown> }[],
-): string | undefined {
-  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: { type: string }[]): boolean {
-  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: { str(name: string): string | undefined; bool?(name: string, dflt?: boolean): boolean },
-  events: { type: string; attrs?: Record<string, unknown> }[],
-  writer: TraceWriter,
-  out: Output,
-  /** The recording's own frames, so the servers are answered from rather than started. */
-  recordedFrames?: string,
-  /** The recording's directory, which holds its own copy of the config it was given. */
-  recordedRunDir?: string,
-): Promise<McpCapture | undefined> {
-  // 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: Record<string, string>, configPath: string): void {
-  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: unknown): value is McpFrameRecord {
-  // 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 as { ts?: unknown }).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: McpCapture,
-  writer: TraceWriter,
-  turnAt: (at: number) => number,
-  fallbackTurn: number,
-): Promise<void> {
-  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 as never,
-    });
-  }
-}
-
-/**
- * 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: {
-  sourceConfigPath: string;
-  runDir: string;
-  out: Output;
-  /**
-   * Frames to answer from instead of starting the servers.
-   *
-   * Capture was only half of what this layer is for. The reason to record a server's traffic is
-   * that the run stays reproducible once the server is not — the token revoked, the repository
-   * moved, the service retired. Replay re-instrumented the same config and started the real server
-   * again, so an MCP recording could be read but not reproduced, and came apart on the first call
-   * when the server had gone. Pointed at a capture, the shim serves from it and launches nothing.
-   */
-  replayFrames?: string;
-}): Promise<McpCapture | undefined> {
-  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: unknown;
-  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: McpFrameRecord[] = [];
-      // 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(): string {
-  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(): Promise<boolean> {
-  let entry: string;
-  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: string) => {
-      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')));
-  });
-}