@absolutejs/voice 0.0.22-beta.631 → 0.0.22-beta.633

package/dist/manifest.json

@@ -0,0 +1,385 @@
+{
+	"contract": 1,
+	"identity": {
+		"accent": "#f43f5e",
+		"category": "voice",
+		"description": "Self-hosted voice assistant runtime for Elysia: browser and phone-call sessions over WebSockets, pluggable speech-to-text (`voice/stt`), text-to-speech (`voice/tts`), and speech-to-speech (`voice/realtime`) vendor adapters, turn detection, barge-in, greetings, reconnect recovery, session stores (`voice/session-store`), traces, evals, and live-monitor surfaces — the orchestration hosted voice platforms keep behind their dashboards, inside your own server.",
+		"docsUrl": "https://github.com/absolutejs/voice",
+		"name": "@absolutejs/voice",
+		"tagline": "Let people talk to your site and get spoken answers."
+	},
+	"implements": [
+		{
+			"contract": "voice/session-store",
+			"factory": "createVoiceMemoryStore",
+			"from": "@absolutejs/voice",
+			"title": "In memory (development only — calls are forgotten on restart)",
+			"wiring": {
+				"code": "createVoiceMemoryStore()",
+				"imports": [
+					{
+						"from": "@absolutejs/voice",
+						"names": [
+							"createVoiceMemoryStore"
+						]
+					}
+				]
+			}
+		},
+		{
+			"contract": "voice/session-store",
+			"factory": "createVoiceSQLiteSessionStore",
+			"from": "@absolutejs/voice",
+			"settings": {
+				"type": "object",
+				"required": [
+					"path"
+				],
+				"properties": {
+					"path": {
+						"description": "Database file on this machine where call sessions are kept. Created if missing.",
+						"examples": [
+							"./var/voice-sessions.sqlite"
+						],
+						"title": "Database file",
+						"type": "string"
+					},
+					"tableName": {
+						"description": "Table the sessions are stored in.",
+						"title": "Table name",
+						"type": "string"
+					}
+				}
+			},
+			"title": "SQLite file on this machine",
+			"wiring": {
+				"code": "createVoiceSQLiteSessionStore(${settings})",
+				"imports": [
+					{
+						"from": "@absolutejs/voice",
+						"names": [
+							"createVoiceSQLiteSessionStore"
+						]
+					}
+				]
+			}
+		},
+		{
+			"contract": "voice/session-store",
+			"factory": "createVoicePostgresSessionStore",
+			"from": "@absolutejs/voice",
+			"requires": {
+				"env": [
+					{
+						"description": "Postgres connection string (call sessions are stored here)",
+						"example": "postgres://user:pass@host/db",
+						"key": "DATABASE_URL",
+						"secret": true
+					}
+				],
+				"services": [
+					{
+						"description": "Stores call sessions durably",
+						"id": "postgres"
+					}
+				]
+			},
+			"settings": {
+				"type": "object",
+				"properties": {
+					"schemaName": {
+						"description": "Postgres schema the table lives in.",
+						"title": "Schema name",
+						"type": "string"
+					},
+					"tableName": {
+						"description": "Table the sessions are stored in.",
+						"title": "Table name",
+						"type": "string"
+					}
+				}
+			},
+			"title": "Postgres",
+			"wiring": {
+				"code": "createVoicePostgresSessionStore({ connectionString: ${env.DATABASE_URL} ?? \"\", ...${settings} })",
+				"imports": [
+					{
+						"from": "@absolutejs/voice",
+						"names": [
+							"createVoicePostgresSessionStore"
+						]
+					}
+				]
+			}
+		},
+		{
+			"contract": "voice/session-store",
+			"factory": "createVoiceFileSessionStore",
+			"from": "@absolutejs/voice",
+			"settings": {
+				"type": "object",
+				"required": [
+					"directory"
+				],
+				"properties": {
+					"directory": {
+						"description": "Folder on this machine where each call session is kept as a JSON file. Created if missing.",
+						"examples": [
+							"./var/voice-sessions"
+						],
+						"title": "Storage folder",
+						"type": "string"
+					}
+				}
+			},
+			"title": "JSON files on this machine",
+			"wiring": {
+				"code": "createVoiceFileSessionStore(${settings})",
+				"imports": [
+					{
+						"from": "@absolutejs/voice",
+						"names": [
+							"createVoiceFileSessionStore"
+						]
+					}
+				]
+			}
+		}
+	],
+	"requires": {
+		"peers": [
+			{
+				"name": "elysia",
+				"range": ">= 1.4.18",
+				"reason": "plugin host"
+			}
+		]
+	},
+	"settings": {
+		"type": "object",
+		"properties": {
+			"backchannelBargeInGuard": {
+				"description": "Keep the assistant talking through listening cues like \"mm-hm\" or \"right\" instead of treating them as interruptions.",
+				"title": "Ignore listening cues",
+				"type": "boolean"
+			},
+			"greeting": {
+				"description": "Spoken by the assistant the moment a call connects, before the caller says anything.",
+				"examples": [
+					"Hi! How can I help you today?"
+				],
+				"title": "Opening greeting",
+				"type": "string"
+			},
+			"normalizeNumbers": {
+				"description": "Rewrite spoken numbers to digits in transcripts (\"ten million\" becomes \"10 million\") so downstream systems read them consistently.",
+				"title": "Write numbers as digits",
+				"type": "boolean"
+			},
+			"path": {
+				"default": "/voice/realtime",
+				"description": "The WebSocket route callers connect to.",
+				"title": "Call route",
+				"type": "string"
+			},
+			"preset": {
+				"description": "Tuned bundle of turn-taking and latency defaults for the kind of calls you take — casual chat, guided intake, dictation, noisy rooms, or phone lines.",
+				"title": "Conversation preset",
+				"anyOf": [
+					{
+						"const": "default",
+						"type": "string"
+					},
+					{
+						"const": "chat",
+						"type": "string"
+					},
+					{
+						"const": "guided-intake",
+						"type": "string"
+					},
+					{
+						"const": "dictation",
+						"type": "string"
+					},
+					{
+						"const": "noisy-room",
+						"type": "string"
+					},
+					{
+						"const": "pstn-balanced",
+						"type": "string"
+					},
+					{
+						"const": "pstn-fast",
+						"type": "string"
+					},
+					{
+						"const": "reliability",
+						"type": "string"
+					}
+				]
+			},
+			"resumeGreeting": {
+				"description": "Spoken when a dropped call reconnects, so the caller knows they are back.",
+				"examples": [
+					"Sorry, we got cut off — where were we?"
+				],
+				"title": "Reconnect greeting",
+				"type": "string"
+			}
+		}
+	},
+	"slots": {
+		"realtime": {
+			"configPath": "realtime",
+			"contract": "voice/realtime",
+			"description": "One speech-to-speech model that listens and talks in a single stream — an alternative to picking separate speech-to-text and text-to-speech services.",
+			"known": [
+				"@absolutejs/voice-openai",
+				"@absolutejs/voice-gemini"
+			]
+		},
+		"session": {
+			"configPath": "session",
+			"contract": "voice/session-store",
+			"description": "Where each call's transcript and state is kept while it runs (and after, for review)",
+			"known": [
+				"@absolutejs/voice#memory",
+				"@absolutejs/voice#sqlite",
+				"@absolutejs/voice#postgres",
+				"@absolutejs/voice#file"
+			],
+			"required": true
+		},
+		"stt": {
+			"configPath": "stt",
+			"contract": "voice/stt",
+			"description": "The service that turns the caller's speech into text. Not needed when a speech-to-speech (realtime) adapter is chosen instead.",
+			"known": [
+				"@absolutejs/voice-deepgram",
+				"@absolutejs/voice-assemblyai",
+				"@absolutejs/voice-gladia",
+				"@absolutejs/voice-soniox",
+				"@absolutejs/voice-speechmatics",
+				"@absolutejs/voice-azure",
+				"@absolutejs/voice-google-speech",
+				"@absolutejs/voice-openai-whisper"
+			]
+		},
+		"tts": {
+			"configPath": "tts",
+			"contract": "voice/tts",
+			"description": "The service that speaks the assistant's replies out loud. Not needed when a speech-to-speech (realtime) adapter is chosen instead.",
+			"known": [
+				"@absolutejs/voice-elevenlabs",
+				"@absolutejs/voice-cartesia",
+				"@absolutejs/voice-azure",
+				"@absolutejs/voice-lmnt",
+				"@absolutejs/voice-playht",
+				"@absolutejs/voice-rime",
+				"@absolutejs/voice-smallest",
+				"@absolutejs/voice-neets"
+			]
+		}
+	},
+	"wiring": [
+		{
+			"description": "Pick a speech-to-text and a text-to-speech service, choose where call sessions are stored, and write the onTurn handler — the assistant's brain.",
+			"id": "default",
+			"server": {
+				"code": "// Every call's transcript and state lives in the session store.\nconst voiceSessions = ${slot.session};\n\n// Mount with .use(voiceAssistant); callers connect over WebSocket at `path`.\nconst voiceAssistant = voice({\n\tonTurn: async (session, turn) => {\n\t\t// TODO: generate the assistant's reply (call your LLM here).\n\t\treturn { assistantText: \"You said: \" + turn.text };\n\t},\n\tsession: voiceSessions,\n\tstt: ${slot.stt},\n\ttts: ${slot.tts},\n\t...${settings}\n});",
+				"imports": [
+					{
+						"from": "@absolutejs/voice",
+						"names": [
+							"voice"
+						]
+					}
+				],
+				"placement": "module-scope"
+			},
+			"title": "Voice assistant with separate STT + TTS"
+		},
+		{
+			"description": "Use one speech-to-speech model (OpenAI Realtime, Gemini Live) that listens and talks in a single stream instead of separate STT and TTS services.",
+			"id": "realtime",
+			"server": {
+				"code": "// Every call's transcript and state lives in the session store.\nconst voiceSessions = ${slot.session};\n\n// Mount with .use(voiceAssistant); callers connect over WebSocket at `path`.\nconst voiceAssistant = voice({\n\tonTurn: async (session, turn) => {\n\t\t// TODO: generate the assistant's reply (call your LLM here).\n\t\treturn { assistantText: \"You said: \" + turn.text };\n\t},\n\trealtime: ${slot.realtime},\n\tsession: voiceSessions,\n\t...${settings}\n});",
+				"imports": [
+					{
+						"from": "@absolutejs/voice",
+						"names": [
+							"voice"
+						]
+					}
+				],
+				"placement": "module-scope"
+			},
+			"title": "Voice assistant with a speech-to-speech model"
+		}
+	],
+	"tools": {
+		"delete_session": {
+			"annotations": {
+				"destructiveHint": true,
+				"idempotentHint": true
+			},
+			"description": "Delete one call session (its transcript and state) by id. Deleting an unknown id succeeds.",
+			"input": {
+				"type": "object",
+				"required": [
+					"id"
+				],
+				"properties": {
+					"id": {
+						"minLength": 1,
+						"type": "string"
+					}
+				}
+			},
+			"kind": "runtime"
+		},
+		"get_session": {
+			"annotations": {
+				"readOnlyHint": true
+			},
+			"description": "Fetch one call session by id: status, timing, and the committed conversation turns (caller text and assistant reply), most recent last.",
+			"input": {
+				"type": "object",
+				"required": [
+					"id"
+				],
+				"properties": {
+					"id": {
+						"minLength": 1,
+						"type": "string"
+					},
+					"maxTurns": {
+						"maximum": 200,
+						"minimum": 1,
+						"type": "integer"
+					}
+				}
+			},
+			"kind": "runtime"
+		},
+		"list_sessions": {
+			"annotations": {
+				"readOnlyHint": true
+			},
+			"description": "List call sessions with status, creation time, last activity, and turn count — most recently active first.",
+			"input": {
+				"type": "object",
+				"properties": {
+					"limit": {
+						"maximum": 200,
+						"minimum": 1,
+						"type": "integer"
+					}
+				}
+			},
+			"kind": "runtime"
+		}
+	}
+}

