@inkibra/voice-sdk 0.1.1 → 0.2.0

package/README.md

@@ -1,75 +1,155 @@
 # `@inkibra/voice-sdk`
 
-The browser and server SDK for Inkibra Live Voice.
+Browser and server SDK, version 0.2. One audio owner per session; additional participants observe or execute tools without opening media. The Durable Object remains the sole conversation authority.
+
+## Create, listen, then start
 
 ```ts
 import LiveVoice from "@inkibra/voice-sdk";
 
-const session = await LiveVoice.connect({
+const session = await LiveVoice.create({
   token,
   prompt: "Help the user complete a concise inventory.",
-  conversation: {
-    starts: "assistant",
-    prompt: "Be concise and clarify uncertainty before moving on.",
-  },
-  tools: {
-    update_inventory: {
-      description: "Update an inventory item",
-      parameters: {
-        type: "object",
-        properties: { name: { type: "string" }, quantity: { type: "number" } },
-        required: ["name", "quantity"],
-        additionalProperties: false,
-      },
-      execute: async ({ name, quantity }) => updateInventory(String(name), Number(quantity)),
-    },
-  },
+  conversation: { starts: "assistant", prompt: "Clarify uncertainty before moving on." },
+  tools: browserTools,
 });
 
 session.on("transcript.instantaneous", ({ text }) => console.log(text));
 session.on("transcript.canonical", ({ turns }) => console.log(turns));
 session.on("floor", ({ owner, assistantAudible }) => console.log(owner, assistantAudible));
-session.on("assistant.energy", ({ current, predictions }) => {
-  animateAgent(current);
-  renderAssistantForecast(predictions);
-});
-session.on("phase", ({ phase, previousPhase }) => console.log(phase, previousPhase));
-session.on("tool.call", ({ name, input }) => console.log(name, input));
+session.on("phase", ({ phase }) => console.log(phase));
+session.on("task.update", task => renderTask(task));
 session.on("error", console.error);
 
+await session.start();
 // Later:
-session.stop();
+await session.stop();
+session.dispose();
+```
+
+`create()` establishes control ownership and acknowledges tool registration. It does not open the microphone or begin the assistant opening. Await any backend attachments before `start()` if their tools must be available at the opening.
+## Rate a completed session
+
+Owners can submit one rating per rater kind after a call. Re-submitting replaces the previous rating for that session and rater:
+
+```ts
+const result = await session.rate({
+  overall: 5,
+  scores: { waiting: 4, interruptions: 5, backchannels: 4, voice: 5, tools: 4 },
+  note: "Clear and responsive.",
+});
+console.log(result.storedFields);
 ```
 
