@nebutra/voice-realtime 0.1.0

package/README.md

@@ -0,0 +1,20 @@
+# @nebutra/voice-realtime
+
+Status: WIP — Not yet integrated into any production app.
+
+`@nebutra/voice-realtime` owns voice session lifecycle, narration synthesis,
+interrupt metadata, and voice enrollment contracts. The zero-config path writes
+valid narration WAV files through audio utilities; realtime WebRTC/STT/TTS is a
+sidecar port.
+
+It does not own Thread/Turn/Item state, model provider routing, or prompt
+orchestration.
+
+## Commands
+
+```bash
+pnpm voice:doctor
+pnpm voice:debug
+pnpm voice:enroll
+pnpm voice:test-mic
+```

package/dist/chunk-GARLTI7J.js

@@ -0,0 +1,108 @@
+// src/index.ts
+import { mkdir, writeFile } from "fs/promises";
+import { dirname, join } from "path";
+import { createToneWav } from "@nebutra/audio-pipeline";
+import { appendCapabilityDebug, readCapabilityDebug } from "@nebutra/capability-kit/debug";
+import {
+  assetId,
+  requireBrandContext
+} from "@nebutra/generation-context";
+async function readVoiceDebug(root = process.cwd(), limit = 10) {
+  return readCapabilityDebug("voice-realtime", { root, limit });
+}
+var VoiceRealtime = class {
+  #root;
+  constructor(options = {}) {
+    this.#root = options.root ?? process.cwd();
+  }
+  async startSession(input) {
+    const session = {
+      id: assetId("voice_session", input.threadId),
+      tenantId: input.tenantId,
+      threadId: input.threadId,
+      room: `voice_${input.tenantId}_${input.threadId}`,
+      state: "listening"
+    };
+    await appendCapabilityDebug(
+      "voice-realtime",
+      { type: "session", session },
+      { root: this.#root }
+    );
+    return session;
+  }
+  async synthesizeNarration(request, brandInput) {
+    const brand = requireBrandContext(brandInput, "voice-realtime");
+    const durationS = Math.max(
+      1,
+      Math.min(request.targetDurationS ?? Math.ceil(request.script.length / 24), 20)
+    );
+    const id = assetId("voice", `${brand.brandId}_${request.script}`);
+    const path = join(this.#root, ".nebutra", "generated", "voice-realtime", `${id}.wav`);
+    await mkdir(dirname(path), { recursive: true });
+    await writeFile(path, createToneWav(durationS, 330));
+    const asset = {
+      id,
+      tenantId: brand.tenantId,
+      kind: "voice",
+      path,
+      brandId: brand.brandId,
+      provider: "tone-local",
+      model: "brand-context-narration-v1",
+      createdAt: (/* @__PURE__ */ new Date()).toISOString(),
+      license: { status: "commercial-ok", source: "deterministic local renderer" },
+      transcript: request.script,
+      durationS,
+      format: "wav",
+      voiceProfileId: request.voiceProfileId ?? "default",
+      metadata: { brandSource: brand.sourcePath }
+    };
+    await appendCapabilityDebug(
+      "voice-realtime",
+      { type: "narration", asset },
+      { root: this.#root }
+    );
+    return asset;
+  }
+  async enroll(input) {
+    const profile = {
+      id: assetId("voice_profile", input.tenantId),
+      tenantId: input.tenantId,
+      consentRecordedAt: (/* @__PURE__ */ new Date()).toISOString(),
+      sampleCount: input.samplePaths?.length ?? 0
+    };
+    await appendCapabilityDebug(
+      "voice-realtime",
+      { type: "enroll", profile },
+      { root: this.#root }
+    );
+    return profile;
+  }
+  async testMic() {
+    return {
+      provider: "local-mic",
+      ok: Boolean(process.env.VOICE_MIC_PERMISSION === "granted"),
+      suggestion: "Grant microphone access in the desktop app before realtime sessions."
+    };
+  }
+  async doctor() {
+    return [
+      await this.testMic(),
+      {
+        provider: "voice-sidecar",
+        ok: Boolean(process.env.VOICE_SIDECAR_URL),
+        suggestion: "Set VOICE_SIDECAR_URL to enable realtime WebRTC/STT/TTS."
+      },
+      {
+        provider: "remote-tts",
+        ok: Boolean(process.env.VOICE_REMOTE_API_KEY),
+        suggestion: "Set VOICE_REMOTE_API_KEY to enable remote voice fallback."
+      }
+    ];
+  }
+};
+
+export {
+  readVoiceDebug,
+  VoiceRealtime
+};
+//# sourceMappingURL=chunk-GARLTI7J.js.map

package/dist/chunk-GARLTI7J.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/index.ts"],"sourcesContent":["import { mkdir, writeFile } from \"node:fs/promises\";\nimport { dirname, join } from \"node:path\";\nimport { createToneWav } from \"@nebutra/audio-pipeline\";\nimport { appendCapabilityDebug, readCapabilityDebug } from \"@nebutra/capability-kit/debug\";\nimport {\n  assetId,\n  type BrandContext,\n  type GeneratedAsset,\n  requireBrandContext,\n} from \"@nebutra/generation-context\";\n\nexport type VoiceState = \"listening\" | \"thinking\" | \"speaking\" | \"paused\" | \"closed\";\n\nexport interface VoiceSession {\n  readonly id: string;\n  readonly tenantId: string;\n  readonly threadId: string;\n  readonly room: string;\n  readonly state: VoiceState;\n}\n\nexport interface NarrationRequest {\n  readonly script: string;\n  readonly voiceProfileId?: string;\n  readonly targetDurationS?: number;\n}\n\nexport interface VoiceAsset extends GeneratedAsset {\n  readonly kind: \"voice\";\n  readonly transcript: string;\n  readonly durationS: number;\n  readonly format: \"wav\";\n  readonly voiceProfileId: string;\n}\n\nexport interface VoiceProfile {\n  readonly id: string;\n  readonly tenantId: string;\n  readonly consentRecordedAt: string;\n  readonly sampleCount: number;\n}\n\nexport interface VoiceHealth {\n  readonly provider: string;\n  readonly ok: boolean;\n  readonly suggestion?: string;\n}\n\nexport interface VoiceRealtimeOptions {\n  readonly root?: string;\n}\n\nexport async function readVoiceDebug(root = process.cwd(), limit = 10): Promise<unknown[]> {\n  return readCapabilityDebug(\"voice-realtime\", { root, limit });\n}\n\nexport class VoiceRealtime {\n  readonly #root: string;\n\n  constructor(options: VoiceRealtimeOptions = {}) {\n    this.#root = options.root ?? process.cwd();\n  }\n\n  async startSession(input: { tenantId: string; threadId: string }): Promise<VoiceSession> {\n    const session: VoiceSession = {\n      id: assetId(\"voice_session\", input.threadId),\n      tenantId: input.tenantId,\n      threadId: input.threadId,\n      room: `voice_${input.tenantId}_${input.threadId}`,\n      state: \"listening\",\n    };\n    await appendCapabilityDebug(\n      \"voice-realtime\",\n      { type: \"session\", session },\n      { root: this.#root },\n    );\n    return session;\n  }\n\n  async synthesizeNarration(\n    request: NarrationRequest,\n    brandInput: BrandContext | undefined,\n  ): Promise<VoiceAsset> {\n    const brand = requireBrandContext(brandInput, \"voice-realtime\");\n    const durationS = Math.max(\n      1,\n      Math.min(request.targetDurationS ?? Math.ceil(request.script.length / 24), 20),\n    );\n    const id = assetId(\"voice\", `${brand.brandId}_${request.script}`);\n    const path = join(this.#root, \".nebutra\", \"generated\", \"voice-realtime\", `${id}.wav`);\n    await mkdir(dirname(path), { recursive: true });\n    await writeFile(path, createToneWav(durationS, 330));\n    const asset: VoiceAsset = {\n      id,\n      tenantId: brand.tenantId,\n      kind: \"voice\",\n      path,\n      brandId: brand.brandId,\n      provider: \"tone-local\",\n      model: \"brand-context-narration-v1\",\n      createdAt: new Date().toISOString(),\n      license: { status: \"commercial-ok\", source: \"deterministic local renderer\" },\n      transcript: request.script,\n      durationS,\n      format: \"wav\",\n      voiceProfileId: request.voiceProfileId ?? \"default\",\n      metadata: { brandSource: brand.sourcePath },\n    };\n    await appendCapabilityDebug(\n      \"voice-realtime\",\n      { type: \"narration\", asset },\n      { root: this.#root },\n    );\n    return asset;\n  }\n\n  async enroll(input: {\n    tenantId: string;\n    samplePaths?: readonly string[];\n  }): Promise<VoiceProfile> {\n    const profile: VoiceProfile = {\n      id: assetId(\"voice_profile\", input.tenantId),\n      tenantId: input.tenantId,\n      consentRecordedAt: new Date().toISOString(),\n      sampleCount: input.samplePaths?.length ?? 0,\n    };\n    await appendCapabilityDebug(\n      \"voice-realtime\",\n      { type: \"enroll\", profile },\n      { root: this.#root },\n    );\n    return profile;\n  }\n\n  async testMic(): Promise<VoiceHealth> {\n    return {\n      provider: \"local-mic\",\n      ok: Boolean(process.env.VOICE_MIC_PERMISSION === \"granted\"),\n      suggestion: \"Grant microphone access in the desktop app before realtime sessions.\",\n    };\n  }\n\n  async doctor(): Promise<VoiceHealth[]> {\n    return [\n      await this.testMic(),\n      {\n        provider: \"voice-sidecar\",\n        ok: Boolean(process.env.VOICE_SIDECAR_URL),\n        suggestion: \"Set VOICE_SIDECAR_URL to enable realtime WebRTC/STT/TTS.\",\n      },\n      {\n        provider: \"remote-tts\",\n        ok: Boolean(process.env.VOICE_REMOTE_API_KEY),\n        suggestion: \"Set VOICE_REMOTE_API_KEY to enable remote voice fallback.\",\n      },\n    ];\n  }\n}\n"],"mappings":";AAAA,SAAS,OAAO,iBAAiB;AACjC,SAAS,SAAS,YAAY;AAC9B,SAAS,qBAAqB;AAC9B,SAAS,uBAAuB,2BAA2B;AAC3D;AAAA,EACE;AAAA,EAGA;AAAA,OACK;AA2CP,eAAsB,eAAe,OAAO,QAAQ,IAAI,GAAG,QAAQ,IAAwB;AACzF,SAAO,oBAAoB,kBAAkB,EAAE,MAAM,MAAM,CAAC;AAC9D;AAEO,IAAM,gBAAN,MAAoB;AAAA,EAChB;AAAA,EAET,YAAY,UAAgC,CAAC,GAAG;AAC9C,SAAK,QAAQ,QAAQ,QAAQ,QAAQ,IAAI;AAAA,EAC3C;AAAA,EAEA,MAAM,aAAa,OAAsE;AACvF,UAAM,UAAwB;AAAA,MAC5B,IAAI,QAAQ,iBAAiB,MAAM,QAAQ;AAAA,MAC3C,UAAU,MAAM;AAAA,MAChB,UAAU,MAAM;AAAA,MAChB,MAAM,SAAS,MAAM,QAAQ,IAAI,MAAM,QAAQ;AAAA,MAC/C,OAAO;AAAA,IACT;AACA,UAAM;AAAA,MACJ;AAAA,MACA,EAAE,MAAM,WAAW,QAAQ;AAAA,MAC3B,EAAE,MAAM,KAAK,MAAM;AAAA,IACrB;AACA,WAAO;AAAA,EACT;AAAA,EAEA,MAAM,oBACJ,SACA,YACqB;AACrB,UAAM,QAAQ,oBAAoB,YAAY,gBAAgB;AAC9D,UAAM,YAAY,KAAK;AAAA,MACrB;AAAA,MACA,KAAK,IAAI,QAAQ,mBAAmB,KAAK,KAAK,QAAQ,OAAO,SAAS,EAAE,GAAG,EAAE;AAAA,IAC/E;AACA,UAAM,KAAK,QAAQ,SAAS,GAAG,MAAM,OAAO,IAAI,QAAQ,MAAM,EAAE;AAChE,UAAM,OAAO,KAAK,KAAK,OAAO,YAAY,aAAa,kBAAkB,GAAG,EAAE,MAAM;AACpF,UAAM,MAAM,QAAQ,IAAI,GAAG,EAAE,WAAW,KAAK,CAAC;AAC9C,UAAM,UAAU,MAAM,cAAc,WAAW,GAAG,CAAC;AACnD,UAAM,QAAoB;AAAA,MACxB;AAAA,MACA,UAAU,MAAM;AAAA,MAChB,MAAM;AAAA,MACN;AAAA,MACA,SAAS,MAAM;AAAA,MACf,UAAU;AAAA,MACV,OAAO;AAAA,MACP,YAAW,oBAAI,KAAK,GAAE,YAAY;AAAA,MAClC,SAAS,EAAE,QAAQ,iBAAiB,QAAQ,+BAA+B;AAAA,MAC3E,YAAY,QAAQ;AAAA,MACpB;AAAA,MACA,QAAQ;AAAA,MACR,gBAAgB,QAAQ,kBAAkB;AAAA,MAC1C,UAAU,EAAE,aAAa,MAAM,WAAW;AAAA,IAC5C;AACA,UAAM;AAAA,MACJ;AAAA,MACA,EAAE,MAAM,aAAa,MAAM;AAAA,MAC3B,EAAE,MAAM,KAAK,MAAM;AAAA,IACrB;AACA,WAAO;AAAA,EACT;AAAA,EAEA,MAAM,OAAO,OAGa;AACxB,UAAM,UAAwB;AAAA,MAC5B,IAAI,QAAQ,iBAAiB,MAAM,QAAQ;AAAA,MAC3C,UAAU,MAAM;AAAA,MAChB,oBAAmB,oBAAI,KAAK,GAAE,YAAY;AAAA,MAC1C,aAAa,MAAM,aAAa,UAAU;AAAA,IAC5C;AACA,UAAM;AAAA,MACJ;AAAA,MACA,EAAE,MAAM,UAAU,QAAQ;AAAA,MAC1B,EAAE,MAAM,KAAK,MAAM;AAAA,IACrB;AACA,WAAO;AAAA,EACT;AAAA,EAEA,MAAM,UAAgC;AACpC,WAAO;AAAA,MACL,UAAU;AAAA,MACV,IAAI,QAAQ,QAAQ,IAAI,yBAAyB,SAAS;AAAA,MAC1D,YAAY;AAAA,IACd;AAAA,EACF;AAAA,EAEA,MAAM,SAAiC;AACrC,WAAO;AAAA,MACL,MAAM,KAAK,QAAQ;AAAA,MACnB;AAAA,QACE,UAAU;AAAA,QACV,IAAI,QAAQ,QAAQ,IAAI,iBAAiB;AAAA,QACzC,YAAY;AAAA,MACd;AAAA,MACA;AAAA,QACE,UAAU;AAAA,QACV,IAAI,QAAQ,QAAQ,IAAI,oBAAoB;AAAA,QAC5C,YAAY;AAAA,MACd;AAAA,IACF;AAAA,EACF;AACF;","names":[]}

package/dist/cli.d.ts

@@ -0,0 +1,2 @@
+
+export {  }

package/dist/cli.js

@@ -0,0 +1,42 @@
+import {
+  VoiceRealtime,
+  readVoiceDebug
+} from "./chunk-GARLTI7J.js";
+
+// src/cli.ts
+import { createDemoBrandContext } from "@nebutra/generation-context";
+var command = process.argv[2] ?? "doctor";
+var voice = new VoiceRealtime();
+if (command === "doctor") {
+  process.stdout.write(
+    `${JSON.stringify({ capability: "voice-realtime", results: await voice.doctor() }, null, 2)}
+`
+  );
+} else if (command === "debug") {
+  process.stdout.write(
+    `${JSON.stringify({ capability: "voice-realtime", entries: await readVoiceDebug() }, null, 2)}
+`
+  );
+} else if (command === "enroll") {
+  process.stdout.write(
+    `${JSON.stringify({ capability: "voice-realtime", profile: await voice.enroll({ tenantId: "local" }) }, null, 2)}
+`
+  );
+} else if (command === "test-mic") {
+  process.stdout.write(
+    `${JSON.stringify({ capability: "voice-realtime", mic: await voice.testMic() }, null, 2)}
+`
+  );
+} else if (command === "narrate") {
+  const asset = await voice.synthesizeNarration(
+    { script: "Loop helps indie developers debug the work that matters.", targetDurationS: 3 },
+    createDemoBrandContext()
+  );
+  process.stdout.write(`${JSON.stringify({ capability: "voice-realtime", asset }, null, 2)}
+`);
+} else {
+  process.stderr.write(`Unknown voice-realtime command: ${command}
+`);
+  process.exitCode = 1;
+}
+//# sourceMappingURL=cli.js.map

package/dist/cli.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/cli.ts"],"sourcesContent":["import { createDemoBrandContext } from \"@nebutra/generation-context\";\nimport { readVoiceDebug, VoiceRealtime } from \"./index\";\n\nconst command = process.argv[2] ?? \"doctor\";\nconst voice = new VoiceRealtime();\n\nif (command === \"doctor\") {\n  process.stdout.write(\n    `${JSON.stringify({ capability: \"voice-realtime\", results: await voice.doctor() }, null, 2)}\\n`,\n  );\n} else if (command === \"debug\") {\n  process.stdout.write(\n    `${JSON.stringify({ capability: \"voice-realtime\", entries: await readVoiceDebug() }, null, 2)}\\n`,\n  );\n} else if (command === \"enroll\") {\n  process.stdout.write(\n    `${JSON.stringify({ capability: \"voice-realtime\", profile: await voice.enroll({ tenantId: \"local\" }) }, null, 2)}\\n`,\n  );\n} else if (command === \"test-mic\") {\n  process.stdout.write(\n    `${JSON.stringify({ capability: \"voice-realtime\", mic: await voice.testMic() }, null, 2)}\\n`,\n  );\n} else if (command === \"narrate\") {\n  const asset = await voice.synthesizeNarration(\n    { script: \"Loop helps indie developers debug the work that matters.\", targetDurationS: 3 },\n    createDemoBrandContext(),\n  );\n  process.stdout.write(`${JSON.stringify({ capability: \"voice-realtime\", asset }, null, 2)}\\n`);\n} else {\n  process.stderr.write(`Unknown voice-realtime command: ${command}\\n`);\n  process.exitCode = 1;\n}\n"],"mappings":";;;;;;AAAA,SAAS,8BAA8B;AAGvC,IAAM,UAAU,QAAQ,KAAK,CAAC,KAAK;AACnC,IAAM,QAAQ,IAAI,cAAc;AAEhC,IAAI,YAAY,UAAU;AACxB,UAAQ,OAAO;AAAA,IACb,GAAG,KAAK,UAAU,EAAE,YAAY,kBAAkB,SAAS,MAAM,MAAM,OAAO,EAAE,GAAG,MAAM,CAAC,CAAC;AAAA;AAAA,EAC7F;AACF,WAAW,YAAY,SAAS;AAC9B,UAAQ,OAAO;AAAA,IACb,GAAG,KAAK,UAAU,EAAE,YAAY,kBAAkB,SAAS,MAAM,eAAe,EAAE,GAAG,MAAM,CAAC,CAAC;AAAA;AAAA,EAC/F;AACF,WAAW,YAAY,UAAU;AAC/B,UAAQ,OAAO;AAAA,IACb,GAAG,KAAK,UAAU,EAAE,YAAY,kBAAkB,SAAS,MAAM,MAAM,OAAO,EAAE,UAAU,QAAQ,CAAC,EAAE,GAAG,MAAM,CAAC,CAAC;AAAA;AAAA,EAClH;AACF,WAAW,YAAY,YAAY;AACjC,UAAQ,OAAO;AAAA,IACb,GAAG,KAAK,UAAU,EAAE,YAAY,kBAAkB,KAAK,MAAM,MAAM,QAAQ,EAAE,GAAG,MAAM,CAAC,CAAC;AAAA;AAAA,EAC1F;AACF,WAAW,YAAY,WAAW;AAChC,QAAM,QAAQ,MAAM,MAAM;AAAA,IACxB,EAAE,QAAQ,4DAA4D,iBAAiB,EAAE;AAAA,IACzF,uBAAuB;AAAA,EACzB;AACA,UAAQ,OAAO,MAAM,GAAG,KAAK,UAAU,EAAE,YAAY,kBAAkB,MAAM,GAAG,MAAM,CAAC,CAAC;AAAA,CAAI;AAC9F,OAAO;AACL,UAAQ,OAAO,MAAM,mCAAmC,OAAO;AAAA,CAAI;AACnE,UAAQ,WAAW;AACrB;","names":[]}

