@inkibra/voice-sdk 0.1.0

package/dist/public.d.ts

@@ -0,0 +1,109 @@
+export type LiveVoiceTool<TInput extends Record<string, unknown> = Record<string, unknown>, TResult = unknown> = {
+    description: string;
+    parameters: Record<string, unknown>;
+    execute(input: TInput): TResult | Promise<TResult>;
+};
+export type LiveVoiceTools = Record<string, LiveVoiceTool>;
+export type LiveVoicePlatformVoice = "eve" | "ara" | "rex" | "sal" | "leo";
+export type LiveVoiceConversationOptions = {
+    /** Instructions for the rhythm and social behavior of the conversation. */
+    prompt?: string;
+    /** Selects which participant opens the session. Defaults to the user. */
+    starts?: "user" | "assistant";
+    phases?: {
+        /** The phase active when the session begins. */
+        initial: string;
+        /** Instructions governing when the agent should move between phases. */
+        prompt?: string;
+        /** Developer-defined phases and the behavior appropriate to each one. */
+        definitions: Record<string, string>;
+    };
+};
+export type LiveVoiceConnectOptions = {
+    token: string;
+    /** Task, domain, persona, and tool-use instructions for the agent. */
+    prompt?: string;
+    /** Provider-neutral control over conversational behavior and phases. */
+    conversation?: LiveVoiceConversationOptions;
+    tools?: LiveVoiceTools;
+    endpoint?: string;
+};
+export type LiveVoiceCanonicalTurn = {
+    id: string;
+    role: "user" | "assistant";
+    text: string;
+    truncated?: boolean;
+};
+export type LiveVoiceConnectionState = "connecting" | "live" | "closed" | "error";
+export type LiveVoiceFloorState = {
+    owner: "USER" | "ASSISTANT";
+    assistantAudible: boolean;
+};
+export type LiveVoiceToolCall = {
+    callId: string;
+    name: string;
+    input: Record<string, unknown>;
+};
+export type LiveVoicePhaseEvent = {
+    phase: string;
+    previousPhase?: string;
+    source: "initial" | "floor";
+};
+export type LiveVoiceEventMap = {
+    "connection": {
+        state: LiveVoiceConnectionState;
+        detail?: string;
+    };
+    "transcript.instantaneous": {
+        text: string;
+    };
+    "transcript.canonical": {
+        turns: LiveVoiceCanonicalTurn[];
+    };
+    "floor": LiveVoiceFloorState;
+    "phase": LiveVoicePhaseEvent;
+    "quick-reaction": {
+        reaction: string;
+        status: "prepared" | "playing" | "completed" | "cancelled";
+    };
+    "tool.call": LiveVoiceToolCall;
+    "tool.result": LiveVoiceToolCall & {
+        ok: boolean;
+        output?: unknown;
+        error?: string;
+    };
+    "limit": {
+        reason: string;
+        durationSeconds?: number;
+    };
+    "error": {
+        code: string;
+        message: string;
+    };
+};
+type EventName = keyof LiveVoiceEventMap;
+type EventHandler<K extends EventName> = (event: LiveVoiceEventMap[K]) => void;
+export declare class LiveVoiceSession {
+    private client;
+    private tools;
+    private listeners;
+    private previousPartial;
+    private previousCanonical;
+    private previousFloor;
+    private reactionStates;
+    private currentPhase?;
+    private constructor();
+    static connect(options: LiveVoiceConnectOptions): Promise<LiveVoiceSession>;
+    on<K extends EventName>(event: K, handler: EventHandler<K>): () => void;
+    get phase(): string | undefined;
+    stop(): void;
+    dispose(): void;
+    private emit;
+    private acceptApplicationEvent;
+    private acceptState;
+    private executeTool;
+}
+export default class LiveVoice {
+    static connect(options: LiveVoiceConnectOptions): Promise<LiveVoiceSession>;
+}
+export {};

package/dist/server.d.ts

