voice-runtime 0.0.2 → 1.0.1

package/README.md

@@ -8,18 +8,136 @@
 [TVIC](https://github.com/Kkartik14/TVIC), a provider-neutral runtime for realtime
 voice agents with bring-your-own telephony, speech, model, and synthesis providers.
 
-## Status: early preview
+## Status
 
-This `0.0.x` release reserves the stable package name while the high-level
-`createVoiceAgent` API is completed. **It does not yet export the executable
-runtime, and it should not be used in production.**
+`voice-runtime@1.0.0` is the public Node.js entry point for the TVIC runtime. It
+declares Node.js 20 or newer, ships both ESM and CommonJS entry points, and is
+server-side only. The main CI compatibility matrix exercises Node 22, 24, and 26;
+Node 20 remains the package engine floor.
 
-Publishing an explicit placeholder is intentional. Shipping an unfinished runtime
-API under a stable name would be worse than shipping nothing.
+Browser audio connects to a Node server through the browser-audio transport
+adapter. Browser code does not import this package directly.
 
-The runtime itself is executable today and developed in the open. To run it now,
-work from the [repository](https://github.com/Kkartik14/TVIC) rather than from this
-package.
+The stable managed API assembles the STT → LLM → TTS pipeline from a prompt and
+provider configuration. The host application still owns its HTTP server,
+webhook authentication, browser-session authentication, and domain tools.
+
+If you are new to voice systems, read the [beginner guide on GitHub](https://github.com/Kkartik14/TVIC/blob/main/docs/start-here.md)
+before using the lower-level examples. The [provider guide](https://github.com/Kkartik14/TVIC/blob/main/docs/providers.md)
+explains credentials, model selection, and maturity labels.
+
+## Install
+
+```sh
+npm install voice-runtime
+```
+
+The package has no provider SDK lock-in. You may use the built-in adapters, pass
+your own provider implementations, or mix both approaches.
+
+## Optional AI agent guidance
+
+To give Claude Code, Codex, or another compatible coding agent project-scoped
+TVIC guidance, run this explicitly from your project directory:
+
+```sh
+npx voice-runtime skills install
+```
+
+The command asks for `y` before writing `.claude/skills/tvic/SKILL.md` for Claude
+Code and `.agents/skills/tvic/SKILL.md` for Codex and OpenRouter-compatible
+agents. It does not run automatically during `npm install`, write to a home
+directory, or overwrite an existing skill without `--force`. Use
+`npx voice-runtime skills install --yes` in automation. See the [AI agent skills
+guide](https://github.com/Kkartik14/TVIC/blob/main/docs/agent-skills.md).
+
+## Prompt-first agent
+
+The prompt-first API assembles the STT → LLM → TTS pipeline. It still needs an
+authenticated transport `CallHandle`; `npm install` does not create a public
+audio endpoint or a phone call for your application.
+
+```ts
+import { createVoiceAgent } from "voice-runtime";
+
+const agent = createVoiceAgent({
+  prompt: "You schedule appointments for Dr. Kartik. Be concise and confirm the time.",
+  providers: {
+    telephony: { provider: "web-client-audio" },
+    stt: { provider: "deepgram", apiKey: process.env.DEEPGRAM_API_KEY },
+    llm: {
+      provider: "openai",
+      apiKey: process.env.OPENAI_API_KEY,
+      model: "gpt-4.1-mini",
+    },
+    tts: {
+      provider: "cartesia",
+      apiKey: process.env.CARTESIA_API_KEY,
+      voiceId: process.env.CARTESIA_VOICE_ID,
+    },
+  },
+});
+
+// `callHandle` comes from a verified transport connection or your own adapter.
+const session = await agent.start({
+  callHandle,
+  channel: "web_audio",
+});
+
+for await (const event of session.run) {
+  if (event.kind === "transcript_delta") console.log("caller:", event.text);
+  if (event.kind === "error") console.error(event.error);
+}
+
+const result = await session.run;
+console.log(result.turnsHandled);
+await agent.stop();
+```
+
+`agent.start()` returns `{ sessionId, run }`. The `run` value is both an async
+event stream and an awaitable final result. The separate envelope is required by
+JavaScript Promise assimilation rules; returning the Promise-like run directly
+from an async `start()` method would make `await agent.start()` lose the session
+handle. Use `agent.run(options)` when you only need the final result.
+
+TVIC does not receive media from a prompt alone. A verified transport adapter
+must produce the `callHandle` passed to `start()`.
+
+For a built-in Web Client Audio or Twilio adapter, use the factory form so the
+adapter receives the session ID created by TVIC:
+
+```ts
+import { createTwilioMediaStreamsProvider, createVoiceAgent } from "voice-runtime";
+
+const telephony = createTwilioMediaStreamsProvider();
+
+const session = await agent.start({
+  call: verifiedInboundCall,
+  channel: "phone",
+  callHandle: ({ sessionId, call }) => telephony.acceptWebSocket(socket, call.id, sessionId),
+});
+```
+
+The factory runs after the runtime session exists and receives
+`{ sessionId, call, channel }`. The supplied call is required in this form, and
+its ID must match the returned handle's `callId`. Replace the provider and
+`channel` with `createWebClientAudioProvider()` and `"web_audio"` for browser
+audio. A preconstructed custom `CallHandle` is also supported when the adapter
+already knows how to correlate its events to the managed session.
+
+`agent.stop()` is idempotent. If a session is still running, it cancels and
+drains that session before closing the runtime and its stores.
+
+Errors on `VoiceEvent` and `MediaEvent` payloads are JSON-safe
+`NormalizedError` values. Check them with `isNormalizedError`; the
+`isTvicError` marker is reserved for thrown `TvicThrowableError` wrappers and
+is not present on plain event payloads.
+
+TVIC-created error codes use lowercase, namespaced identifiers such as
+`auth.invalid_key` and `provider.open_failed`. Custom calls to
+`normalizedError()` and `normalizeUnknownError()` must use one or more
+lowercase dot-separated segments; older persisted error records retain their
+legacy codes during migration.
 
 ## What TVIC does
 
@@ -31,6 +149,123 @@ Recordings, traces, incident analysis, and dashboards are deliberately out of sc
 Those belong to Earshot, a separate voice observability product that integrates
 outside the realtime critical path.
 
+## Providers, models, and credentials
+
+Each stage is configured independently. Built-in options currently include:
+
+- STT: Deepgram, Sarvam, ElevenLabs Scribe, AssemblyAI, and Soniox.
+- LLM: OpenAI Responses.
+- TTS: Cartesia and ElevenLabs.
+- Transport: browser audio and inbound Twilio Media Streams.
+
+Maturity is intentionally explicit: Web Client Audio and inbound Twilio Media
+Streams are the stable transport paths in `1.0.0`. The paid STT, LLM,
+and TTS adapters are currently `experimental`. Their deterministic protocol
+coverage passes, but each still needs a credential-gated live-service check
+before release notes can call it stable. The root export `PROVIDER_STABILITY`
+contains the machine-readable labels.
+
+Pass an explicit `apiKey` or use the documented environment variable. Explicit
+credentials take precedence; missing credentials fail before a live session is
+created.
+
+| Provider   | Environment variable |
+| ---------- | -------------------- |
+| Deepgram   | `DEEPGRAM_API_KEY`   |
+| Sarvam     | `SARVAM_API_KEY`     |
+| ElevenLabs | `ELEVENLABS_API_KEY` |
+| AssemblyAI | `ASSEMBLYAI_API_KEY` |
+| Soniox     | `SONIOX_API_KEY`     |
+| OpenAI     | `OPENAI_API_KEY`     |
+| Cartesia   | `CARTESIA_API_KEY`   |
+
+STT, LLM, and TTS models are independent settings. TTS voice selection is also
+independent. Built-in TTS can read `CARTESIA_VOICE_ID` or
+`ELEVENLABS_VOICE_ID` for its voice. For complete provider-specific control,
+pass a constructed provider instance instead of a built-in configuration object.
+Built-in STT and OpenAI-compatible LLM configurations reject models outside the
+dated TVIC catalog unless `allowUnknownModel: true` is explicitly set.
+
+Tools are application-owned functions. Define their schema and executor once,
+then include them in the agent:
+
+```ts
+import { createVoiceAgent, defineTool } from "voice-runtime";
+
+const bookAppointment = defineTool<{ date: string }, { booked: boolean }>({
+  id: "book_appointment",
+  name: "book_appointment",
+  description: "Books an appointment for a requested date.",
+  inputSchema: { type: "object", required: ["date"] },
+  outputSchema: { type: "object", required: ["booked"] },
+  async execute(input) {
+    // Call your application service here; TVIC does not own domain state.
+    return { booked: input.date.length > 0 };
+  },
+});
+
+const providers = {
+  telephony: { provider: "web-client-audio" as const },
+  stt: { provider: "deepgram" as const, apiKey: process.env.DEEPGRAM_API_KEY },
+  llm: { provider: "openai" as const, apiKey: process.env.OPENAI_API_KEY },
+  tts: {
+    provider: "cartesia" as const,
+    apiKey: process.env.CARTESIA_API_KEY,
+    voiceId: process.env.CARTESIA_VOICE_ID,
+  },
+};
+
+const agentWithTools = createVoiceAgent({
+  prompt: "Schedule appointments and use the booking tool when needed.",
+  tools: [bookAppointment],
+  providers,
+});
+```
+
+Tool execution receives a session/turn-scoped `AbortSignal`; authorization,
+confirmation for irreversible actions, and domain-state writes remain the host
+application's responsibility.
+
+## Composable API
+
+Advanced runtime, media, provider, normalized-error, and durable-adapter APIs
+are exported from the package root. There are no advanced subpath imports in
+1.0.0. This lets a developer start with `createVoiceAgent` and later own
+the runtime/session/pipeline boundaries without changing package names.
+
+The host remains responsible for creating authenticated transport connections,
+owning HTTP/webhook lifecycle, and implementing application-domain tools. TVIC
+does not automatically create public unauthenticated endpoints or choose a
+provider fallback policy.
+
+## Persistence adapters
+
+The root also exposes the PostgreSQL and Redis durability building blocks. The
+database drivers are intentionally injected, so install and configure `pg` and
+`redis` in your application:
+
+```ts
+import {
+  createPostgresMemory,
+  createPostgresRedisDurableRuntimeStore,
+  runPostgresMemoryMigrations,
+  runPostgresMigrations,
+} from "voice-runtime";
+
+await runPostgresMigrations(pgPool);
+await runPostgresMemoryMigrations(memoryPool);
+const memory = createPostgresMemory({ pool: memoryPool });
+const durable = createPostgresRedisDurableRuntimeStore({
+  pool: pgPool,
+  redis: redisClient,
+});
+```
+
+The migration SQL is bundled into the published package and can also be
+inspected in the package's migration sources. Run each migration function once
+at deploy time; repeated calls are idempotent. PostgreSQL is authoritative for
+the composite store, while Redis is used for its cache/projection layer.
+
 ## License
 
 [Apache-2.0](./LICENSE)

package/bin/voice-runtime.mjs

@@ -0,0 +1,248 @@
+#!/usr/bin/env node
+
+import { mkdir, readFile, writeFile } from "node:fs/promises";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+import readline from "node:readline/promises";
+
+const packageRoot = path.resolve(path.dirname(fileURLToPath(import.meta.url)), "..");
+const skillSource = path.join(packageRoot, "skills", "tvic", "SKILL.md");
+
+const AGENT_TARGETS = Object.freeze({
+  claude: Object.freeze({
+    label: "Claude Code",
+    relativePath: path.join(".claude", "skills", "tvic", "SKILL.md"),
+  }),
+  codex: Object.freeze({
+    label: "Codex",
+    relativePath: path.join(".agents", "skills", "tvic", "SKILL.md"),
+  }),
+  openrouter: Object.freeze({
+    label: "OpenRouter-compatible agents",
+    relativePath: path.join(".agents", "skills", "tvic", "SKILL.md"),
+  }),
+});
+
+const DEFAULT_AGENTS = Object.freeze(["claude", "codex", "openrouter"]);
+
+function printHelp() {
+  process.stdout.write("voice-runtime\n\n");
+  process.stdout.write("Install the optional TVIC guidance skill in the current project.\n\n");
+  process.stdout.write("Usage:\n");
+  process.stdout.write("  voice-runtime skills install [options]\n\n");
+  process.stdout.write("Options:\n");
+  process.stdout.write("  --agent <name>  Target claude, codex, or openrouter. Repeatable.\n");
+  process.stdout.write("  --yes           Confirm installation without a prompt.\n");
+  process.stdout.write("  --dry-run       Show planned files without changing anything.\n");
+  process.stdout.write("  --force         Replace an existing TVIC skill file.\n");
+  process.stdout.write("  --help          Show this help.\n\n");
+  process.stdout.write("Project paths:\n");
+  process.stdout.write("  Claude Code: .claude/skills/tvic/SKILL.md\n");
+  process.stdout.write("  Codex/OpenRouter: .agents/skills/tvic/SKILL.md\n");
+}
+
+function parseArgs(args) {
+  const options = {
+    agents: [],
+    dryRun: false,
+    force: false,
+    help: false,
+    yes: false,
+  };
+
+  for (let index = 0; index < args.length; index += 1) {
+    const argument = args[index];
+    if (argument === "--help" || argument === "-h") {
+      options.help = true;
+      continue;
+    }
+    if (argument === "--yes" || argument === "-y") {
+      options.yes = true;
+      continue;
+    }
+    if (argument === "--dry-run") {
+      options.dryRun = true;
+      continue;
+    }
+    if (argument === "--force" || argument === "-f") {
+      options.force = true;
+      continue;
+    }
+
+    if (argument === "--agent") {
+      const value = args[index + 1];
+      if (!value) throw new Error("--agent requires a value");
+      options.agents.push(...value.split(","));
+      index += 1;
+      continue;
+    }
+
+    if (argument.startsWith("--agent=")) {
+      options.agents.push(...argument.slice("--agent=".length).split(","));
+      continue;
+    }
+
+    throw new Error(`Unknown option: ${argument}`);
+  }
+
+  return options;
+}
+
+function selectedAgents(requestedAgents) {
+  const names = requestedAgents.length > 0 ? requestedAgents : DEFAULT_AGENTS;
+  const selected = new Set();
+
+  for (const requested of names) {
+    const name = requested.trim().toLowerCase();
+    if (name === "all") {
+      for (const agent of DEFAULT_AGENTS) selected.add(agent);
+      continue;
+    }
+    if (!Object.hasOwn(AGENT_TARGETS, name)) {
+      throw new Error(`Unknown agent "${requested}". Choose claude, codex, or openrouter.`);
+    }
+    selected.add(name);
+  }
+
+  return [...selected];
+}
+
+function plannedFiles(agentNames, projectDirectory) {
+  const plans = new Map();
+
+  for (const agentName of agentNames) {
+    const target = AGENT_TARGETS[agentName];
+    const absolutePath = path.resolve(projectDirectory, target.relativePath);
+    const existing = plans.get(absolutePath);
+    if (existing) {
+      existing.agentNames.push(agentName);
+    } else {
+      plans.set(absolutePath, {
+        agentNames: [agentName],
+        absolutePath,
+        relativePath: path.relative(projectDirectory, absolutePath),
+      });
+    }
+  }
+
+  return [...plans.values()];
+}
+
+async function inspectPlans(plans, source, force) {
+  const inspected = [];
+
+  for (const plan of plans) {
+    let current;
+    try {
+      current = await readFile(plan.absolutePath, "utf8");
+    } catch (error) {
+      if (error?.code !== "ENOENT") throw error;
+    }
+
+    let action = "create";
+    if (current !== undefined) {
+      action = current === source ? "unchanged" : force ? "replace" : "conflict";
+    }
+    inspected.push({ ...plan, action });
+  }
+
+  return inspected;
+}
+
+async function confirmInstallation(projectDirectory, plans) {
+  if (!process.stdin.isTTY || !process.stdout.isTTY) {
+    throw new Error(
+      "No interactive terminal is available. Re-run with --yes to confirm installation.",
+    );
+  }
+
+  const labels = [...new Set(plans.flatMap((plan) => plan.agentNames))]
+    .map((agentName) => AGENT_TARGETS[agentName].label)
+    .join(", ");
+  const prompt = `Install TVIC guidance for ${labels} in ${projectDirectory}? (y/N) `;
+  const terminal = readline.createInterface({ input: process.stdin, output: process.stdout });
+  try {
+    const answer = await terminal.question(prompt);
+    return answer.trim().toLowerCase() === "y";
+  } finally {
+    terminal.close();
+  }
+}
+
+async function installPlans(plans, source) {
+  for (const plan of plans) {
+    if (plan.action === "unchanged") {
+      process.stdout.write(`Already installed: ${plan.relativePath}\n`);
+      continue;
+    }
+    await mkdir(path.dirname(plan.absolutePath), { recursive: true });
+    await writeFile(plan.absolutePath, source, "utf8");
+    process.stdout.write(
+      `${plan.action === "replace" ? "Updated" : "Installed"}: ${plan.relativePath}\n`,
+    );
+  }
+}
+
+async function installSkills(options) {
+  const projectDirectory = process.cwd();
+  const agents = selectedAgents(options.agents);
+  const source = await readFile(skillSource, "utf8");
+  const plans = await inspectPlans(plannedFiles(agents, projectDirectory), source, options.force);
+
+  process.stdout.write(`Project: ${projectDirectory}\n`);
+  for (const plan of plans) {
+    const agentsForPath = [...new Set(plan.agentNames)]
+      .map((agentName) => AGENT_TARGETS[agentName].label)
+      .join(" and ");
+    process.stdout.write(`  ${plan.relativePath} (${agentsForPath})\n`);
+  }
+
+  if (options.dryRun) {
+    process.stdout.write("Dry run: no files changed.\n");
+    return;
+  }
+
+  const conflicts = plans.filter((plan) => plan.action === "conflict");
+  if (conflicts.length > 0) {
+    throw new Error(
+      `Existing TVIC skill files differ: ${conflicts
+        .map((plan) => plan.relativePath)
+        .join(", ")}. Use --force to replace them.`,
+    );
+  }
+
+  if (!options.yes && !(await confirmInstallation(projectDirectory, plans))) {
+    process.stdout.write("No files changed.\n");
+    return;
+  }
+
+  await installPlans(plans, source);
+  process.stdout.write(
+    "TVIC agent guidance is ready. Restart the agent if it does not appear automatically.\n",
+  );
+}
+
+async function main() {
+  const [command, subcommand, ...args] = process.argv.slice(2);
+  if (command === "--help" || command === "-h" || !command) {
+    printHelp();
+    return;
+  }
+  if (command !== "skills" || subcommand !== "install") {
+    throw new Error("Use: voice-runtime skills install [options]");
+  }
+
+  const options = parseArgs(args);
+  if (options.help) {
+    printHelp();
+    return;
+  }
+  await installSkills(options);
+}
+
+main().catch((error) => {
+  process.stderr.write(
+    `voice-runtime: ${error instanceof Error ? error.message : String(error)}\n`,
+  );
+  process.exitCode = 1;
+});