package/dist/index.d.ts

@@ -0,0 +1,54 @@
+import { GeneratedAsset, BrandContext } from '@nebutra/generation-context';
+
+type VoiceState = "listening" | "thinking" | "speaking" | "paused" | "closed";
+interface VoiceSession {
+    readonly id: string;
+    readonly tenantId: string;
+    readonly threadId: string;
+    readonly room: string;
+    readonly state: VoiceState;
+}
+interface NarrationRequest {
+    readonly script: string;
+    readonly voiceProfileId?: string;
+    readonly targetDurationS?: number;
+}
+interface VoiceAsset extends GeneratedAsset {
+    readonly kind: "voice";
+    readonly transcript: string;
+    readonly durationS: number;
+    readonly format: "wav";
+    readonly voiceProfileId: string;
+}
+interface VoiceProfile {
+    readonly id: string;
+    readonly tenantId: string;
+    readonly consentRecordedAt: string;
+    readonly sampleCount: number;
+}
+interface VoiceHealth {
+    readonly provider: string;
+    readonly ok: boolean;
+    readonly suggestion?: string;
+}
+interface VoiceRealtimeOptions {
+    readonly root?: string;
+}
+declare function readVoiceDebug(root?: string, limit?: number): Promise<unknown[]>;
+declare class VoiceRealtime {
+    #private;
+    constructor(options?: VoiceRealtimeOptions);
+    startSession(input: {
+        tenantId: string;
+        threadId: string;
+    }): Promise<VoiceSession>;
+    synthesizeNarration(request: NarrationRequest, brandInput: BrandContext | undefined): Promise<VoiceAsset>;
+    enroll(input: {
+        tenantId: string;
+        samplePaths?: readonly string[];
+    }): Promise<VoiceProfile>;
+    testMic(): Promise<VoiceHealth>;
+    doctor(): Promise<VoiceHealth[]>;
+}
+
+export { type NarrationRequest, type VoiceAsset, type VoiceHealth, type VoiceProfile, VoiceRealtime, type VoiceRealtimeOptions, type VoiceSession, type VoiceState, readVoiceDebug };

