@inkibra/voice-sdk 0.1.0 → 0.2.0

package/dist/participant.d.ts

@@ -0,0 +1,75 @@
+import { ControlClient } from "./control.js";
+import type { LiveVoiceConversationOptions, LiveVoiceEventMap, LiveVoiceSnapshot, LiveVoiceTask, LiveVoiceTools } from "./session-protocol.js";
+export declare const defaultEndpoint = "wss://inkibra-voice.inkibra.workers.dev/v1/live";
+export type ParticipantOptions = {
+    token: string;
+    endpoint?: string;
+    tools?: LiveVoiceTools;
+    prompt?: string;
+    conversation?: LiveVoiceConversationOptions;
+};
+export type Reconciliation = {
+    status: "succeeded" | "failed" | "cancelled";
+    output?: unknown;
+    error?: string;
+};
+export type LiveVoiceRating = {
+    overall: number;
+    scores?: {
+        waiting?: number;
+        interruptions?: number;
+        backchannels?: number;
+        voice?: number;
+        tools?: number;
+    };
+    note?: string;
+    moments?: {
+        atSeconds: number;
+        note: string;
+    }[];
+};
+export type LiveVoiceRatingResult = {
+    rating: LiveVoiceRating & Record<string, unknown>;
+    storedFields: string[];
+};
+/** Internal shared participant surface; owners and attachments expose different lifecycle operations. */
+export declare class LiveVoiceParticipant {
+    protected readonly client: ControlClient;
+    protected readonly tools: LiveVoiceTools;
+    protected readonly developer: {
+        prompt: string;
+        conversation?: LiveVoiceConversationOptions;
+    };
+    protected connectedToken: string;
+    private listeners;
+    private readonly lifetime;
+    readonly closed: Promise<void>;
+    constructor(options: ParticipantOptions, client?: ControlClient);
+    get snapshot(): LiveVoiceSnapshot;
+    get sessionId(): string;
+    get participantId(): string;
+    get connectionId(): string;
+    get phase(): string | undefined;
+    on<K extends keyof LiveVoiceEventMap>(event: K, handler: (value: LiveVoiceEventMap[K]) => void): () => void;
+    protected rateSession(rating: LiveVoiceRating): Promise<LiveVoiceRatingResult>;
+    reconnect(options?: {
+        token?: string;
+    }): Promise<LiveVoiceSnapshot>;
+    dispose(): void;
+    protected finish(): void;
+    protected connectionChanged(state: LiveVoiceEventMap["connection"]["state"], detail?: string): void;
+    protected unknownMessage(message: Record<string, unknown>): void;
+    protected emit<K extends keyof LiveVoiceEventMap>(event: K, value: LiveVoiceEventMap[K]): void;
+    protected taskApi(): {
+        list: () => Promise<LiveVoiceTask[]>;
+        get: (taskId: string) => Promise<LiveVoiceTask | undefined>;
+        cancel: (taskId: string) => Promise<LiveVoiceTask | undefined>;
+    };
+    protected attachmentTaskApi(): {
+        reconcile: (taskId: string, resolution: Reconciliation) => Promise<LiveVoiceTask | undefined>;
+        list: () => Promise<LiveVoiceTask[]>;
+        get: (taskId: string) => Promise<LiveVoiceTask | undefined>;
+        cancel: (taskId: string) => Promise<LiveVoiceTask | undefined>;
+    };
+    private acceptEvent;
+}

package/dist/public.d.ts