@@ -0,0 +1,120 @@
+import type { LiveVoiceConversationOptions, LiveVoiceEventMap, LiveVoicePlatformVoice, LiveVoiceTools } from "./public";
+export type { LiveVoiceCanonicalTurn, LiveVoiceConversationOptions, LiveVoiceEventMap, LiveVoiceFloorState, LiveVoicePhaseEvent, LiveVoicePlatformVoice, LiveVoiceTool, LiveVoiceToolCall, LiveVoiceTools, } from "./public";
+export type LiveVoicePcmFormat = {
+    encoding: "pcm_s16le";
+    sampleRate: 24_000;
+    channels: 1;
+};
+export declare const liveVoicePcmFormat: LiveVoicePcmFormat;
+export type LiveVoiceAudioOutputCommand = 
+/** Append PCM in arrival order. `buffer` is inaudible until release; `play` is immediately eligible for playback. */
+{
+    type: "enqueue";
+    generationId: string;
+    lane: "FOREGROUND" | "REACTION";
+    pcm: Uint8Array;
+    mode: "buffer" | "play";
+    gain: number;
+}
+/** Prevent this foreground generation from becoming audible while its speculative audio arrives. */
+ | {
+    type: "block-foreground";
+    generationId: string;
+}
+/** Make the buffered generation eligible for playback at the supplied gain. */
+ | {
+    type: "release";
+    generationId: string;
+    gain: number;
+}
+/** Stop this generation and discard all of its queued PCM. */
+ | {
+    type: "cancel";
+    generationId: string;
+}
+/** No more PCM will arrive for this generation; completion still waits for the playback queue to drain. */
+ | {
+    type: "done";
+    generationId: string;
+    lane: "FOREGROUND" | "REACTION";
+};
+export type LiveVoicePlaybackReceipt = {
+    event: "started" | "completed" | "cancelled";
+    lane: "FOREGROUND" | "REACTION";
+    generationId: string;
+    /** Samples actually played, expressed at the native 24 kHz format. */
+    playedSamples: number;
+};
+export type LiveVoiceAudioTransportHandlers = {
+    /** Supply mono PCM16LE at 24 kHz. Frame boundaries do not imply conversational boundaries. */
+    input(pcm: Uint8Array): void;
+    /** Report the first audible sample and exactly one terminal outcome for each audible generation. */
+    receipt(receipt: LiveVoicePlaybackReceipt): void;
+    /** End the Live Voice session because the caller-side transport closed. */
+    close(reason?: string): void;
+    error(error: Error): void;
+};
+export interface LiveVoiceAudioTransport {
+    /** SDK-facing format after any provider-specific decoding or resampling performed by the adapter. */
+    readonly format: LiveVoicePcmFormat;
+    /** Attach the session callbacks and make the transport ready to accept output commands. */
+    start(handlers: LiveVoiceAudioTransportHandlers): void | Promise<void>;
+    /** Apply commands in call order; the transport owns only PCM playback, never conversational state. */
+    output(command: LiveVoiceAudioOutputCommand): void | Promise<void>;
+    stop(): void | Promise<void>;
+}
+type LiveVoiceServerAuthorization = {
+    token: string;
+    apiKey?: never;
+} | {
+    apiKey: string;
+    token?: never;
+};
+export type LiveVoiceServerConnectOptions = LiveVoiceServerAuthorization & {
+    audio: LiveVoiceAudioTransport;
+    prompt?: string;
+    conversation?: LiveVoiceConversationOptions;
+    tools?: LiveVoiceTools;
+    /** Built-in voice selected when this SDK creates a session with `apiKey`. */
+    voice?: LiveVoicePlatformVoice;
+    /** Override the Live Voice WebSocket URL. */
+    endpoint?: string;
+    /** Override the HTTP API origin used with apiKey. */
+    apiBaseUrl?: string;
+};
+type EventName = keyof LiveVoiceEventMap;
+type EventHandler<K extends EventName> = (event: LiveVoiceEventMap[K]) => void;
+export declare class LiveVoiceServerSession {
+    private socket;
+    private audio;
+    private tools;
+    readonly closed: Promise<void>;
+    private resolveClosed;
+    private listeners;
+    private previousPartial;
+    private previousCanonical;
+    private previousFloor;
+    private reactionStates;
+    private state?;
+    private stopped;
+    private prepared?;
+    private constructor();
+    static connect(options: LiveVoiceServerConnectOptions): Promise<LiveVoiceServerSession>;
+    on<K extends EventName>(event: K, handler: EventHandler<K>): () => void;
+    get phase(): string | undefined;
+    stop(): void;
+    dispose(): void;
+    private bindSocket;
+    private prepare;
+    private onMessage;
+    private writeInput;
+    private sendReceipt;
+    private executeTool;
+    private acceptState;
+    private acceptApplicationEvent;
+    private emit;
+    private finish;
+}
+export default class LiveVoiceServer {
+    static connect(options: LiveVoiceServerConnectOptions): Promise<LiveVoiceServerSession>;
+}