package/dist/index.js

@@ -0,0 +1,9 @@
+import {
+  VoiceRealtime,
+  readVoiceDebug
+} from "./chunk-GARLTI7J.js";
+export {
+  VoiceRealtime,
+  readVoiceDebug
+};
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":[],"sourcesContent":[],"mappings":"","names":[]}

package/examples/enroll.ts

@@ -0,0 +1,5 @@
+import { VoiceRealtime } from "../src/index";
+
+const profile = await new VoiceRealtime().enroll({ tenantId: "demo", samplePaths: [] });
+
+process.stdout.write(`${profile.id}\n`);

package/examples/narration.ts

@@ -0,0 +1,9 @@
+import { createDemoBrandContext } from "@nebutra/generation-context";
+import { VoiceRealtime } from "../src/index";
+
+const asset = await new VoiceRealtime().synthesizeNarration(
+  { script: "Loop makes debugging visible.", targetDurationS: 3 },
+  createDemoBrandContext(),
+);
+
+process.stdout.write(`${asset.path}\n`);

package/examples/session.ts

@@ -0,0 +1,5 @@
+import { VoiceRealtime } from "../src/index";
+
+process.stdout.write(
+  `${JSON.stringify(await new VoiceRealtime().startSession({ tenantId: "demo", threadId: "thread_1" }), null, 2)}\n`,
+);

