@kuralle-syrinx/cli 4.4.0 → 4.5.0

package/dist/turn-runner.d.ts

@@ -0,0 +1,55 @@
+import { VoiceAgentSession } from "@kuralle-syrinx/core";
+/** A pre-built session, or a zero-arg factory producing one — the same contract examples/02-hello-voice-headless/scripts/dev-server.ts's `--agent` seam uses. */
+export type SessionFactory = () => VoiceAgentSession | Promise<VoiceAgentSession>;
+export interface PerTurnMetrics {
+    readonly turnId: string;
+    readonly inputAudioMs: number;
+    readonly speechEndToFinalTranscriptMs: number;
+    readonly speechEndToFirstAudioMs: number;
+    readonly endpointingMs: number;
+    readonly llmTTFTMs: number;
+    readonly ttsTTFBMs: number;
+    readonly e2eLatencyMs: number;
+    readonly agentTokens: number;
+    readonly playedMs: number;
+    readonly truncated: boolean;
+    readonly toolCalls: number;
+}
+export interface TurnResult {
+    readonly sessionDir: string;
+    readonly finalTranscript: string;
+    readonly agentReply: string;
+    readonly agentOutWavPath: string;
+    readonly inputWavPath: string;
+    readonly eventsJsonlPath: string;
+    readonly eventsJsonPath: string;
+    readonly transcriptJsonPath: string;
+    readonly metricsJsonPath: string;
+    readonly metrics: PerTurnMetrics;
+    readonly durationMs: number;
+}
+export interface DriveTurnOptions {
+    /** An already-registered VoiceAgentSession, or a factory producing one. Built by the caller — this module never constructs providers. */
+    readonly session: VoiceAgentSession | SessionFactory;
+    readonly inputWavPath: string;
+    readonly sessionDir: string;
+    /** Skips WAV read; must be mono 16 kHz PCM decoded samples. */
+    readonly syntheticMono16kSamples?: Readonly<Int16Array>;
+    readonly realtimePacing?: boolean;
+    /** Called once per fed audio frame (including the trailing silence pad), right after it is pushed onto the bus — for a VAD implementation (or a scripted test fake) that needs an explicit per-frame tick outside the bus event flow. */
+    readonly onAudioFrame?: (contextId: string) => void;
+    /** Called once after all audio (including the silence pad) has been fed, before waiting for tts.end — for an STT implementation (or a scripted test fake) that finalizes on an explicit signal. */
+    readonly onAudioFed?: (contextId: string) => void | Promise<void>;
+    readonly ttsEndTimeoutMs?: number;
+}
+export declare function readPcm16Mono16kWav(filePath: string): Int16Array;
+/** Resolves a WAV path, falling back to the repo's bundled demo fixture for the literal name "hello.wav" — a convenience inherited from the pre-move script, harmless (and inert) outside this monorepo. */
+export declare function resolveInputWavPath(path: string): string;
+/**
+ * Feed one turn's worth of audio into an already-built session and report the
+ * transcript, reply, per-stage timings, and written artifacts. This is the one
+ * implementation of "drive a turn" — it knows nothing about which STT/TTS/
+ * reasoner backends the session was assembled from.
+ */
+export declare function driveTurn(opts: DriveTurnOptions): Promise<TurnResult>;
+//# sourceMappingURL=turn-runner.d.ts.map

