@inkibra/voice-sdk
v0.2.0
Published
Browser and server SDK for Inkibra Live Voice
Readme
@inkibra/voice-sdk
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
import LiveVoice from "@inkibra/voice-sdk";
const session = await LiveVoice.create({
token,
prompt: "Help the user complete a concise inventory.",
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("phase", ({ phase }) => console.log(phase));
session.on("task.update", task => renderTask(task));
session.on("error", console.error);
await session.start();
// Later:
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:
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);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:
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({}),
});
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
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 };
},
},
},
});
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.
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.
await session.reconnect({ token: refreshedOwnerToken });
await attachment.reconnect({ token: refreshedAttachmentToken });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/calling adapters use the same two-phase lifecycle:
import LiveVoice from "@inkibra/voice-sdk/server";
const session = await LiveVoice.create({
apiKey: process.env.INKIBRA_API_KEY!,
audio: providerAudioTransport,
prompt: "Help callers schedule an appointment.",
conversation: { starts: "assistant" },
});
await session.start();
await session.closed;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.resultsubscriptions withtask.update; use one publictaskId. - Use
execute(input, task)for progress, partial results, and cooperative cancellation. - Await
stop()for the owner ordetach()for an attachment.