package/package.json

@@ -0,0 +1,61 @@
+{
+  "name": "@nebutra/voice-realtime",
+  "version": "0.1.0",
+  "description": "Voice session lifecycle, narration synthesis, and enrollment surface",
+  "private": false,
+  "license": "MIT",
+  "type": "module",
+  "nebutra": {
+    "status": "wip",
+    "productionReady": false,
+    "surface": "generation-capability",
+    "requires": [
+      "@nebutra/generation-context for BrandContext",
+      "@nebutra/audio-pipeline for audio rendering utilities",
+      "A voice sidecar for production WebRTC/STT/TTS transport"
+    ],
+    "gaps": [
+      "Realtime transport is represented as a session contract until the sidecar is wired",
+      "Voice enrollment stores metadata only",
+      "Low-latency STT/TTS providers are health-checked through env only"
+    ],
+    "featureId": "voice-realtime",
+    "category": "ai",
+    "summary": "Realtime voice session and narration synthesis surface"
+  },
+  "main": "./src/index.ts",
+  "types": "./src/index.ts",
+  "exports": {
+    ".": "./src/index.ts"
+  },
+  "dependencies": {
+    "@nebutra/audio-pipeline": "0.1.0",
+    "@nebutra/capability-kit": "0.2.0",
+    "@nebutra/errors": "0.1.0",
+    "@nebutra/generation-context": "0.1.0"
+  },
+  "devDependencies": {
+    "@types/node": "^22.19.15",
+    "tsup": "^8.5.1",
+    "tsx": "^4.21.0",
+    "typescript": "^5.9.3",
+    "vitest": "^4.1.4"
+  },
+  "homepage": "https://github.com/Nebutra/Nebutra-Sailor/tree/main/packages/ai/voice-realtime#readme",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/Nebutra/Nebutra-Sailor.git",
+    "directory": "packages/ai/voice-realtime"
+  },
+  "bugs": {
+    "url": "https://github.com/Nebutra/Nebutra-Sailor/issues"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "build": "tsup",
+    "test": "vitest run",
+    "typecheck": "tsc --noEmit"
+  }
+}