@@ -1,109 +1,43 @@
-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 = {
+import { LiveVoiceParticipant, type LiveVoiceRating, type LiveVoiceRatingResult, type ParticipantOptions } from "./participant.js";
+export type * from "./session-protocol.js";
+import type { LiveVoiceSnapshot, LiveVoiceTools } from "./session-protocol.js";
+export type { LiveVoiceRating, LiveVoiceRatingResult } from "./participant.js";
+export type LiveVoiceCreateOptions = ParticipantOptions & {
+    mediaMode?: "browser";
+};
+export type LiveVoiceAttachOptions = {
     token: string;
-    /** Task, domain, persona, and tool-use instructions for the agent. */
-    prompt?: string;
-    /** Provider-neutral control over conversational behavior and phases. */
-    conversation?: LiveVoiceConversationOptions;
+    sessionId: string;
+    participantId: string;
     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 type LiveVoiceReconnectOptions = {
+    token?: string;
+};
+export declare class LiveVoiceOwner extends LiveVoiceParticipant {
+    readonly tasks: {
+        list: () => Promise<import("./session-protocol.js").LiveVoiceTask[]>;
+        get: (taskId: string) => Promise<import("./session-protocol.js").LiveVoiceTask | undefined>;
+        cancel: (taskId: string) => Promise<import("./session-protocol.js").LiveVoiceTask | undefined>;
+    };
+    private started;
+    private starting?;
+    start(): Promise<void>;
+    rate(rating: LiveVoiceRating): Promise<LiveVoiceRatingResult>;
+    stop(): Promise<void>;
+    reconnect(options?: LiveVoiceReconnectOptions): Promise<LiveVoiceSnapshot>;
+}
+export declare class LiveVoiceAttachment extends LiveVoiceParticipant {
+    readonly tasks: {
+        reconcile: (taskId: string, resolution: import("./participant.js").Reconciliation) => Promise<import("./session-protocol.js").LiveVoiceTask | undefined>;
+        list: () => Promise<import("./session-protocol.js").LiveVoiceTask[]>;
+        get: (taskId: string) => Promise<import("./session-protocol.js").LiveVoiceTask | undefined>;
+        cancel: (taskId: string) => Promise<import("./session-protocol.js").LiveVoiceTask | undefined>;
+    };
+    detach(): Promise<void>;
 }
 export default class LiveVoice {
-    static connect(options: LiveVoiceConnectOptions): Promise<LiveVoiceSession>;
+    static create(options: LiveVoiceCreateOptions): Promise<LiveVoiceOwner>;
+    static attach(options: LiveVoiceAttachOptions): Promise<LiveVoiceAttachment>;
 }
-export {};

package/dist/server.d.ts

@@ -1,120 +1,120 @@
-import type { LiveVoiceConversationOptions, LiveVoiceEventMap, LiveVoicePlatformVoice, LiveVoiceTools } from "./public";
-export type { LiveVoiceCanonicalTurn, LiveVoiceConversationOptions, LiveVoiceEventMap, LiveVoiceFloorState, LiveVoicePhaseEvent, LiveVoicePlatformVoice, LiveVoiceTool, LiveVoiceToolCall, LiveVoiceTools, } from "./public";
+import { ControlClient } from "./control.js";
+import { LiveVoiceParticipant, type LiveVoiceRating, type LiveVoiceRatingResult } from "./participant.js";
+export type { LiveVoiceRating, LiveVoiceRatingResult } from "./participant.js";
+import type { LiveVoiceConversationOptions, LiveVoiceEventMap, LiveVoicePlatformVoice, LiveVoiceSnapshot, LiveVoiceTools } from "./session-protocol.js";
+export type * from "./session-protocol.js";
 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. */
-{
+export type LiveVoiceAudioOutputCommand = {
     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;
+    bufferedSamples: number;
+    completed: boolean;
+    cancelled?: boolean;
 };
 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 = {
+type Authorization = {
     token: string;
     apiKey?: never;
 } | {
     apiKey: string;
     token?: never;
 };
-export type LiveVoiceServerConnectOptions = LiveVoiceServerAuthorization & {
+export type LiveVoiceServerCreateOptions = Authorization & {
     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;
+export type LiveVoiceServerAttachOptions = Authorization & {
+    sessionId: string;
+    participantId: string;
+    audio?: never;
+    tools?: LiveVoiceTools;
+    endpoint?: string;
+    apiBaseUrl?: string;
+};
+export declare class LiveVoiceServerSession extends LiveVoiceParticipant {
+    private readonly audio;
+    readonly tasks: {
+        list: () => Promise<import("./session-protocol.js").LiveVoiceTask[]>;
+        get: (taskId: string) => Promise<import("./session-protocol.js").LiveVoiceTask | undefined>;
+        cancel: (taskId: string) => Promise<import("./session-protocol.js").LiveVoiceTask | undefined>;
+    };
+    private mediaWanted;
+    private audioActive;
+    private audioEpoch;
+    private starting?;
+    private audioStopping?;
+    constructor(options: {
+        token: string;
+        endpoint?: string;
+        tools?: LiveVoiceTools;
+        prompt?: string;
+        conversation?: LiveVoiceConversationOptions;
+    }, client: ControlClient, audio: LiveVoiceAudioTransport);
+    start(): Promise<void>;
+    private startMedia;
+    stop(): Promise<void>;
+    rate(rating: LiveVoiceRating): Promise<LiveVoiceRatingResult>;
+    reconnect(options?: {
+        token?: string;
+    }): Promise<LiveVoiceSnapshot>;
     dispose(): void;
-    private bindSocket;
-    private prepare;
-    private onMessage;
-    private writeInput;
-    private sendReceipt;
-    private executeTool;
-    private acceptState;
-    private acceptApplicationEvent;
-    private emit;
-    private finish;
+    protected connectionChanged(state: LiveVoiceEventMap["connection"]["state"], detail?: string): void;
+    private stopAudio;
+    protected unknownMessage(message: Record<string, unknown>): void;
+}
+export declare class LiveVoiceServerAttachment extends LiveVoiceParticipant {
+    readonly tasks: {
+        reconcile: (taskId: string, resolution: import("./participant.js").Reconciliation) => Promise<import("./session-protocol.js").LiveVoiceTask | undefined>;
+        list: () => Promise<import("./session-protocol.js").LiveVoiceTask[]>;
+        get: (taskId: string) => Promise<import("./session-protocol.js").LiveVoiceTask | undefined>;
+        cancel: (taskId: string) => Promise<import("./session-protocol.js").LiveVoiceTask | undefined>;
+    };
+    detach(): Promise<void>;
 }
 export default class LiveVoiceServer {
-    static connect(options: LiveVoiceServerConnectOptions): Promise<LiveVoiceServerSession>;
+    static create(options: LiveVoiceServerCreateOptions): Promise<LiveVoiceServerSession>;
+    static attach(options: LiveVoiceServerAttachOptions): Promise<LiveVoiceServerAttachment>;
 }