@absolutejs/voice 0.0.22-beta.67 → 0.0.22-beta.670

package/dist/internal/evidence.d.ts

@@ -0,0 +1,10 @@
+export type VoiceEvidenceAssertion = {
+    ok: boolean;
+    issues: string[];
+};
+/**
+ * Throw if an evidence assertion failed, formatting its issues into the error
+ * message. Returns the assertion unchanged when it passed, so callers can
+ * `return assertVoiceEvidence(label, evaluate(...))`.
+ */
+export declare const assertVoiceEvidence: <A extends VoiceEvidenceAssertion>(failureMessage: string, assertion: A) => A;

package/dist/internal/html.d.ts

@@ -0,0 +1,6 @@
+/**
+ * Escape a value for safe interpolation into HTML text/attributes. Accepts any
+ * value (non-strings are stringified) and escapes the five HTML-significant
+ * characters.
+ */
+export declare const escapeHtml: (value: unknown) => string;

package/dist/internal/status.d.ts

@@ -0,0 +1,7 @@
+/**
+ * The shared three-level health status used across voice reports. Severity
+ * order is fail > warn > pass.
+ */
+export type VoiceStatus = "fail" | "pass" | "warn";
+/** Reduce a set of statuses to the worst one (fail > warn > pass). */
+export declare const worstVoiceStatus: (statuses: Iterable<VoiceStatus>) => VoiceStatus;

package/dist/manifest.d.ts

@@ -0,0 +1,17 @@
+import type { VoicePluginConfig, VoiceSessionStore } from "./core/types";
+export declare const manifest: Omit<import("@absolutejs/manifest").PackageManifest<VoicePluginConfig, VoiceSessionStore>, "tools" | "contract" | "settings"> & (({
+    contract: 1;
+    tools?: Record<string, import("@absolutejs/manifest").LegacyManifestTool<VoiceSessionStore>> | undefined;
+} | {
+    contract: 2;
+    tools?: Record<string, import("@absolutejs/manifest").AuthorizedManifestTool<VoiceSessionStore>> | undefined;
+}) & {
+    settings: import("@sinclair/typebox").TObject<{
+        backchannelBargeInGuard: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TBoolean>;
+        greeting: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TString>;
+        normalizeNumbers: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TBoolean>;
+        path: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TString>;
+        preset: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TUnion<[import("@sinclair/typebox").TLiteral<"default">, import("@sinclair/typebox").TLiteral<"chat">, import("@sinclair/typebox").TLiteral<"guided-intake">, import("@sinclair/typebox").TLiteral<"dictation">, import("@sinclair/typebox").TLiteral<"noisy-room">, import("@sinclair/typebox").TLiteral<"pstn-balanced">, import("@sinclair/typebox").TLiteral<"pstn-fast">, import("@sinclair/typebox").TLiteral<"reliability">]>>;
+        resumeGreeting: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TString>;
+    }>;
+});

package/dist/manifest.js