package/src/cli.ts

@@ -0,0 +1,32 @@
+import { createDemoBrandContext } from "@nebutra/generation-context";
+import { readVoiceDebug, VoiceRealtime } from "./index";
+
+const command = process.argv[2] ?? "doctor";
+const voice = new VoiceRealtime();
+
+if (command === "doctor") {
+  process.stdout.write(
+    `${JSON.stringify({ capability: "voice-realtime", results: await voice.doctor() }, null, 2)}\n`,
+  );
+} else if (command === "debug") {
+  process.stdout.write(
+    `${JSON.stringify({ capability: "voice-realtime", entries: await readVoiceDebug() }, null, 2)}\n`,
+  );
+} else if (command === "enroll") {
+  process.stdout.write(
+    `${JSON.stringify({ capability: "voice-realtime", profile: await voice.enroll({ tenantId: "local" }) }, null, 2)}\n`,
+  );
+} else if (command === "test-mic") {
+  process.stdout.write(
+    `${JSON.stringify({ capability: "voice-realtime", mic: await voice.testMic() }, null, 2)}\n`,
+  );
+} else if (command === "narrate") {
+  const asset = await voice.synthesizeNarration(
+    { script: "Loop helps indie developers debug the work that matters.", targetDurationS: 3 },
+    createDemoBrandContext(),
+  );
+  process.stdout.write(`${JSON.stringify({ capability: "voice-realtime", asset }, null, 2)}\n`);
+} else {
+  process.stderr.write(`Unknown voice-realtime command: ${command}\n`);
+  process.exitCode = 1;
+}