package/dist/turn-runner.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"turn-runner.d.ts","sourceRoot":"","sources":["../src/turn-runner.ts"],"names":[],"mappings":"AAsBA,OAAO,EAEL,iBAAiB,EAKlB,MAAM,sBAAsB,CAAC;AAU9B,iKAAiK;AACjK,MAAM,MAAM,cAAc,GAAG,MAAM,iBAAiB,GAAG,OAAO,CAAC,iBAAiB,CAAC,CAAC;AAElF,MAAM,WAAW,cAAc;IAC7B,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,YAAY,EAAE,MAAM,CAAC;IAC9B,QAAQ,CAAC,4BAA4B,EAAE,MAAM,CAAC;IAC9C,QAAQ,CAAC,uBAAuB,EAAE,MAAM,CAAC;IACzC,QAAQ,CAAC,aAAa,EAAE,MAAM,CAAC;IAC/B,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAC3B,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAC3B,QAAQ,CAAC,YAAY,EAAE,MAAM,CAAC;IAC9B,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;IAC7B,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,QAAQ,CAAC,SAAS,EAAE,OAAO,CAAC;IAC5B,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;CAC5B;AAED,MAAM,WAAW,UAAU;IACzB,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;IAC5B,QAAQ,CAAC,eAAe,EAAE,MAAM,CAAC;IACjC,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;IAC5B,QAAQ,CAAC,eAAe,EAAE,MAAM,CAAC;IACjC,QAAQ,CAAC,YAAY,EAAE,MAAM,CAAC;IAC9B,QAAQ,CAAC,eAAe,EAAE,MAAM,CAAC;IACjC,QAAQ,CAAC,cAAc,EAAE,MAAM,CAAC;IAChC,QAAQ,CAAC,kBAAkB,EAAE,MAAM,CAAC;IACpC,QAAQ,CAAC,eAAe,EAAE,MAAM,CAAC;IACjC,QAAQ,CAAC,OAAO,EAAE,cAAc,CAAC;IACjC,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;CAC7B;AAED,MAAM,WAAW,gBAAgB;IAC/B,yIAAyI;IACzI,QAAQ,CAAC,OAAO,EAAE,iBAAiB,GAAG,cAAc,CAAC;IACrD,QAAQ,CAAC,YAAY,EAAE,MAAM,CAAC;IAC9B,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;IAC5B,+DAA+D;IAC/D,QAAQ,CAAC,uBAAuB,CAAC,EAAE,QAAQ,CAAC,UAAU,CAAC,CAAC;IACxD,QAAQ,CAAC,cAAc,CAAC,EAAE,OAAO,CAAC;IAClC,yOAAyO;IACzO,QAAQ,CAAC,YAAY,CAAC,EAAE,CAAC,SAAS,EAAE,MAAM,KAAK,IAAI,CAAC;IACpD,mMAAmM;IACnM,QAAQ,CAAC,UAAU,CAAC,EAAE,CAAC,SAAS,EAAE,MAAM,KAAK,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAClE,QAAQ,CAAC,eAAe,CAAC,EAAE,MAAM,CAAC;CACnC;AAED,wBAAgB,mBAAmB,CAAC,QAAQ,EAAE,MAAM,GAAG,UAAU,CAehE;AAED,4MAA4M;AAC5M,wBAAgB,mBAAmB,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CASxD;AA2DD;;;;;GAKG;AACH,wBAAsB,SAAS,CAAC,IAAI,EAAE,gBAAgB,GAAG,OAAO,CAAC,UAAU,CAAC,CA0M3E"}

package/dist/turn-runner.js

