voice-runtime 1.0.0 → 1.0.1

package/README.md

@@ -10,18 +10,21 @@ voice agents with bring-your-own telephony, speech, model, and synthesis provide
 
 ## 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.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.
+
+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
 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`.
+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
 
@@ -32,8 +35,28 @@ 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";
 
@@ -136,8 +159,8 @@ Each stage is configured independently. Built-in options currently include:
 - 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.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.
@@ -206,8 +229,8 @@ 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.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,

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

package/package.json

@@ -1,8 +1,11 @@
 {
   "name": "voice-runtime",
-  "version": "1.0.0",
+  "version": "1.0.1",
   "description": "Local-first, provider-neutral runtime for realtime voice agents, powered by TVIC.",
   "type": "module",
+  "bin": {
+    "voice-runtime": "./bin/voice-runtime.mjs"
+  },
   "main": "./dist/index.cjs",
   "module": "./dist/index.js",
   "types": "./dist/index.d.ts",
@@ -16,6 +19,8 @@
   },
   "files": [
     "dist",
+    "bin",
+    "skills",
     "README.md",
     "LICENSE"
   ],

package/skills/tvic/SKILL.md

@@ -0,0 +1,79 @@
+---
+name: tvic
+description: Use when building, configuring, testing, or debugging a voice agent with voice-runtime or TVIC. Covers the prompt-first API, composable runtime, providers, transports, events, persistence, and security boundaries.
+---
+
+# TVIC development guidance
+
+Use this skill when the project uses `voice-runtime` or the TVIC runtime. It is
+guidance for the coding agent, not a replacement for the host application's
+authorization or business rules.
+
+## Start with the installed package
+
+Before suggesting code, inspect the installed `voice-runtime` version and read
+`node_modules/voice-runtime/README.md` when it exists. Prefer APIs exported from
+the package root. Do not invent exports or copy repository-only imports into a
+consumer application.
+
+## Core model
+
+TVIC runs a server-side cascaded voice pipeline:
+
+```text
+transport -> speech to text -> turn handling -> language model and tools -> text to speech -> transport
+```
+
+The host application supplies an authenticated `CallHandle`, chooses providers,
+and owns the HTTP or WebSocket lifecycle. A prompt configures behavior, but a
+prompt does not create a phone call, public endpoint, user authentication, or
+permission to change business data.
+
+## Managed API
+
+Use `createVoiceAgent` when the application wants TVIC to assemble the standard
+speech to text, language model, and text to speech pipeline. Configure every
+required provider explicitly. Start a session only after the host has
+authenticated the connection and created or received its `CallHandle`.
+
+The managed run is both an event stream and an awaitable final result. Consume
+events for live UI, transcripts, errors, and audio state, then await the same run
+for the final outcome. Do not assume that audio sent to a socket was heard. Use
+the transport's playout acknowledgement when deciding whether a response was
+delivered.
+
+## Composable API
+
+Use the lower-level root exports when the application needs to own part of the
+pipeline or provide a custom STT, language model, text to speech, telephony,
+memory, or durable-store implementation. Preserve TVIC's normalized contracts,
+capability declarations, cancellation behavior, and event semantics.
+
+## Providers and models
+
+Use built-in adapters only with their documented provider names, credentials,
+models, and maturity labels. Do not describe an experimental adapter as stable.
+If a provider or model is not in the built-in catalog, prefer a constructed
+custom provider or the explicit unknown-model option rather than silently
+changing the user's selection.
+
+## Tools and security
+
+Tools belong to the host application. Validate their inputs and outputs, enforce
+authorization and confirmation for irreversible actions, and make retries safe
+when an action can be performed twice. Keep provider keys, signing secrets,
+database URLs, transcripts, and recordings on the server. Treat caller speech,
+transcripts, prompts, tool arguments, and external controller data as untrusted.
+
+## Testing and troubleshooting
+
+For a consumer project, test the exact transport and provider configuration being
+used. Mock providers are useful for deterministic tests, but they do not prove a
+live provider works. When debugging a missing response, trace the complete path:
+authenticated transport, inbound media, transcript finality, completed turn,
+model or tool result, synthesized audio, transport receipt, and playout evidence.
+
+When changing a public contract, add a test through the public package entry
+point and update the relevant documentation. Report uncertainty instead of
+claiming delivery, cancellation, provider stability, or authorization behavior
+that the underlying integration does not prove.