package/src/index.test.ts

@@ -0,0 +1,33 @@
+import { mkdtemp, readFile, rm } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { createDemoBrandContext } from "@nebutra/generation-context";
+import { afterEach, describe, expect, it } from "vitest";
+import { readVoiceDebug, VoiceRealtime } from "./index";
+
+let root: string | undefined;
+
+afterEach(async () => {
+  if (root) await rm(root, { recursive: true, force: true });
+  root = undefined;
+});
+
+describe("VoiceRealtime", () => {
+  it("starts a thread-bound voice session without importing the runtime", async () => {
+    const session = await new VoiceRealtime().startSession({
+      tenantId: "tenant_a",
+      threadId: "thread_1",
+    });
+    expect(session.state).toBe("listening");
+  });
+
+  it("synthesizes narration with BrandContext", async () => {
+    root = await mkdtemp(join(tmpdir(), "voice-realtime-"));
+    const asset = await new VoiceRealtime({ root }).synthesizeNarration(
+      { script: "Ship the story with the founder voice.", targetDurationS: 2 },
+      createDemoBrandContext(),
+    );
+    expect((await readFile(asset.path)).subarray(0, 4).toString()).toBe("RIFF");
+    expect(await readVoiceDebug(root)).toHaveLength(1);
+  });
+});

