@tonyclaw/agent-inspector 4.0.1 → 4.0.3

package/src/proxy/chunkStorage.ts

@@ -1,123 +0,0 @@
-import {
-  writeFileSync,
-  readFileSync,
-  unlinkSync,
-  existsSync,
-  renameSync,
-  copyFileSync,
-} from "node:fs";
-import { join, isAbsolute } from "node:path";
-import { logger } from "./logger";
-import { z } from "zod";
-import { JsonValueSchema, type StreamingChunk } from "./schemas";
-import { getDataDir } from "./dataDir";
-import {
-  ensurePrivateDirectorySync,
-  PRIVATE_FILE_MODE,
-  securePrivateFileSync,
-} from "./privateDataPath";
-
-export type StreamingChunksData = {
-  chunks: StreamingChunk[];
-  truncated?: boolean;
-};
-
-const StreamingChunkSchema: z.ZodType<StreamingChunk> = z.object({
-  index: z.number(),
-  timestamp: z.number(),
-  type: z.string(),
-  data: JsonValueSchema,
-});
-
-const StreamingChunksDataSchema = z.object({
-  chunks: z.array(StreamingChunkSchema),
-  truncated: z.boolean().optional(),
-});
-
-export function getChunksDir(): string {
-  const chunksDirEnv = process.env["CHUNKS_DIR"];
-  if (chunksDirEnv !== undefined && chunksDirEnv !== "") {
-    return isAbsolute(chunksDirEnv) ? chunksDirEnv : join(getDataDir(), chunksDirEnv);
-  }
-  return join(getDataDir(), "chunks");
-}
-
-function getChunkFilePath(logId: number): string {
-  return join(getChunksDir(), `${logId}.json`);
-}
-
-function getTempFilePath(logId: number): string {
-  return join(getChunksDir(), `.${logId}.tmp`);
-}
-
-/**
- * Write chunks to disk atomically: write to temp file first, then rename.
- * Returns the absolute path to the written chunk file.
- */
-export function writeChunks(logId: number, chunks: StreamingChunk[], truncated?: boolean): string {
-  const dir = getChunksDir();
-  const targetPath = getChunkFilePath(logId);
-  const tempPath = getTempFilePath(logId);
-
-  // Ensure directory exists
-  if (!ensurePrivateDirectorySync(dir)) {
-    logger.error("[chunkStorage] Failed to secure chunks directory:", dir);
-    return targetPath;
-  }
-
-  const data: StreamingChunksData = { chunks, truncated };
-
-  // Write to temp file first
-  try {
-    writeFileSync(tempPath, JSON.stringify(data), {
-      encoding: "utf-8",
-      mode: PRIVATE_FILE_MODE,
-    });
-    if (!securePrivateFileSync(tempPath)) {
-      unlinkSync(tempPath);
-      logger.error("[chunkStorage] Failed to secure chunks temp file:", tempPath);
-      return targetPath;
-    }
-  } catch (err) {
-    logger.error("[chunkStorage] Failed to write chunks temp file:", String(err));
-    return targetPath;
-  }
-
-  // Rename to target (atomic on most filesystems)
-  try {
-    renameSync(tempPath, targetPath);
-  } catch (err) {
-    logger.warn("[chunkStorage] Rename failed, falling back to copy+delete:", String(err));
-    // If rename fails, try copy + delete
-    try {
-      copyFileSync(tempPath, targetPath);
-      if (!securePrivateFileSync(targetPath)) {
-        logger.error("[chunkStorage] Failed to secure chunks file:", targetPath);
-      }
-      unlinkSync(tempPath);
-    } catch (copyErr) {
-      logger.error("[chunkStorage] Failed to copy chunks file:", String(copyErr));
-    }
-  }
-
-  return targetPath;
-}
-
-/**
- * Read chunks from a chunk file path.
- * Returns null if the file does not exist or cannot be read.
- */
-export function readChunks(path: string): StreamingChunksData | null {
-  if (!existsSync(path)) {
-    return null;
-  }
-  try {
-    const content = readFileSync(path, "utf-8");
-    const parsed: unknown = JSON.parse(content);
-    const result = StreamingChunksDataSchema.safeParse(parsed);
-    if (!result.success) return null;
-    return result.data;
-  } catch {
-    return null;
-  }
-}

