@crewhaus/target-voice 0.1.0

package/package.json

@@ -0,0 +1,43 @@
+{
+  "name": "@crewhaus/target-voice",
+  "version": "0.1.0",
+  "type": "module",
+  "description": "Codegen for the VOICE target — emits a realtime daemon (Section 24 VOICE)",
+  "main": "src/index.ts",
+  "types": "src/index.ts",
+  "exports": {
+    ".": "./src/index.ts"
+  },
+  "scripts": {
+    "test": "bun test src"
+  },
+  "dependencies": {
+    "@crewhaus/errors": "0.0.0",
+    "@crewhaus/infra-utils": "0.0.0",
+    "@crewhaus/ir": "0.0.0"
+  },
+  "license": "Apache-2.0",
+  "author": {
+    "name": "Max Meier",
+    "email": "max@studiomax.io",
+    "url": "https://studiomax.io"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/crewhaus/factory.git",
+    "directory": "packages/target-voice"
+  },
+  "homepage": "https://github.com/crewhaus/factory/tree/main/packages/target-voice#readme",
+  "bugs": {
+    "url": "https://github.com/crewhaus/factory/issues"
+  },
+  "publishConfig": {
+    "access": "restricted"
+  },
+  "files": [
+    "src",
+    "README.md",
+    "LICENSE",
+    "NOTICE"
+  ]
+}

package/src/index.test.ts

@@ -0,0 +1,88 @@
+import { describe, expect, test } from "bun:test";
+import type { IrVoiceV0 } from "@crewhaus/ir";
+import { TargetEmitError, emitVoice } from "./index.js";
+
+const baseIr: IrVoiceV0 = {
+  version: 0,
+  name: "hello-voice",
+  target: "voice",
+  agent: { model: "gpt-4o-realtime-preview", instructions: "be brief" },
+  voice: {
+    provider: "openai",
+    voiceId: "alloy",
+    vad: "server",
+    bargeInTriggerFrames: 4,
+    bargeInWindowMs: 200,
+  },
+  tools: [],
+  toolConfigs: Object.freeze({}),
+  mcp_servers: Object.freeze({}),
+  permissions: { rules: [] },
+  compaction: {},
+};
+
+describe("emitVoice", () => {
+  test("emits agent.ts + voice-loop.ts + daemon.ts (T1 bundle structure)", () => {
+    const bundle = emitVoice(baseIr);
+    expect(bundle.files.map((f) => f.path).sort()).toEqual([
+      "agent.ts",
+      "daemon.ts",
+      "voice-loop.ts",
+    ]);
+  });
+
+  test("agent.ts exports AGENT_CONFIG with the spec values inlined", () => {
+    const code = emitVoice(baseIr).files.find((f) => f.path === "agent.ts")?.content ?? "";
+    expect(code).toContain("AGENT_CONFIG");
+    expect(code).toContain('"hello-voice"');
+    expect(code).toContain('"gpt-4o-realtime-preview"');
+    expect(code).toContain('"alloy"');
+    expect(code).toContain("bargeInTriggerFrames: 4");
+  });
+
+  test("voice-loop.ts wires barge-in-controller + vad-engine + voice-runtime", () => {
+    const code = emitVoice(baseIr).files.find((f) => f.path === "voice-loop.ts")?.content ?? "";
+    expect(code).toContain("@crewhaus/barge-in-controller");
+    expect(code).toContain("@crewhaus/voice-runtime");
+    expect(code).toContain("@crewhaus/vad-engine");
+    expect(code).toContain("createBargeInController");
+    expect(code).toContain("createRealtimeAdapter");
+    expect(code).toContain("frames30ms");
+  });
+
+  test("daemon.ts has a --smoke <pcm-path> path that emits voice_event JSON lines", () => {
+    const code = emitVoice(baseIr).files.find((f) => f.path === "daemon.ts")?.content ?? "";
+    expect(code).toContain('"--smoke"');
+    expect(code).toContain('"voice_event"');
+    expect(code).toContain('"smoke_start"');
+    expect(code).toContain('"smoke_done"');
+    expect(code).toContain("loadPcm");
+  });
+
+  test("vapi provider is forwarded to the loop verbatim", () => {
+    const ir: IrVoiceV0 = {
+      ...baseIr,
+      voice: { ...baseIr.voice, provider: "vapi" },
+    };
+    const code = emitVoice(ir).files.find((f) => f.path === "agent.ts")?.content ?? "";
+    expect(code).toContain('provider: "vapi"');
+  });
+
+  test("telephony block (when present) is wired into AGENT_CONFIG", () => {
+    const ir: IrVoiceV0 = {
+      ...baseIr,
+      telephony: { provider: "twilio" },
+    };
+    const code = emitVoice(ir).files.find((f) => f.path === "agent.ts")?.content ?? "";
+    expect(code).toContain('telephony: { provider: "twilio" }');
+  });
+
+  test("absent telephony block yields telephony: undefined", () => {
+    const code = emitVoice(baseIr).files.find((f) => f.path === "agent.ts")?.content ?? "";
+    expect(code).toContain("telephony: undefined");
+  });
+
+  test("TargetEmitError type is exported", () => {
+    expect(TargetEmitError).toBeDefined();
+  });
+});