package/dist/testing/index.js

@@ -6751,6 +6751,9 @@ var createVoiceSession = (options) => {
     if (callSilenceTimeoutMs === undefined || callSilenceFired) {
       return;
     }
+    if (callerPaused) {
+      return;
+    }
     clearCallSilenceWatchdog();
     callSilenceWatchdog = setTimeout(fireCallSilenceTimeout, callSilenceTimeoutMs);
   };
@@ -6796,6 +6799,9 @@ var createVoiceSession = (options) => {
     if (stuckCloseAfterMs === undefined || stuckCloseFired) {
       return;
     }
+    if (callerPaused) {
+      return;
+    }
     clearStuckCloseWatchdog();
     stuckCloseWatchdog = setTimeout(fireStuckClose, stuckCloseAfterMs);
   };
@@ -6818,6 +6824,9 @@ var createVoiceSession = (options) => {
       idleRepromptsUsed = 0;
     }
     clearIdleRepromptWatchdog();
+    if (callerPaused) {
+      return;
+    }
     if (idleRepromptsUsed >= idleRepromptMax) {
       return;
     }
@@ -6838,6 +6847,60 @@ var createVoiceSession = (options) => {
       });
     }, idleRepromptAfterMs);
   };
+  const PAUSE_MAX_MS_DEFAULT = 600000;
+  const pauseMaxMs = options.pause?.maxMs && options.pause.maxMs > 0 ? options.pause.maxMs : PAUSE_MAX_MS_DEFAULT;
+  let callerPaused = false;
+  let pauseTimeout = null;
+  const clearPauseTimeout = () => {
+    if (pauseTimeout) {
+      clearTimeout(pauseTimeout);
+      pauseTimeout = null;
+    }
+  };
+  const pauseInternal = async () => {
+    if (callerPaused) {
+      return;
+    }
+    const snapshot = await readSession();
+    if (snapshot.status === "completed" || snapshot.status === "failed" || snapshot.call?.endedAt) {
+      return;
+    }
+    callerPaused = true;
+    clearCallSilenceWatchdog();
+    clearStuckCloseWatchdog();
+    clearIdleRepromptWatchdog();
+    clearPauseTimeout();
+    pauseTimeout = setTimeout(() => {
+      pauseTimeout = null;
+      api.close("pause-timeout");
+    }, pauseMaxMs);
+    await appendTrace({
+      payload: {
+        action: "call.paused",
+        maxMs: pauseMaxMs
+      },
+      session: snapshot,
+      type: "call.lifecycle"
+    });
+  };
+  const resumeInternal = async () => {
+    if (!callerPaused) {
+      return;
+    }
+    callerPaused = false;
+    clearPauseTimeout();
+    kickCallSilenceWatchdog();
+    kickStuckCloseWatchdog();
+    kickIdleRepromptWatchdog(true);
+    const snapshot = await readSession();
+    await appendTrace({
+      payload: {
+        action: "call.resumed"
+      },
+      session: snapshot,
+      type: "call.lifecycle"
+    });
+  };
   const recordingConfig = options.recording;
   const recordingChannels = new Set(recordingConfig?.channels ?? ["assistant", "user"]);
   const recordingMaxBytes = recordingConfig?.maxBytesPerChannel ?? 50 * 1024 * 1024;