package/src/index.ts

@@ -0,0 +1,158 @@
+import { mkdir, writeFile } from "node:fs/promises";
+import { dirname, join } from "node:path";
+import { createToneWav } from "@nebutra/audio-pipeline";
+import { appendCapabilityDebug, readCapabilityDebug } from "@nebutra/capability-kit/debug";
+import {
+  assetId,
+  type BrandContext,
+  type GeneratedAsset,
+  requireBrandContext,
+} from "@nebutra/generation-context";
+
+export type VoiceState = "listening" | "thinking" | "speaking" | "paused" | "closed";
+
+export interface VoiceSession {
+  readonly id: string;
+  readonly tenantId: string;
+  readonly threadId: string;
+  readonly room: string;
+  readonly state: VoiceState;
+}
+
+export interface NarrationRequest {
+  readonly script: string;
+  readonly voiceProfileId?: string;
+  readonly targetDurationS?: number;
+}
+
+export interface VoiceAsset extends GeneratedAsset {
+  readonly kind: "voice";
+  readonly transcript: string;
+  readonly durationS: number;
+  readonly format: "wav";
+  readonly voiceProfileId: string;
+}
+
+export interface VoiceProfile {
+  readonly id: string;
+  readonly tenantId: string;
+  readonly consentRecordedAt: string;
+  readonly sampleCount: number;
+}
+
+export interface VoiceHealth {
+  readonly provider: string;
+  readonly ok: boolean;
+  readonly suggestion?: string;
+}
+
+export interface VoiceRealtimeOptions {
+  readonly root?: string;
+}
+
+export async function readVoiceDebug(root = process.cwd(), limit = 10): Promise<unknown[]> {
+  return readCapabilityDebug("voice-realtime", { root, limit });
+}
+
+export class VoiceRealtime {
+  readonly #root: string;
+
+  constructor(options: VoiceRealtimeOptions = {}) {
+    this.#root = options.root ?? process.cwd();
+  }
+
+  async startSession(input: { tenantId: string; threadId: string }): Promise<VoiceSession> {
+    const session: VoiceSession = {
+      id: assetId("voice_session", input.threadId),
+      tenantId: input.tenantId,
+      threadId: input.threadId,
+      room: `voice_${input.tenantId}_${input.threadId}`,
+      state: "listening",
+    };
+    await appendCapabilityDebug(
+      "voice-realtime",
+      { type: "session", session },
+      { root: this.#root },
+    );
+    return session;
+  }
+
+  async synthesizeNarration(
+    request: NarrationRequest,
+    brandInput: BrandContext | undefined,
+  ): Promise<VoiceAsset> {
+    const brand = requireBrandContext(brandInput, "voice-realtime");
+    const durationS = Math.max(
+      1,
+      Math.min(request.targetDurationS ?? Math.ceil(request.script.length / 24), 20),
+    );
+    const id = assetId("voice", `${brand.brandId}_${request.script}`);
+    const path = join(this.#root, ".nebutra", "generated", "voice-realtime", `${id}.wav`);
+    await mkdir(dirname(path), { recursive: true });
+    await writeFile(path, createToneWav(durationS, 330));
+    const asset: VoiceAsset = {
+      id,
+      tenantId: brand.tenantId,
+      kind: "voice",
+      path,
+      brandId: brand.brandId,
+      provider: "tone-local",
+      model: "brand-context-narration-v1",
+      createdAt: new Date().toISOString(),
+      license: { status: "commercial-ok", source: "deterministic local renderer" },
+      transcript: request.script,
+      durationS,
+      format: "wav",
+      voiceProfileId: request.voiceProfileId ?? "default",
+      metadata: { brandSource: brand.sourcePath },
+    };
+    await appendCapabilityDebug(
+      "voice-realtime",
+      { type: "narration", asset },
+      { root: this.#root },
+    );
+    return asset;
+  }
+
+  async enroll(input: {
+    tenantId: string;
+    samplePaths?: readonly string[];
+  }): Promise<VoiceProfile> {
+    const profile: VoiceProfile = {
+      id: assetId("voice_profile", input.tenantId),
+      tenantId: input.tenantId,
+      consentRecordedAt: new Date().toISOString(),
+      sampleCount: input.samplePaths?.length ?? 0,
+    };
+    await appendCapabilityDebug(
+      "voice-realtime",
+      { type: "enroll", profile },
+      { root: this.#root },
+    );
+    return profile;
+  }
+
+  async testMic(): Promise<VoiceHealth> {
+    return {
+      provider: "local-mic",
+      ok: Boolean(process.env.VOICE_MIC_PERMISSION === "granted"),
+      suggestion: "Grant microphone access in the desktop app before realtime sessions.",
+    };
+  }
+
+  async doctor(): Promise<VoiceHealth[]> {
+    return [
+      await this.testMic(),
+      {
+        provider: "voice-sidecar",
+        ok: Boolean(process.env.VOICE_SIDECAR_URL),
+        suggestion: "Set VOICE_SIDECAR_URL to enable realtime WebRTC/STT/TTS.",
+      },
+      {
+        provider: "remote-tts",
+        ok: Boolean(process.env.VOICE_REMOTE_API_KEY),
+        suggestion: "Set VOICE_REMOTE_API_KEY to enable remote voice fallback.",
+      },
+    ];
+  }
+}

package/tsconfig.json

@@ -0,0 +1,12 @@
+{
+  "extends": "../../../tsconfig.base.json",
+  "compilerOptions": {
+    "module": "ESNext",
+    "moduleResolution": "bundler",
+    "target": "esnext",
+    "types": ["node"],
+    "incremental": false
+  },
+  "include": ["src", "examples"],
+  "exclude": ["node_modules", "dist"]
+}

package/tsup.config.ts

@@ -0,0 +1,16 @@
+import { defineConfig } from "tsup";
+
+export default defineConfig({
+  entry: ["src/index.ts", "src/cli.ts"],
+  format: ["esm"],
+  dts: true,
+  sourcemap: true,
+  clean: true,
+  target: "es2022",
+  external: [
+    "@nebutra/audio-pipeline",
+    "@nebutra/capability-kit/debug",
+    "@nebutra/errors",
+    "@nebutra/generation-context",
+  ],
+});