package/src/index.ts

@@ -0,0 +1,195 @@
+/**
+ * Catalog F2 `target-voice` — Section 24 VOICE.
+ *
+ * Codegen for the realtime voice target. Emits three files:
+ *
+ *   - `voice-loop.ts` — the per-call audio I/O loop. Wires the
+ *     RealtimeAdapter, vad-engine + barge-in-controller, and an event
+ *     emitter that forwards transcripts/audio/tool-uses to the daemon.
+ *   - `agent.ts` — config wrapper exporting the spec's model +
+ *     instructions + tool list + voice block.
+ *   - `daemon.ts` — entrypoint. Either runs a one-shot smoke handler
+ *     (when invoked with `--smoke <pcm-path>` it pumps a PCM file in
+ *     and emits one JSON event per stdout line; useful for the smoke
+ *     test) or boots a long-running WebSocket bridge (placeholder; v0
+ *     ships the smoke path, full bridge lands in a follow-up).
+ *
+ * The emitted bundle is callable headless (no microphone needed) — the
+ * daemon reads PCM from stdin or a file path, so the VOICE smoke
+ * doesn't require a browser.
+ */
+import { CrewhausError } from "@crewhaus/errors";
+import { escapeJsonString } from "@crewhaus/infra-utils";
+import type { Bundle, IrVoiceV0 } from "@crewhaus/ir";
+
+export class TargetEmitError extends CrewhausError {
+  override readonly name = "TargetEmitError";
+  constructor(message: string, cause?: unknown) {
+    super("compiler", message, cause);
+  }
+}
+
+export function emitVoice(ir: IrVoiceV0): Bundle {
+  return {
+    files: [
+      { path: "agent.ts", content: renderAgent(ir) },
+      { path: "voice-loop.ts", content: renderVoiceLoop(ir) },
+      { path: "daemon.ts", content: renderDaemon(ir) },
+    ],
+  };
+}
+
+function renderAgent(ir: IrVoiceV0): string {
+  return `// Generated by crewhaus. DO NOT EDIT.
+// Source spec: ${ir.name} (target: voice, ir version: ${ir.version}, file: agent.ts)
+
+export const AGENT_CONFIG = {
+  name: ${escapeJsonString(ir.name)},
+  model: ${escapeJsonString(ir.agent.model)},
+  instructions: ${escapeJsonString(ir.agent.instructions)},
+  voice: {
+    provider: ${escapeJsonString(ir.voice.provider)},
+    voiceId: ${escapeJsonString(ir.voice.voiceId)},
+    vad: ${escapeJsonString(ir.voice.vad)},
+    bargeInTriggerFrames: ${ir.voice.bargeInTriggerFrames},
+    bargeInWindowMs: ${ir.voice.bargeInWindowMs},
+  },
+  telephony: ${
+    ir.telephony !== undefined
+      ? `{ provider: ${escapeJsonString(ir.telephony.provider)} }`
+      : "undefined"
+  },
+} as const;
+`;
+}
+
+function renderVoiceLoop(ir: IrVoiceV0): string {
+  return `// Generated by crewhaus. DO NOT EDIT.
+// Source spec: ${ir.name} (target: voice, ir version: ${ir.version}, file: voice-loop.ts)
+import { createBargeInController } from "@crewhaus/barge-in-controller";
+import { createRealtimeAdapter, type RealtimeEvent } from "@crewhaus/voice-runtime";
+import { createVadDetector, frames30ms } from "@crewhaus/vad-engine";
+import { AGENT_CONFIG } from "./agent.js";
+
+export type VoiceEventListener = (event: RealtimeEvent | { kind: "barge_in"; speechFrames: number }) => void;
+
+export type VoiceCallOptions = {
+  /** PCM 16-bit signed mono buffer at 24kHz; the loop frames + streams it. */
+  readonly inboundPcm: Int16Array;
+  readonly listener: VoiceEventListener;
+  /** Time budget for a single call. Defaults to 60s. */
+  readonly maxDurationMs?: number;
+};
+
+const DEFAULT_MAX_DURATION_MS = 60_000;
+
+export async function runOneCall(opts: VoiceCallOptions): Promise<void> {
+  const adapter = createRealtimeAdapter(AGENT_CONFIG.voice.provider);
+  // Attach the listener BEFORE connect() so the first session.created
+  // event (and any error events during the upgrade) are captured.
+  const off = adapter.on((ev) => opts.listener(ev));
+  await adapter.connect({
+    model: AGENT_CONFIG.model,
+    instructions: AGENT_CONFIG.instructions,
+    voice: AGENT_CONFIG.voice.voiceId,
+    vad: AGENT_CONFIG.voice.vad,
+  });
+
+  const detector = createVadDetector({ aggressiveness: 1, sampleRate: 24_000 });
+  const bargeIn = createBargeInController({
+    adapter,
+    detector,
+    triggerFrames: AGENT_CONFIG.voice.bargeInTriggerFrames,
+    windowMs: AGENT_CONFIG.voice.bargeInWindowMs,
+    onBargeIn: ({ speechFrames }) => opts.listener({ kind: "barge_in", speechFrames }),
+  });
+
+  const fs = frames30ms(opts.inboundPcm, 24_000);
+  for (const f of fs) {
+    bargeIn.feedAudioFrame(f);
+    adapter.sendAudio(f);
+  }
+  // Tell the server "this is end-of-utterance — process it now". With
+  // server VAD this would happen automatically after silence, but the
+  // smoke pumps a single bounded clip and needs a deterministic kick.
+  adapter.commitInput();
+
+  // Wait for transcript_final or budget expiry.
+  const budget = opts.maxDurationMs ?? DEFAULT_MAX_DURATION_MS;
+  let resolved = false;
+  await new Promise<void>((resolve) => {
+    const timer = setTimeout(() => {
+      if (!resolved) resolve();
+    }, budget);
+    const inner = adapter.on((ev) => {
+      if (ev.kind === "transcript_final" || ev.kind === "disconnect") {
+        if (!resolved) {
+          resolved = true;
+          clearTimeout(timer);
+          inner();
+          resolve();
+        }
+      }
+    });
+  });
+
+  bargeIn.stop();
+  off();
+  await adapter.disconnect();
+}
+`;
+}
+
+function renderDaemon(ir: IrVoiceV0): string {
+  return `#!/usr/bin/env bun
+// Generated by crewhaus. DO NOT EDIT.
+// Source spec: ${ir.name} (target: voice, ir version: ${ir.version}, file: daemon.ts)
+import { existsSync, readFileSync } from "node:fs";
+import { runOneCall } from "./voice-loop.js";
+
+function emit(event: Record<string, unknown>): void {
+  process.stdout.write(\`\${JSON.stringify(event)}\\n\`);
+}
+
+function loadPcm(path: string): Int16Array {
+  if (!existsSync(path)) {
+    throw new Error("[voice-daemon] PCM file not found: " + path);
+  }
+  const buf = readFileSync(path);
+  // raw PCM 16-bit little-endian mono. Align onto a fresh ArrayBuffer
+  // because Buffer's underlying buffer can have an unaligned offset.
+  const aligned = new ArrayBuffer(buf.byteLength);
+  new Uint8Array(aligned).set(buf);
+  return new Int16Array(aligned);
+}
+
+async function smokeMode(pcmPath: string): Promise<void> {
+  emit({ kind: "smoke_start", pcmPath });
+  const pcm = loadPcm(pcmPath);
+  emit({ kind: "smoke_pcm_loaded", samples: pcm.length });
+  await runOneCall({
+    inboundPcm: pcm,
+    listener: (ev) => emit({ kind: "voice_event", event: ev }),
+  });
+  emit({ kind: "smoke_done" });
+}
+
+async function main(): Promise<void> {
+  const args = process.argv.slice(2);
+  const smokeIdx = args.indexOf("--smoke");
+  if (smokeIdx !== -1 && smokeIdx + 1 < args.length) {
+    await smokeMode(args[smokeIdx + 1]!);
+    return;
+  }
+  process.stderr.write(
+    "[voice-daemon] no --smoke <pcm-path> provided. v0 ships the headless smoke path; the WebRTC + telephony bridge lands in a follow-up.\\n",
+  );
+  process.exit(2);
+}
+
+main().catch((err) => {
+  process.stderr.write(\`[voice-daemon] fatal: \${(err as Error).message}\\n\`);
+  process.exit(1);
+});
+`;
+}