-Create the short-lived browser token on your server. Never expose your Inkibra API key to the browser:
+The browser and server owner sessions use the owner session token already held by the SDK and derive the HTTPS control-plane origin from the realtime endpoint. Customer sessions retain only numeric scores and operational metadata; notes and moments are retained for private operator sessions.
+
+Control and task events use WebSocket. Browser audio uses a native `RTCPeerConnection` with short-lived TURN credentials. Do not wrap the browser SDK in PCM capture/playback: native WebRTC playout is required for browser acoustic echo cancellation. Microphone capture requests mono, automatic gain control, echo cancellation, and noise suppression; effectiveness depends on browser/device support.
+
+## Authorization
+
+Create the owner token on your server; never put your Inkibra API key in browser code:
 
 ```ts
 const response = await fetch("https://inkibra-voice.inkibra.workers.dev/v1/sessions", {
   method: "POST",
   headers: { authorization: `Bearer ${process.env.INKIBRA_API_KEY}`, "content-type": "application/json" },
-  body: JSON.stringify({ voice: "ara" }),
+  body: JSON.stringify({}),
+});
+if (!response.ok) throw new Error("Session authorization failed");
+const { token, sessionId } = await response.json();
+```
+
+Browser attachments use a separate token from `POST /v1/sessions/{sessionId}/attachment-tokens`, authenticated by the account's API key. Body: `{ participantId, observe: true, tools: ["search_docs"] }`. Tokens bind the account, session, participant, observation permission, allowed tool names, and expiry (15 minutes). `observe` defaults to `true`; `tools` defaults to `[]`. A session ID is not authorization. Do not share the owner token with observers or tools.
+
+## Attach backend tools
+
+```ts
+import LiveVoice from "@inkibra/voice-sdk/server";
+
+const attachment = await LiveVoice.attach({
+  apiKey: process.env.INKIBRA_API_KEY!,
+  sessionId,
+  participantId: "research-backend",
+  tools: {
+    search_docs: {
+      description: "Search internal documentation",
+      parameters: {
+        type: "object",
+        properties: { query: { type: "string" } },
+        required: ["query"],
+        additionalProperties: false,
+      },
+      async execute({ query }, task) {
+        await task.progress({ message: "Searching documents", fraction: 0.1 });
+        const matches = await searchDocuments(String(query), { signal: task.signal });
+        await task.partial({ matches });
+        return { matches };
+      },
+    },
+  },
 });
 
-const { token } = await response.json();
+attachment.on("transcript.canonical", ({ turns }) => console.log(turns));
+attachment.on("task.update", task => console.log(task));
+// Disconnect only this participant:
+await attachment.detach();
+```
+
+The browser entry also has `attach({ token, sessionId, participantId, tools? })`. Neither attachment entry opens audio, changes the prompt, takes ownership, or stops the conversation. Tool names are unique across the session; collisions reject registration rather than overwrite another provider. Disconnected providers' tools are unavailable for new calls.
+
+## Tasks and cancellation
+
+Tools receive `execute(input, { taskId, sourceUserTurnId, signal, progress, partial })`. `sourceUserTurnId` is the optional canonical user-turn origin associated by the runtime with the task; it is separate from model-provided input and is absent after zero-data-retention clearing or an operational restart. Inputs, partials, and outputs must be JSON serializable. Progress updates status/UI; it does not instruct speech. Partial and final results enter model context through ordinary turn control, without forcing playback interruption. The conversation does not wait for the tool promise.
+
+```ts
+const tasks = await session.tasks.list();
+const task = await session.tasks.get(taskId);
+await session.tasks.cancel(taskId);
+
+// Only the owning provider, after independently verifying unknown work:
+await attachment.tasks.reconcile(taskId, { status: "succeeded", output: verifiedResult });
+```
+
+Statuses: `queued`, `running`, `cancel_requested`, `succeeded`, `failed`, `cancelled`, `unknown`. The owner can inspect/cancel all tasks; each provider can inspect/cancel its own. An observer does not receive another provider's task payloads. Cancellation requests abort the handler's signal; they do not prove an external side effect was stopped or rolled back. Returning a value still reports success. Session shutdown requests cancellation without waiting indefinitely for external work.
+
+## Reconnect and snapshots
+
+Both handles expose `sessionId`, stable `participantId`, physical `connectionId`, and `snapshot`. `create()`, `attach()`, and `reconnect()` resolve after the authorized snapshot is synchronized, followed by ordered events. Catchup restores current state, not every missed interim token.
+
+Connection events report `ready` once control is connected and synchronized; this does not mean media is running. The owner reports `live` after `start()` succeeds. `snapshot` events report synchronization and conversation-status changes.
+
+```ts
+await session.reconnect({ token: refreshedOwnerToken });
+await attachment.reconnect({ token: refreshedAttachmentToken });
 ```
 
-## Server media
+Omit `token` to reuse an unexpired credential. Reconnect the existing handle rather than creating a new session. Running handlers in that process continue; unacknowledged updates are resent and deduplicated. Old connections are fenced. Losing execution state makes delivered work `unknown`, never automatically reexecuted. Use `taskId` as an external idempotency key where supported; this is not an exactly-once side-effect guarantee.
+
+Owner disconnection suspends audio for a 30-second grace period. Attachments cannot take over audio, and stale buffered audio is not replayed. After a Durable Object restart, the conversation fails closed. Delivered work without retained provider execution state becomes `unknown`; a surviving same-process handler may still report its operational outcome. Only opaque operational task metadata is persisted: prompts, transcripts, tool names/arguments/results, partials, and progress messages are not. Consequently `name`, `input`, and result fields can be unavailable after restart or conversation shutdown.
+
+Within that grace period, reconnecting an already-started owner starts fresh media and restores canonical conversation text to the speech provider. It does not replay prior audio or restart background tools.
+
+## Server audio owner
 
-Telephone and calling-provider adapters use the server entry point. The adapter supplies PCM16LE mono audio at 24 kHz and maps Inkibra output commands to its provider playback queue.
+Telephone/calling adapters use the same two-phase lifecycle:
 
 ```ts
 import LiveVoice from "@inkibra/voice-sdk/server";
 
-const session = await LiveVoice.connect({
+const session = await LiveVoice.create({
   apiKey: process.env.INKIBRA_API_KEY!,
   audio: providerAudioTransport,
-  voice: "ara",
   prompt: "Help callers schedule an appointment.",
   conversation: { starts: "assistant" },
-  tools: {},
 });
-
+await session.start();
 await session.closed;
 ```
 
-The Durable Object remains the sole owner of conversation state. The server audio transport owns only codec conversion and transient provider playback.
+`audio` is PCM16LE mono at 24 kHz. The transport owns codec conversion and transient provider playback, not conversation state. Playback receipts report actual played samples and explicit completion/cancellation; queued bytes are not proof of playback. Supply `token` instead of `apiKey` when your backend issues owner tokens separately.
+
+## Breaking migration from 0.1
+
+- Replace `tool.call`/`tool.result` subscriptions with `task.update`; use one public `taskId`.
+- Use `execute(input, task)` for progress, partial results, and cooperative cancellation.
+- Await `stop()` for the owner or `detach()` for an attachment.