@@ -7345,6 +7408,7 @@ var createVoiceSession = (options) => {
     clearCallSilenceWatchdog();
     clearStuckCloseWatchdog();
     clearIdleRepromptWatchdog();
+    clearPauseTimeout();
     clearAmdEvaluationTimer();
     await closeTTSSession("failed");
     await closeAdapter("failed");
@@ -7456,6 +7520,7 @@ var createVoiceSession = (options) => {
     clearCallSilenceWatchdog();
     clearStuckCloseWatchdog();
     clearIdleRepromptWatchdog();
+    clearPauseTimeout();
     clearAmdEvaluationTimer();
     await closeTTSSession("complete");
     await closeAdapter("complete");
@@ -8416,6 +8481,19 @@ var createVoiceSession = (options) => {
     }
     kickStuckCloseWatchdog();
     kickIdleRepromptWatchdog(true);
+    if (callerPaused) {
+      await appendTrace({
+        payload: {
+          action: "turn.skipped",
+          reason: "caller-paused",
+          status: "skipped"
+        },
+        session,
+        turnId: turn.id,
+        type: "call.lifecycle"
+      });
+      return;
+    }
     const liveOpsControl = await options.liveOps?.getControl(options.id);
     if (liveOpsControl?.assistantPaused || liveOpsControl?.operatorTakeover) {
       await appendTrace({
@@ -9266,6 +9344,7 @@ var createVoiceSession = (options) => {
     clearCallSilenceWatchdog();
     clearStuckCloseWatchdog();
     clearIdleRepromptWatchdog();
+    clearPauseTimeout();
     clearAmdEvaluationTimer();
     if (options.noiseSuppressor?.close) {
       try {
@@ -9331,9 +9410,15 @@ var createVoiceSession = (options) => {
     markVoicemail: async (input) => runSerial("api.markVoicemail", async () => {
       await markVoicemailInternal(input);
     }),
+    pause: async () => runSerial("api.pause", async () => {
+      await pauseInternal();
+    }),
     receiveAudio: async (audio) => runSerial("api.receiveAudio", async () => {
       await receiveAudioInternal(audio);
     }),
+    resume: async () => runSerial("api.resume", async () => {
+      await resumeInternal();
+    }),
     snapshot: async () => runSerial("api.snapshot", async () => readSession()),
     transfer: async (input) => runSerial("api.transfer", async () => {
       await transferInternal(input);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@absolutejs/voice",
-  "version": "0.0.22-beta.631",
+  "version": "0.0.22-beta.633",
   "description": "Voice primitives and Elysia plugin for AbsoluteJS",
   "repository": {
     "type": "git",
@@ -19,7 +19,7 @@
   "license": "BSL-1.1",
   "author": "Alex Kahn",
   "scripts": {
-    "build": "rm -rf dist && bun build ./src/index.ts ./src/client/index.ts ./src/react/index.ts ./src/vue/index.ts ./src/svelte/index.ts ./src/angular/index.ts ./src/testing/index.ts ./src/drizzle/index.ts --outdir dist --target bun --external elysia --external react --external vue --external @angular/core --external @absolutejs/absolute --external @absolutejs/ai --external @absolutejs/media --external drizzle-orm && bun build ./src/client/htmxBootstrap.ts --outdir dist/client --target browser --format esm && bun build ./src/embed/index.ts --outfile dist/embed/voice-widget.js --target browser --format iife --minify && bun build ./src/embed/index.ts --outdir dist/embed --target browser --format esm && tsc --emitDeclarationOnly --project tsconfig.json",
+    "build": "rm -rf dist && bun build ./src/index.ts ./src/manifest.ts ./src/client/index.ts ./src/react/index.ts ./src/vue/index.ts ./src/svelte/index.ts ./src/angular/index.ts ./src/testing/index.ts ./src/drizzle/index.ts --outdir dist --root ./src --target bun --external elysia --external react --external vue --external @angular/core --external @absolutejs/absolute --external @absolutejs/ai --external @absolutejs/media --external drizzle-orm && bun build ./src/client/htmxBootstrap.ts --outdir dist/client --target browser --format esm && bun build ./src/embed/index.ts --outfile dist/embed/voice-widget.js --target browser --format iife --minify && bun build ./src/embed/index.ts --outdir dist/embed --target browser --format esm && tsc --emitDeclarationOnly --project tsconfig.json && absolute-manifest emit",
     "config": "absolute config",
     "format": "absolute prettier --write",
     "knip": "knip",
@@ -75,7 +75,12 @@
       "import": "./dist/embed/index.js",
       "types": "./dist/embed/index.d.ts"
     },
-    "./embed/voice-widget.js": "./dist/embed/voice-widget.js"
+    "./embed/voice-widget.js": "./dist/embed/voice-widget.js",
+    "./manifest": {
+      "import": "./dist/manifest.js",
+      "types": "./dist/manifest.d.ts"
+    },
+    "./manifest.json": "./dist/manifest.json"
   },
   "typesVersions": {
     "*": {
@@ -102,6 +107,9 @@
       ],
       "embed": [
         "dist/embed/index.d.ts"
+      ],
+      "manifest": [
+        "dist/manifest.d.ts"
       ]
     }
   },
@@ -132,7 +140,9 @@
     }
   },
   "dependencies": {
-    "@absolutejs/media": "0.0.1-beta.19"
+    "@absolutejs/manifest": "^0.1.0",
+    "@absolutejs/media": "0.0.1-beta.19",
+    "@sinclair/typebox": "^0.34.0"
   },
   "devDependencies": {
     "@absolutejs/absolute": "0.19.0-beta.1009",
@@ -157,5 +167,8 @@
     "typescript": "^5.9.3",
     "typescript-eslint": "^8.57.2",
     "vue": "3.5.27"
+  },
+  "absolutejs": {
+    "manifestContract": 1
   }
 }