@@ -0,0 +1,424 @@
+// @bun
+var __create = Object.create;
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __name = (target, name) => {
+  Object.defineProperty(target, "name", {
+    value: name,
+    enumerable: false,
+    configurable: true
+  });
+  return target;
+};
+var __returnValue = (v) => v;
+function __exportSetter(name, newValue) {
+  this[name] = __returnValue.bind(null, newValue);
+}
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, {
+      get: all[name],
+      enumerable: true,
+      configurable: true,
+      set: __exportSetter.bind(all, name)
+    });
+};
+var __knownSymbol = (name, symbol) => (symbol = Symbol[name]) ? symbol : Symbol.for("Symbol." + name);
+var __typeError = (msg) => {
+  throw TypeError(msg);
+};
+var __defNormalProp = (obj, key, value) => (key in obj) ? __defProp(obj, key, { enumerable: true, configurable: true, writable: true, value }) : obj[key] = value;
+var __accessCheck = (obj, member, msg) => member.has(obj) || __typeError("Cannot " + msg);
+var __privateIn = (member, obj) => Object(obj) !== obj ? __typeError('Cannot use the "in" operator on this value') : member.has(obj);
+var __privateGet = (obj, member, getter) => (__accessCheck(obj, member, "read from private field"), getter ? getter.call(obj) : member.get(obj));
+var __privateSet = (obj, member, value, setter) => (__accessCheck(obj, member, "write to private field"), setter ? setter.call(obj, value) : member.set(obj, value), value);
+var __privateMethod = (obj, member, method) => (__accessCheck(obj, member, "access private method"), method);
+var __decoratorStart = (base) => [, , , __create(base?.[__knownSymbol("metadata")] ?? null)];
+var __decoratorStrings = ["class", "method", "getter", "setter", "accessor", "field", "value", "get", "set"];
+var __expectFn = (fn) => fn !== undefined && typeof fn !== "function" ? __typeError("Function expected") : fn;
+var __decoratorContext = (kind, name, done, metadata, fns) => ({
+  kind: __decoratorStrings[kind],
+  name,
+  metadata,
+  addInitializer: (fn) => done._ ? __typeError("Already initialized") : fns.push(__expectFn(fn || null))
+});
+var __decoratorMetadata = (array, target) => __defNormalProp(target, __knownSymbol("metadata"), array[3]);
+var __runInitializers = (array, flags, self, value) => {
+  for (var i = 0, fns = array[flags >> 1], n = fns && fns.length;i < n; i++)
+    flags & 1 ? fns[i].call(self) : value = fns[i].call(self, value);
+  return value;
+};
+var __decorateElement = (array, flags, name, decorators, target, extra) => {
+  var fn, it, done, ctx, access, k = flags & 7, s = !!(flags & 8), p = !!(flags & 16);
+  var j = k > 3 ? array.length + 1 : k ? s ? 1 : 2 : 0, key = __decoratorStrings[k + 5];
+  var initializers = k > 3 && (array[j - 1] = []), extraInitializers = array[j] || (array[j] = []);
+  var desc = k && (!p && !s && (target = target.prototype), k < 5 && (k > 3 || !p) && __getOwnPropDesc(k < 4 ? target : {
+    get [name]() {
+      return __privateGet(this, extra);
+    },
+    set [name](x) {
+      __privateSet(this, extra, x);
+    }
+  }, name));
+  k ? p && k < 4 && __name(extra, (k > 2 ? "set " : k > 1 ? "get " : "") + name) : __name(target, name);
+  for (var i = decorators.length - 1;i >= 0; i--) {
+    ctx = __decoratorContext(k, name, done = {}, array[3], extraInitializers);
+    if (k) {
+      ctx.static = s, ctx.private = p, access = ctx.access = { has: p ? (x) => __privateIn(target, x) : (x) => (name in x) };
+      if (k ^ 3)
+        access.get = p ? (x) => (k ^ 1 ? __privateGet : __privateMethod)(x, target, k ^ 4 ? extra : desc.get) : (x) => x[name];
+      if (k > 2)
+        access.set = p ? (x, y) => __privateSet(x, target, y, k ^ 4 ? extra : desc.set) : (x, y) => x[name] = y;
+    }
+    it = (0, decorators[i])(k ? k < 4 ? p ? extra : desc[key] : k > 4 ? undefined : { get: desc.get, set: desc.set } : target, ctx);
+    done._ = 1;
+    if (k ^ 4 || it === undefined)
+      __expectFn(it) && (k > 4 ? initializers.unshift(it) : k ? p ? extra = it : desc[key] = it : target = it);
+    else if (typeof it !== "object" || it === null)
+      __typeError("Object expected");
+    else
+      __expectFn(fn = it.get) && (desc.get = fn), __expectFn(fn = it.set) && (desc.set = fn), __expectFn(fn = it.init) && initializers.unshift(fn);
+  }
+  return k || __decoratorMetadata(array, target), desc && __defProp(target, name, desc), p ? k ^ 4 ? extra : desc : target;
+};
+var __require = import.meta.require;
+
+// src/manifest.ts
+import {
+  defineImplementation,
+  defineManifest,
+  toolFactory
+} from "@absolutejs/manifest";
+import { Type } from "@sinclair/typebox";
+var tool = toolFactory();
+var MAX_LIST_LIMIT = 200;
+var MAX_TRANSCRIPT_TURNS = 20;
+var manifest = defineManifest()({
+  contract: 2,
+  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 \u2014 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: [
+    defineImplementation()({
+      contract: "voice/session-store",
+      factory: "createVoiceMemoryStore",
+      from: "@absolutejs/voice",
+      title: "In memory (development only \u2014 calls are forgotten on restart)",
+      wiring: {
+        code: "createVoiceMemoryStore()",
+        imports: [
+          { from: "@absolutejs/voice", names: ["createVoiceMemoryStore"] }
+        ]
+      }
+    }),
+    defineImplementation()({
+      contract: "voice/session-store",
+      factory: "createVoiceSQLiteSessionStore",
+      from: "@absolutejs/voice",
+      settings: Type.Object({
+        path: Type.String({
+          description: "Database file on this machine where call sessions are kept. Created if missing.",
+          examples: ["./var/voice-sessions.sqlite"],
+          title: "Database file"
+        }),
+        tableName: Type.Optional(Type.String({
+          description: "Table the sessions are stored in.",
+          title: "Table name"
+        }))
+      }),
+      title: "SQLite file on this machine",
+      wiring: {
+        code: "createVoiceSQLiteSessionStore(${settings})",
+        imports: [
+          {
+            from: "@absolutejs/voice",
+            names: ["createVoiceSQLiteSessionStore"]
+          }
+        ]
+      }
+    }),
+    defineImplementation()({
+      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({
+        schemaName: Type.Optional(Type.String({
+          description: "Postgres schema the table lives in.",
+          title: "Schema name"
+        })),
+        tableName: Type.Optional(Type.String({
+          description: "Table the sessions are stored in.",
+          title: "Table name"
+        }))
+      }),
+      title: "Postgres",
+      wiring: {
+        code: 'createVoicePostgresSessionStore({ connectionString: ${env.DATABASE_URL} ?? "", ...${settings} })',
+        imports: [
+          {
+            from: "@absolutejs/voice",
+            names: ["createVoicePostgresSessionStore"]
+          }
+        ]
+      }
+    }),
+    defineImplementation()({
+      contract: "voice/session-store",
+      factory: "createVoiceFileSessionStore",
+      from: "@absolutejs/voice",
+      settings: Type.Object({
+        directory: Type.String({
+          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"
+        })
+      }),
+      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({
+    backchannelBargeInGuard: Type.Optional(Type.Boolean({
+      description: 'Keep the assistant talking through listening cues like "mm-hm" or "right" instead of treating them as interruptions.',
+      title: "Ignore listening cues"
+    })),
+    greeting: Type.Optional(Type.String({
+      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"
+    })),
+    normalizeNumbers: Type.Optional(Type.Boolean({
+      description: 'Rewrite spoken numbers to digits in transcripts ("ten million" becomes "10 million") so downstream systems read them consistently.',
+      title: "Write numbers as digits"
+    })),
+    path: Type.Optional(Type.String({
+      default: "/voice/realtime",
+      description: "The WebSocket route callers connect to.",
+      title: "Call route"
+    })),
+    preset: Type.Optional(Type.Union([
+      Type.Literal("default"),
+      Type.Literal("chat"),
+      Type.Literal("guided-intake"),
+      Type.Literal("dictation"),
+      Type.Literal("noisy-room"),
+      Type.Literal("pstn-balanced"),
+      Type.Literal("pstn-fast"),
+      Type.Literal("reliability")
+    ], {
+      description: "Tuned bundle of turn-taking and latency defaults for the kind of calls you take \u2014 casual chat, guided intake, dictation, noisy rooms, or phone lines.",
+      title: "Conversation preset"
+    })),
+    resumeGreeting: Type.Optional(Type.String({
+      description: "Spoken when a dropped call reconnects, so the caller knows they are back.",
+      examples: ["Sorry, we got cut off \u2014 where were we?"],
+      title: "Reconnect greeting"
+    }))
+  }),
+  slots: {
+    realtime: {
+      configPath: "realtime",
+      contract: "voice/realtime",
+      description: "One speech-to-speech model that listens and talks in a single stream \u2014 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"
+      ]
+    }
+  },
+  tools: {
+    delete_session: tool.runtime({
+      annotations: { destructiveHint: true, idempotentHint: true },
+      authorization: {
+        approval: "policy",
+        audience: "owner",
+        effects: ["delete"],
+        idempotency: { mode: "resource" },
+        requiredScopes: ["voice:sessions:delete"],
+        resource: { idField: "id", type: "voice-session" },
+        reversible: false
+      },
+      description: "Delete one call session (its transcript and state) by id. Deleting an unknown id succeeds.",
+      input: Type.Object({ id: Type.String({ minLength: 1 }) }),
+      handler: async ({ id }, store) => {
+        await store.remove(id);
+        return `deleted session ${id}`;
+      }
+    }),
+    get_session: tool.runtime({
+      annotations: { readOnlyHint: true },
+      authorization: {
+        approval: "never",
+        audience: "owner",
+        effects: ["read"],
+        requiredScopes: ["voice:sessions:read"],
+        resource: { idField: "id", type: "voice-session" }
+      },
+      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({
+        id: Type.String({ minLength: 1 }),
+        maxTurns: Type.Optional(Type.Integer({ maximum: MAX_LIST_LIMIT, minimum: 1 }))
+      }),
+      handler: async ({ id, maxTurns }, store) => {
+        const session = await store.get(id);
+        if (session === undefined)
+          return `no session with id ${id}`;
+        const limit = maxTurns ?? MAX_TRANSCRIPT_TURNS;
+        return JSON.stringify({
+          createdAt: session.createdAt,
+          disposition: session.call?.disposition,
+          id: session.id,
+          lastActivityAt: session.lastActivityAt,
+          status: session.status,
+          turnCount: session.turns.length,
+          turns: session.turns.slice(-limit).map((turn) => ({
+            assistantText: turn.assistantText,
+            committedAt: turn.committedAt,
+            userText: turn.text
+          }))
+        });
+      }
+    }),
+    list_sessions: tool.runtime({
+      annotations: { readOnlyHint: true },
+      authorization: {
+        approval: "never",
+        audience: "owner",
+        effects: ["read"],
+        requiredScopes: ["voice:sessions:read"]
+      },
+      description: "List call sessions with status, creation time, last activity, and turn count \u2014 most recently active first.",
+      input: Type.Object({
+        limit: Type.Optional(Type.Integer({ maximum: MAX_LIST_LIMIT, minimum: 1 }))
+      }),
+      handler: async ({ limit }, store) => {
+        const sessions = await store.list();
+        return JSON.stringify(sessions.slice(0, limit ?? MAX_LIST_LIMIT));
+      }
+    })
+  },
+  wiring: [
+    {
+      description: "Pick a speech-to-text and a text-to-speech service, choose where call sessions are stored, and write the onTurn handler \u2014 the assistant's brain.",
+      id: "default",
+      server: {
+        code: [
+          "// Every call's transcript and state lives in the session store.",
+          "const voiceSessions = ${slot.session};",
+          "",
+          "// Mount with .use(voiceAssistant); callers connect over WebSocket at `path`.",
+          "const voiceAssistant = voice({",
+          "\tonTurn: async (session, turn) => {",
+          "\t\t// TODO: generate the assistant's reply (call your LLM here).",
+          '\t\treturn { assistantText: "You said: " + turn.text };',
+          "\t},",
+          "\tsession: voiceSessions,",
+          "\tstt: ${slot.stt},",
+          "\ttts: ${slot.tts},",
+          "\t...${settings}",
+          "});"
+        ].join(`
+`),
+        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.",
+          "const voiceSessions = ${slot.session};",
+          "",
+          "// Mount with .use(voiceAssistant); callers connect over WebSocket at `path`.",
+          "const voiceAssistant = voice({",
+          "\tonTurn: async (session, turn) => {",
+          "\t\t// TODO: generate the assistant's reply (call your LLM here).",
+          '\t\treturn { assistantText: "You said: " + turn.text };',
+          "\t},",
+          "\trealtime: ${slot.realtime},",
+          "\tsession: voiceSessions,",
+          "\t...${settings}",
+          "});"
+        ].join(`
+`),
+        imports: [{ from: "@absolutejs/voice", names: ["voice"] }],
+        placement: "module-scope"
+      },
+      title: "Voice assistant with a speech-to-speech model"
+    }
+  ]
+});
+export {
+  manifest
+};