voice-runtime 0.0.2 → 1.0.1

package/package.json

@@ -1,20 +1,26 @@
 {
   "name": "voice-runtime",
-  "version": "0.0.2",
+  "version": "1.0.1",
   "description": "Local-first, provider-neutral runtime for realtime voice agents, powered by TVIC.",
   "type": "module",
-  "main": "./index.js",
-  "types": "./index.d.ts",
+  "bin": {
+    "voice-runtime": "./bin/voice-runtime.mjs"
+  },
+  "main": "./dist/index.cjs",
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.ts",
   "exports": {
     ".": {
-      "types": "./index.d.ts",
-      "import": "./index.js",
-      "default": "./index.js"
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js",
+      "require": "./dist/index.cjs",
+      "default": "./dist/index.js"
     }
   },
   "files": [
-    "index.js",
-    "index.d.ts",
+    "dist",
+    "bin",
+    "skills",
     "README.md",
     "LICENSE"
   ],
@@ -38,6 +44,34 @@
     "tvic"
   ],
   "license": "Apache-2.0",
+  "scripts": {
+    "build": "node build.mjs",
+    "typecheck": "tsc -p tsconfig.json --noEmit && tsc -p tsconfig.test.json",
+    "test": "vitest run",
+    "clean": "rm -rf dist dist-types .turbo *.tsbuildinfo"
+  },
+  "dependencies": {
+    "@types/node": "^22.19.19",
+    "@types/ws": "^8.18.1",
+    "ws": "^8.21.0"
+  },
+  "devDependencies": {
+    "@tvic/core": "workspace:*",
+    "@tvic/dal": "workspace:*",
+    "@tvic/dal-composite": "workspace:*",
+    "@tvic/dal-postgres": "workspace:*",
+    "@tvic/dal-postgres-memory": "workspace:*",
+    "@tvic/dal-redis": "workspace:*",
+    "@tvic/media": "workspace:*",
+    "@tvic/providers": "workspace:*",
+    "@tvic/runtime": "workspace:*",
+    "@tvic/tools": "workspace:*",
+    "esbuild": "^0.28.0",
+    "rollup": "^4.60.4",
+    "rollup-plugin-dts": "^6.3.0",
+    "typescript": "^5.7.2",
+    "vitest": "^2.1.8"
+  },
   "engines": {
     "node": ">=20.0.0"
   },

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.

package/index.d.ts

@@ -1,8 +0,0 @@
-export interface VoiceRuntimeIdentity {
-  readonly name: "voice-runtime";
-  readonly project: "TVIC";
-  readonly stage: "early-preview";
-  readonly repository: "https://github.com/Kkartik14/TVIC";
-}
-
-export declare const voiceRuntime: VoiceRuntimeIdentity;

package/index.js

@@ -1,13 +0,0 @@
-/**
- * Public identity for the early voice-runtime preview.
- *
- * The executable createVoiceAgent API will land here once its contract is
- * stable enough for external users. Publishing this explicit preview avoids
- * presenting an unfinished runtime API as production-ready.
- */
-export const voiceRuntime = Object.freeze({
-  name: "voice-runtime",
-  project: "TVIC",
-  stage: "early-preview",
-  repository: "https://github.com/Kkartik14/TVIC",
-});