package/dist/server.js

@@ -0,0 +1,392 @@
+// src/server.ts
+var liveVoicePcmFormat = {
+  encoding: "pcm_s16le",
+  sampleRate: 24000,
+  channels: 1
+};
+var defaultApiBaseUrl = "https://inkibra-voice.inkibra.workers.dev";
+var defaultEndpoint = "wss://inkibra-voice.inkibra.workers.dev/v1/live";
+
+class LiveVoiceServerSession {
+  socket;
+  audio;
+  tools;
+  closed;
+  resolveClosed;
+  listeners = new Map;
+  stopped = false;
+  prepared;
+  started;
+  currentPhase;
+  acceptingInput = false;
+  constructor(socket, audio, tools) {
+    this.socket = socket;
+    this.audio = audio;
+    this.tools = tools;
+    this.closed = new Promise((resolve) => {
+      this.resolveClosed = resolve;
+    });
+  }
+  static async connect(options) {
+    validateAudioFormat(options.audio.format);
+    const credentials = await resolveSessionCredentials(options);
+    const socket = new WebSocket(withSessionToken(`${credentials.endpoint.replace(/\/$/u, "")}/${crypto.randomUUID()}`, credentials.token));
+    const session = new LiveVoiceServerSession(socket, options.audio, options.tools ?? {});
+    session.bindSocket();
+    session.emit("connection", { state: "connecting" });
+    await waitForOpen(socket);
+    try {
+      await session.prepare();
+    } catch (error) {
+      session.finish(error instanceof Error ? error.message : String(error));
+      throw error;
+    }
+    try {
+      await options.audio.start({
+        input: (pcm) => session.writeInput(pcm),
+        receipt: (receipt) => session.sendReceipt(receipt),
+        close: (reason) => session.finish(reason),
+        error: (error) => {
+          session.emit("error", { code: "AUDIO_TRANSPORT_ERROR", message: error.message });
+          session.finish(error.message);
+        }
+      });
+    } catch (error) {
+      session.finish(error instanceof Error ? error.message : String(error));
+      throw error;
+    }
+    const started = new Promise((resolve, reject) => {
+      session.started = { resolve, reject };
+    });
+    socket.send(JSON.stringify({
+      type: "session.start",
+      developer: {
+        prompt: options.prompt ?? "",
+        conversation: options.conversation,
+        tools: Object.entries(options.tools ?? {}).map(([name, tool]) => ({
+          type: "function",
+          name,
+          description: tool.description,
+          parameters: tool.parameters
+        }))
+      }
+    }));
+    try {
+      await started;
+    } catch (error) {
+      session.finish(error instanceof Error ? error.message : String(error));
+      throw error;
+    }
+    session.acceptingInput = true;
+    session.emit("connection", { state: "live" });
+    return session;
+  }
+  on(event, handler) {
+    const handlers = this.listeners.get(event) ?? new Set;
+    handlers.add(handler);
+    this.listeners.set(event, handlers);
+    return () => handlers.delete(handler);
+  }
+  get phase() {
+    return this.currentPhase;
+  }
+  stop() {
+    this.finish("stopped", true);
+  }
+  dispose() {
+    this.stop();
+    this.listeners.clear();
+  }
+  bindSocket() {
+    this.socket.addEventListener("message", (event) => this.onMessage(event.data));
+    this.socket.addEventListener("close", () => this.finish("Live Voice connection closed."));
+    this.socket.addEventListener("error", () => {
+      const error = new Error("Live Voice WebSocket failed.");
+      this.prepared?.reject(error);
+      this.emit("error", { code: "CONNECTION_ERROR", message: error.message });
+      this.finish(error.message);
+    });
+  }
+  prepare() {
+    const promise = new Promise((resolve, reject) => {
+      this.prepared = { resolve, reject };
+    });
+    this.socket.send(JSON.stringify({ type: "session.prepare", protocolVersion: 1 }));
+    return promise;
+  }
+  onMessage(raw) {
+    if (typeof raw !== "string")
+      return;
+    let message;
+    try {
+      message = JSON.parse(raw);
+    } catch {
+      return;
+    }
+    const type = String(message.type ?? "");
+    if (type === "session.prepared") {
+      this.prepared?.resolve();
+      this.prepared = undefined;
+      return;
+    }
+    if (type === "session.prepare_failed") {
+      const error = new Error(String(message.message ?? "Session preparation failed."));
+      this.prepared?.reject(error);
+      this.prepared = undefined;
+      return;
+    }
+    if (type === "session.started") {
+      this.started?.resolve();
+      this.started = undefined;
+      return;
+    }
+    if (type === "public.event") {
+      this.acceptPublicEvent(String(message.name ?? "unknown"), asRecord(message.payload), Number.isFinite(Number(message.atMs)) ? Number(message.atMs) : undefined);
+      return;
+    }
+    if (type === "tool.call") {
+      this.executeTool({
+        callId: String(message.callId ?? ""),
+        name: String(message.name ?? ""),
+        input: asRecord(message.input)
+      });
+      return;
+    }
+    if (type === "session.limit") {
+      this.emit("limit", {
+        reason: String(message.reason ?? "SESSION_LIMIT"),
+        ...Number.isFinite(Number(message.durationSeconds)) ? { durationSeconds: Number(message.durationSeconds) } : {}
+      });
+      return;
+    }
+    if (type === "output.block") {
+      this.audio.output({ type: "block-foreground", generationId: String(message.generationId ?? "") });
+      return;
+    }
+    if (type === "output.audio" && typeof message.delta === "string") {
+      this.audio.output({
+        type: "enqueue",
+        generationId: String(message.generationId ?? ""),
+        lane: message.queue === "reaction" ? "REACTION" : "FOREGROUND",
+        pcm: base64Bytes(message.delta),
+        mode: message.mode === "play" ? "play" : "buffer",
+        gain: clamp01(Number(message.gain ?? 1))
+      });
+      return;
+    }
+    if (type === "output.release") {
+      this.audio.output({ type: "release", generationId: String(message.generationId ?? ""), gain: clamp01(Number(message.gain ?? 1)) });
+      return;
+    }
+    if (type === "output.cancel") {
+      this.audio.output({ type: "cancel", generationId: String(message.generationId ?? "") });
+      return;
+    }
+    if (type === "output.done") {
+      this.audio.output({
+        type: "done",
+        generationId: String(message.generationId ?? ""),
+        lane: message.queue === "reaction" ? "REACTION" : "FOREGROUND"
+      });
+      return;
+    }
+    this.emit("unknown", { message });
+  }
+  writeInput(pcm) {
+    if (this.stopped || !this.acceptingInput || this.socket.readyState !== WebSocket.OPEN)
+      return;
+    if (pcm.byteLength % 2 !== 0) {
+      this.emit("error", { code: "INVALID_AUDIO_FRAME", message: "PCM16 input must contain complete 16-bit samples." });
+      return;
+    }
+    this.socket.send(pcm);
+  }
+  sendReceipt(receipt) {
+    if (this.stopped || this.socket.readyState !== WebSocket.OPEN)
+      return;
+    this.socket.send(JSON.stringify({ type: "output.receipt", ...receipt }));
+  }
+  async executeTool(call) {
+    if (!call.callId || !call.name || this.socket.readyState !== WebSocket.OPEN)
+      return;
+    this.emit("tool.call", call);
+    const tool = this.tools[call.name];
+    if (!tool) {
+      const error = `No server handler is registered for tool ${call.name}`;
+      this.socket.send(JSON.stringify({ type: "tool.result", callId: call.callId, ok: false, error }));
+      this.emit("tool.result", { ...call, ok: false, error });
+      return;
+    }
+    try {
+      const output = await tool.execute(call.input);
+      this.socket.send(JSON.stringify({ type: "tool.result", callId: call.callId, ok: true, output: output ?? null }));
+      this.emit("tool.result", { ...call, ok: true, output });
+    } catch (error) {
+      const message = error instanceof Error ? error.message : String(error);
+      this.socket.send(JSON.stringify({ type: "tool.result", callId: call.callId, ok: false, error: message }));
+      this.emit("tool.result", { ...call, ok: false, error: message });
+    }
+  }
+  acceptPublicEvent(name, payload, atMs) {
+    if (name === "transcript.instantaneous" && typeof payload.text === "string") {
+      this.emit("transcript.instantaneous", { text: payload.text });
+      return;
+    }
+    if (name === "transcript.canonical" && Array.isArray(payload.turns)) {
+      const turns = [];
+      for (const value of payload.turns) {
+        if (!value || typeof value !== "object" || Array.isArray(value))
+          continue;
+        const turn = value;
+        const role = turn.role;
+        if (typeof turn.id !== "string" || role !== "user" && role !== "assistant" || typeof turn.text !== "string")
+          continue;
+        turns.push({
+          id: turn.id,
+          role,
+          text: turn.text,
+          ...typeof turn.truncated === "boolean" ? { truncated: turn.truncated } : {}
+        });
+      }
+      this.emit("transcript.canonical", { turns });
+      return;
+    }
+    if (name === "floor" && (payload.owner === "USER" || payload.owner === "ASSISTANT") && typeof payload.assistantAudible === "boolean") {
+      this.emit("floor", { owner: payload.owner, assistantAudible: payload.assistantAudible });
+      return;
+    }
+    if (name === "phase" && typeof payload.phase === "string") {
+      const event = {
+        phase: payload.phase,
+        source: payload.source === "floor" ? "floor" : "initial",
+        ...typeof payload.previousPhase === "string" ? { previousPhase: payload.previousPhase } : {}
+      };
+      this.currentPhase = event.phase;
+      this.emit("phase", event);
+      return;
+    }
+    if (name === "quick-reaction" && typeof payload.reaction === "string" && (payload.status === "prepared" || payload.status === "playing" || payload.status === "completed" || payload.status === "cancelled")) {
+      this.emit("quick-reaction", { reaction: payload.reaction, status: payload.status });
+      return;
+    }
+    if (name === "assistant.energy" && Number.isFinite(Number(payload.current)) && Array.isArray(payload.predictions)) {
+      const predictions = [];
+      let valid = true;
+      for (const value of payload.predictions) {
+        if (!value || typeof value !== "object" || Array.isArray(value)) {
+          valid = false;
+          break;
+        }
+        const prediction = value;
+        const startMs = Number(prediction.startMs);
+        const endMs = Number(prediction.endMs);
+        const energy = Number(prediction.energy);
+        if (!Number.isFinite(startMs) || startMs < 0 || !Number.isFinite(endMs) || endMs <= startMs || !Number.isFinite(energy)) {
+          valid = false;
+          break;
+        }
+        predictions.push({ startMs, endMs, energy: clamp01(energy) });
+      }
+      if (valid) {
+        this.emit("assistant.energy", { current: clamp01(Number(payload.current)), predictions });
+        return;
+      }
+    }
+    if (name === "error" && typeof payload.code === "string" && typeof payload.message === "string") {
+      this.emit("error", { code: payload.code, message: payload.message });
+      return;
+    }
+    this.emit("unknown", { message: { type: "public.event", name, payload, ...atMs === undefined ? {} : { atMs } } });
+  }
+  emit(event, value) {
+    for (const handler of this.listeners.get(event) ?? [])
+      handler(value);
+  }
+  finish(reason, notifyServer = false) {
+    if (this.stopped)
+      return;
+    this.stopped = true;
+    const ended = new Error(reason ?? "Session ended.");
+    this.prepared?.reject(ended);
+    this.prepared = undefined;
+    this.started?.reject(ended);
+    this.started = undefined;
+    if (notifyServer && this.socket.readyState === WebSocket.OPEN)
+      this.socket.send(JSON.stringify({ type: "session.stop" }));
+    if (this.socket.readyState === WebSocket.OPEN || this.socket.readyState === WebSocket.CONNECTING)
+      this.socket.close(1000, reason ?? "stopped");
+    this.audio.stop();
+    this.emit("connection", { state: "closed", ...reason ? { detail: reason } : {} });
+    this.resolveClosed();
+  }
+}
+
+class LiveVoiceServer {
+  static connect(options) {
+    return LiveVoiceServerSession.connect(options);
+  }
+}
+async function resolveSessionCredentials(options) {
+  if (Boolean(options.token) === Boolean(options.apiKey))
+    throw new Error("Supply exactly one of token or apiKey.");
+  if (options.token)
+    return { token: options.token, endpoint: options.endpoint ?? defaultEndpoint };
+  const apiBaseUrl = (options.apiBaseUrl ?? defaultApiBaseUrl).replace(/\/$/u, "");
+  const response = await fetch(`${apiBaseUrl}/v1/sessions`, {
+    method: "POST",
+    headers: { authorization: `Bearer ${options.apiKey}`, "content-type": "application/json" },
+    body: JSON.stringify(options.voice ? { voice: options.voice } : {})
+  });
+  const result = await response.json();
+  if (!response.ok || typeof result.token !== "string")
+    throw new Error(String(result.error ?? `Unable to create Live Voice session (${response.status}).`));
+  return {
+    token: result.token,
+    endpoint: options.endpoint ?? (typeof result.realtimeUrl === "string" ? result.realtimeUrl : defaultEndpoint)
+  };
+}
+function validateAudioFormat(format) {
+  if (!format)
+    throw new Error("Audio transports must declare their SDK-facing PCM format.");
+  if (format.encoding !== liveVoicePcmFormat.encoding || format.sampleRate !== liveVoicePcmFormat.sampleRate || format.channels !== liveVoicePcmFormat.channels) {
+    throw new Error("Audio transports must expose mono PCM16LE at 24 kHz.");
+  }
+}
+function waitForOpen(socket) {
+  if (socket.readyState === WebSocket.OPEN)
+    return Promise.resolve();
+  return new Promise((resolve, reject) => {
+    const opened = () => finish();
+    const failed = () => finish(new Error("Live Voice WebSocket failed while connecting."));
+    const finish = (error) => {
+      socket.removeEventListener("open", opened);
+      socket.removeEventListener("error", failed);
+      if (error)
+        reject(error);
+      else
+        resolve();
+    };
+    socket.addEventListener("open", opened, { once: true });
+    socket.addEventListener("error", failed, { once: true });
+  });
+}
+function withSessionToken(value, token) {
+  const url = new URL(value);
+  url.searchParams.set("token", token);
+  return url.toString();
+}
+function base64Bytes(encoded) {
+  const binary = atob(encoded);
+  return Uint8Array.from(binary, (character) => character.charCodeAt(0));
+}
+function clamp01(value) {
+  return Number.isFinite(value) ? Math.max(0, Math.min(1, value)) : 1;
+}
+function asRecord(value) {
+  return value && typeof value === "object" && !Array.isArray(value) ? value : {};
+}
+export {
+  LiveVoiceServerSession,
+  LiveVoiceServer as default,
+  liveVoicePcmFormat
+};

package/package.json

@@ -0,0 +1,35 @@
+{
+  "name": "@inkibra/voice-sdk",
+  "version": "0.1.0",
+  "description": "Browser and server SDK for Inkibra Live Voice",
+  "license": "MIT",
+  "repository": { "type": "git", "url": "git+https://github.com/inkibra/voice.git", "directory": "packages/sdk" },
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js",
+      "default": "./dist/index.js"
+    },
+    "./server": {
+      "types": "./dist/server.d.ts",
+      "import": "./dist/server.js",
+      "default": "./dist/server.js"
+    }
+  },
+  "files": [
+    "dist/index.js",
+    "dist/index.d.ts",
+    "dist/public.d.ts",
+    "dist/server.js",
+    "dist/server.d.ts"
+  ],
+  "sideEffects": false,
+  "publishConfig": { "access": "public" },
+  "scripts": {
+    "build": "bun build src/index.ts --outdir dist --format esm --target browser && bun build src/server.ts --outdir dist --format esm --target node && tsc -p tsconfig.build.json && rm -rf dist/sdk dist/protocol",
+    "prepack": "bun run build"
+  }
+}