package/dist/client.d.ts

@@ -0,0 +1,18 @@
+import { ControlClient, type LiveControlCallbacks, type LiveSessionOptions } from "./control.js";
+export type { LivePublicEvent, LiveSessionOpenOptions, LiveSessionOptions } from "./control.js";
+export type LiveClientCallbacks = LiveControlCallbacks & {
+    onLevel(level: number): void;
+    onMediaStream?(track: "microphone" | "assistant", stream: MediaStream): void;
+    onAudioElement?(element: HTMLAudioElement): void;
+    onMediaClosed?(): void;
+};
+/** Browser media adapter over the shared control/task engine. */
+export declare class LiveVoiceClient extends ControlClient {
+    private readonly mediaCallbacks;
+    private media?;
+    private mediaStarting?;
+    constructor(endpoint: string, mediaCallbacks: LiveClientCallbacks);
+    start(options?: LiveSessionOptions): Promise<void>;
+    closeSocket(reason?: string, terminal?: boolean): void;
+    private closeMedia;
+}

package/dist/control.d.ts

@@ -0,0 +1,77 @@
+import type { LiveVoiceSnapshot, LiveVoiceTask, LiveVoiceTool, ToolContext } from "./session-protocol.js";
+export type LivePublicEvent = {
+    name: string;
+    payload: Record<string, unknown>;
+    sequence?: number;
+    atMs?: number;
+};
+export type LiveControlCallbacks = {
+    onConnection(state: "connecting" | "ready" | "live" | "closed" | "error", detail?: string): void;
+    onPublicEvent(event: LivePublicEvent): void;
+    onSnapshot?(snapshot: LiveVoiceSnapshot): void;
+    onUnknown?(message: Record<string, unknown>): void;
+    onTaskExecute?(task: LiveVoiceTask, context: ToolContext): unknown | Promise<unknown>;
+    onTaskUpdate?(task: LiveVoiceTask): void;
+    onSessionLimit?(reason: string, durationSeconds?: number): void;
+};
+export type LiveSessionOpenOptions = {
+    token: string;
+    sessionId?: string;
+    participantId?: string;
+    mode: "create" | "attach" | "reconnect";
+    tools?: Record<string, LiveVoiceTool>;
+    developer?: unknown;
+    mediaMode?: "browser" | "server";
+    retainedTaskIds?: string[];
+};
+export type LiveSessionOptions = {
+    token?: string;
+    developer?: unknown;
+    mediaMode?: "browser" | "server";
+};
+/** Shared browser/server control, task execution, acknowledgement, and reconnect state. */
+export declare class ControlClient {
+    protected endpoint: string;
+    protected callbacks: LiveControlCallbacks;
+    protected socket?: WebSocket;
+    protected sessionToken?: string;
+    private snapshotValue?;
+    private waits;
+    private executions;
+    private requestCounter;
+    private prepared;
+    private preparing?;
+    private starting?;
+    private started;
+    private terminal;
+    constructor(endpoint: string, callbacks: LiveControlCallbacks);
+    ratingUrl(sessionId: string): string;
+    setCallbacks(callbacks: LiveControlCallbacks): void;
+    get currentSnapshot(): LiveVoiceSnapshot | undefined;
+    retainedTaskIds(): string[];
+    open(options: LiveSessionOpenOptions): Promise<LiveVoiceSnapshot>;
+    prepare(): Promise<void>;
+    start(options?: LiveSessionOptions): Promise<void>;
+    stop(): Promise<void>;
+    detach(): Promise<void>;
+    closeSocket(reason?: string, terminal?: boolean): void;
+    dispose(): void;
+    reconnect(options: Omit<LiveSessionOpenOptions, "mode" | "token"> & {
+        token?: string;
+    }): Promise<LiveVoiceSnapshot>;
+    requestTask(operation: "list" | "get" | "cancel" | "reconcile", taskId?: string, resolution?: {
+        status: "succeeded" | "failed" | "cancelled";
+        output?: unknown;
+        error?: string;
+    }): Promise<LiveVoiceTask | LiveVoiceTask[] | undefined>;
+    playUiCue(cue: "recognition" | "committed"): void;
+    send(message: Record<string, unknown> | Uint8Array): void;
+    private exchange;
+    private onMessage;
+    private execute;
+}
+export declare function deferred<T>(): {
+    promise: Promise<T>;
+    resolve(value: T | PromiseLike<T>): void;
+    reject(reason?: unknown): void;
+};

package/dist/index.d.ts

@@ -1,3 +1,3 @@
-import LiveVoice from "./public";
-export * from "./public";
+import LiveVoice from "./public.js";
+export * from "./public.js";
 export default LiveVoice;