voice-runtime 1.0.0 → 1.1.0

package/README.md

@@ -8,20 +8,29 @@
 [TVIC](https://github.com/Kkartik14/TVIC), a provider-neutral runtime for realtime
 voice agents with bring-your-own telephony, speech, model, and synthesis providers.
 
+New to the package? Start with the [beginner's guide](https://github.com/Kkartik14/TVIC/blob/main/docs/getting-started.md).
+Use the [voice-agent guide](https://github.com/Kkartik14/TVIC/blob/main/docs/building-a-voice-agent.md)
+for application design, [providers](https://github.com/Kkartik14/TVIC/blob/main/docs/providers.md)
+for model setup, and [transports](https://github.com/Kkartik14/TVIC/blob/main/docs/transports.md)
+for browser and phone connections.
+
 ## Status
 
-The package is the public Node.js entry point for the TVIC runtime. The first
-release targets Node 20 through 26 and ships both ESM and CommonJS entry points.
-It is server-side only: browser audio connects to a Node server through the
-browser-audio transport adapter, while browser imports from this package remain
-out of scope for the first release.
+`voice-runtime@1.0.1` is the public Node.js entry point for the TVIC runtime. It
+supports Node.js 22, 24, and 26, ships both ESM and CommonJS entry points, and is
+server-side only. The main CI compatibility matrix exercises all three supported
+lines.
+
+Browser audio connects to a Node server through the browser-audio transport
+adapter. Browser code does not import this package directly.
 
-The stable managed API assembles the STT → LLM → TTS pipeline from a prompt and
+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.
 
-This README describes the intended public contract; release status is tracked in
-the repository's `local/release/1.0.0/checklist.md`.
+For a system overview, read [How it works](https://github.com/Kkartik14/TVIC/blob/main/docs/how-it-works.md).
+For testing and deployment, read the [testing guide](https://github.com/Kkartik14/TVIC/blob/main/docs/testing.md)
+and [deployment guide](https://github.com/Kkartik14/TVIC/blob/main/docs/deploying.md).
 
 ## Install
 
@@ -32,8 +41,29 @@ 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 coding-agent
+guide](https://github.com/Kkartik14/TVIC/blob/main/docs/ai-coding-agents.md) and
+[skills reference](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";
 
@@ -43,9 +73,9 @@ const agent = createVoiceAgent({
     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",
+      provider: "groq",
+      apiKey: process.env.GROQ_API_KEY,
+      model: "openai/gpt-oss-20b",
     },
     tts: {
       provider: "cartesia",
@@ -130,14 +160,17 @@ outside the realtime critical path.
 
 Each stage is configured independently. Built-in options currently include:
 
+The complete matrix, catalog dates, official provider links, and live-test
+guidance are in the [provider guide](https://github.com/Kkartik14/TVIC/blob/main/docs/providers.md).
+
 - STT: Deepgram, Sarvam, ElevenLabs Scribe, AssemblyAI, and Soniox.
-- LLM: OpenAI Responses.
+- LLM: Groq Chat Completions (the reference path) and an optional OpenAI Responses adapter.
 - 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 candidates for `1.0.0`. The paid STT, LLM,
-and TTS adapters are currently `experimental`—their deterministic protocol
+Streams are the stable transport paths in `1.0.1`. 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.
@@ -153,6 +186,7 @@ created.
 | ElevenLabs | `ELEVENLABS_API_KEY` |
 | AssemblyAI | `ASSEMBLYAI_API_KEY` |
 | Soniox     | `SONIOX_API_KEY`     |
+| Groq       | `GROQ_API_KEY`       |
 | OpenAI     | `OPENAI_API_KEY`     |
 | Cartesia   | `CARTESIA_API_KEY`   |
 
@@ -160,7 +194,7 @@ 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
+Built-in STT and 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,
@@ -184,7 +218,7 @@ const bookAppointment = defineTool<{ date: string }, { booked: boolean }>({
 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 },
+  llm: { provider: "groq" as const, apiKey: process.env.GROQ_API_KEY },
   tts: {
     provider: "cartesia" as const,
     apiKey: process.env.CARTESIA_API_KEY,
@@ -206,10 +240,14 @@ 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 the
-first release. This lets a developer start with `createVoiceAgent` and later own
+are exported from the package root. There are no advanced subpath imports in
+1.0.1. This lets a developer start with `createVoiceAgent` and later own
 the runtime/session/pipeline boundaries without changing package names.
 
+Read the [voice-agent guide](https://github.com/Kkartik14/TVIC/blob/main/docs/building-a-voice-agent.md)
+for the managed to composable migration path and the [API reference](https://github.com/Kkartik14/TVIC/blob/main/docs/api-reference.md)
+for the root exports.
+
 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
@@ -221,6 +259,9 @@ 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:
 
+The [persistence guide](https://github.com/Kkartik14/TVIC/blob/main/docs/persistence.md)
+covers migrations, memory scopes, Docker, ownership, and production retention.
+
 ```ts
 import {
   createPostgresMemory,

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;
+});