@jsonstudio/rcc 0.85.9

package/scripts/tests/anthropic-responses-roundtrip.mjs

@@ -0,0 +1,297 @@
+#!/usr/bin/env node
+import fs from 'node:fs';
+import path from 'node:path';
+import os from 'node:os';
+import { pathToFileURL } from 'node:url';
+
+const CODEX_ROOT = path.join(os.homedir(), '.routecodex', 'codex-samples');
+const SEARCH_PATHS = [
+  { dir: path.join(CODEX_ROOT, 'openai-responses'), format: 'responses' },
+  { dir: path.join(CODEX_ROOT, 'anthropic-messages'), format: 'anthropic' }
+];
+
+function isObject(value) {
+  return !!value && typeof value === 'object';
+}
+
+function looksResponsesPayload(node) {
+  if (!isObject(node)) return false;
+  if (Array.isArray(node.output)) return true;
+  if (Array.isArray(node.items)) return true;
+  if (isObject(node.required_action)) return true;
+  return false;
+}
+
+function looksAnthropicPayload(node) {
+  if (!isObject(node)) return false;
+  if (Array.isArray(node.content)) return true;
+  if (Array.isArray(node.messages)) return true;
+  if (typeof node.stop_reason === 'string' && typeof node.role === 'string') return true;
+  return false;
+}
+
+function bfsFindPayload(doc, predicate) {
+  if (!isObject(doc)) return null;
+  const queue = [doc];
+  const seen = new WeakSet();
+  while (queue.length) {
+    const current = queue.shift();
+    if (!isObject(current)) continue;
+    if (seen.has(current)) continue;
+    seen.add(current);
+    if (predicate(current)) {
+      return current;
+    }
+    for (const value of Object.values(current)) {
+      if (isObject(value)) queue.push(value);
+    }
+  }
+  return null;
+}
+
+function loadCodexSample() {
+  for (const entry of SEARCH_PATHS) {
+    if (!fs.existsSync(entry.dir)) continue;
+    const files = fs.readdirSync(entry.dir).filter(f => f.toLowerCase().endsWith('.json')).sort();
+    for (const file of files) {
+      const full = path.join(entry.dir, file);
+      try {
+        const json = JSON.parse(fs.readFileSync(full, 'utf8'));
+        const payload = bfsFindPayload(json, entry.format === 'responses' ? looksResponsesPayload : looksAnthropicPayload);
+        if (payload) {
+          return { file: full, format: entry.format, payload };
+        }
+      } catch {
+        // ignore parse errors
+      }
+    }
+  }
+  return null;
+}
+
+async function loadConverters() {
+  const distRoot = path.resolve(process.cwd(), 'sharedmodule', 'llmswitch-core', 'dist');
+  const responsesBridgePath = path.join(distRoot, 'conversion', 'responses', 'responses-openai-bridge.js');
+  const responseRuntimePath = path.join(distRoot, 'conversion', 'hub', 'response', 'response-runtime.js');
+  if (!fs.existsSync(responsesBridgePath) || !fs.existsSync(responseRuntimePath)) {
+    throw new Error('llmswitch-core dist missing. 请先在 sharedmodule/llmswitch-core 运行 npm run build');
+  }
+  const responsesBridge = await import(pathToFileURL(responsesBridgePath).href);
+  const responseRuntime = await import(pathToFileURL(responseRuntimePath).href);
+  const { buildChatResponseFromResponses, buildResponsesPayloadFromChat } = responsesBridge;
+  const { buildAnthropicResponseFromChat, buildOpenAIChatFromAnthropicMessage } = responseRuntime;
+  if (
+    typeof buildChatResponseFromResponses !== 'function' ||
+    typeof buildResponsesPayloadFromChat !== 'function' ||
+    typeof buildAnthropicResponseFromChat !== 'function' ||
+    typeof buildOpenAIChatFromAnthropicMessage !== 'function'
+  ) {
+    throw new Error('conversion helpers missing. 请确认 sharedmodule/llmswitch-core 构建完成');
+  }
+  return {
+    buildChatResponseFromResponses,
+    buildResponsesPayloadFromChat,
+    buildAnthropicResponseFromChat,
+    buildOpenAIChatFromAnthropicMessage
+  };
+}
+
+async function main() {
+  const sample = loadCodexSample();
+  if (!sample) {
+    console.log('[anthropic-roundtrip] codex samples 未找到，跳过验证（可运行 npm run replay:codex-sample 捕获样本）');
+    return;
+  }
+  const converters = await loadConverters();
+  console.log(`[anthropic-roundtrip] 使用样本 ${sample.file} (${sample.format})`);
+
+  let baseResponsesPayload;
+  if (sample.format === 'responses') {
+    baseResponsesPayload = sample.payload;
+  } else {
+    const chatFromAnthropic = converters.buildOpenAIChatFromAnthropicMessage(sample.payload);
+    baseResponsesPayload = converters.buildResponsesPayloadFromChat(chatFromAnthropic);
+  }
+
+  const chatFromResponses = converters.buildChatResponseFromResponses(baseResponsesPayload);
+  const anthropicFromChat = converters.buildAnthropicResponseFromChat(chatFromResponses);
+  const chatRoundtrip = converters.buildOpenAIChatFromAnthropicMessage(anthropicFromChat);
+  const responsesRoundtrip = converters.buildResponsesPayloadFromChat(chatRoundtrip);
+
+  validateToolCalls(baseResponsesPayload, responsesRoundtrip);
+  validateToolCalls(responsesRoundtrip, baseResponsesPayload);
+  validatePrimaryFields(baseResponsesPayload, responsesRoundtrip);
+  validatePrimaryFields(responsesRoundtrip, baseResponsesPayload);
+
+  console.log('[anthropic-roundtrip] responses → chat → anthropic → chat → responses 闭环校验通过');
+}
+
+function toolSignature(entry) {
+  if (!isObject(entry)) return null;
+  const fn = isObject(entry.function) ? entry.function : entry;
+  const name = typeof fn.name === 'string' ? fn.name : '';
+  const args = typeof fn.arguments === 'string' ? fn.arguments : (isObject(fn.arguments) ? JSON.stringify(fn.arguments) : '');
+  if (!name) return null;
+  return `${name}::${args}`;
+}
+
+function collectToolCalls(payload) {
+  const rawRequired = payload?.required_action?.submit_tool_outputs?.tool_calls;
+  const required = Array.isArray(rawRequired) ? rawRequired : [];
+  const outputCalls = Array.isArray(payload?.output)
+    ? payload.output.filter(part => part && typeof part === 'object' && part.type === 'function_call')
+    : [];
+  return {
+    required: required.map(toolSignature).filter(Boolean).sort(),
+    output: outputCalls.map(toolSignature).filter(Boolean).sort()
+  };
+}
+
+function validateToolCalls(original, candidate) {
+  const orig = collectToolCalls(original || {});
+  const next = collectToolCalls(candidate || {});
+  if (orig.required.join('|') !== next.required.join('|') || orig.output.join('|') !== next.output.join('|')) {
+    console.error('[anthropic-roundtrip] tool call drift detected');
+    const diffDir = path.join(process.cwd(), 'tmp');
+    try { fs.mkdirSync(diffDir, { recursive: true }); } catch { /* ignore */ }
+    const outA = path.join(diffDir, 'responses-roundtrip-original.json');
+    const outB = path.join(diffDir, 'responses-roundtrip-result.json');
+    fs.writeFileSync(outA, JSON.stringify(original, null, 2));
+    fs.writeFileSync(outB, JSON.stringify(candidate, null, 2));
+    console.error(`详情已写入:\n  ${outA}\n  ${outB}`);
+    throw new Error('roundtrip tool call mismatch');
+  }
+}
+
+const PRIMARY_KEYS = [
+  'object',
+  'model',
+  'status',
+  'output_text',
+  'instructions',
+  'temperature',
+  'top_p',
+  'max_tokens',
+  'max_output_tokens',
+  'tool_choice',
+  'parallel_tool_calls',
+  'response_format',
+  'user',
+  'tools',
+  'required_action',
+  'output',
+  'usage'
+];
+
+const DROP_KEYS = new Set([
+  'id',
+  'created',
+  'created_at',
+  'response_id',
+  'item_id',
+  'chunk_id',
+  'request_id',
+  'requestId',
+  'entryEndpoint',
+  'annotations',
+  'system_fingerprint'
+]);
+
+function sanitizeNode(value) {
+  if (Array.isArray(value)) {
+    return value.map(v => sanitizeNode(v));
+  }
+  if (!isObject(value)) return value;
+  const out = {};
+  for (const key of Object.keys(value).sort()) {
+    if (DROP_KEYS.has(key)) continue;
+    if (key === 'metadata') continue;
+    const sanitized = sanitizeNode(value[key]);
+    if (sanitized === undefined) continue;
+    out[key] = sanitized;
+  }
+  return out;
+}
+
+function unwrapResponsesPayload(payload) {
+  let current = payload;
+  const visited = new Set();
+  while (isObject(current) && !visited.has(current)) {
+    visited.add(current);
+    if (current.object === 'response') return current;
+    if (isObject(current.response)) {
+      current = current.response;
+      continue;
+    }
+    if (isObject(current.data)) {
+      current = current.data;
+      continue;
+    }
+    break;
+  }
+  return payload;
+}
+
+function extractPrimaryFields(payload) {
+  if (!isObject(payload)) return {};
+  const base = unwrapResponsesPayload(payload);
+  const picked = {};
+  for (const key of PRIMARY_KEYS) {
+    if (base[key] === undefined) continue;
+    if (key === 'output') {
+      if (Array.isArray(base.output)) {
+        picked.output = base.output
+          .filter(item => {
+            const t = typeof (item && item.type) === 'string' ? String(item.type).toLowerCase() : '';
+            return t !== 'reasoning';
+          })
+          .map(item => sanitizeNode(item));
+      } else {
+        picked.output = [];
+      }
+      continue;
+    }
+    picked[key] = sanitizeNode(base[key]);
+    if (key === 'usage' && isObject(picked[key])) {
+      const details = picked[key].prompt_tokens_details;
+      if (isObject(details) && Object.keys(details).length === 0) {
+        delete picked[key].prompt_tokens_details;
+      }
+      if (picked[key].output_tokens !== undefined) delete picked[key].output_tokens;
+      if (picked[key].input_tokens !== undefined) delete picked[key].input_tokens;
+    }
+  }
+  return picked;
+}
+
+function normalizeForCompare(value) {
+  if (Array.isArray(value)) return value.map(normalizeForCompare);
+  if (!isObject(value)) return value;
+  const out = {};
+  for (const key of Object.keys(value).sort()) {
+    out[key] = normalizeForCompare(value[key]);
+  }
+  return out;
+}
+
+function validatePrimaryFields(original, candidate) {
+  const orig = normalizeForCompare(extractPrimaryFields(original || {}));
+  const next = normalizeForCompare(extractPrimaryFields(candidate || {}));
+  const origStr = JSON.stringify(orig);
+  const nextStr = JSON.stringify(next);
+  if (origStr !== nextStr) {
+    console.error('[anthropic-roundtrip] primary field drift detected');
+    const diffDir = path.join(process.cwd(), 'tmp');
+    try { fs.mkdirSync(diffDir, { recursive: true }); } catch { /* ignore */ }
+    const outA = path.join(diffDir, 'responses-roundtrip-primary-original.json');
+    const outB = path.join(diffDir, 'responses-roundtrip-primary-result.json');
+    fs.writeFileSync(outA, JSON.stringify(orig, null, 2));
+    fs.writeFileSync(outB, JSON.stringify(next, null, 2));
+    throw new Error('roundtrip primary field mismatch');
+  }
+}
+
+main().catch((err) => {
+  console.error('[anthropic-roundtrip] failed:', err);
+  process.exitCode = 1;
+});