package/src/proxy/config.ts

@@ -1,218 +0,0 @@
-import { writeFileSync, readFileSync, unlinkSync, existsSync, renameSync } from "node:fs";
-import { join } from "node:path";
-import { logger } from "./logger";
-import { getDataDir } from "./dataDir";
-import {
-  ensurePrivateDirectorySync,
-  PRIVATE_FILE_MODE,
-  securePrivateFileSync,
-} from "./privateDataPath";
-import {
-  CaptureModeSchema,
-  DEFAULT_CAPTURE_MODE,
-  DEFAULT_PROVIDER_TEST_TIMEOUT_SECONDS,
-  DEFAULT_SLOW_RESPONSE_THRESHOLD_SECONDS,
-  DEFAULT_TIME_DISPLAY_FORMAT,
-  RuntimeConfigSchema,
-  type CaptureMode,
-  type RuntimeConfig,
-} from "../lib/runtimeConfig";
-
-// Re-export so server-side callers (api/config.ts, tests) keep the
-// existing import path `from "../../proxy/config"`.
-export { RuntimeConfigSchema };
-export type { RuntimeConfig };
-
-/**
- * Runtime-mutable server config. Includes proxy behavior flags and UI tuning
- * settings that should take effect without restarting the dev server. The API
- * layer reads and writes the same object via `getConfig` / `setConfig`.
- *
- * Boot-time precedence (first match wins):
- *   1. `data/config.json` on disk (persisted state)
- *   2. `AGENT_INSPECTOR_STRIP_CLAUDE_CODE_BILLING_HEADER` env var
- *   3. `false` (off by default, to keep the proxy transparent)
- *
- * The env var is read once at module init; changing it requires a restart.
- * Once the user has saved a value via the API, the persisted file takes
- * precedence over the env var for the lifetime of the process.
- */
-
-// --- Persistence ---
-
-function getConfigFilePath(): string {
-  return join(getDataDir(), "config.json");
-}
-
-function getConfigTempPath(): string {
-  return join(getDataDir(), "config.json.tmp");
-}
-
-// --- Module state ---
-
-// Internal: writeable singleton. Read via getConfig(), mutate via setConfig().
-let currentConfig: RuntimeConfig = resolveInitialConfig();
-
-type MutableRuntimeConfig = Omit<RuntimeConfig, "captureMode">;
-
-function resolveInitialCaptureMode(): CaptureMode {
-  const value = process.env["AGENT_INSPECTOR_CAPTURE_MODE"] ?? process.env["AGENT_INSPECTOR_MODE"];
-  if (value === undefined || value === "") return DEFAULT_CAPTURE_MODE;
-
-  const result = CaptureModeSchema.safeParse(value);
-  if (result.success) return result.data;
-
-  logger.warn(`[config] Invalid capture mode ${value}; falling back to ${DEFAULT_CAPTURE_MODE}`);
-  return DEFAULT_CAPTURE_MODE;
-}
-
-function resolveInitialConfig(): RuntimeConfig {
-  const captureMode = resolveInitialCaptureMode();
-
-  // 1. Persisted file
-  const filePath = getConfigFilePath();
-  if (existsSync(filePath)) {
-    try {
-      const content = readFileSync(filePath, "utf-8");
-      const parsed: unknown = JSON.parse(content);
-      const result = RuntimeConfigSchema.safeParse(parsed);
-      if (result.success) {
-        logger.info(`[config] Loaded persisted config from ${filePath}`);
-        return { ...result.data, captureMode };
-      }
-      logger.warn(
-        `[config] Persisted config at ${filePath} is invalid; falling back to env/default`,
-      );
-    } catch (err) {
-      logger.warn(
-        `[config] Failed to read persisted config at ${filePath}: ${String(err)}; falling back to env/default`,
-      );
-    }
-  }
-
-  // 2. Env var
-  if (process.env["AGENT_INSPECTOR_STRIP_CLAUDE_CODE_BILLING_HEADER"] === "1") {
-    return {
-      stripClaudeCodeBillingHeader: true,
-      hasSeenOnboarding: false,
-      slowResponseThresholdSeconds: DEFAULT_SLOW_RESPONSE_THRESHOLD_SECONDS,
-      providerTestTimeoutSeconds: DEFAULT_PROVIDER_TEST_TIMEOUT_SECONDS,
-      timeDisplayFormat: DEFAULT_TIME_DISPLAY_FORMAT,
-      captureMode,
-    };
-  }
-
-  // 3. Default off
-  return {
-    stripClaudeCodeBillingHeader: false,
-    hasSeenOnboarding: false,
-    slowResponseThresholdSeconds: DEFAULT_SLOW_RESPONSE_THRESHOLD_SECONDS,
-    providerTestTimeoutSeconds: DEFAULT_PROVIDER_TEST_TIMEOUT_SECONDS,
-    timeDisplayFormat: DEFAULT_TIME_DISPLAY_FORMAT,
-    captureMode,
-  };
-}
-
-/**
- * Returns the current config. Synchronous; safe to call on the hot path.
- */
-export function getConfig(): RuntimeConfig {
-  return currentConfig;
-}
-
-/**
- * Applies a partial update after atomically persisting it to disk.
- * Returns the updated full config on success or null when persistence
- * fails. A failed write leaves both the in-memory value and the existing
- * on-disk value unchanged.
- */
-export function setConfig(patch: Partial<MutableRuntimeConfig>): RuntimeConfig | null {
-  const next: RuntimeConfig = {
-    ...currentConfig,
-    ...patch,
-    captureMode: currentConfig.captureMode,
-  };
-  if (!persistConfig(next)) return null;
-  currentConfig = next;
-  return next;
-}
-
-/**
- * For tests: reset the in-memory config to a known value without
- * touching disk. Use `setConfig` in production code.
- */
-export function _resetConfigForTests(value: RuntimeConfig): void {
-  currentConfig = value;
-}
-
-/**
- * For tests: re-run the boot-time resolution against the current env vars
- * and the on-disk config file, and update the in-memory value. Use this to
- * test env-var precedence without having to reload the module.
- */
-export function _rebootForTests(): void {
-  currentConfig = resolveInitialConfig();
-}
-
-// --- Atomic write ---
-
-/**
- * Atomic write: secure temp file + rename in the same directory.
- * Returns true on success, false on failure (logged but not thrown). There is
- * deliberately no copy fallback because replacing the target through a copy
- * could expose a partially written config after a crash.
- */
-function persistConfig(value: RuntimeConfig): boolean {
-  const dir = getDataDir();
-  const targetPath = getConfigFilePath();
-  const tempPath = getConfigTempPath();
-
-  if (!ensurePrivateDirectorySync(dir)) {
-    logger.error(`[config] Failed to secure data directory ${dir}`);
-    return false;
-  }
-
-  try {
-    writeFileSync(tempPath, JSON.stringify(toPersistedConfig(value)), {
-      encoding: "utf-8",
-      mode: PRIVATE_FILE_MODE,
-      flush: true,
-    });
-    if (!securePrivateFileSync(tempPath)) {
-      removeConfigTempFile(tempPath);
-      logger.error(`[config] Failed to secure config temp file ${tempPath}`);
-      return false;
-    }
-  } catch (err) {
-    removeConfigTempFile(tempPath);
-    logger.error(`[config] Failed to write config temp file: ${String(err)}`);
-    return false;
-  }
-
-  try {
-    renameSync(tempPath, targetPath);
-    return true;
-  } catch (err) {
-    removeConfigTempFile(tempPath);
-    logger.error(`[config] Failed to atomically replace config file: ${String(err)}`);
-    return false;
-  }
-}
-
-function removeConfigTempFile(tempPath: string): void {
-  try {
-    unlinkSync(tempPath);
-  } catch {
-    // Best effort. A stale temp path is never read as runtime configuration.
-  }
-}
-
-function toPersistedConfig(value: RuntimeConfig): Record<string, unknown> {
-  return {
-    stripClaudeCodeBillingHeader: value.stripClaudeCodeBillingHeader,
-    hasSeenOnboarding: value.hasSeenOnboarding,
-    slowResponseThresholdSeconds: value.slowResponseThresholdSeconds,
-    providerTestTimeoutSeconds: value.providerTestTimeoutSeconds,
-    timeDisplayFormat: value.timeDisplayFormat,
-  };
-}