@@ -0,0 +1,250 @@
+// src/turn-runner.ts
+import { randomUUID } from "node:crypto";
+import { readFileSync } from "node:fs";
+import { mkdir, writeFile } from "node:fs/promises";
+import { createRequire } from "node:module";
+import { basename, join, resolve } from "node:path";
+import {
+  Route
+} from "@kuralle-syrinx/core";
+var require2 = createRequire(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 = readFileSync(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 : resamplePcm16(mono, fmt.sampleRate, 16e3);
+}
+function resolveInputWavPath(path) {
+  const resolved = resolve(path);
+  try {
+    readFileSync(resolved);
+    return resolved;
+  } catch {
+    if (basename(path) === "hello.wav") return DEFAULT_FIXTURE_PATH;
+    throw new Error(`input WAV not found: ${resolved}`);
+  }
+}
+function resamplePcm16(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 resolveSession(session) {
+  return typeof session === "function" ? session() : session;
+}
+async function driveTurn(opts) {
+  const session = await resolveSession(opts.session);
+  const sessionDir = resolve(opts.sessionDir);
+  await mkdir(sessionDir, { recursive: true });
+  const pcm = opts.syntheticMono16kSamples !== void 0 ? Int16Array.from(opts.syntheticMono16kSamples) : readPcm16Mono16kWav(resolveInputWavPath(opts.inputWavPath));
+  const contextId = randomUUID();
+  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(Route.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(Route.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(Route.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 = join(sessionDir, "audio-in.wav");
+  const agentOutWavPath = join(sessionDir, "audio-out.wav");
+  const eventsJsonlPath = join(sessionDir, "events.jsonl");
+  const eventsJsonPath = join(sessionDir, "events.json");
+  const transcriptJsonPath = join(sessionDir, "transcript.json");
+  const metricsJsonPath = join(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
+  };
+}
+export {
+  driveTurn,
+  readPcm16Mono16kWav,
+  resolveInputWavPath
+};
+//# sourceMappingURL=turn-runner.js.map

package/dist/turn-runner.js.map

@@ -0,0 +1,7 @@
+{
+  "version": 3,
+  "sources": ["../src/turn-runner.ts"],
+  "sourcesContent": ["// SPDX-License-Identifier: MIT\n//\n// Provider-agnostic turn driver (LDT-20, revised). This module owns exactly one\n// thing: feeding audio into an ALREADY-CONSTRUCTED VoiceAgentSession and\n// capturing the transcript/reply/timings/artifacts \u2014 never how that session's\n// STT/TTS/reasoner plugins got built. The CLI itself must not depend on any\n// provider SDK (Deepgram, Cartesia, OpenAI, ...); the caller (the CLI's\n// --agent seam, or examples/02-hello-voice-headless's own hardcoded default\n// kernel) supplies the session.\n//\n// examples/02-hello-voice-headless/src/run-one-turn.ts is the other caller: it\n// keeps its own `runOneTurn(...)` with the hardcoded Deepgram+OpenAI+Cartesia+\n// Silero default (legitimate there \u2014 it's an example harness, not a shipped\n// CLI) and delegates the actual audio-feed/metrics/event-capture work to\n// `driveTurn` here, so there is exactly one implementation of that part.\n\nimport { randomUUID } from \"node:crypto\";\nimport { readFileSync } from \"node:fs\";\nimport { mkdir, writeFile } from \"node:fs/promises\";\nimport { createRequire } from \"node:module\";\nimport { basename, join, resolve } from \"node:path\";\n\nimport {\n  Route,\n  VoiceAgentSession,\n  type RecordUserAudioPacket,\n  type TextToSpeechAudioPacket,\n  type TextToSpeechEndPacket,\n  type VoiceAgentSessionEvents,\n} from \"@kuralle-syrinx/core\";\n\nconst require = createRequire(import.meta.url);\nconst { WaveFile } = require(\"wavefile\") as typeof import(\"wavefile\");\n\nconst SAMPLES_PER_FRAME = 320;\nconst DEFAULT_FIXTURE_PATH =\n  \"/Users/mithushancj/Documents/asyncdot/openscoped/voice-media-transport/research/agents/tests/test_realtime/hello_world.wav\";\nconst DEFAULT_TTS_END_TIMEOUT_MS = 120_000;\n\n/** A pre-built session, or a zero-arg factory producing one \u2014 the same contract examples/02-hello-voice-headless/scripts/dev-server.ts's `--agent` seam uses. */\nexport type SessionFactory = () => VoiceAgentSession | Promise<VoiceAgentSession>;\n\nexport interface PerTurnMetrics {\n  readonly turnId: string;\n  readonly inputAudioMs: number;\n  readonly speechEndToFinalTranscriptMs: number;\n  readonly speechEndToFirstAudioMs: number;\n  readonly endpointingMs: number;\n  readonly llmTTFTMs: number;\n  readonly ttsTTFBMs: number;\n  readonly e2eLatencyMs: number;\n  readonly agentTokens: number;\n  readonly playedMs: number;\n  readonly truncated: boolean;\n  readonly toolCalls: number;\n}\n\nexport interface TurnResult {\n  readonly sessionDir: string;\n  readonly finalTranscript: string;\n  readonly agentReply: string;\n  readonly agentOutWavPath: string;\n  readonly inputWavPath: string;\n  readonly eventsJsonlPath: string;\n  readonly eventsJsonPath: string;\n  readonly transcriptJsonPath: string;\n  readonly metricsJsonPath: string;\n  readonly metrics: PerTurnMetrics;\n  readonly durationMs: number;\n}\n\nexport interface DriveTurnOptions {\n  /** An already-registered VoiceAgentSession, or a factory producing one. Built by the caller \u2014 this module never constructs providers. */\n  readonly session: VoiceAgentSession | SessionFactory;\n  readonly inputWavPath: string;\n  readonly sessionDir: string;\n  /** Skips WAV read; must be mono 16 kHz PCM decoded samples. */\n  readonly syntheticMono16kSamples?: Readonly<Int16Array>;\n  readonly realtimePacing?: boolean;\n  /** Called once per fed audio frame (including the trailing silence pad), right after it is pushed onto the bus \u2014 for a VAD implementation (or a scripted test fake) that needs an explicit per-frame tick outside the bus event flow. */\n  readonly onAudioFrame?: (contextId: string) => void;\n  /** Called once after all audio (including the silence pad) has been fed, before waiting for tts.end \u2014 for an STT implementation (or a scripted test fake) that finalizes on an explicit signal. */\n  readonly onAudioFed?: (contextId: string) => void | Promise<void>;\n  readonly ttsEndTimeoutMs?: number;\n}\n\nexport function readPcm16Mono16kWav(filePath: string): Int16Array {\n  const buf = readFileSync(filePath);\n  const wav = new WaveFile(Buffer.from(buf));\n  const fmt = wav.fmt as {\n    sampleRate: number;\n    numChannels: number;\n    bitsPerSample: number;\n    audioFormat: number;\n  };\n  if (fmt.numChannels !== 1) throw new Error(`expected mono WAV, got ${String(fmt.numChannels)} channels`);\n  if (fmt.bitsPerSample !== 16 || fmt.audioFormat !== 1) throw new Error(\"expected 16-bit PCM WAV\");\n  const raw = wav.getSamples(false, Int16Array);\n  const mono: Int16Array | undefined = Array.isArray(raw) ? raw[0] : raw;\n  if (mono === undefined || !(mono instanceof Int16Array)) throw new Error(\"WAV has no mono channel samples\");\n  return fmt.sampleRate === 16000 ? mono : resamplePcm16(mono, fmt.sampleRate, 16000);\n}\n\n/** Resolves a WAV path, falling back to the repo's bundled demo fixture for the literal name \"hello.wav\" \u2014 a convenience inherited from the pre-move script, harmless (and inert) outside this monorepo. */\nexport function resolveInputWavPath(path: string): string {\n  const resolved = resolve(path);\n  try {\n    readFileSync(resolved);\n    return resolved;\n  } catch {\n    if (basename(path) === \"hello.wav\") return DEFAULT_FIXTURE_PATH;\n    throw new Error(`input WAV not found: ${resolved}`);\n  }\n}\n\nfunction resamplePcm16(samples: Int16Array, fromHz: number, toHz: number): Int16Array {\n  if (fromHz <= 0 || toHz <= 0) throw new Error(\"invalid WAV sample rate\");\n  const outLength = Math.max(1, Math.round((samples.length * toHz) / fromHz));\n  const out = new Int16Array(outLength);\n  const ratio = fromHz / toHz;\n  for (let i = 0; i < out.length; i += 1) {\n    const src = i * ratio;\n    const lo = Math.floor(src);\n    const hi = Math.min(samples.length - 1, lo + 1);\n    const frac = src - lo;\n    out[i] = Math.round(samples[lo]! * (1 - frac) + samples[hi]! * frac);\n  }\n  return out;\n}\n\nfunction pcmToBytes(samples: Readonly<Int16Array>): Uint8Array {\n  return new Uint8Array(samples.buffer, samples.byteOffset, samples.byteLength);\n}\n\nfunction sliceFramePcm(samples: Readonly<Int16Array>, offset: number): Int16Array {\n  const end = Math.min(offset + SAMPLES_PER_FRAME, samples.length);\n  const frame = new Int16Array(SAMPLES_PER_FRAME);\n  if (end > offset) frame.set(samples.subarray(offset, end));\n  return frame;\n}\n\nfunction mergeBytes(chunks: readonly Uint8Array[]): Uint8Array {\n  const total = chunks.reduce((sum, chunk) => sum + chunk.byteLength, 0);\n  const merged = new Uint8Array(total);\n  let offset = 0;\n  for (const chunk of chunks) {\n    merged.set(chunk, offset);\n    offset += chunk.byteLength;\n  }\n  return merged;\n}\n\nfunction writePcm16Wav(path: string, chunks: readonly Uint8Array[], sampleRateHz: number): Promise<void> {\n  const bytes = mergeBytes(chunks);\n  const samples = new Int16Array(bytes.buffer, bytes.byteOffset, Math.floor(bytes.byteLength / 2));\n  const wav = new WaveFile();\n  wav.fromScratch(1, sampleRateHz, \"16\", samples);\n  return writeFile(path, Buffer.from(wav.toBuffer()));\n}\n\nfunction eventLine(kind: string, data: Record<string, unknown>): string {\n  return `${JSON.stringify({ tsMs: Date.now(), kind, ...data })}\\n`;\n}\n\nfunction sleep(ms: number): Promise<void> {\n  return new Promise((resolveSleep) => setTimeout(resolveSleep, ms));\n}\n\nasync function resolveSession(session: VoiceAgentSession | SessionFactory): Promise<VoiceAgentSession> {\n  return typeof session === \"function\" ? session() : session;\n}\n\n/**\n * Feed one turn's worth of audio into an already-built session and report the\n * transcript, reply, per-stage timings, and written artifacts. This is the one\n * implementation of \"drive a turn\" \u2014 it knows nothing about which STT/TTS/\n * reasoner backends the session was assembled from.\n */\nexport async function driveTurn(opts: DriveTurnOptions): Promise<TurnResult> {\n  // Resolve (and, if a factory, construct) the session before touching the\n  // filesystem: a caller's agent failing to construct is a different failure\n  // class (CONFIG) than a bad input file (USAGE/BACKEND), and should surface\n  // as itself rather than being masked by a WAV-read error that never got the\n  // chance to matter.\n  const session = await resolveSession(opts.session);\n\n  const sessionDir = resolve(opts.sessionDir);\n  await mkdir(sessionDir, { recursive: true });\n\n  const pcm =\n    opts.syntheticMono16kSamples !== undefined\n      ? Int16Array.from(opts.syntheticMono16kSamples)\n      : readPcm16Mono16kWav(resolveInputWavPath(opts.inputWavPath));\n\n  const contextId = randomUUID();\n  const inputChunks: Uint8Array[] = [];\n  const outputChunks: Uint8Array[] = [];\n  const eventLines: string[] = [];\n  const timeline = {\n    feedStartMs: 0,\n    speechEndMs: 0,\n    finalTranscriptMs: 0,\n    firstLlmDeltaMs: 0,\n    firstTtsAudioMs: 0,\n    ttsEndMs: 0,\n  };\n  let finalTranscript = \"\";\n  let agentReply = \"\";\n  let toolCalls = 0;\n\n  const offRecordUser = session.bus.on<RecordUserAudioPacket>(\"record.user_audio\", (pkt) => {\n    inputChunks.push(pkt.audio);\n  });\n  const offTtsAudio = session.bus.on<TextToSpeechAudioPacket>(\"tts.audio\", (pkt) => {\n    if (timeline.firstTtsAudioMs === 0) timeline.firstTtsAudioMs = pkt.timestampMs;\n    outputChunks.push(pkt.audio);\n  });\n\n  const ttsEnd = new Promise<void>((resolveEnd, reject) => {\n    const timeout = setTimeout(() => {\n      offTtsEnd();\n      reject(new Error(\"tts.end timeout\"));\n    }, opts.ttsEndTimeoutMs ?? DEFAULT_TTS_END_TIMEOUT_MS);\n    const offTtsEnd = session.bus.on<TextToSpeechEndPacket>(\"tts.end\", (pkt) => {\n      if (pkt.contextId !== contextId) return;\n      clearTimeout(timeout);\n      offTtsEnd();\n      timeline.ttsEndMs = pkt.timestampMs;\n      resolveEnd();\n    });\n  });\n\n  const on = <K extends keyof VoiceAgentSessionEvents>(event: K, handler: VoiceAgentSessionEvents[K]): void => {\n    session.on(event, handler);\n  };\n  on(\"user_input_final\", (event) => {\n    finalTranscript = event.text;\n    timeline.finalTranscriptMs = event.tsMs;\n    eventLines.push(eventLine(\"user_input_final\", { turnId: event.turnId, text: event.text }));\n  });\n  on(\"agent_text_delta\", (event) => {\n    if (timeline.firstLlmDeltaMs === 0) timeline.firstLlmDeltaMs = event.tsMs;\n    agentReply += event.delta;\n    eventLines.push(eventLine(\"agent_text_delta\", { turnId: event.turnId, delta: event.delta }));\n  });\n  on(\"agent_tool_call\", (event) => {\n    toolCalls += 1;\n    eventLines.push(eventLine(\"agent_tool_call\", { turnId: event.turnId, name: event.name }));\n  });\n  on(\"agent_finished\", (event) => {\n    eventLines.push(eventLine(\"agent_finished\", { turnId: event.turnId }));\n  });\n  on(\"error\", (event) => {\n    eventLines.push(eventLine(\"error\", { stage: event.stage, category: event.category, message: event.message }));\n  });\n\n  await session.start();\n\n  session.bus.push(Route.Main, {\n    kind: \"turn.change\",\n    contextId,\n    previousContextId: \"\",\n    reason: \"headless_turn_start\",\n    timestampMs: Date.now(),\n  });\n\n  let offset = 0;\n  while (offset < pcm.length) {\n    const frame = sliceFramePcm(pcm, offset);\n    const audio = pcmToBytes(frame);\n    if (timeline.feedStartMs === 0) timeline.feedStartMs = Date.now();\n    session.bus.push(Route.Main, {\n      kind: \"user.audio_received\",\n      contextId,\n      timestampMs: Date.now(),\n      audio,\n    });\n    opts.onAudioFrame?.(contextId);\n    offset += SAMPLES_PER_FRAME;\n    if (opts.realtimePacing === true) await sleep(20);\n  }\n  timeline.speechEndMs = Date.now();\n\n  for (let pad = 0; pad < 40; pad += 1) {\n    const frame = new Int16Array(SAMPLES_PER_FRAME);\n    session.bus.push(Route.Main, {\n      kind: \"user.audio_received\",\n      contextId,\n      timestampMs: Date.now(),\n      audio: pcmToBytes(frame),\n    });\n    opts.onAudioFrame?.(contextId);\n    if (opts.realtimePacing === true) await sleep(20);\n  }\n\n  await opts.onAudioFed?.(contextId);\n  await ttsEnd;\n\n  offRecordUser();\n  offTtsAudio();\n\n  const metrics: PerTurnMetrics = {\n    turnId: contextId,\n    inputAudioMs: Math.round((pcm.length / 16000) * 1000),\n    speechEndToFinalTranscriptMs:\n      timeline.speechEndMs > 0 && timeline.finalTranscriptMs > 0\n        ? Math.max(0, timeline.finalTranscriptMs - timeline.speechEndMs)\n        : 0,\n    speechEndToFirstAudioMs:\n      timeline.speechEndMs > 0 && timeline.firstTtsAudioMs > 0\n        ? Math.max(0, timeline.firstTtsAudioMs - timeline.speechEndMs)\n        : 0,\n    endpointingMs:\n      timeline.feedStartMs > 0 && timeline.finalTranscriptMs > 0\n        ? Math.max(0, timeline.finalTranscriptMs - timeline.feedStartMs)\n        : 0,\n    llmTTFTMs:\n      timeline.finalTranscriptMs > 0 && timeline.firstLlmDeltaMs > 0\n        ? Math.max(0, timeline.firstLlmDeltaMs - timeline.finalTranscriptMs)\n        : 0,\n    ttsTTFBMs:\n      timeline.firstLlmDeltaMs > 0 && timeline.firstTtsAudioMs > 0\n        ? Math.max(0, timeline.firstTtsAudioMs - timeline.firstLlmDeltaMs)\n        : 0,\n    e2eLatencyMs:\n      timeline.feedStartMs > 0 && timeline.firstTtsAudioMs > 0\n        ? Math.max(0, timeline.firstTtsAudioMs - timeline.feedStartMs)\n        : 0,\n    agentTokens: agentReply.trim().length === 0 ? 0 : agentReply.trim().split(/\\s+/).length,\n    playedMs: Math.round((mergeBytes(outputChunks).byteLength / 2 / 16000) * 1000),\n    truncated: false,\n    toolCalls,\n  };\n\n  const inputWavPath = join(sessionDir, \"audio-in.wav\");\n  const agentOutWavPath = join(sessionDir, \"audio-out.wav\");\n  const eventsJsonlPath = join(sessionDir, \"events.jsonl\");\n  const eventsJsonPath = join(sessionDir, \"events.json\");\n  const transcriptJsonPath = join(sessionDir, \"transcript.json\");\n  const metricsJsonPath = join(sessionDir, \"metrics.json\");\n  const events = eventLines\n    .map((line) => line.trim())\n    .filter((line) => line.length > 0)\n    .map((line) => JSON.parse(line) as Record<string, unknown>);\n  const qualityGate = {\n    passed: finalTranscript.trim().length > 0 && agentReply.trim().length > 0 && outputChunks.length > 0,\n    failures: [\n      ...(finalTranscript.trim().length === 0 ? [\"missing final transcript\"] : []),\n      ...(agentReply.trim().length === 0 ? [\"missing agent reply\"] : []),\n      ...(outputChunks.length === 0 ? [\"missing TTS audio\"] : []),\n    ],\n  };\n\n  await writePcm16Wav(inputWavPath, inputChunks, 16000);\n  await writePcm16Wav(agentOutWavPath, outputChunks, 16000);\n  await writeFile(eventsJsonlPath, eventLines.join(\"\"), \"utf8\");\n  await writeFile(eventsJsonPath, `${JSON.stringify({ events, qualityGate }, null, 2)}\\n`, \"utf8\");\n  await writeFile(\n    transcriptJsonPath,\n    `${JSON.stringify({ finalTranscript, agentReply, turnCount: 1, metrics, qualityGate }, null, 2)}\\n`,\n    \"utf8\",\n  );\n  await writeFile(metricsJsonPath, `${JSON.stringify({ ...metrics, turnCount: 1, qualityGate }, null, 2)}\\n`, \"utf8\");\n\n  await session.close();\n\n  return {\n    sessionDir,\n    finalTranscript,\n    agentReply,\n    agentOutWavPath,\n    inputWavPath,\n    eventsJsonlPath,\n    eventsJsonPath,\n    transcriptJsonPath,\n    metricsJsonPath,\n    metrics,\n    durationMs:\n      timeline.feedStartMs > 0 && timeline.ttsEndMs > 0 ? Math.max(0, timeline.ttsEndMs - timeline.feedStartMs) : 0,\n  };\n}\n"],
+  "mappings": "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",
+  "names": ["require"]
+}

package/dist/version.d.ts

@@ -0,0 +1,25 @@
+export declare const CLI_VERSION: string;
+export declare const CORE_PACKAGE_NAME = "@kuralle-syrinx/core";
+export interface ResolvedPackageVersion {
+    readonly version: string;
+    readonly packageJsonPath: string;
+}
+/** First path component of a semver string, e.g. "4.3.0" -> "4". Not validated against full semver — good enough for a major-version skew check. */
+export declare function majorOf(version: string): string;
+/**
+ * Resolve `pkgName`'s installed version by walking node_modules resolution from
+ * `fromDir` (normally the invoking project's cwd), then walking up from the
+ * resolved entry file to the package's own package.json. Returns undefined when
+ * the package cannot be resolved at all (not installed in this project).
+ */
+export declare function resolveInstalledPackageVersion(pkgName: string, fromDir: string): ResolvedPackageVersion | undefined;
+export interface VersionSkewCheck {
+    readonly cliVersion: string;
+    readonly coreVersion: string | undefined;
+    readonly coreResolved: boolean;
+    readonly mismatch: boolean;
+}
+export declare function checkCoreVersionSkew(fromDir: string): VersionSkewCheck;
+/** Prints a loud warning to stderr when the CLI's major and the project's installed core major differ. Never writes to stdout. */
+export declare function warnOnVersionSkew(fromDir: string): VersionSkewCheck;
+//# sourceMappingURL=version.d.ts.map

package/dist/version.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"version.d.ts","sourceRoot":"","sources":["../src/version.ts"],"names":[],"mappings":"AAcA,eAAO,MAAM,WAAW,EAAE,MAA+B,CAAC;AAC1D,eAAO,MAAM,iBAAiB,yBAAyB,CAAC;AAExD,MAAM,WAAW,sBAAsB;IACrC,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,QAAQ,CAAC,eAAe,EAAE,MAAM,CAAC;CAClC;AAED,oJAAoJ;AACpJ,wBAAgB,OAAO,CAAC,OAAO,EAAE,MAAM,GAAG,MAAM,CAE/C;AAED;;;;;GAKG;AACH,wBAAgB,8BAA8B,CAAC,OAAO,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,GAAG,sBAAsB,GAAG,SAAS,CA6BnH;AAED,MAAM,WAAW,gBAAgB;IAC/B,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;IAC5B,QAAQ,CAAC,WAAW,EAAE,MAAM,GAAG,SAAS,CAAC;IACzC,QAAQ,CAAC,YAAY,EAAE,OAAO,CAAC;IAC/B,QAAQ,CAAC,QAAQ,EAAE,OAAO,CAAC;CAC5B;AAED,wBAAgB,oBAAoB,CAAC,OAAO,EAAE,MAAM,GAAG,gBAAgB,CAOtE;AAED,kIAAkI;AAClI,wBAAgB,iBAAiB,CAAC,OAAO,EAAE,MAAM,GAAG,gBAAgB,CAUnE"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@kuralle-syrinx/cli",
-  "version": "4.4.0",
+  "version": "4.5.0",
   "private": false,
   "description": "Agent-facing CLI for Syrinx — 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": [
@@ -32,21 +32,24 @@
     "README.md"
   ],
   "exports": {
-    "./turn-runner": "./src/turn-runner.ts"
+    "./turn-runner": {
+      "types": "./dist/turn-runner.d.ts",
+      "default": "./dist/turn-runner.js"
+    }
   },
   "dependencies": {
     "wavefile": "^11.0.0",
-    "@kuralle-syrinx/core": "4.4.0"
+    "@kuralle-syrinx/core": "4.5.0"
   },
   "devDependencies": {
     "@types/node": "^22.0.0",
     "esbuild": "^0.28.1",
     "typescript": "^5.7.0",
     "vitest": "^3.2.6",
-    "@kuralle-syrinx/test": "4.4.0"
+    "@kuralle-syrinx/test": "4.5.0"
   },
   "scripts": {
-    "build": "node scripts/build.mjs",
+    "build": "node scripts/build.mjs && tsc -p tsconfig.build.json --emitDeclarationOnly",
     "typecheck": "tsc --noEmit",
     "test": "vitest run"
   }