@kuralle-syrinx/cli 4.4.0

package/dist/index.js

@@ -0,0 +1,1161 @@
+#!/usr/bin/env node
+
+// src/cli.ts
+import { parseArgs } from "node:util";
+
+// src/agent-resolve.ts
+import { isAbsolute, resolve } from "node:path";
+import { pathToFileURL } from "node:url";
+
+// src/exit-codes.ts
+var EXIT_CODES = {
+  SUCCESS: 0,
+  INTERNAL: 1,
+  USAGE: 2,
+  CONFIG: 3,
+  BACKEND: 4,
+  ASSERTION: 5
+};
+var EXIT_CODE_TABLE = [
+  { code: EXIT_CODES.SUCCESS, name: "SUCCESS", meaning: "the command completed and, where applicable, any assertion matched" },
+  { code: EXIT_CODES.INTERNAL, name: "INTERNAL", meaning: "an unexpected error inside the CLI itself (not a usage or backend problem) \u2014 treat as a bug" },
+  { code: EXIT_CODES.USAGE, name: "USAGE", meaning: "bad invocation: unknown verb/flag, a missing required argument, or a fixture the CLI cannot honour (unsupported format, capture-config mismatch)" },
+  { code: EXIT_CODES.CONFIG, name: "CONFIG", meaning: "required provider configuration or API keys are missing" },
+  { code: EXIT_CODES.BACKEND, name: "BACKEND", meaning: "the agent or backend failed while running the turn (provider/network error, timeout, pipeline error)" },
+  { code: EXIT_CODES.ASSERTION, name: "ASSERTION", meaning: "a replayed fixture's transcript drifted from the expected transcript" }
+];
+var CliError = class extends Error {
+  exitCode;
+  details;
+  constructor(exitCode, message, details) {
+    super(message);
+    this.name = "CliError";
+    this.exitCode = exitCode;
+    this.details = details;
+  }
+};
+
+// src/agent-resolve.ts
+async function resolveAgentFactory(spec, baseDir) {
+  const [modulePath, exportName] = spec.split("#");
+  if (!modulePath) {
+    throw new CliError(EXIT_CODES.USAGE, `--agent needs a module path, got: ${spec}`);
+  }
+  const abs = isAbsolute(modulePath) ? modulePath : resolve(baseDir, modulePath);
+  const url = pathToFileURL(abs).href;
+  let mod;
+  try {
+    mod = await import(url);
+  } catch (err) {
+    throw new CliError(EXIT_CODES.USAGE, `could not load --agent module "${modulePath}" (resolved to ${abs}): ${err instanceof Error ? err.message : String(err)}`);
+  }
+  const picked = exportName ? mod[exportName] : mod["default"] ?? mod["createSession"];
+  if (typeof picked !== "function") {
+    const available = Object.keys(mod).filter((k) => typeof mod[k] === "function");
+    throw new CliError(
+      EXIT_CODES.USAGE,
+      `${abs} has no callable export ${exportName ? `"${exportName}"` : "(default or createSession)"}. Callable exports: ${available.length > 0 ? available.join(", ") : "(none)"}`
+    );
+  }
+  const factory = picked;
+  const label = `${modulePath}${exportName ? `#${exportName}` : ""}`;
+  return {
+    label,
+    factory: async () => {
+      try {
+        return await factory();
+      } catch (err) {
+        throw new CliError(
+          EXIT_CODES.CONFIG,
+          `--agent ${label} failed to construct a session: ${err instanceof Error ? err.message : String(err)}`
+        );
+      }
+    }
+  };
+}
+
+// src/version.ts
+import { createRequire } from "node:module";
+import { existsSync, readFileSync } from "node:fs";
+import { dirname, join, resolve as resolvePath } from "node:path";
+
+// package.json
+var package_default = {
+  name: "@kuralle-syrinx/cli",
+  version: "4.3.0",
+  private: false,
+  description: "Agent-facing CLI for Syrinx \u2014 run a turn or a text exchange with deterministic, machine-readable (--json) output and exit codes. Not a console: no REPL, no chat loop, no microphone.",
+  keywords: [
+    "voice",
+    "voice-agent",
+    "speech",
+    "syrinx",
+    "cli",
+    "agent",
+    "testing"
+  ],
+  license: "MIT",
+  homepage: "https://github.com/kuralle/syrinx#readme",
+  repository: {
+    type: "git",
+    url: "git+https://github.com/kuralle/syrinx.git",
+    directory: "packages/cli"
+  },
+  bugs: {
+    url: "https://github.com/kuralle/syrinx/issues"
+  },
+  type: "module",
+  bin: {
+    syrinx: "./dist/index.js"
+  },
+  files: [
+    "dist",
+    "src",
+    "README.md"
+  ],
+  exports: {
+    "./turn-runner": "./src/turn-runner.ts"
+  },
+  scripts: {
+    build: "node scripts/build.mjs",
+    typecheck: "tsc --noEmit",
+    test: "vitest run"
+  },
+  dependencies: {
+    "@kuralle-syrinx/core": "workspace:*",
+    wavefile: "^11.0.0"
+  },
+  devDependencies: {
+    "@kuralle-syrinx/test": "workspace:*",
+    "@types/node": "^22.0.0",
+    esbuild: "^0.28.1",
+    typescript: "^5.7.0",
+    vitest: "^3.2.6"
+  }
+};
+
+// src/version.ts
+var CLI_VERSION = package_default.version;
+var CORE_PACKAGE_NAME = "@kuralle-syrinx/core";
+function majorOf(version) {
+  return version.split(".")[0] ?? version;
+}
+function resolveInstalledPackageVersion(pkgName, fromDir) {
+  const anchor = join(resolvePath(fromDir), "package.json");
+  const require3 = createRequire(anchor);
+  let entryPath;
+  try {
+    entryPath = require3.resolve(pkgName);
+  } catch {
+    return void 0;
+  }
+  let dir = dirname(entryPath);
+  for (let depth = 0; depth < 20; depth += 1) {
+    const candidate = join(dir, "package.json");
+    if (existsSync(candidate)) {
+      try {
+        const parsed = JSON.parse(readFileSync(candidate, "utf8"));
+        if (parsed.name === pkgName && typeof parsed.version === "string") {
+          return { version: parsed.version, packageJsonPath: candidate };
+        }
+      } catch {
+      }
+    }
+    const parent = dirname(dir);
+    if (parent === dir) break;
+    dir = parent;
+  }
+  return void 0;
+}
+function checkCoreVersionSkew(fromDir) {
+  const resolved = resolveInstalledPackageVersion(CORE_PACKAGE_NAME, fromDir);
+  if (!resolved) {
+    return { cliVersion: CLI_VERSION, coreVersion: void 0, coreResolved: false, mismatch: false };
+  }
+  const mismatch = majorOf(resolved.version) !== majorOf(CLI_VERSION);
+  return { cliVersion: CLI_VERSION, coreVersion: resolved.version, coreResolved: true, mismatch };
+}
+function warnOnVersionSkew(fromDir) {
+  const check = checkCoreVersionSkew(fromDir);
+  if (check.mismatch) {
+    console.error(
+      `[syrinx] warning: CLI version ${check.cliVersion} (major ${majorOf(check.cliVersion)}) does not match the installed ${CORE_PACKAGE_NAME} version ${String(check.coreVersion)} (major ${majorOf(check.coreVersion ?? "")}) in ${fromDir}. Behavior may differ from what this CLI version expects.`
+    );
+  }
+  return check;
+}
+
+// src/doctor.ts
+var WELL_KNOWN_PROVIDER_KEYS = ["DEEPGRAM_API_KEY", "OPENAI_API_KEY", "CARTESIA_API_KEY", "GEMINI_API_KEY", "ELEVENLABS_API_KEY", "GROK_API_KEY"];
+async function runDoctor(opts = {}) {
+  const cwd = opts.cwd ?? process.cwd();
+  const env = opts.env ?? process.env;
+  const skew = checkCoreVersionSkew(cwd);
+  const wellKnownProviderKeys = Object.fromEntries(
+    WELL_KNOWN_PROVIDER_KEYS.map((key) => [key, Boolean(env[key]?.trim())])
+  );
+  let agent = null;
+  if (opts.agentSpec) {
+    try {
+      const resolved = await resolveAgentFactory(opts.agentSpec, cwd);
+      agent = { spec: opts.agentSpec, resolved: true, label: resolved.label };
+    } catch (err) {
+      agent = {
+        spec: opts.agentSpec,
+        resolved: false,
+        error: err instanceof CliError ? err.message : err instanceof Error ? err.message : String(err)
+      };
+    }
+  }
+  const summary = !skew.coreResolved ? `${CORE_PACKAGE_NAME} is not installed in this project` : agent ? agent.resolved ? `agent resolved: ${agent.label}` : `agent could not be resolved: ${agent.error}` : "pass --agent <module>#<export> to check whether a specific agent resolves; the provider keys above are informational only \u2014 this CLI does not require any specific set";
+  return {
+    cliVersion: CLI_VERSION,
+    node: { version: opts.nodeVersion ?? process.version, platform: opts.platform ?? process.platform },
+    core: {
+      package: CORE_PACKAGE_NAME,
+      resolved: skew.coreResolved,
+      version: skew.coreVersion,
+      cliMajor: majorOf(CLI_VERSION),
+      coreMajor: skew.coreVersion ? majorOf(skew.coreVersion) : void 0,
+      majorMismatch: skew.mismatch
+    },
+    wellKnownProviderKeys,
+    agent,
+    summary
+  };
+}
+
+// src/help.ts
+var EXIT_CODE_LINES = EXIT_CODE_TABLE.map((row) => `  ${String(row.code)}  ${row.name.padEnd(9)} ${row.meaning}`).join("\n");
+var HELP_TEXT = `syrinx \u2014 the agent-facing CLI for a Syrinx voice agent.
+
+Not a console: no REPL, no chat loop, no microphone. Every command is a single
+deterministic invocation with a documented exit code, meant to be run by a
+coding agent (or a script), not a human at a prompt.
+
+This CLI brings no providers of its own \u2014 no Deepgram, no Cartesia, no OpenAI.
+--agent points it at YOUR agent module; that module owns its own providers.
+
+USAGE
+  syrinx <command> [options]
+
+AGENT RESOLUTION (--agent, required for turn and text)
+  --agent <module>[#namedExport]
+      <module> is a path (resolved relative to cwd unless absolute) to your
+      own code; the export must be a zero-arg factory returning a
+      VoiceAgentSession (or a Promise of one) \u2014 exactly the contract
+      examples/02-hello-voice-headless/scripts/dev-server.ts's --agent flag
+      uses. Omit #export for a default export (or a "createSession" export).
+      Resolution failures (module not found, no such export, export not
+      callable) exit USAGE and name the callable exports that were found.
+      If the export IS callable but throws when invoked, that exits CONFIG \u2014
+      most plausibly the agent's own module is missing something it needs
+      (an env var, a key file, ...).
+
+COMMANDS
+  turn --in <fixture.wav|fixture.json> --agent <module>#<export> [options]
+      Run one turn through the resolved agent and report the transcript, the
+      reply, and per-stage timings. Given a fixture.json sidecar (produced by
+      the Studio's "Save as fixture"), honours its recorded capture config
+      and, when the sidecar carries an expected transcript, asserts the
+      replay matches it.
+    --in <path>              required. fixture.wav or fixture.json
+    --agent <module>#<export>  required.
+    --session-dir <dir>       where turn artifacts are written (default: a temp dir)
+    --json                    emit one parseable JSON object on stdout
+
+  text "<message>" --agent <module>#<export> [options]
+      Send a typed turn (no STT, no microphone) to the resolved agent and
+      report the reply.
+    --agent <module>#<export>  required.
+    --json                    emit one parseable JSON object on stdout
+
+  doctor [--agent <module>#<export>] [--json]
+      Report what is configured: the Node runtime, whether
+      @kuralle-syrinx/core is installed and its version, and \u2014 informational
+      only \u2014 which well-known provider keys are present in the environment
+      (never their values). This CLI does not require any specific provider
+      key; pass --agent to check whether a SPECIFIC agent module resolves.
+      Always exits 0 \u2014 this command diagnoses, it does not assert.
+
+  --help, -h                show this help
+  --version, -v              print the CLI version
+
+OUTPUT
+  --json is a first-class output mode: every command supports it and emits a
+  single parseable JSON object on stdout. Diagnostics (warnings, e.g. a
+  version-skew notice) always go to stderr, never stdout, so --json output
+  stays parseable. Without --json, commands print a short human-readable
+  summary to stdout and errors to stderr.
+
+EXIT CODES
+${EXIT_CODE_LINES}
+`;
+
+// src/text-turn.ts
+import { randomUUID } from "node:crypto";
+
+// ../core/src/pricing.ts
+var DEFAULT_PRICE_CATALOG = {
+  source: "voice-prices@3 | deepgram.com/pricing PAYG Nova-3 streaming monolingual $0.0077/min \u2192 $0.000128333/s; deepgram.com/pricing Aura-2 TTS $0.030/1k chars \u2192 $30/1M; cartesia.ai/pricing + docs.cartesia.ai/pricing ~1 credit/char, PAYG ~$50/1M chars (cloudtalk.io cartesia-pricing 2026); openai tts-1 $15/1M chars (openai.com api pricing); gpt-4o-mini-tts text $0.60/1M (community/azure listed text input rate); openai GPT-4.1-mini $0.40/$1.60 per 1M in/out (developers.openai.com/api/docs/pricing; Azure GPT-4.1-mini-2025-04-14 Global); cloud.google.com/speech-to-text/pricing V2 standard recognition $0.016/min \u2192 $0.000266667/s (latest_long); ai.google.dev/pricing Gemini 2.5 Flash TTS preview text $0.50/1M chars (Gemini API TTS text input rate, 2026); elevenlabs.io/pricing/api Flash/Turbo TTS $0.05/1k chars \u2192 $50/1M; Multilingual v2/v3 $0.10/1k \u2192 $100/1M; Scribe v2 Realtime $0.39/hour \u2192 $0.000108333/s; grok/stt + grok/* TTS + epsilon/epsilon-tts intentionally ABSENT (no public list price \u2192 costOf unpriced, never silent $0)",
+  version: "3",
+  stt: {
+    "deepgram/nova-3": { usdPerAudioSecond: 77e-4 / 60 },
+    "deepgram/nova-2": { usdPerAudioSecond: 77e-4 / 60 },
+    "deepgram/flux-general-en": { usdPerAudioSecond: 77e-4 / 60 },
+    // Google Cloud Speech-to-Text V2 standard streaming recognition list rate.
+    "google/latest_long": { usdPerAudioSecond: 0.016 / 60 },
+    "google/latest_short": { usdPerAudioSecond: 0.016 / 60 },
+    "google/chirp_2": { usdPerAudioSecond: 0.016 / 60 },
+    // ElevenLabs Scribe v2 Realtime — public list $0.39/hour.
+    "elevenlabs/scribe_v2_realtime": { usdPerAudioSecond: 0.39 / 3600 },
+    "local/whisper": { usdPerAudioSecond: 0 }
+    // grok/stt: no public list price — omit so costOf → unpriced
+  },
+  llm: {
+    "openai/gpt-4.1-mini": {
+      usdPer1MInputTokens: 0.4,
+      usdPer1MOutputTokens: 1.6,
+      usdPer1MCachedInputTokens: 0.1
+    },
+    "local/llm": {
+      usdPer1MInputTokens: 0,
+      usdPer1MOutputTokens: 0
+    }
+  },
+  tts: {
+    "cartesia/sonic-3": { usdPer1MCharacters: 50 },
+    "openai/gpt-4o-mini-tts": { usdPer1MCharacters: 0.6 },
+    "openai/tts-1": { usdPer1MCharacters: 15 },
+    "deepgram/aura-2-thalia-en": { usdPer1MCharacters: 30 },
+    // Gemini TTS preview models — Gemini API TTS text input list rate.
+    "gemini/gemini-3.1-flash-tts-preview": { usdPer1MCharacters: 0.5 },
+    "gemini/gemini-2.5-flash-preview-tts": { usdPer1MCharacters: 0.5 },
+    "gemini/gemini-2.5-pro-preview-tts": { usdPer1MCharacters: 0.5 },
+    // ElevenLabs public list — Flash/Turbo $0.05/1k, Multilingual $0.10/1k.
+    "elevenlabs/eleven_flash_v2_5": { usdPer1MCharacters: 50 },
+    "elevenlabs/eleven_flash_v2": { usdPer1MCharacters: 50 },
+    "elevenlabs/eleven_turbo_v2_5": { usdPer1MCharacters: 50 },
+    "elevenlabs/eleven_turbo_v2": { usdPer1MCharacters: 50 },
+    "elevenlabs/eleven_multilingual_v2": { usdPer1MCharacters: 100 },
+    "local/tts": { usdPer1MCharacters: 0 }
+    // grok/* voice keys + epsilon/epsilon-tts: no public list — omit → unpriced
+  }
+};
+
+// ../core/src/audio-envelope.ts
+var SYRINX_AUDIO_ENVELOPE_MAGIC = new Uint8Array([83, 89, 82, 88, 65, 49, 10]);
+
+// ../core/src/audio/g722.ts
+var QMF_FWD = Object.freeze([
+  3,
+  -11,
+  12,
+  32,
+  -210,
+  951,
+  3876,
+  -805,
+  362,
+  -156,
+  53,
+  -11
+]);
+var QMF_REV = Object.freeze([
+  -11,
+  53,
+  -156,
+  362,
+  -805,
+  3876,
+  951,
+  -210,
+  32,
+  12,
+  -11,
+  3
+]);
+var QM2 = Object.freeze([-7408, -1616, 7408, 1616]);
+var QM4 = Object.freeze([
+  0,
+  -20456,
+  -12896,
+  -8968,
+  -6288,
+  -4240,
+  -2584,
+  -1200,
+  20456,
+  12896,
+  8968,
+  6288,
+  4240,
+  2584,
+  1200,
+  0
+]);
+var QM6 = Object.freeze([
+  -136,
+  -136,
+  -136,
+  -136,
+  -24808,
+  -21904,
+  -19008,
+  -16704,
+  -14984,
+  -13512,
+  -12280,
+  -11192,
+  -10232,
+  -9360,
+  -8576,
+  -7856,
+  -7192,
+  -6576,
+  -6e3,
+  -5456,
+  -4944,
+  -4464,
+  -4008,
+  -3576,
+  -3168,
+  -2776,
+  -2400,
+  -2032,
+  -1688,
+  -1360,
+  -1040,
+  -728,
+  24808,
+  21904,
+  19008,
+  16704,
+  14984,
+  13512,
+  12280,
+  11192,
+  10232,
+  9360,
+  8576,
+  7856,
+  7192,
+  6576,
+  6e3,
+  5456,
+  4944,
+  4464,
+  4008,
+  3576,
+  3168,
+  2776,
+  2400,
+  2032,
+  1688,
+  1360,
+  1040,
+  728,
+  432,
+  136,
+  -432,
+  -136
+]);
+var Q6 = Object.freeze([
+  0,
+  35,
+  72,
+  110,
+  150,
+  190,
+  233,
+  276,
+  323,
+  370,
+  422,
+  473,
+  530,
+  587,
+  650,
+  714,
+  786,
+  858,
+  940,
+  1023,
+  1121,
+  1219,
+  1339,
+  1458,
+  1612,
+  1765,
+  1980,
+  2195,
+  2557,
+  2919,
+  0,
+  0
+]);
+var ILB = Object.freeze([
+  2048,
+  2093,
+  2139,
+  2186,
+  2233,
+  2282,
+  2332,
+  2383,
+  2435,
+  2489,
+  2543,
+  2599,
+  2656,
+  2714,
+  2774,
+  2834,
+  2896,
+  2960,
+  3025,
+  3091,
+  3158,
+  3228,
+  3298,
+  3371,
+  3444,
+  3520,
+  3597,
+  3676,
+  3756,
+  3838,
+  3922,
+  4008
+]);
+var ILN = Object.freeze([0, 63, 62, 31, 30, 29, 28, 27, 26, 25, 24, 23, 22, 21, 20, 19, 18, 17, 16, 15, 14, 13, 12, 11, 10, 9, 8, 7, 6, 5, 4, 0]);
+var ILP = Object.freeze([0, 61, 60, 59, 58, 57, 56, 55, 54, 53, 52, 51, 50, 49, 48, 47, 46, 45, 44, 43, 42, 41, 40, 39, 38, 37, 36, 35, 34, 33, 32, 0]);
+var IHN = Object.freeze([0, 1, 0]);
+var IHP = Object.freeze([0, 3, 2]);
+var WL = Object.freeze([-60, -30, 58, 172, 334, 538, 1198, 3042]);
+var RL42 = Object.freeze([0, 7, 6, 5, 4, 3, 2, 1, 7, 6, 5, 4, 3, 2, 1, 0]);
+var WH = Object.freeze([0, -214, 798]);
+var RH2 = Object.freeze([2, 1, 2, 1]);
+
+// src/text-turn.ts
+var DEFAULT_TIMEOUT_MS = 6e4;
+async function resolveSession(session) {
+  return typeof session === "function" ? session() : session;
+}
+async function driveText(opts) {
+  const session = await resolveSession(opts.session);
+  const contextId = randomUUID();
+  const t0 = performance.now();
+  let ttftMs = -1;
+  let reply = "";
+  let toolCalls = 0;
+  const on = (event, handler) => {
+    session.on(event, handler);
+  };
+  const finished = new Promise((resolveFinished, reject) => {
+    const timeout = setTimeout(() => {
+      reject(new CliError(EXIT_CODES.BACKEND, `agent did not finish within ${String(opts.timeoutMs ?? DEFAULT_TIMEOUT_MS)}ms`));
+    }, opts.timeoutMs ?? DEFAULT_TIMEOUT_MS);
+    on("agent_text_delta", (event) => {
+      if (event.turnId !== contextId) return;
+      if (ttftMs < 0) ttftMs = performance.now() - t0;
+      reply += event.delta;
+    });
+    on("agent_tool_call", (event) => {
+      if (event.turnId !== contextId) return;
+      toolCalls += 1;
+    });
+    on("agent_finished", (event) => {
+      if (event.turnId !== contextId) return;
+      clearTimeout(timeout);
+      resolveFinished();
+    });
+    on("error", (event) => {
+      clearTimeout(timeout);
+      reject(new CliError(EXIT_CODES.BACKEND, `agent failed: ${event.message} (${event.stage}/${event.category})`));
+    });
+  });
+  void finished.catch(() => {
+  });
+  try {
+    await session.start();
+    session.bus.push(1 /* Main */, {
+      kind: "user.text_received",
+      contextId,
+      timestampMs: Date.now(),
+      text: opts.message
+    });
+    await finished;
+  } catch (err) {
+    if (err instanceof CliError) throw err;
+    throw new CliError(EXIT_CODES.BACKEND, `agent failed: ${err instanceof Error ? err.message : String(err)}`);
+  } finally {
+    await session.close().catch(() => {
+    });
+  }
+  return {
+    reply,
+    ttftMs: ttftMs < 0 ? 0 : Math.round(ttftMs),
+    totalMs: Math.round(performance.now() - t0),
+    toolCalls
+  };
+}
+
+// src/text-command.ts
+async function runTextCommand(opts) {
+  const resolvedAgent = await resolveAgentFactory(opts.agentSpec, opts.cwd ?? process.cwd());
+  let result;
+  try {
+    result = await driveText({ session: resolvedAgent.factory, message: opts.message });
+  } catch (err) {
+    if (err instanceof CliError) throw err;
+    throw new CliError(EXIT_CODES.BACKEND, `text turn failed: ${err instanceof Error ? err.message : String(err)}`);
+  }
+  return { ...result, agent: resolvedAgent.label };
+}
+
+// src/turn-command.ts
+import { mkdtempSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { extname, join as join4, resolve as resolve3 } from "node:path";
+
+// src/fixture.ts
+import { readFileSync as readFileSync2 } from "node:fs";
+import { dirname as dirname2, join as join2 } from "node:path";
+var FIXTURE_FORMAT = "syrinx.fixture.v1";
+function loadFixture(sidecarPath) {
+  let raw;
+  try {
+    raw = readFileSync2(sidecarPath, "utf8");
+  } catch (err) {
+    throw new CliError(EXIT_CODES.USAGE, `fixture not found: ${sidecarPath}`, { cause: String(err) });
+  }
+  let sidecar;
+  try {
+    sidecar = JSON.parse(raw);
+  } catch (err) {
+    throw new CliError(EXIT_CODES.USAGE, `fixture is not valid JSON: ${sidecarPath}`, { cause: String(err) });
+  }
+  if (sidecar.format !== FIXTURE_FORMAT) {
+    throw new CliError(EXIT_CODES.USAGE, `unsupported fixture format "${sidecar.format}" (expected "${FIXTURE_FORMAT}")`);
+  }
+  if (sidecar.audio.sampleRateHz !== 16e3 || sidecar.audio.channels !== 1) {
+    throw new CliError(
+      EXIT_CODES.USAGE,
+      `this replay path needs mono 16 kHz audio; fixture is ${String(sidecar.audio.channels)}ch @ ${String(sidecar.audio.sampleRateHz)} Hz`
+    );
+  }
+  const dir = dirname2(sidecarPath);
+  const sibling = join2(dir, "captured.wav");
+  let wavPath;
+  try {
+    readFileSync2(sibling);
+    wavPath = sibling;
+  } catch {
+    wavPath = join2(dir, sidecar.audioFile);
+  }
+  return { sidecarPath, sidecar, wavPath };
+}
+function normalizeTranscript(text) {
+  return text.toLowerCase().replace(/[^a-z0-9\s]/g, " ").replace(/\s+/g, " ").trim();
+}
+function assertTranscript(expectedTranscript, actualTranscript) {
+  return {
+    expectedTranscript,
+    actualTranscript,
+    match: normalizeTranscript(expectedTranscript) === normalizeTranscript(actualTranscript)
+  };
+}
+
+// src/turn-runner.ts
+import { randomUUID as randomUUID2 } from "node:crypto";
+import { readFileSync as readFileSync3 } from "node:fs";
+import { mkdir, writeFile } from "node:fs/promises";
+import { createRequire as createRequire2 } from "node:module";
+import { basename, join as join3, resolve as resolve2 } from "node:path";
+var require2 = createRequire2(import.meta.url);
+var { WaveFile } = require2("wavefile");
+var SAMPLES_PER_FRAME = 320;
+var DEFAULT_FIXTURE_PATH = "/Users/mithushancj/Documents/asyncdot/openscoped/voice-media-transport/research/agents/tests/test_realtime/hello_world.wav";
+var DEFAULT_TTS_END_TIMEOUT_MS = 12e4;
+function readPcm16Mono16kWav(filePath) {
+  const buf = readFileSync3(filePath);
+  const wav = new WaveFile(Buffer.from(buf));
+  const fmt = wav.fmt;
+  if (fmt.numChannels !== 1) throw new Error(`expected mono WAV, got ${String(fmt.numChannels)} channels`);
+  if (fmt.bitsPerSample !== 16 || fmt.audioFormat !== 1) throw new Error("expected 16-bit PCM WAV");
+  const raw = wav.getSamples(false, Int16Array);
+  const mono = Array.isArray(raw) ? raw[0] : raw;
+  if (mono === void 0 || !(mono instanceof Int16Array)) throw new Error("WAV has no mono channel samples");
+  return fmt.sampleRate === 16e3 ? mono : resamplePcm162(mono, fmt.sampleRate, 16e3);
+}
+function resolveInputWavPath(path) {
+  const resolved = resolve2(path);
+  try {
+    readFileSync3(resolved);
+    return resolved;
+  } catch {
+    if (basename(path) === "hello.wav") return DEFAULT_FIXTURE_PATH;
+    throw new Error(`input WAV not found: ${resolved}`);
+  }
+}
+function resamplePcm162(samples, fromHz, toHz) {
+  if (fromHz <= 0 || toHz <= 0) throw new Error("invalid WAV sample rate");
+  const outLength = Math.max(1, Math.round(samples.length * toHz / fromHz));
+  const out = new Int16Array(outLength);
+  const ratio = fromHz / toHz;
+  for (let i = 0; i < out.length; i += 1) {
+    const src = i * ratio;
+    const lo = Math.floor(src);
+    const hi = Math.min(samples.length - 1, lo + 1);
+    const frac = src - lo;
+    out[i] = Math.round(samples[lo] * (1 - frac) + samples[hi] * frac);
+  }
+  return out;
+}
+function pcmToBytes(samples) {
+  return new Uint8Array(samples.buffer, samples.byteOffset, samples.byteLength);
+}
+function sliceFramePcm(samples, offset) {
+  const end = Math.min(offset + SAMPLES_PER_FRAME, samples.length);
+  const frame = new Int16Array(SAMPLES_PER_FRAME);
+  if (end > offset) frame.set(samples.subarray(offset, end));
+  return frame;
+}
+function mergeBytes(chunks) {
+  const total = chunks.reduce((sum, chunk) => sum + chunk.byteLength, 0);
+  const merged = new Uint8Array(total);
+  let offset = 0;
+  for (const chunk of chunks) {
+    merged.set(chunk, offset);
+    offset += chunk.byteLength;
+  }
+  return merged;
+}
+function writePcm16Wav(path, chunks, sampleRateHz) {
+  const bytes = mergeBytes(chunks);
+  const samples = new Int16Array(bytes.buffer, bytes.byteOffset, Math.floor(bytes.byteLength / 2));
+  const wav = new WaveFile();
+  wav.fromScratch(1, sampleRateHz, "16", samples);
+  return writeFile(path, Buffer.from(wav.toBuffer()));
+}
+function eventLine(kind, data) {
+  return `${JSON.stringify({ tsMs: Date.now(), kind, ...data })}
+`;
+}
+function sleep(ms) {
+  return new Promise((resolveSleep) => setTimeout(resolveSleep, ms));
+}
+async function resolveSession2(session) {
+  return typeof session === "function" ? session() : session;
+}
+async function driveTurn(opts) {
+  const session = await resolveSession2(opts.session);
+  const sessionDir = resolve2(opts.sessionDir);
+  await mkdir(sessionDir, { recursive: true });
+  const pcm = opts.syntheticMono16kSamples !== void 0 ? Int16Array.from(opts.syntheticMono16kSamples) : readPcm16Mono16kWav(resolveInputWavPath(opts.inputWavPath));
+  const contextId = randomUUID2();
+  const inputChunks = [];
+  const outputChunks = [];
+  const eventLines = [];
+  const timeline = {
+    feedStartMs: 0,
+    speechEndMs: 0,
+    finalTranscriptMs: 0,
+    firstLlmDeltaMs: 0,
+    firstTtsAudioMs: 0,
+    ttsEndMs: 0
+  };
+  let finalTranscript = "";
+  let agentReply = "";
+  let toolCalls = 0;
+  const offRecordUser = session.bus.on("record.user_audio", (pkt) => {
+    inputChunks.push(pkt.audio);
+  });
+  const offTtsAudio = session.bus.on("tts.audio", (pkt) => {
+    if (timeline.firstTtsAudioMs === 0) timeline.firstTtsAudioMs = pkt.timestampMs;
+    outputChunks.push(pkt.audio);
+  });
+  const ttsEnd = new Promise((resolveEnd, reject) => {
+    const timeout = setTimeout(() => {
+      offTtsEnd();
+      reject(new Error("tts.end timeout"));
+    }, opts.ttsEndTimeoutMs ?? DEFAULT_TTS_END_TIMEOUT_MS);
+    const offTtsEnd = session.bus.on("tts.end", (pkt) => {
+      if (pkt.contextId !== contextId) return;
+      clearTimeout(timeout);
+      offTtsEnd();
+      timeline.ttsEndMs = pkt.timestampMs;
+      resolveEnd();
+    });
+  });
+  const on = (event, handler) => {
+    session.on(event, handler);
+  };
+  on("user_input_final", (event) => {
+    finalTranscript = event.text;
+    timeline.finalTranscriptMs = event.tsMs;
+    eventLines.push(eventLine("user_input_final", { turnId: event.turnId, text: event.text }));
+  });
+  on("agent_text_delta", (event) => {
+    if (timeline.firstLlmDeltaMs === 0) timeline.firstLlmDeltaMs = event.tsMs;
+    agentReply += event.delta;
+    eventLines.push(eventLine("agent_text_delta", { turnId: event.turnId, delta: event.delta }));
+  });
+  on("agent_tool_call", (event) => {
+    toolCalls += 1;
+    eventLines.push(eventLine("agent_tool_call", { turnId: event.turnId, name: event.name }));
+  });
+  on("agent_finished", (event) => {
+    eventLines.push(eventLine("agent_finished", { turnId: event.turnId }));
+  });
+  on("error", (event) => {
+    eventLines.push(eventLine("error", { stage: event.stage, category: event.category, message: event.message }));
+  });
+  await session.start();
+  session.bus.push(1 /* Main */, {
+    kind: "turn.change",
+    contextId,
+    previousContextId: "",
+    reason: "headless_turn_start",
+    timestampMs: Date.now()
+  });
+  let offset = 0;
+  while (offset < pcm.length) {
+    const frame = sliceFramePcm(pcm, offset);
+    const audio = pcmToBytes(frame);
+    if (timeline.feedStartMs === 0) timeline.feedStartMs = Date.now();
+    session.bus.push(1 /* Main */, {
+      kind: "user.audio_received",
+      contextId,
+      timestampMs: Date.now(),
+      audio
+    });
+    opts.onAudioFrame?.(contextId);
+    offset += SAMPLES_PER_FRAME;
+    if (opts.realtimePacing === true) await sleep(20);
+  }
+  timeline.speechEndMs = Date.now();
+  for (let pad = 0; pad < 40; pad += 1) {
+    const frame = new Int16Array(SAMPLES_PER_FRAME);
+    session.bus.push(1 /* Main */, {
+      kind: "user.audio_received",
+      contextId,
+      timestampMs: Date.now(),
+      audio: pcmToBytes(frame)
+    });
+    opts.onAudioFrame?.(contextId);
+    if (opts.realtimePacing === true) await sleep(20);
+  }
+  await opts.onAudioFed?.(contextId);
+  await ttsEnd;
+  offRecordUser();
+  offTtsAudio();
+  const metrics = {
+    turnId: contextId,
+    inputAudioMs: Math.round(pcm.length / 16e3 * 1e3),
+    speechEndToFinalTranscriptMs: timeline.speechEndMs > 0 && timeline.finalTranscriptMs > 0 ? Math.max(0, timeline.finalTranscriptMs - timeline.speechEndMs) : 0,
+    speechEndToFirstAudioMs: timeline.speechEndMs > 0 && timeline.firstTtsAudioMs > 0 ? Math.max(0, timeline.firstTtsAudioMs - timeline.speechEndMs) : 0,
+    endpointingMs: timeline.feedStartMs > 0 && timeline.finalTranscriptMs > 0 ? Math.max(0, timeline.finalTranscriptMs - timeline.feedStartMs) : 0,
+    llmTTFTMs: timeline.finalTranscriptMs > 0 && timeline.firstLlmDeltaMs > 0 ? Math.max(0, timeline.firstLlmDeltaMs - timeline.finalTranscriptMs) : 0,
+    ttsTTFBMs: timeline.firstLlmDeltaMs > 0 && timeline.firstTtsAudioMs > 0 ? Math.max(0, timeline.firstTtsAudioMs - timeline.firstLlmDeltaMs) : 0,
+    e2eLatencyMs: timeline.feedStartMs > 0 && timeline.firstTtsAudioMs > 0 ? Math.max(0, timeline.firstTtsAudioMs - timeline.feedStartMs) : 0,
+    agentTokens: agentReply.trim().length === 0 ? 0 : agentReply.trim().split(/\s+/).length,
+    playedMs: Math.round(mergeBytes(outputChunks).byteLength / 2 / 16e3 * 1e3),
+    truncated: false,
+    toolCalls
+  };
+  const inputWavPath = join3(sessionDir, "audio-in.wav");
+  const agentOutWavPath = join3(sessionDir, "audio-out.wav");
+  const eventsJsonlPath = join3(sessionDir, "events.jsonl");
+  const eventsJsonPath = join3(sessionDir, "events.json");
+  const transcriptJsonPath = join3(sessionDir, "transcript.json");
+  const metricsJsonPath = join3(sessionDir, "metrics.json");
+  const events = eventLines.map((line) => line.trim()).filter((line) => line.length > 0).map((line) => JSON.parse(line));
+  const qualityGate = {
+    passed: finalTranscript.trim().length > 0 && agentReply.trim().length > 0 && outputChunks.length > 0,
+    failures: [
+      ...finalTranscript.trim().length === 0 ? ["missing final transcript"] : [],
+      ...agentReply.trim().length === 0 ? ["missing agent reply"] : [],
+      ...outputChunks.length === 0 ? ["missing TTS audio"] : []
+    ]
+  };
+  await writePcm16Wav(inputWavPath, inputChunks, 16e3);
+  await writePcm16Wav(agentOutWavPath, outputChunks, 16e3);
+  await writeFile(eventsJsonlPath, eventLines.join(""), "utf8");
+  await writeFile(eventsJsonPath, `${JSON.stringify({ events, qualityGate }, null, 2)}
+`, "utf8");
+  await writeFile(
+    transcriptJsonPath,
+    `${JSON.stringify({ finalTranscript, agentReply, turnCount: 1, metrics, qualityGate }, null, 2)}
+`,
+    "utf8"
+  );
+  await writeFile(metricsJsonPath, `${JSON.stringify({ ...metrics, turnCount: 1, qualityGate }, null, 2)}
+`, "utf8");
+  await session.close();
+  return {
+    sessionDir,
+    finalTranscript,
+    agentReply,
+    agentOutWavPath,
+    inputWavPath,
+    eventsJsonlPath,
+    eventsJsonPath,
+    transcriptJsonPath,
+    metricsJsonPath,
+    metrics,
+    durationMs: timeline.feedStartMs > 0 && timeline.ttsEndMs > 0 ? Math.max(0, timeline.ttsEndMs - timeline.feedStartMs) : 0
+  };
+}
+
+// src/turn-command.ts
+async function runTurnCommand(opts) {
+  const inputPath = resolve3(opts.inputPath);
+  const isFixtureSidecar = extname(inputPath).toLowerCase() === ".json";
+  const fixture = isFixtureSidecar ? loadFixture(inputPath) : void 0;
+  const wavPath = fixture ? fixture.wavPath : inputPath;
+  const resolvedAgent = await resolveAgentFactory(opts.agentSpec, opts.cwd ?? process.cwd());
+  const sessionDir = opts.sessionDir ?? mkdtempSync(join4(tmpdir(), "syrinx-turn-"));
+  let result;
+  try {
+    result = await driveTurn({
+      session: resolvedAgent.factory,
+      inputWavPath: wavPath,
+      sessionDir
+    });
+  } catch (err) {
+    if (err instanceof CliError) throw err;
+    throw new CliError(EXIT_CODES.BACKEND, `turn failed: ${err instanceof Error ? err.message : String(err)}`);
+  }
+  let assertion = null;
+  if (fixture?.sidecar.expectedTranscript !== void 0) {
+    assertion = assertTranscript(fixture.sidecar.expectedTranscript, result.finalTranscript);
+    if (!assertion.match) {
+      throw new CliError(EXIT_CODES.ASSERTION, "replayed fixture's transcript drifted from the expected transcript", {
+        assertion
+      });
+    }
+  }
+  return {
+    input: inputPath,
+    agent: resolvedAgent.label,
+    sessionDir: result.sessionDir,
+    transcript: result.finalTranscript,
+    reply: result.agentReply,
+    timings: result.metrics,
+    durationMs: result.durationMs,
+    assertion
+  };
+}
+
+// src/cli.ts
+var defaultIO = {
+  stdout: (line) => {
+    process.stdout.write(`${line}
+`);
+  },
+  stderr: (line) => {
+    process.stderr.write(`${line}
+`);
+  }
+};
+function exitCodeName(code) {
+  return EXIT_CODE_TABLE.find((row) => row.code === code)?.name ?? "UNKNOWN";
+}
+function looksLikeJsonRequested(args) {
+  return args.includes("--json");
+}
+function reportSuccess(io, json, verb, payload, prose) {
+  if (json) {
+    io.stdout(JSON.stringify({ ok: true, verb, ...payload }));
+  } else {
+    io.stdout(prose);
+  }
+  return EXIT_CODES.SUCCESS;
+}
+function reportError(io, json, verb, err) {
+  const cliErr = err instanceof CliError ? err : new CliError(EXIT_CODES.INTERNAL, err instanceof Error ? err.message : String(err));
+  if (cliErr.exitCode === EXIT_CODES.INTERNAL && err instanceof Error && err.stack) {
+    io.stderr(err.stack);
+  }
+  if (json) {
+    io.stdout(
+      JSON.stringify({
+        ok: false,
+        verb,
+        error: { code: exitCodeName(cliErr.exitCode), message: cliErr.message, ...cliErr.details ?? {} }
+      })
+    );
+  } else {
+    io.stderr(`error: ${cliErr.message}`);
+  }
+  return cliErr.exitCode;
+}
+async function handleTurn(args, io) {
+  let values;
+  try {
+    ({ values } = parseArgs({
+      args,
+      options: {
+        in: { type: "string" },
+        agent: { type: "string" },
+        "session-dir": { type: "string" },
+        json: { type: "boolean", default: false }
+      },
+      strict: true,
+      allowPositionals: false
+    }));
+  } catch (err) {
+    return reportError(io, looksLikeJsonRequested(args), "turn", new CliError(EXIT_CODES.USAGE, err instanceof Error ? err.message : String(err)));
+  }
+  const json = values.json === true;
+  if (!values.in) {
+    return reportError(io, json, "turn", new CliError(EXIT_CODES.USAGE, "turn requires --in <fixture.wav|fixture.json>"));
+  }
+  if (!values.agent) {
+    return reportError(
+      io,
+      json,
+      "turn",
+      new CliError(EXIT_CODES.USAGE, "turn requires --agent <module>#<export> \u2014 the CLI brings no providers of its own (see --help)")
+    );
+  }
+  try {
+    const result = await runTurnCommand({
+      inputPath: values.in,
+      agentSpec: values.agent,
+      sessionDir: values["session-dir"]
+    });
+    const prose = [
+      `agent: ${result.agent}`,
+      `transcript: ${result.transcript || "(empty)"}`,
+      `reply: ${result.reply || "(empty)"}`,
+      `session: ${result.sessionDir}`,
+      result.assertion ? `assertion: match (expected "${result.assertion.expectedTranscript}")` : "assertion: none"
+    ].join("\n");
+    return reportSuccess(io, json, "turn", { ...result }, prose);
+  } catch (err) {
+    return reportError(io, json, "turn", err);
+  }
+}
+async function handleText(args, io) {
+  let values, positionals;
+  try {
+    ({ values, positionals } = parseArgs({
+      args,
+      options: {
+        agent: { type: "string" },
+        json: { type: "boolean", default: false }
+      },
+      strict: true,
+      allowPositionals: true
+    }));
+  } catch (err) {
+    return reportError(io, looksLikeJsonRequested(args), "text", new CliError(EXIT_CODES.USAGE, err instanceof Error ? err.message : String(err)));
+  }
+  const json = values.json === true;
+  const message = positionals[0];
+  if (!message) {
+    return reportError(io, json, "text", new CliError(EXIT_CODES.USAGE, 'text requires a message: syrinx text "<message>" --agent <module>#<export>'));
+  }
+  if (!values.agent) {
+    return reportError(
+      io,
+      json,
+      "text",
+      new CliError(EXIT_CODES.USAGE, "text requires --agent <module>#<export> \u2014 the CLI brings no providers of its own (see --help)")
+    );
+  }
+  try {
+    const result = await runTextCommand({ message, agentSpec: values.agent });
+    const prose = `agent: ${result.agent}
+reply: ${result.reply || "(empty)"}
+ttft: ${String(result.ttftMs)}ms  total: ${String(result.totalMs)}ms`;
+    return reportSuccess(io, json, "text", { ...result }, prose);
+  } catch (err) {
+    return reportError(io, json, "text", err);
+  }
+}
+async function handleDoctor(args, io) {
+  let values;
+  try {
+    ({ values } = parseArgs({
+      args,
+      options: { agent: { type: "string" }, json: { type: "boolean", default: false } },
+      strict: true,
+      allowPositionals: false
+    }));
+  } catch (err) {
+    return reportError(io, looksLikeJsonRequested(args), "doctor", new CliError(EXIT_CODES.USAGE, err instanceof Error ? err.message : String(err)));
+  }
+  const json = values.json === true;
+  const report = await runDoctor({ agentSpec: values.agent });
+  const prose = [
+    `syrinx cli ${report.cliVersion}  node ${report.node.version} (${report.node.platform})`,
+    `${report.core.package}: ${report.core.resolved ? `v${String(report.core.version)}` : "not installed"}${report.core.majorMismatch ? "  (major mismatch with CLI)" : ""}`,
+    "well-known provider keys (informational only):",
+    ...Object.entries(report.wellKnownProviderKeys).map(([key, present]) => `  ${key}: ${present ? "present" : "missing"}`),
+    ...report.agent ? [`agent (${report.agent.spec}): ${report.agent.resolved ? `resolved -> ${String(report.agent.label)}` : `NOT resolved (${String(report.agent.error)})`}`] : [],
+    report.summary
+  ].join("\n");
+  return reportSuccess(io, json, "doctor", { ...report }, prose);
+}
+async function main(argv, io = defaultIO) {
+  try {
+    warnOnVersionSkew(process.cwd());
+  } catch {
+  }
+  const [verb, ...rest] = argv;
+  if (verb === void 0 || verb === "--help" || verb === "-h") {
+    io.stdout(HELP_TEXT);
+    return EXIT_CODES.SUCCESS;
+  }
+  if (verb === "--version" || verb === "-v") {
+    io.stdout(CLI_VERSION);
+    return EXIT_CODES.SUCCESS;
+  }
+  switch (verb) {
+    case "turn":
+      return handleTurn(rest, io);
+    case "text":
+      return handleText(rest, io);
+    case "doctor":
+      return handleDoctor(rest, io);
+    case "console":
+    case "chat":
+    case "listen":
+      return reportError(
+        io,
+        looksLikeJsonRequested(rest),
+        verb,
+        new CliError(EXIT_CODES.USAGE, `"${verb}" is not a syrinx command \u2014 this CLI is non-interactive by design (see --help). Use the Studio for that.`)
+      );
+    default:
+      return reportError(
+        io,
+        looksLikeJsonRequested(rest),
+        verb,
+        new CliError(EXIT_CODES.USAGE, `unknown command: ${verb} (see --help)`)
+      );
+  }
+}
+
+// src/index.ts
+function fail(err) {
+  if (err instanceof CliError) {
+    console.error(err.message);
+    return err.exitCode;
+  }
+  console.error(err instanceof Error ? err.stack ?? err.message : String(err));
+  return EXIT_CODES.INTERNAL;
+}
+process.on("unhandledRejection", (reason) => {
+  process.exitCode = fail(reason);
+});
+main(process.argv.slice(2)).then((code) => {
+  process.exitCode = code;
+}).catch((err) => {
+  process.exitCode = fail(err);
+});
+//# sourceMappingURL=index.js.map