package/scripts/tests/responses-provider-dry-run.mjs

@@ -0,0 +1,137 @@
+#!/usr/bin/env node
+/**
+ * Responses provider dry-run harness.
+ * Loads a provider config (default ~/.routecodex/provider/c4m/config.v1.json),
+ * instantiates the Responses provider, and runs preprocessRequest to inspect
+ * the sanitized payload (before HTTP send). Useful for verifying compatibility
+ * stripping (e.g. max_output_tokens) without touching upstream APIs.
+ */
+
+import fs from 'node:fs';
+import path from 'node:path';
+import { fileURLToPath, pathToFileURL } from 'node:url';
+
+const __dirname = path.dirname(fileURLToPath(import.meta.url));
+const ROOT = path.resolve(__dirname, '../..');
+
+const ProviderFactory = (await import(pathToFileURL(
+  path.join(ROOT, 'dist/modules/pipeline/modules/provider/v2/core/provider-factory.js')
+).href)).ProviderFactory;
+const { attachProviderRuntimeMetadata, extractProviderRuntimeMetadata } = await import(pathToFileURL(
+  path.join(ROOT, 'dist/modules/pipeline/modules/provider/v2/core/provider-runtime-metadata.js')
+).href);
+
+function usage(err) {
+  const msg = err ? `❌ ${err}\n` : '';
+  console.log(`${msg}Usage: node scripts/tests/responses-provider-dry-run.mjs [configPath] [providerId.modelId]`);
+  process.exit(err ? 1 : 0);
+}
+
+const args = process.argv.slice(2);
+const configPath = args[0] || path.join(process.env.HOME || '~', '.routecodex', 'provider', 'c4m', 'config.v1.json');
+if (!fs.existsSync(configPath)) usage(`Config file not found: ${configPath}`);
+const providerTarget = args[1] || 'c4m.gpt-5.1';
+const [providerId, modelId = 'gpt-5.1'] = providerTarget.split('.');
+
+const config = JSON.parse(fs.readFileSync(configPath, 'utf8'));
+const providerDef = config?.virtualrouter?.providers?.[providerId];
+if (!providerDef) usage(`Provider "${providerId}" not found in config`);
+const auth = providerDef.auth || {};
+const apiKey = auth.apiKey || auth.value || process.env.DRY_RUN_API_KEY || 'dry-run-key';
+
+const runtime = {
+  runtimeKey: `${providerId}.dry`,
+  providerId,
+  providerKey: `${providerId}.dry`,
+  keyAlias: 'dry',
+  providerType: (providerDef.type || 'openai').toLowerCase(),
+  endpoint: providerDef.baseURL || providerDef.baseUrl || providerDef.endpoint || 'https://example.local/v1',
+  auth: {
+    type: 'apikey',
+    value: apiKey
+  },
+  compatibilityProfile: providerDef.compat || 'default',
+  outboundProfile: providerDef.type === 'responses' ? 'openai-responses' : 'openai-chat',
+  defaultModel: modelId
+};
+
+const dependencies = {
+  logger: {
+    logModule: (module, event, data) => {
+      if (process.env.DRY_LOG_VERBOSE === '1') {
+        console.log(`[${module}] ${event}`, data || '');
+      }
+    },
+    logError: (error, ctx) => console.error('[dry-run] logError', error.message, ctx || {}),
+    logInfo: (msg, data) => {
+      if (process.env.DRY_LOG_VERBOSE === '1') {
+        console.log('[dry-run]', msg, data || {});
+      }
+    },
+    logProviderRequest: () => {},
+    logProviderResponse: () => {}
+  },
+  errorHandlingCenter: {
+    handleError: () => {}
+  },
+  debugCenter: {
+    log: () => {}
+  }
+};
+
+const provider = ProviderFactory.createProviderFromRuntime(runtime, dependencies);
+await provider.initialize();
+
+function buildSampleRequest() {
+  return {
+    data: {
+      model: modelId,
+      input: [
+        {
+          role: 'system',
+          content: [{ type: 'input_text', text: 'dry-run system prompt' }]
+        },
+        {
+          role: 'user',
+          content: [{ type: 'input_text', text: 'hello from dry-run' }]
+        }
+      ],
+      max_output_tokens: 9999,
+      temperature: 0.6
+    },
+    metadata: {
+      entryEndpoint: '/v1/messages',
+      stream: false
+    }
+  };
+}
+
+const request = buildSampleRequest();
+attachProviderRuntimeMetadata(request, {
+  requestId: `dry-run-${Date.now()}`,
+  providerId: runtime.providerId,
+  providerKey: runtime.providerKey,
+  providerType: runtime.providerType,
+  providerProtocol: runtime.outboundProfile === 'openai-responses' ? 'openai-responses' : 'openai-chat',
+  routeName: 'default',
+  target: {
+    providerKey: `${runtime.providerId}.${runtime.keyAlias}.${modelId}`,
+    providerType: runtime.providerType,
+    compatibilityProfile: runtime.compatibilityProfile,
+    runtimeKey: runtime.runtimeKey,
+    modelId
+  },
+  metadata: {
+    stream: false
+  }
+});
+
+console.log('runtime metadata detected before preprocess:', extractProviderRuntimeMetadata(request));
+if (typeof provider.createContext === 'function') {
+  provider.createContext(request);
+}
+const processed = await provider.preprocessRequest(request);
+console.log('runtime metadata after preprocess:', extractProviderRuntimeMetadata(processed));
+const body = processed?.data || processed;
+console.log('--- Sanitized request body ---');
+console.log(JSON.stringify(body, null, 2));