package/src/proxy/constants.ts

@@ -1,66 +0,0 @@
-// Proxy module constants
-
-export const DEFAULT_UPSTREAM = "https://api.anthropic.com";
-export const DEFAULT_OPENAI_UPSTREAM = "https://api.openai.com/v1";
-
-// Unified proxy identity - used as user-agent and x-proxy-identity header value
-export const PROXY_IDENTITY = process.env["PROXY_IDENTITY"] ?? "inspector9527@Tony";
-
-// API paths
-export const PATH_V1_CHAT_COMPLETIONS = "/v1/chat/completions";
-export const PATH_CHAT_COMPLETIONS = "/chat/completions";
-export const PATH_V1_RESPONSES = "/v1/responses";
-export const PATH_RESPONSES = "/responses";
-export const PATH_V1_MESSAGES = "/v1/messages";
-
-// Header names
-export const HEADER_CONTENT_TYPE = "content-type";
-export const HEADER_USER_AGENT = "user-agent";
-export const HEADER_X_PROXY_IDENTITY = "x-proxy-identity";
-export const HEADER_AUTHORIZATION = "authorization";
-export const HEADER_X_API_KEY = "x-api-key";
-export const HEADER_CONTENT_ENCODING = "content-encoding";
-export const HEADER_CONTENT_LENGTH = "content-length";
-export const HEADER_HOST = "host";
-
-// Auth header types
-export const AUTH_HEADER_X_API_KEY = "x-api-key";
-
-// Headers whose values contain secrets (API keys, bearer tokens).
-// These are redacted before being written to logs when captureMode is "full".
-export const SENSITIVE_HEADERS = new Set([
-  HEADER_AUTHORIZATION,
-  HEADER_X_API_KEY,
-  "cookie",
-  "set-cookie",
-  "proxy-authorization",
-]);
-
-// Content types
-export const CONTENT_TYPE_EVENT_STREAM = "text/event-stream";
-
-// Response status
-export const STATUS_FORBIDDEN = 403;
-export const STATUS_BAD_GATEWAY = 502;
-export const STATUS_PAYLOAD_TOO_LARGE = 413;
-
-// Maximum request body size accepted by the proxy (50 MB).
-// Legitimate LLM API requests (system prompts, conversation history, tool
-// definitions) are well under this limit; larger payloads are almost certainly
-// malicious or malformed.
-export const MAX_REQUEST_BODY_BYTES = 50 * 1024 * 1024;
-
-// Standard/safe headers to preserve when forwarding to upstream.
-// NOTE: Authorization is intentionally excluded to prevent client auth tokens from leaking.
-export const PRESERVE_HEADERS = new Set([HEADER_CONTENT_TYPE]);
-
-// Opt-in rewrite: the *initial* value for the strip-Claude-Code-billing-header
-// flag. The runtime, mutable source of truth is `src/proxy/config.ts`, which
-// reads this constant at module-load time as its precedence-2 fallback (after
-// the persisted `data/config.json`, before the `false` default). After boot,
-// the handler reads `getConfig().stripClaudeCodeBillingHeader` on every
-// request, so a PATCH to `/api/config` (or the Settings → Proxy tab in the UI)
-// takes effect without a restart. The env var itself is read once at boot.
-//
-// What it does: when enabled, the proxy strips the
-// `x-anthropic-billing-header:` text block that Claude Code prepends to the

