@lumavox/client 0.0.0-stage → 0.1.1

package/dist/conversation.d.ts

@@ -0,0 +1,324 @@
+/**
+ * A conversation on the agent's socket, kept alive: `client.connect()`
+ * answers one at once, and it dials, authenticates, reconnects, replaces
+ * a refused key, queues what is sent while it cannot be, and publishes
+ * what it knows as a snapshot (`subscribe`) — on `socket.ts`'s one socket
+ * at a time.
+ *
+ * - **The key before the dial**: minting does not eat the edge's 10 s to
+ *   authenticate.
+ * - **One turn at a time, queued.** A message sent during the greeting, a
+ *   turn, a reconnect or a quiet spell waits its turn instead of being
+ *   refused; each `send` answers a promise of its outcome that **never
+ *   rejects** — `done`, `interrupted`, or `dropped` (closed, cancelled,
+ *   refused) — so leaving during the greeting is no unhandled rejection.
+ *   A message the edge never acknowledged is sent again once after a
+ *   reconnect; one it acknowledged is never sent twice (it was billed).
+ * - **Recordings carry an id** (`r1`, `r2`, …: a counter, since Hermes has
+ *   no `randomUUID`), which the edge echoes, so a `transcribeOnly` end
+ *   answers its own recording's words however the transcripts finish. A
+ *   recording started before the socket is ready is held and sent at
+ *   `ready`; one cut by a reconnect is over, since the new socket never
+ *   had it — audio sent for it would close the socket (4011).
+ * - **Speech is not paid for unheard**: with no `onAudio` handler every
+ *   turn says `speech: false`, unless `connect`'s options say otherwise.
+ * - **A watchdog, no pings**: the edge sends `pong` after 30 s of client
+ *   silence, so 60 s with nothing from it, and nothing said for as long,
+ *   is a dead socket (half-open, after a phone changed networks): it is
+ *   dropped and dialled again. A ping never resets the edge's idle timer.
+ * - **The app's handlers cannot break it**: one that throws is rethrown on
+ *   its own (`call`), after the state it was told about is in place.
+ *
+ * Cost per frame: one snapshot (and one turn) object per change a screen
+ * shows — a `text.delta`, say — and none for audio, which is passed
+ * through, never copied.
+ */
+import type { ErrorFrame, InterruptedFrame, KnowledgeFrame, ReadyFrame, ServerFrame, ServerFrames, TranscriptFrame, TurnDoneFrame } from "./events.js";
+import type { RelationInfo } from "./gen/index.js";
+import { type AudioFrame, type Warning, type WebSocketConstructor } from "./socket.js";
+import type { Tokens } from "./token.js";
+export type ConversationState = 
+/** Dialling for the first time. */
+"connecting"
+/** Authenticated and idle: a `send` goes at once. */
+ | "ready"
+/** A turn is running — the greeting, or a message — and sends queue behind it. */
+ | "busy"
+/** The connection dropped and is being made again. */
+ | "reconnecting"
+/** The edge hung up on a quiet connection (4007): the next `send`, `startAudio` or `reconnect()` dials. */
+ | "dormant"
+/** Over: `close()`, or a close nothing can cure (`onClose` says which). */
+ | "closed";
+/** The turn in progress, or the last one. */
+export interface TurnSnapshot {
+    /** From `turn.start`; `null` while a message is on its way. */
+    id: string | null;
+    /** The reply so far; the whole of it once `done`. */
+    text: string;
+    /** The reply as cut for speech, piece by piece. */
+    chunks: string[];
+    mood: {
+        mood: string;
+        intensity: number | null;
+    } | null;
+    /** The tool the model is waiting on, between `tool.start` and `tool.end`. */
+    tool: string | null;
+    knowledge: KnowledgeFrame[];
+    /** A spoken turn's transcript. */
+    heard: string | null;
+    done: boolean;
+    interrupted: boolean;
+}
+export interface Snapshot {
+    state: ConversationState;
+    /** The last `ready`: the agent, its voice's format, the greeting. */
+    ready: ReadyFrame | null;
+    turn: TurnSnapshot | null;
+    /** The open recording as heard so far (`heard.partial`), until its words arrive. */
+    caption: string | null;
+    /** The standing relationship, from `ready` and every `relation` since. */
+    relation: RelationInfo | null;
+    /** Sends waiting behind the running turn, a reconnect or the greeting. */
+    queued: number;
+}
+/** How a turn this conversation sent ended. */
+export type TurnOutcome = {
+    status: "done";
+    frame: TurnDoneFrame;
+}
+/** Cut short: by `cancel()`, a failure (its `error` came first), or the connection (`frame: null`). It was taken, and billed. */
+ | {
+    status: "interrupted";
+    frame: InterruptedFrame | null;
+} | Dropped;
+/** How a `transcribeOnly` recording ended. */
+export type TranscriptOutcome = {
+    status: "done";
+    text: string;
+    seconds: number;
+    frame: TranscriptFrame;
+}
+/** The edge refused or failed it: a rate it does not take, no audio, the provider. */
+ | {
+    status: "failed";
+    frame: ErrorFrame;
+} | Dropped;
+/** Never taken: the connection ended, `cancel()` dropped it, or it was refused before it was a turn. */
+export interface Dropped {
+    status: "dropped";
+    reason: "closed" | "cancelled" | "refused";
+    detail?: string;
+}
+/** Why a conversation ended without reconnecting. */
+export interface CloseInfo {
+    code: number;
+    reason: string;
+    /** `true` when reconnecting cannot help: `reconnect()` revives only a conversation that is not. */
+    final: boolean;
+    /** What `getToken` threw, when that ended it. */
+    error?: unknown;
+}
+type On<K extends keyof ServerFrames> = (frame: ServerFrames[K]) => void;
+/** A socket that closed: its code and reason, and whether it had reached `ready`. */
+export interface Disconnect {
+    code: number;
+    reason: string;
+    ready: boolean;
+}
+/** Every handler is optional; each is given the wire's frame as it is. */
+export interface ConversationHandlers {
+    onReady?: On<"ready">;
+    onTurnStart?: On<"turn.start">;
+    onHeard?: On<"heard">;
+    onHeardPartial?: On<"heard.partial">;
+    onKnowledge?: On<"knowledge">;
+    onMood?: On<"mood">;
+    onThought?: On<"thought.delta">;
+    onText?: On<"text.delta">;
+    onChunk?: On<"text.chunk">;
+    onToolStart?: On<"tool.start">;
+    onToolEnd?: On<"tool.end">;
+    onUsage?: On<"usage">;
+    onMuted?: On<"muted">;
+    onAudioStart?: On<"audio.start">;
+    onAudioEnd?: On<"audio.end">;
+    /** A reply's PCM, with its window's format. Its presence turns speech on (`ConnectOptions.speech`). */
+    onAudio?: (frame: AudioFrame) => void;
+    onTranscript?: On<"transcript">;
+    onDone?: On<"turn.done">;
+    onInterrupted?: On<"interrupted">;
+    /** The relationship, from `ready` and when it moves: each change once. */
+    onRelation?: (relation: RelationInfo) => void;
+    onError?: On<"error">;
+    onState?: (state: ConversationState) => void;
+    /** Only when it will **not** reconnect. */
+    onClose?: (close: CloseInfo) => void;
+    /**
+     * Every socket the edge or the network closed — `close()` aside — before
+     * the close table decides what follows: for logging a drop the
+     * conversation recovers from as well as one it does not.
+     */
+    onDisconnect?: (drop: Disconnect) => void;
+    onWarning?: (warning: Warning) => void;
+    /** Every frame, the ones above included: what a newer edge sends that this SDK does not know. */
+    onEvent?: (frame: ServerFrame) => void;
+}
+export interface ConnectOptions {
+    /**
+     * Every turn's `speech`. By default `false` when there is no `onAudio`
+     * handler — nothing would play it, and speech is billed — and otherwise
+     * the agent's own switch.
+     */
+    speech?: boolean;
+    /** Ask every turn for thinking summaries (`onThought`). */
+    thoughts?: boolean;
+}
+/** Per turn: overrides `ConnectOptions`. */
+export interface TurnOptions {
+    speech?: boolean;
+    thoughts?: boolean;
+}
+export interface StartAudioOptions extends TurnOptions {
+    /** The PCM's rate, Hz: one of `RECORDING_RATES`. Raw PCM has no header, so this is the only thing that says what the samples are — and what they are billed as. */
+    rate: number;
+    /** A language hint, 2 to 8 characters; detected per recording when unset. */
+    language?: string;
+    /** A transcription model (`STT_MODELS`); the agent's own when unset. */
+    model?: string;
+}
+/** What `client.connect` hands the conversation. */
+export interface Setup {
+    sessionId: string;
+    socketUrl: string;
+    tokens: Tokens;
+    WebSocket: WebSocketConstructor;
+    handlers: ConversationHandlers;
+    options: ConnectOptions;
+}
+/** No `ready` this long after the dial — a proxy that took the upgrade and says nothing — is a dropped connection. */
+export declare const READY_DEADLINE_MS = 15000;
+export declare class Conversation {
+    readonly sessionId: string;
+    private readonly setup;
+    private readonly speech;
+    private snap;
+    private listeners;
+    private socket;
+    /** Moves with every dial and every end: a callback from an older one is stale. */
+    private generation;
+    private key;
+    private attempts;
+    /** A new key was taken for a refusal, and no turn has finished on it yet. */
+    private replaced;
+    private closed;
+    /** Closed by giving up, not by a final code: `reconnect()` may dial again. */
+    private revivable;
+    private dormant;
+    private everReady;
+    /** The socket now open reached `ready`. */
+    private socketReady;
+    /** A turn this conversation did not send is running: the greeting. */
+    private running;
+    private inFlight;
+    private queue;
+    private open;
+    /** `transcribeOnly` recordings waiting for their words, oldest first. */
+    private hearing;
+    /** Recordings waiting for `ready`. */
+    private held;
+    private recordings;
+    /** The turn whose terminal frame was taken: a second for it says nothing new. */
+    private finished;
+    private relationSeen;
+    private retry;
+    private deadline;
+    private watchdog;
+    private heardAt;
+    private saidAt;
+    constructor(setup: Setup);
+    /** What is known now. A new object on every change: compare by identity. */
+    get snapshot(): Snapshot;
+    get state(): ConversationState;
+    /** `fn` is called after every change of `snapshot`. Answers the unsubscribe. */
+    subscribe(fn: () => void): () => void;
+    /**
+     * Take a turn by typing. Queued behind the greeting, a running turn, a
+     * reconnect or a quiet spell; answers how it ended, and never rejects.
+     * 1 to 32,000 characters, or it is `dropped: refused` here.
+     */
+    send(text: string, options?: TurnOptions): Promise<TurnOutcome>;
+    /**
+     * Open a recording at `rate`, which must be one of `RECORDING_RATES`.
+     * Answers its id. A recording already open is abandoned, as the edge
+     * abandons it.
+     */
+    startAudio(options: StartAudioOptions): string;
+    /**
+     * PCM for the open recording: 16-bit samples, or their little-endian
+     * bytes. Answers whether it was taken — not past the 10 MB a recording
+     * may carry (`onWarning`), nor with no recording open.
+     */
+    sendAudio(pcm: ArrayBuffer | Int16Array): boolean;
+    /**
+     * Close the recording. As a turn: queued like a `send`, and answered the
+     * same way. With `transcribeOnly`: no turn — the words come back for
+     * this recording alone, matched by its id, however its transcript and
+     * others' finish; `onTranscript` still fires for each.
+     */
+    endAudio(options: {
+        transcribeOnly: true;
+    }): Promise<TranscriptOutcome>;
+    endAudio(options?: {
+        transcribeOnly?: false;
+    }): Promise<TurnOutcome>;
+    /** Stop the turn in flight, and drop what is queued and the open recording. What was said is still billed and stored. */
+    cancel(): void;
+    /** Stop speaking, and let the turn finish: the rest of the reply is never spoken, nor billed. */
+    mute(): void;
+    /** Liveness only: answered with `pong`, and never counted as activity. Not needed — the SDK's watchdog listens for the edge's own. */
+    ping(): void;
+    /**
+     * Dial now: the app came to the foreground, the network came back. A
+     * dormant conversation, one waiting to retry, and one that gave up (not
+     * a final close) dial at once; a live one is left alone.
+     */
+    reconnect(): void;
+    /** End it, for good. Every pending promise answers `dropped: closed`. */
+    close(): void;
+    private dial;
+    /** A socket given up on from this side: lost as a dropped network is (1006). */
+    private drop;
+    /** The socket closed: settle what it carried, then reconnect, rest or end. */
+    private lost;
+    /** It will not reconnect: say why, once. */
+    private finish;
+    /** Closed: no socket, no timer, and every promise answered. */
+    private end;
+    private stopTimers;
+    private frame;
+    private ready;
+    /** The end of a turn: answers whether it was a second for the same turn, which says nothing new. */
+    private terminal;
+    private error;
+    /** An error naming a recording: it was refused, or failed. */
+    private refuse;
+    private transcript;
+    /** Each change of the relationship once: `ready` repeats it on every reconnect. */
+    private relate;
+    private enqueue;
+    /** The next queued turn goes, when nothing is running and the socket is ready. */
+    private pump;
+    /** A turn's frame with its `speech` and `thoughts`. */
+    private turnFrame;
+    /** The open recording is over before its end: the edge discards the rest. */
+    private abandon;
+    private said;
+    /** A recording's words are still to come: a partial is a caption. */
+    private listening;
+    private update;
+    private emit;
+    /** The state, from what is true now; `onState` when it moved. */
+    private sync;
+}
+export {};