package/scripts/tests/virtual-router-health.mjs

@@ -0,0 +1,269 @@
+#!/usr/bin/env node
+/**
+ * Virtual Router health + error-handling simulator
+ *
+ *  - 复用 sharedmodule/llmswitch-core 的 VirtualRouterEngine/ProviderErrorCenter
+ *  - 注入不同错误类型（429/401/400/5xx/timeout/...），观察熔断与调度行为
+ *  - 输出 JSON summary 以及逐步日志，供集成测试 / dry-run 分析
+ */
+
+import fs from 'node:fs/promises';
+import path from 'node:path';
+import { fileURLToPath, pathToFileURL } from 'node:url';
+
+const __dirname = path.dirname(fileURLToPath(import.meta.url));
+const ROOT = path.resolve(__dirname, '../..');
+const CORE_DIST = path.join(ROOT, 'sharedmodule', 'llmswitch-core', 'dist', 'v2', 'router', 'virtual-router');
+
+async function loadCoreModule(rel) {
+  const file = path.join(CORE_DIST, rel);
+  return import(pathToFileURL(file).href);
+}
+
+const { VirtualRouterEngine } = await loadCoreModule('engine.js');
+const { providerErrorCenter } = await loadCoreModule('error-center.js');
+const { VirtualRouterError } = await loadCoreModule('types.js');
+
+function parseArgs(argv) {
+  const args = { out: null };
+  const list = [...argv];
+  while (list.length) {
+    const cur = list.shift();
+    if (cur === '--out' || cur === '--output') {
+      args.out = list.shift() || null;
+    } else if (cur === '--help' || cur === '-h') {
+      args.help = true;
+    }
+  }
+  return args;
+}
+
+function buildProviderProfile(providerKey, endpoint) {
+  return {
+    providerKey,
+    providerType: 'openai',
+    endpoint,
+    auth: { type: 'apiKey', secretRef: providerKey },
+    outboundProfile: 'openai-chat',
+    compatibilityProfile: 'default',
+    defaultModel: 'sim-model'
+  };
+}
+
+function createRouterConfig() {
+  const providers = {
+    'alpha.sim-model': buildProviderProfile('alpha.sim-model', 'https://alpha.local/v1'),
+    'bravo.sim-model': buildProviderProfile('bravo.sim-model', 'https://bravo.local/v1'),
+    'charlie.sim-model': buildProviderProfile('charlie.sim-model', 'https://charlie.local/v1')
+  };
+  const routing = {
+    default: Object.keys(providers),
+    coding: ['bravo.sim-model', 'charlie.sim-model'],
+    thinking: ['charlie.sim-model', 'alpha.sim-model']
+  };
+  return {
+    routing,
+    providers,
+    classifier: {
+      longContextThresholdTokens: 60000,
+      thinkingKeywords: ['think', '考', 'reason'],
+      backgroundKeywords: []
+    },
+    loadBalancing: { strategy: 'round-robin' },
+    health: {
+      failureThreshold: 2,
+      cooldownMs: 5000,
+      fatalCooldownMs: 60_000
+    }
+  };
+}
+
+const REQUEST_TEMPLATE = {
+  model: 'sim-model',
+  messages: [
+    { role: 'system', content: 'integration-test' },
+    { role: 'user', content: 'routecodex virtual-router health test' }
+  ]
+};
+
+function cloneRequest(text) {
+  return {
+    ...REQUEST_TEMPLATE,
+    messages: [
+      REQUEST_TEMPLATE.messages[0],
+      { role: 'user', content: text || REQUEST_TEMPLATE.messages[1].content }
+    ]
+  };
+}
+
+class VirtualRouterSimulator {
+  constructor(config) {
+    this.engine = new VirtualRouterEngine();
+    this.engine.initialize(config);
+    this.unsubscribe = providerErrorCenter.subscribe((event) => {
+      this.engine.handleProviderFailure(event);
+    });
+    this.sequence = 0;
+    this.history = [];
+  }
+
+  dispose() {
+    this.unsubscribe?.();
+  }
+
+  log(stage, data) {
+    const payload = { stage, timestamp: Date.now(), ...data };
+    this.history.push(payload);
+    const printable = JSON.stringify(payload);
+    console.log(printable);
+  }
+
+  emitError(providerKey, signal) {
+    const event = providerErrorCenter.emit({
+      providerKey,
+      routeName: signal?.routeName ?? 'default',
+      ...signal
+    });
+    this.log('error', { providerKey, event });
+    return event;
+  }
+
+  runRoute(label = 'default') {
+    const requestId = `req_${++this.sequence}`;
+    const request = cloneRequest(`scenario:${label}:${Date.now()}`);
+    const metadata = {
+      requestId,
+      entryEndpoint: '/v1/chat/completions',
+      processMode: 'chat',
+      stream: false,
+      direction: 'request',
+      providerProtocol: 'openai-chat',
+      routeHint: label
+    };
+    try {
+      const result = this.engine.route(request, metadata);
+      this.log('route', { label, providerKey: result.decision.providerKey, decision: result.decision });
+      return result.decision.providerKey;
+    } catch (error) {
+      if (error instanceof VirtualRouterError) {
+        this.log('route-error', { label, code: error.code, message: error.message });
+      } else {
+        this.log('route-error', { label, message: String(error) });
+      }
+      return null;
+    }
+  }
+
+  snapshot(name) {
+    const status = this.engine.getStatus();
+    this.log('snapshot', { name, routes: status.routes, health: status.health });
+    return status;
+  }
+}
+
+async function runScenario(name, fn) {
+  console.log(`\n=== Scenario: ${name} ===`);
+  const simulator = new VirtualRouterSimulator(createRouterConfig());
+  try {
+    await fn(simulator);
+    simulator.snapshot(name);
+    return { name, status: 'ok', history: simulator.history };
+  } catch (error) {
+    simulator.snapshot(`${name}-failure`);
+    console.error(`[scenario:${name}] failed:`, error);
+    return { name, status: 'failed', error: error instanceof Error ? error.message : String(error), history: simulator.history };
+  } finally {
+    simulator.dispose();
+  }
+}
+
+async function scenarioRateLimit(sim) {
+  sim.runRoute('default');
+  sim.emitError('alpha.sim-model', { statusCode: 429 });
+  sim.emitError('alpha.sim-model', { statusCode: 429 });
+  sim.runRoute('default');
+}
+
+async function scenarioAuthFatal(sim) {
+  sim.runRoute('default');
+  sim.emitError('bravo.sim-model', { statusCode: 401, fatal: true, cooldownOverrideMs: 120000 });
+  sim.runRoute('default');
+  sim.emitError('charlie.sim-model', { statusCode: 403, fatal: true, cooldownOverrideMs: 120000 });
+  sim.runRoute('default');
+}
+
+async function scenarioClientError(sim) {
+  sim.runRoute('default');
+  sim.emitError('alpha.sim-model', { statusCode: 400, affectsHealth: false });
+  sim.runRoute('default');
+}
+
+async function scenarioUpstream(sim) {
+  sim.runRoute('default');
+  sim.emitError('alpha.sim-model', { statusCode: 502 });
+  sim.emitError('alpha.sim-model', { statusCode: 500 });
+  sim.runRoute('default');
+  sim.emitError('bravo.sim-model', { statusCode: 502 });
+  sim.emitError('charlie.sim-model', { statusCode: 502 });
+  sim.runRoute('default');
+}
+
+async function scenarioTimeout(sim) {
+  sim.runRoute('default');
+  sim.emitError('alpha.sim-model', { statusCode: 0, reason: 'timeout', retryable: true, affectsHealth: true, cooldownOverrideMs: 2000 });
+  sim.runRoute('default');
+  await new Promise((resolve) => setTimeout(resolve, 2100));
+  sim.runRoute('default');
+}
+
+async function scenarioScheduler(sim) {
+  sim.runRoute('thinking');
+  sim.emitError('charlie.sim-model', { statusCode: 500 });
+  sim.emitError('charlie.sim-model', { statusCode: 500 });
+  sim.runRoute('thinking');
+  sim.emitError('alpha.sim-model', { statusCode: 401, fatal: true, cooldownOverrideMs: 15000 });
+  sim.emitError('bravo.sim-model', { statusCode: 401, fatal: true, cooldownOverrideMs: 15000 });
+  sim.emitError('charlie.sim-model', { statusCode: 401, fatal: true, cooldownOverrideMs: 15000 });
+  sim.runRoute('thinking');
+}
+
+async function main() {
+  const args = parseArgs(process.argv.slice(2));
+  if (args.help) {
+    console.log('Usage: node scripts/tests/virtual-router-health.mjs [--out summary.json]');
+    return;
+  }
+
+  const scenarios = [
+    ['rate-limit', scenarioRateLimit],
+    ['auth-fatal', scenarioAuthFatal],
+    ['client-error', scenarioClientError],
+    ['upstream', scenarioUpstream],
+    ['timeout', scenarioTimeout],
+    ['scheduler', scenarioScheduler]
+  ];
+
+  const summary = [];
+  for (const [name, fn] of scenarios) {
+    const result = await runScenario(name, fn);
+    summary.push({
+      name,
+      status: result.status,
+      lastHealth: result.history.filter((entry) => entry.stage === 'snapshot').slice(-1)[0]?.health ?? null
+    });
+  }
+
+  if (args.out) {
+    const outFile = path.resolve(process.cwd(), args.out);
+    await fs.mkdir(path.dirname(outFile), { recursive: true });
+    await fs.writeFile(outFile, JSON.stringify(summary, null, 2), 'utf-8');
+    console.log(`Summary written to ${outFile}`);
+  } else {
+    console.log(JSON.stringify(summary, null, 2));
+  }
+}
+
+main().catch((error) => {
+  console.error('virtual-router-health failed:', error);
+  process.exit(1);
+});