package/src/proxy/dataDir.ts

@@ -1,147 +0,0 @@
-import { cpSync, existsSync, readdirSync, renameSync, rmSync } from "node:fs";
-import { isAbsolute, join } from "node:path";
-import {
-  ensurePrivateDirectorySync,
-  isPathTreeFreeOfIndirectionSync,
-  securePrivateTreeSync,
-} from "./privateDataPath";
-
-const CURRENT_DATA_DIR_NAME = ".agent-inspector";
-const LEGACY_DATA_DIR_NAMES = [".llm-inspector", ".llm-agent"];
-
-/**
- * Compute the directory where agent-inspector stores its on-disk state
- * (runtime config, providers config, log chunks, etc.). Centralised here
- * so every store agrees on the same path.
- *
- * Resolution order (first match wins):
- *   1. `AGENT_INSPECTOR_DATA_DIR` env var - absolute path used as-is,
- *      relative path joined to the OS-specific base below.
- *   2. `AGENT_INSPECTOR_CONFIG_DIR` env var - kept for backward compat
- *      with the runtime config; treated as a directory *name* (relative
- *      to the OS-specific base) when not absolute.
- *   3. OS-specific base + `.agent-inspector`.
- *
- * Windows base is `%USERPROFILE%` (falling back to `%APPDATA%`, then `C:\`).
- * macOS / Linux base is `$HOME` (falling back to `/tmp`).
- *
- * The env var is re-read on every call so tests and the CLI can swap the
- * directory after this module has been imported.
- */
-export function getDataDir(): string {
-  migrateLegacyDataDirs();
-  return resolveDataDir(existsSync);
-}
-
-type PathExists = (path: string) => boolean;
-type DataDirEnv = Readonly<Record<string, string | undefined>>;
-
-function hasDataDirState(pathExists: PathExists, dir: string): boolean {
-  return (
-    pathExists(join(dir, "providers.json")) ||
-    pathExists(join(dir, "config.json")) ||
-    pathExists(join(dir, "logs")) ||
-    pathExists(join(dir, "chunks"))
-  );
-}
-
-function defaultBaseDir(
-  env: DataDirEnv = process.env,
-  platform: typeof process.platform = process.platform,
-): string {
-  return platform === "win32"
-    ? (env["USERPROFILE"] ?? env["APPDATA"] ?? "C:\\")
-    : (env["HOME"] ?? "/tmp");
-}
-
-export function resolveDataDir(
-  _pathExists: PathExists,
-  env: DataDirEnv = process.env,
-  platform: typeof process.platform = process.platform,
-): string {
-  const base = defaultBaseDir(env, platform);
-
-  const dirEnv = env["AGENT_INSPECTOR_DATA_DIR"];
-  if (dirEnv !== undefined && dirEnv !== "") {
-    return isAbsolute(dirEnv) ? dirEnv : join(base, dirEnv);
-  }
-
-  // Backward-compat: the runtime config historically read
-  // `AGENT_INSPECTOR_CONFIG_DIR` as a directory *name* (relative to base).
-  // Honour it so existing CLI scripts keep working.
-  const legacyDirEnv = env["AGENT_INSPECTOR_CONFIG_DIR"];
-  if (legacyDirEnv !== undefined && legacyDirEnv !== "") {
-    return isAbsolute(legacyDirEnv) ? legacyDirEnv : join(base, legacyDirEnv);
-  }
-
-  return join(base, CURRENT_DATA_DIR_NAME);
-}
-
-/**
- * `true` when the user has explicitly asked for a non-default data
- * directory. Used to skip the one-time legacy migration so we don't
- * write to a path the user didn't choose.
- */
-export function hasExplicitDataDir(): boolean {
-  return (
-    (process.env["AGENT_INSPECTOR_DATA_DIR"] !== undefined &&
-      process.env["AGENT_INSPECTOR_DATA_DIR"] !== "") ||
-    (process.env["AGENT_INSPECTOR_CONFIG_DIR"] !== undefined &&
-      process.env["AGENT_INSPECTOR_CONFIG_DIR"] !== "")
-  );
-}
-
-export function migrateLegacyDataDirs(): void {
-  if (hasExplicitDataDir()) return;
-
-  const base = defaultBaseDir();
-  const currentDir = join(base, CURRENT_DATA_DIR_NAME);
-  if (hasDataDirState(existsSync, currentDir)) return;
-
-  for (const legacyName of LEGACY_DATA_DIR_NAMES) {
-    const legacyDir = join(base, legacyName);
-    if (!existsSync(legacyDir)) continue;
-
-    const stagingDir = join(
-      base,
-      `${CURRENT_DATA_DIR_NAME}.migration-${String(process.pid)}-${String(Date.now())}`,
-    );
-
-    try {
-      // cpSync may dereference junctions on some Windows runtimes. Reject the source tree before
-      // copying and recheck it afterwards so migration never imports through an indirection.
-      if (!isPathTreeFreeOfIndirectionSync(legacyDir)) return;
-      if (existsSync(currentDir)) {
-        // Never merge legacy state into an unknown or partially initialized destination. A caller
-        // can inspect it and retry after resolving the conflict; the authoritative legacy source
-        // remains untouched.
-        if (readdirSync(currentDir).length > 0) return;
-        rmSync(currentDir, { recursive: true, force: false });
-      }
-      if (!ensurePrivateDirectorySync(stagingDir)) return;
-      for (const entry of readdirSync(legacyDir)) {
-        cpSync(join(legacyDir, entry), join(stagingDir, entry), {
-          recursive: true,
-          force: false,
-          errorOnExist: true,
-        });
-      }
-      if (!isPathTreeFreeOfIndirectionSync(legacyDir)) {
-        rmSync(stagingDir, { recursive: true, force: true });
-        return;
-      }
-      if (!securePrivateTreeSync(stagingDir)) {
-        rmSync(stagingDir, { recursive: true, force: true });
-        return;
-      }
-      renameSync(stagingDir, currentDir);
-      rmSync(legacyDir, { recursive: true, force: true });
-      return;
-    } catch {
-      // A failed staged migration never deletes the legacy source. Remove only this attempt's
-      // private sibling and retry on a later startup.
-      if (existsSync(stagingDir)) rmSync(stagingDir, { recursive: true, force: true });
-      return;
-    }
-  }
-}

package/src/proxy/ecosystemExecutionConfirmation.ts

@@ -1,114 +0,0 @@
-import { randomUUID } from "node:crypto";
-import {
-  ECOSYSTEM_EXECUTION_CONFIRMATION_PHRASE,
-  type EcosystemExecutionConfirmation,
-  type EcosystemExecutionPlan,
-  type EcosystemTaskAction,
-} from "../lib/ecosystemContract";
-import { logger } from "./logger";
-
-const CONFIRMATION_TTL_MS = 2 * 60 * 1000;
-const MAX_PENDING_CONFIRMATIONS = 100;
-
-type ConfirmationRecord = {
-  confirmation: EcosystemExecutionConfirmation;
-  expiresAtMs: number;
-};
-
-type ConfirmationFailureReason =
-  | "missing_or_invalid_confirmation"
-  | "expired_confirmation"
-  | "mismatched_confirmation";
-
-type ConsumeEcosystemConfirmationResult =
-  | { ok: true; plan: EcosystemExecutionPlan }
-  | { ok: false; reason: ConfirmationFailureReason };
-
-type EcosystemAuditEvent = "confirmation_issued" | "confirmation_rejected" | "execution_started";
-type EcosystemAuditReason =
-  | "none"
-  | "invalid_request"
-  | "unknown_target"
-  | "missing_or_invalid_confirmation"
-  | "expired_confirmation"
-  | "mismatched_confirmation"
-  | "task_unavailable";
-
-const confirmations = new Map<string, ConfirmationRecord>();
-
-function pruneConfirmations(nowMs: number): void {
-  for (const [nonce, record] of confirmations) {
-    if (record.expiresAtMs <= nowMs) confirmations.delete(nonce);
-  }
-  while (confirmations.size >= MAX_PENDING_CONFIRMATIONS) {
-    const oldestNonce = confirmations.keys().next().value;
-    if (typeof oldestNonce !== "string") return;
-    confirmations.delete(oldestNonce);
-  }
-}
-
-function safeAuditTarget(targetId: string | null): string {
-  if (targetId === null || !/^[a-z0-9-]{1,64}$/.test(targetId)) return "unrecognized";
-  return targetId;
-}
-
-export function auditEcosystemExecution(
-  event: EcosystemAuditEvent,
-  action: EcosystemTaskAction,
-  targetId: string | null,
-  reason: EcosystemAuditReason,
-): void {
-  logger.info(
-    `[security-audit] event=${event} action=${action} target=${safeAuditTarget(targetId)} reason=${reason}`,
-  );
-}
-
-export function createEcosystemExecutionConfirmation(
-  plan: EcosystemExecutionPlan,
-  nowMs = Date.now(),
-): EcosystemExecutionConfirmation {
-  pruneConfirmations(nowMs);
-  const expiresAtMs = nowMs + CONFIRMATION_TTL_MS;
-  const confirmation: EcosystemExecutionConfirmation = {
-    nonce: randomUUID(),
-    phrase: ECOSYSTEM_EXECUTION_CONFIRMATION_PHRASE,
-    expiresAt: new Date(expiresAtMs).toISOString(),
-    plan,
-  };
-  confirmations.set(confirmation.nonce, { confirmation, expiresAtMs });
-  return confirmation;
-}
-
-export function consumeEcosystemExecutionConfirmation(
-  nonce: string,
-  phrase: string,
-  expectedPlan: EcosystemExecutionPlan,
-  nowMs = Date.now(),
-): ConsumeEcosystemConfirmationResult {
-  const record = confirmations.get(nonce);
-  if (record === undefined) {
-    return { ok: false, reason: "missing_or_invalid_confirmation" };
-  }
-
-  confirmations.delete(nonce);
-  if (record.expiresAtMs <= nowMs) return { ok: false, reason: "expired_confirmation" };
-  const reviewedPlan = record.confirmation.plan;
-  if (
-    phrase !== ECOSYSTEM_EXECUTION_CONFIRMATION_PHRASE ||
-    reviewedPlan.action !== expectedPlan.action ||
-    reviewedPlan.targetId !== expectedPlan.targetId ||
-    reviewedPlan.targetName !== expectedPlan.targetName ||
-    reviewedPlan.command !== expectedPlan.command ||
-    reviewedPlan.source !== expectedPlan.source ||
-    reviewedPlan.timeoutMs !== expectedPlan.timeoutMs ||
-    reviewedPlan.scope !== expectedPlan.scope
-  ) {
-    return { ok: false, reason: "mismatched_confirmation" };
-  }
-
-  return { ok: true, plan: reviewedPlan };
-}
-
-export function resetEcosystemExecutionConfirmationsForTests(): void {
-  confirmations.clear();
-}