@live-assistant/gemini 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Recep Tayyip Ekşi
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,12 @@
+# @live-assistant/gemini
+
+The Gemini Live implementation of `AssistantSession`: one WebSocket, its setup handshake, and the frames in both directions (binary JSON frames, 16 kHz in and 24 kHz out, generic tool calls and cancellations).
+
+```ts
+const session = new GeminiLiveSession();
+await session.connect({ token, model }); // wsUrl defaults to the constrained endpoint
+```
+
+Tokens come from `@live-assistant/token-server`. Gemini fixes the session's configuration when the token is minted.
+
+See the [overview](../README.md).

package/dist/dtos/live-server-message-dto.d.ts

@@ -0,0 +1,57 @@
+/**
+ * One frame as the Live API sends it, before anything is trusted about it.
+ *
+ * @remarks
+ * - **Every field is optional because the wire says so.** A frame carries
+ *   exactly one of these envelopes, and which one is not discriminated by any
+ *   tag — the presence of the key IS the tag. Modelling it as a union here
+ *   would be asserting a shape rather than describing one.
+ * - **`unknown` for anything nested that gets narrowed later.** The parts of a
+ *   model turn are the only place a wrong assumption is invisible: an
+ *   `inlineData` that is not base64 audio would decode to noise instead of
+ *   throwing, so the mapper checks rather than casts.
+ */
+export interface LiveServerMessageDto {
+    setupComplete?: Record<string, unknown>;
+    serverContent?: {
+        modelTurn?: {
+            parts?: {
+                inlineData?: {
+                    mimeType?: string;
+                    data?: string;
+                };
+                text?: string;
+            }[];
+        };
+        inputTranscription?: {
+            text?: string;
+        };
+        outputTranscription?: {
+            text?: string;
+        };
+        interrupted?: boolean;
+        turnComplete?: boolean;
+        generationComplete?: boolean;
+    };
+    toolCall?: {
+        functionCalls?: {
+            id?: string;
+            name?: string;
+            args?: Record<string, unknown>;
+        }[];
+    };
+    toolCallCancellation?: {
+        ids?: unknown[];
+    };
+    sessionResumptionUpdate?: {
+        newHandle?: string;
+        resumable?: boolean;
+    };
+    goAway?: {
+        timeLeft?: string;
+    };
+    usageMetadata?: {
+        totalTokenCount?: number;
+    };
+}
+//# sourceMappingURL=live-server-message-dto.d.ts.map

package/dist/dtos/live-server-message-dto.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"live-server-message-dto.d.ts","sourceRoot":"","sources":["../../src/dtos/live-server-message-dto.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AACH,MAAM,WAAW,oBAAoB;IACnC,aAAa,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IACxC,aAAa,CAAC,EAAE;QACd,SAAS,CAAC,EAAE;YAAE,KAAK,CAAC,EAAE;gBAAE,UAAU,CAAC,EAAE;oBAAE,QAAQ,CAAC,EAAE,MAAM,CAAC;oBAAC,IAAI,CAAC,EAAE,MAAM,CAAA;iBAAE,CAAC;gBAAC,IAAI,CAAC,EAAE,MAAM,CAAA;aAAE,EAAE,CAAA;SAAE,CAAC;QAC/F,kBAAkB,CAAC,EAAE;YAAE,IAAI,CAAC,EAAE,MAAM,CAAA;SAAE,CAAC;QACvC,mBAAmB,CAAC,EAAE;YAAE,IAAI,CAAC,EAAE,MAAM,CAAA;SAAE,CAAC;QACxC,WAAW,CAAC,EAAE,OAAO,CAAC;QACtB,YAAY,CAAC,EAAE,OAAO,CAAC;QACvB,kBAAkB,CAAC,EAAE,OAAO,CAAC;KAC9B,CAAC;IACF,QAAQ,CAAC,EAAE;QAAE,aAAa,CAAC,EAAE;YAAE,EAAE,CAAC,EAAE,MAAM,CAAC;YAAC,IAAI,CAAC,EAAE,MAAM,CAAC;YAAC,IAAI,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAA;SAAE,EAAE,CAAA;KAAE,CAAC;IAChG,oBAAoB,CAAC,EAAE;QAAE,GAAG,CAAC,EAAE,OAAO,EAAE,CAAA;KAAE,CAAC;IAC3C,uBAAuB,CAAC,EAAE;QAAE,SAAS,CAAC,EAAE,MAAM,CAAC;QAAC,SAAS,CAAC,EAAE,OAAO,CAAA;KAAE,CAAC;IACtE,MAAM,CAAC,EAAE;QAAE,QAAQ,CAAC,EAAE,MAAM,CAAA;KAAE,CAAC;IAC/B,aAAa,CAAC,EAAE;QAAE,eAAe,CAAC,EAAE,MAAM,CAAA;KAAE,CAAC;CAC9C"}

package/dist/dtos/live-server-message-dto.js

@@ -0,0 +1,3 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+//# sourceMappingURL=live-server-message-dto.js.map

package/dist/dtos/live-server-message-dto.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"live-server-message-dto.js","sourceRoot":"","sources":["../../src/dtos/live-server-message-dto.ts"],"names":[],"mappings":""}

package/dist/dtos/live-setup-request-dto.d.ts

@@ -0,0 +1,16 @@
+/**
+ * The one frame that opens a live session.
+ *
+ * It carries only the model. For a token minted WITH a setup — the way this
+ * package's token server mints them — the session's configuration (system
+ * instruction, tools, modality, transcription, compression, resumption) is
+ * fixed at mint time and anything sent here is discarded. Whether a token
+ * minted without one honours a client's setup is not yet measured. The frame
+ * is mandatory either way: without it the session never reaches `setupComplete`.
+ */
+export interface LiveSetupRequestDto {
+    setup: {
+        model: string;
+    };
+}
+//# sourceMappingURL=live-setup-request-dto.d.ts.map

package/dist/dtos/live-setup-request-dto.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"live-setup-request-dto.d.ts","sourceRoot":"","sources":["../../src/dtos/live-setup-request-dto.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AACH,MAAM,WAAW,mBAAmB;IAClC,KAAK,EAAE;QAAE,KAAK,EAAE,MAAM,CAAA;KAAE,CAAC;CAC1B"}

package/dist/dtos/live-setup-request-dto.js

@@ -0,0 +1,3 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+//# sourceMappingURL=live-setup-request-dto.js.map

package/dist/dtos/live-setup-request-dto.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"live-setup-request-dto.js","sourceRoot":"","sources":["../../src/dtos/live-setup-request-dto.ts"],"names":[],"mappings":""}

package/dist/gemini-live-credentials.d.ts

@@ -0,0 +1,22 @@
+/**
+ * What a Gemini Live session needs to connect.
+ *
+ * @remarks
+ * - **An ephemeral token, never an API key.** Your server holds the key and
+ *   mints a short-lived `auth_tokens/…` token per session; the device only ever
+ *   holds that.
+ * - **The session's configuration is baked into the token.** System
+ *   instruction, tools, voice and transcription are set when the token is
+ *   minted: measured against the live API, a client's own setup is discarded
+ *   for a token that carries one, and tools the token did not declare simply
+ *   do not exist — with no error saying so.
+ * - **`model` must be the one the token was minted for**, e.g.
+ *   `models/gemini-live-2.5-flash-preview`. `wsUrl` defaults to the constrained
+ *   endpoint, the only one an ephemeral token opens.
+ */
+export interface GeminiLiveCredentials {
+    readonly token: string;
+    readonly model: string;
+    readonly wsUrl?: string;
+}
+//# sourceMappingURL=gemini-live-credentials.d.ts.map

package/dist/gemini-live-credentials.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"gemini-live-credentials.d.ts","sourceRoot":"","sources":["../src/gemini-live-credentials.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AACH,MAAM,WAAW,qBAAqB;IACpC,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,KAAK,CAAC,EAAE,MAAM,CAAC;CACzB"}

package/dist/gemini-live-credentials.js

@@ -0,0 +1,3 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+//# sourceMappingURL=gemini-live-credentials.js.map

package/dist/gemini-live-credentials.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"gemini-live-credentials.js","sourceRoot":"","sources":["../src/gemini-live-credentials.ts"],"names":[],"mappings":""}

package/dist/gemini-live-session.d.ts

@@ -0,0 +1,57 @@
+import type { AssistantFailure, AssistantSession, AudioFormat, Result, SessionEvent, ToolCall } from '@live-assistant/core';
+import type { GeminiLiveCredentials } from './gemini-live-credentials';
+/**
+ * The Live API transport: one WebSocket, its setup handshake, and the JSON
+ * frames in both directions.
+ *
+ * @remarks
+ * - **The token rides on the URL, and nothing else authenticates.** A browser
+ *   WebSocket cannot set a header, so the credential is a query parameter or it
+ *   is nowhere. Opened without it the handshake still completes and the server
+ *   then closes the socket — which looks, from the client, exactly like a
+ *   connection that hangs.
+ * - **Connected means `setupComplete`, not open.** The socket opens before the
+ *   server has accepted the model, the tool list or the modality, and audio
+ *   sent in that window is discarded silently rather than rejected. `connect`
+ *   resolves on the acknowledgement, so a caller that awaits it can start the
+ *   microphone knowing the frames will land.
+ * - **Listeners are notified in frame order, and one frame yields several
+ *   events.** The mapper decides that order — notably `interrupted` ahead of
+ *   any audio beside it — so this class must not reorder or batch them.
+ * - **A listener that throws must not kill the socket.** One consumer's bad
+ *   render would otherwise take down the audio session and every other
+ *   listener with it.
+ * - **The resumption handle is remembered but never acted on here.** It cannot
+ *   be: a handle put in the setup frame is discarded, so continuing a session
+ *   means minting a new token with it. Reconnecting also asks whether the user
+ *   still wants to be talking, which is a policy question either way; this
+ *   class only keeps the handle and reports the `goAway` that makes it matter.
+ * - **Whether a close was expected is tracked per socket**, not in a field. A
+ *   reconnect closes the old socket and opens a new one in the same tick, and a
+ *   single flag was read by the old socket's `onclose` after the new
+ *   connection had already reset it — reporting a deliberate close as a drop.
+ */
+type SocketFactory = (url: string) => WebSocket;
+export declare class GeminiLiveSession implements AssistantSession<GeminiLiveCredentials> {
+    private readonly createSocket;
+    readonly audioFormat: AudioFormat;
+    private socket;
+    private readonly listeners;
+    private readonly deliberatelyClosed;
+    private resumptionHandle;
+    constructor(createSocket?: SocketFactory);
+    /** The latest handle a new token can be minted with to continue after a `goAway`. */
+    get lastResumptionHandle(): string | null;
+    connect(credentials: GeminiLiveCredentials): Promise<Result<void, AssistantFailure>>;
+    sendAudio(samples: Float32Array<ArrayBuffer>): void;
+    sendText(text: string): void;
+    respondToTool(call: Pick<ToolCall, 'id' | 'name'>, response: Readonly<Record<string, unknown>>): void;
+    subscribe(listener: (event: SessionEvent) => void): () => void;
+    close(): void;
+    private get isOpen();
+    private send;
+    private parse;
+    private emit;
+}
+export {};
+//# sourceMappingURL=gemini-live-session.d.ts.map

package/dist/gemini-live-session.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"gemini-live-session.d.ts","sourceRoot":"","sources":["../src/gemini-live-session.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,gBAAgB,EAAE,gBAAgB,EAAE,WAAW,EAAE,MAAM,EAAE,YAAY,EAAE,QAAQ,EAAE,MAAM,sBAAsB,CAAC;AAE5H,OAAO,KAAK,EAAE,qBAAqB,EAAE,MAAM,2BAA2B,CAAC;AAMvE;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA8BG;AAGH,KAAK,aAAa,GAAG,CAAC,GAAG,EAAE,MAAM,KAAK,SAAS,CAAC;AAmDhD,qBAAa,iBAAkB,YAAW,gBAAgB,CAAC,qBAAqB,CAAC;IAWnE,OAAO,CAAC,QAAQ,CAAC,YAAY;IAVzC,QAAQ,CAAC,WAAW,EAAE,WAAW,CAG/B;IAEF,OAAO,CAAC,MAAM,CAA0B;IACxC,OAAO,CAAC,QAAQ,CAAC,SAAS,CAA4C;IACtE,OAAO,CAAC,QAAQ,CAAC,kBAAkB,CAA4B;IAC/D,OAAO,CAAC,gBAAgB,CAAuB;gBAElB,YAAY,GAAE,aAA2C;IAEtF,qFAAqF;IACrF,IAAI,oBAAoB,IAAI,MAAM,GAAG,IAAI,CAExC;IAED,OAAO,CAAC,WAAW,EAAE,qBAAqB,GAAG,OAAO,CAAC,MAAM,CAAC,IAAI,EAAE,gBAAgB,CAAC,CAAC;IAmDpF,SAAS,CAAC,OAAO,EAAE,YAAY,CAAC,WAAW,CAAC,GAAG,IAAI;IAYnD,QAAQ,CAAC,IAAI,EAAE,MAAM,GAAG,IAAI;IAM5B,aAAa,CAAC,IAAI,EAAE,IAAI,CAAC,QAAQ,EAAE,IAAI,GAAG,MAAM,CAAC,EAAE,QAAQ,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,GAAG,IAAI;IAIrG,SAAS,CAAC,QAAQ,EAAE,CAAC,KAAK,EAAE,YAAY,KAAK,IAAI,GAAG,MAAM,IAAI;IAO9D,KAAK,IAAI,IAAI;IASb,OAAO,KAAK,MAAM,GAEjB;IAED,OAAO,CAAC,IAAI;IASZ,OAAO,CAAC,KAAK;IAYb,OAAO,CAAC,IAAI;CASb"}

package/dist/gemini-live-session.js

@@ -0,0 +1,190 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.GeminiLiveSession = void 0;
+const core_1 = require("@live-assistant/core");
+const guards_1 = require("./guards");
+const live_protocol_1 = require("./live-protocol");
+const live_message_mapper_1 = require("./live-message-mapper");
+const live_setup_request_1 = require("./live-setup-request");
+const SOCKET_OPEN = 1;
+const ARRAY_BUFFER = 'arraybuffer';
+/**
+ * How long a socket may take to reach `setupComplete` before it is abandoned.
+ *
+ * Without it a socket that opened, took the setup frame and then said nothing
+ * left `connect` pending forever — and a caller that opens the microphone
+ * first would hold the recording device open with nothing counting against it.
+ */
+const CONNECT_TIMEOUT_MS = 15_000;
+const QUERY_START = '?';
+const QUERY_JOIN = '&';
+/**
+ * The socket URL with the session's credential on it.
+ *
+ * The token is the ONLY thing that authenticates this connection — there is no
+ * header to put it in, because a browser WebSocket cannot set one. Opened
+ * without it the socket completes its handshake and is then closed by the
+ * server, which reads as "connecting, and then nothing".
+ *
+ * `access_token` is deliberately NOT percent-encoded. The name contains a
+ * slash (`auth_tokens/…`), and encoding it produced a socket the server
+ * refused — measured against the live API, along with the `key=` spelling,
+ * which it also refuses.
+ */
+function authenticatedUrl(credentials) {
+    const wsUrl = credentials.wsUrl ?? live_protocol_1.LiveProtocol.constrainedWsUrl;
+    const separator = wsUrl.includes(QUERY_START) ? QUERY_JOIN : QUERY_START;
+    return `${wsUrl}${separator}access_token=${credentials.token}`;
+}
+/**
+ * Reads one incoming frame as text.
+ *
+ * The Live API sends its JSON as BINARY WebSocket frames, not text ones — every
+ * frame, including `setupComplete`. A transport that accepted only strings
+ * silently received nothing at all, and its unit tests passed because a fake
+ * socket naturally sends strings. `binaryType` is set to `arraybuffer` so this
+ * stays synchronous; a Blob would have to be awaited, and the mapper's ordering
+ * guarantee does not survive an await between frames.
+ */
+function decodeFrame(data) {
+    if ((0, guards_1.isString)(data))
+        return data;
+    if (data instanceof ArrayBuffer)
+        return new TextDecoder().decode(data);
+    if (ArrayBuffer.isView(data))
+        return new TextDecoder().decode(data.buffer);
+    return null;
+}
+class GeminiLiveSession {
+    constructor(createSocket = (url) => new WebSocket(url)) {
+        this.createSocket = createSocket;
+        this.audioFormat = {
+            inputSampleRate: live_protocol_1.LiveProtocol.inputSampleRate,
+            outputSampleRate: live_protocol_1.LiveProtocol.outputSampleRate,
+        };
+        this.socket = null;
+        this.listeners = new Set();
+        this.deliberatelyClosed = new WeakSet();
+        this.resumptionHandle = null;
+    }
+    /** The latest handle a new token can be minted with to continue after a `goAway`. */
+    get lastResumptionHandle() {
+        return this.resumptionHandle;
+    }
+    connect(credentials) {
+        this.close();
+        return new Promise((resolve) => {
+            let settled = false;
+            const timer = setTimeout(() => {
+                // Settled BEFORE closing: a runtime whose `close()` fires `onclose`
+                // synchronously would otherwise answer with "closed before ready" and
+                // this reason would never be the one anybody reads.
+                settle((0, core_1.fail)({ code: core_1.AssistantFailureCode.ConnectTimedOut }));
+                this.close();
+            }, CONNECT_TIMEOUT_MS);
+            const settle = (result) => {
+                if (settled)
+                    return;
+                settled = true;
+                clearTimeout(timer);
+                resolve(result);
+            };
+            const socket = this.createSocket(authenticatedUrl(credentials));
+            // The server sends its JSON in BINARY frames. Without this the runtime
+            // hands them over as Blob, which cannot be read synchronously.
+            socket.binaryType = ARRAY_BUFFER;
+            this.socket = socket;
+            socket.onopen = () => {
+                socket.send(JSON.stringify((0, live_setup_request_1.toLiveSetupRequest)({ model: credentials.model })));
+            };
+            socket.onmessage = (event) => {
+                for (const mapped of this.parse(event.data)) {
+                    if (mapped.kind === core_1.SessionEventKind.Ready)
+                        settle((0, core_1.ok)(undefined));
+                    if (mapped.kind === core_1.SessionEventKind.Resumption)
+                        this.resumptionHandle = mapped.handle;
+                    this.emit(mapped);
+                }
+            };
+            socket.onerror = () => {
+                settle((0, core_1.fail)({ code: core_1.AssistantFailureCode.SocketFailed }));
+            };
+            socket.onclose = () => {
+                const expected = this.deliberatelyClosed.has(socket);
+                if (this.socket === socket)
+                    this.socket = null;
+                settle((0, core_1.fail)({ code: core_1.AssistantFailureCode.ClosedBeforeReady }));
+                this.emit({ kind: core_1.SessionEventKind.Closed, expected });
+            };
+        });
+    }
+    sendAudio(samples) {
+        if (samples.length === 0)
+            return;
+        // Checked before encoding, not after: capture now starts before the socket
+        // does, so every frame in that window used to be converted to base64 and
+        // then dropped by `send`.
+        if (!this.isOpen)
+            return;
+        this.send({
+            realtimeInput: { audio: { data: (0, core_1.float32ToPcm16Base64)(samples), mimeType: live_protocol_1.LiveProtocol.inputAudioMime } },
+        });
+    }
+    sendText(text) {
+        if (text === '')
+            return;
+        this.send({ clientContent: { turns: [{ role: live_protocol_1.LiveProtocol.userRole, parts: [{ text }] }], turnComplete: true } });
+    }
+    respondToTool(call, response) {
+        this.send({ toolResponse: { functionResponses: [{ id: call.id, name: call.name, response }] } });
+    }
+    subscribe(listener) {
+        this.listeners.add(listener);
+        return () => {
+            this.listeners.delete(listener);
+        };
+    }
+    close() {
+        const socket = this.socket;
+        this.socket = null;
+        if (socket === null)
+            return;
+        this.deliberatelyClosed.add(socket);
+        socket.close();
+    }
+    get isOpen() {
+        return this.socket !== null && this.socket.readyState === SOCKET_OPEN;
+    }
+    send(message) {
+        // A frame produced after the socket went away is dropped: it is one frame
+        // of audio, and there is nothing a caller could usefully do about it.
+        const socket = this.socket;
+        if (socket === null || socket.readyState !== SOCKET_OPEN)
+            return;
+        socket.send(JSON.stringify(message));
+    }
+    parse(data) {
+        const text = decodeFrame(data);
+        if (text === null)
+            return [];
+        try {
+            return (0, live_message_mapper_1.mapLiveServerMessage)(JSON.parse(text));
+        }
+        catch {
+            // A frame we cannot read is not a reason to drop a live conversation.
+            return [];
+        }
+    }
+    emit(event) {
+        for (const listener of this.listeners) {
+            try {
+                listener(event);
+            }
+            catch {
+                // One listener's failure must not take down the audio session.
+            }
+        }
+    }
+}
+exports.GeminiLiveSession = GeminiLiveSession;
+//# sourceMappingURL=gemini-live-session.js.map

package/dist/gemini-live-session.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"gemini-live-session.js","sourceRoot":"","sources":["../src/gemini-live-session.ts"],"names":[],"mappings":"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"}

package/dist/guards.d.ts

@@ -0,0 +1,4 @@
+/** Narrowing helpers for frames this package did not produce. */
+export declare const isString: (value: unknown) => value is string;
+export declare const isNonEmptyString: (value: unknown) => value is string;
+//# sourceMappingURL=guards.d.ts.map

package/dist/guards.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"guards.d.ts","sourceRoot":"","sources":["../src/guards.ts"],"names":[],"mappings":"AAAA,iEAAiE;AACjE,eAAO,MAAM,QAAQ,GAAI,OAAO,OAAO,KAAG,KAAK,IAAI,MAAmC,CAAC;AAEvF,eAAO,MAAM,gBAAgB,GAAI,OAAO,OAAO,KAAG,KAAK,IAAI,MAA6C,CAAC"}

package/dist/guards.js

@@ -0,0 +1,9 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.isNonEmptyString = exports.isString = void 0;
+/** Narrowing helpers for frames this package did not produce. */
+const isString = (value) => typeof value === 'string';
+exports.isString = isString;
+const isNonEmptyString = (value) => (0, exports.isString)(value) && value.length > 0;
+exports.isNonEmptyString = isNonEmptyString;
+//# sourceMappingURL=guards.js.map

package/dist/guards.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"guards.js","sourceRoot":"","sources":["../src/guards.ts"],"names":[],"mappings":";;;AAAA,iEAAiE;AAC1D,MAAM,QAAQ,GAAG,CAAC,KAAc,EAAmB,EAAE,CAAC,OAAO,KAAK,KAAK,QAAQ,CAAC;AAA1E,QAAA,QAAQ,YAAkE;AAEhF,MAAM,gBAAgB,GAAG,CAAC,KAAc,EAAmB,EAAE,CAAC,IAAA,gBAAQ,EAAC,KAAK,CAAC,IAAI,KAAK,CAAC,MAAM,GAAG,CAAC,CAAC;AAA5F,QAAA,gBAAgB,oBAA4E"}

package/dist/index.d.ts

@@ -0,0 +1,3 @@
+export { GeminiLiveSession } from './gemini-live-session';
+export type { GeminiLiveCredentials } from './gemini-live-credentials';
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,iBAAiB,EAAE,MAAM,uBAAuB,CAAC;AAC1D,YAAY,EAAE,qBAAqB,EAAE,MAAM,2BAA2B,CAAC"}

package/dist/index.js

@@ -0,0 +1,6 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.GeminiLiveSession = void 0;
+var gemini_live_session_1 = require("./gemini-live-session");
+Object.defineProperty(exports, "GeminiLiveSession", { enumerable: true, get: function () { return gemini_live_session_1.GeminiLiveSession; } });
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":";;;AAAA,6DAA0D;AAAjD,wHAAA,iBAAiB,OAAA"}

package/dist/live-message-mapper.d.ts

@@ -0,0 +1,4 @@
+import type { SessionEvent } from '@live-assistant/core';
+import type { LiveServerMessageDto } from './dtos/live-server-message-dto';
+export declare function mapLiveServerMessage(dto: LiveServerMessageDto): SessionEvent[];
+//# sourceMappingURL=live-message-mapper.d.ts.map

package/dist/live-message-mapper.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"live-message-mapper.d.ts","sourceRoot":"","sources":["../src/live-message-mapper.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,sBAAsB,CAAC;AACzD,OAAO,KAAK,EAAE,oBAAoB,EAAE,MAAM,gCAAgC,CAAC;AAyC3E,wBAAgB,oBAAoB,CAAC,GAAG,EAAE,oBAAoB,GAAG,YAAY,EAAE,CAgD9E"}

package/dist/live-message-mapper.js

@@ -0,0 +1,84 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.mapLiveServerMessage = mapLiveServerMessage;
+const core_1 = require("@live-assistant/core");
+const guards_1 = require("./guards");
+/**
+ * Turns one Live API frame into the events a consumer acts on.
+ *
+ * @remarks
+ * - **A frame is not an event; it is a bag of them.** A single `serverContent`
+ *   routinely carries a transcript fragment, several audio chunks and the end
+ *   of the turn at once, so this returns a list. Mapping one frame to one event
+ *   would have meant picking which of them to lose.
+ * - **Order within the frame is the order they must be handled.** `interrupted`
+ *   is emitted before any audio in the same frame: the server can mark a turn
+ *   interrupted and still include trailing chunks of it, and handling those
+ *   first would enqueue exactly the audio the flush was meant to drop.
+ * - **`turnComplete`, not `generationComplete`.** The latter fires when the
+ *   model stops generating, which is before the audio it generated has been
+ *   sent — treating it as the end of the turn cuts the last words off.
+ * - **`timeLeft` is a protobuf duration string** (`"9.5s"`), not a number, and
+ *   parsing it as one silently yields `NaN` for every value with a unit.
+ * - **A tool call keeps its name and raw `args`.** The package does not know
+ *   which tools a consumer declared, so it neither validates nor narrows them;
+ *   a call is dropped only when it has no id or name, because nothing could
+ *   answer it.
+ * - **Unknown frames map to nothing rather than to a failure.** The API adds
+ *   message types over time and a session that fell over on an unrecognised
+ *   one would be broken by a server-side release.
+ */
+const AUDIO_MIME_PREFIX = 'audio/';
+const SECONDS_SUFFIX = 's';
+const MS_PER_SECOND = 1000;
+function parseTimeLeftMs(timeLeft) {
+    if (!(0, guards_1.isNonEmptyString)(timeLeft))
+        return 0;
+    const seconds = Number.parseFloat(timeLeft.endsWith(SECONDS_SUFFIX) ? timeLeft.slice(0, -SECONDS_SUFFIX.length) : timeLeft);
+    return Number.isFinite(seconds) ? seconds * MS_PER_SECOND : 0;
+}
+function mapLiveServerMessage(dto) {
+    const events = [];
+    if (dto.setupComplete !== undefined)
+        events.push({ kind: core_1.SessionEventKind.Ready });
+    const content = dto.serverContent;
+    if (content !== undefined) {
+        if (content.interrupted === true)
+            events.push({ kind: core_1.SessionEventKind.Interrupted });
+        const heard = content.inputTranscription?.text;
+        if ((0, guards_1.isNonEmptyString)(heard)) {
+            events.push({ kind: core_1.SessionEventKind.Transcript, speaker: core_1.Speaker.User, text: heard });
+        }
+        const said = content.outputTranscription?.text;
+        if ((0, guards_1.isNonEmptyString)(said)) {
+            events.push({ kind: core_1.SessionEventKind.Transcript, speaker: core_1.Speaker.Assistant, text: said });
+        }
+        for (const part of content.modelTurn?.parts ?? []) {
+            const data = part.inlineData?.data;
+            if ((0, guards_1.isNonEmptyString)(data) && (part.inlineData?.mimeType ?? '').startsWith(AUDIO_MIME_PREFIX)) {
+                events.push({ kind: core_1.SessionEventKind.Audio, samples: (0, core_1.pcm16Base64ToFloat32)(data) });
+            }
+        }
+        if (content.turnComplete === true)
+            events.push({ kind: core_1.SessionEventKind.TurnComplete });
+    }
+    for (const call of dto.toolCall?.functionCalls ?? []) {
+        if (!(0, guards_1.isNonEmptyString)(call.id) || !(0, guards_1.isNonEmptyString)(call.name))
+            continue;
+        events.push({ kind: core_1.SessionEventKind.ToolCall, call: { id: call.id, name: call.name, args: call.args ?? {} } });
+    }
+    const cancelled = (dto.toolCallCancellation?.ids ?? []).filter(guards_1.isNonEmptyString);
+    if (cancelled.length > 0)
+        events.push({ kind: core_1.SessionEventKind.ToolCallCancelled, callIds: cancelled });
+    const handle = dto.sessionResumptionUpdate?.newHandle;
+    if ((0, guards_1.isNonEmptyString)(handle))
+        events.push({ kind: core_1.SessionEventKind.Resumption, handle });
+    if (dto.goAway !== undefined) {
+        events.push({ kind: core_1.SessionEventKind.GoAway, timeLeftMs: parseTimeLeftMs(dto.goAway.timeLeft) });
+    }
+    const totalTokens = dto.usageMetadata?.totalTokenCount;
+    if (typeof totalTokens === 'number')
+        events.push({ kind: core_1.SessionEventKind.Usage, totalTokens });
+    return events;
+}
+//# sourceMappingURL=live-message-mapper.js.map

package/dist/live-message-mapper.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"live-message-mapper.js","sourceRoot":"","sources":["../src/live-message-mapper.ts"],"names":[],"mappings":"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"}

package/dist/live-protocol.d.ts

@@ -0,0 +1,20 @@
+/**
+ * The Live API's fixed wire values, defined once.
+ *
+ * @remarks
+ * - **The input rate is the client's to state; the output rate is not.** The
+ *   microphone frame declares 16 kHz because that is what the audio layer
+ *   resamples to. The model answers at 24 kHz regardless.
+ * - **`constrainedWsUrl` is the only socket an ephemeral token opens.** The
+ *   ordinary `BidiGenerateContent` method refuses one ("Method doesn't allow
+ *   unregistered callers"), measured against the live API.
+ */
+export declare const LiveProtocol: {
+    readonly constrainedWsUrl: string;
+    readonly inputAudioMime: "audio/pcm;rate=16000";
+    /** The wire `role` of a typed turn. Gemini's word, kept apart from `Speaker` so renaming one cannot break the other. */
+    readonly userRole: "user";
+    readonly outputSampleRate: 24000;
+    readonly inputSampleRate: 16000;
+};
+//# sourceMappingURL=live-protocol.d.ts.map

package/dist/live-protocol.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"live-protocol.d.ts","sourceRoot":"","sources":["../src/live-protocol.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AACH,eAAO,MAAM,YAAY;;;IAKvB,wHAAwH;;;;CAIhH,CAAC"}

package/dist/live-protocol.js

@@ -0,0 +1,24 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.LiveProtocol = void 0;
+/**
+ * The Live API's fixed wire values, defined once.
+ *
+ * @remarks
+ * - **The input rate is the client's to state; the output rate is not.** The
+ *   microphone frame declares 16 kHz because that is what the audio layer
+ *   resamples to. The model answers at 24 kHz regardless.
+ * - **`constrainedWsUrl` is the only socket an ephemeral token opens.** The
+ *   ordinary `BidiGenerateContent` method refuses one ("Method doesn't allow
+ *   unregistered callers"), measured against the live API.
+ */
+exports.LiveProtocol = {
+    constrainedWsUrl: 'wss://generativelanguage.googleapis.com/ws/' +
+        'google.ai.generativelanguage.v1alpha.GenerativeService.BidiGenerateContentConstrained',
+    inputAudioMime: 'audio/pcm;rate=16000',
+    /** The wire `role` of a typed turn. Gemini's word, kept apart from `Speaker` so renaming one cannot break the other. */
+    userRole: 'user',
+    outputSampleRate: 24_000,
+    inputSampleRate: 16_000,
+};
+//# sourceMappingURL=live-protocol.js.map

package/dist/live-protocol.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"live-protocol.js","sourceRoot":"","sources":["../src/live-protocol.ts"],"names":[],"mappings":";;;AAAA;;;;;;;;;;GAUG;AACU,QAAA,YAAY,GAAG;IAC1B,gBAAgB,EACd,6CAA6C;QAC7C,uFAAuF;IACzF,cAAc,EAAE,sBAAsB;IACtC,wHAAwH;IACxH,QAAQ,EAAE,MAAM;IAChB,gBAAgB,EAAE,MAAM;IACxB,eAAe,EAAE,MAAM;CACf,CAAC"}

package/dist/live-setup-request.d.ts

@@ -0,0 +1,10 @@
+import type { LiveSetupRequestDto } from './dtos/live-setup-request-dto';
+/**
+ * The first frame on the socket. It only names the model: for a token minted
+ * with a setup, the instruction, tools and voice are baked in at mint time and
+ * the Live API discards whatever a client puts here beyond the model.
+ */
+export declare const toLiveSetupRequest: (input: {
+    model: string;
+}) => LiveSetupRequestDto;
+//# sourceMappingURL=live-setup-request.d.ts.map

package/dist/live-setup-request.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"live-setup-request.d.ts","sourceRoot":"","sources":["../src/live-setup-request.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,+BAA+B,CAAC;AAEzE;;;;GAIG;AACH,eAAO,MAAM,kBAAkB,GAAI,OAAO;IAAE,KAAK,EAAE,MAAM,CAAA;CAAE,KAAG,mBAE5D,CAAC"}

package/dist/live-setup-request.js

@@ -0,0 +1,13 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.toLiveSetupRequest = void 0;
+/**
+ * The first frame on the socket. It only names the model: for a token minted
+ * with a setup, the instruction, tools and voice are baked in at mint time and
+ * the Live API discards whatever a client puts here beyond the model.
+ */
+const toLiveSetupRequest = (input) => ({
+    setup: { model: input.model },
+});
+exports.toLiveSetupRequest = toLiveSetupRequest;
+//# sourceMappingURL=live-setup-request.js.map

package/dist/live-setup-request.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"live-setup-request.js","sourceRoot":"","sources":["../src/live-setup-request.ts"],"names":[],"mappings":";;;AAEA;;;;GAIG;AACI,MAAM,kBAAkB,GAAG,CAAC,KAAwB,EAAuB,EAAE,CAAC,CAAC;IACpF,KAAK,EAAE,EAAE,KAAK,EAAE,KAAK,CAAC,KAAK,EAAE;CAC9B,CAAC,CAAC;AAFU,QAAA,kBAAkB,sBAE5B"}

package/package.json

@@ -0,0 +1,45 @@
+{
+  "name": "@live-assistant/gemini",
+  "version": "0.1.0",
+  "description": "Gemini Live adapter for @live-assistant/core: the socket, its setup handshake and the frames in both directions.",
+  "license": "MIT",
+  "author": "Recep Tayyip Ekşi",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/Recipely-Team/live-assistant.git",
+    "directory": "packages/assistant-gemini"
+  },
+  "homepage": "https://github.com/Recipely-Team/live-assistant/tree/main/packages/assistant-gemini#readme",
+  "bugs": {
+    "url": "https://github.com/Recipely-Team/live-assistant/issues"
+  },
+  "keywords": [
+    "gemini",
+    "gemini-live",
+    "voice-assistant",
+    "realtime",
+    "websocket",
+    "ai"
+  ],
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "files": [
+    "dist",
+    "src",
+    "README.md",
+    "LICENSE",
+    "!src/**/__tests__",
+    "!src/**/__fixtures__"
+  ],
+  "sideEffects": false,
+  "scripts": {
+    "build": "node -e \"require('fs').rmSync('dist',{recursive:true,force:true})\" && tsc -p tsconfig.build.json",
+    "prepack": "npm run build"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "dependencies": {
+    "@live-assistant/core": "0.1.0"
+  }
+}

package/src/dtos/live-server-message-dto.ts

@@ -0,0 +1,29 @@
+/**
+ * One frame as the Live API sends it, before anything is trusted about it.
+ *
+ * @remarks
+ * - **Every field is optional because the wire says so.** A frame carries
+ *   exactly one of these envelopes, and which one is not discriminated by any
+ *   tag — the presence of the key IS the tag. Modelling it as a union here
+ *   would be asserting a shape rather than describing one.
+ * - **`unknown` for anything nested that gets narrowed later.** The parts of a
+ *   model turn are the only place a wrong assumption is invisible: an
+ *   `inlineData` that is not base64 audio would decode to noise instead of
+ *   throwing, so the mapper checks rather than casts.
+ */
+export interface LiveServerMessageDto {
+  setupComplete?: Record<string, unknown>;
+  serverContent?: {
+    modelTurn?: { parts?: { inlineData?: { mimeType?: string; data?: string }; text?: string }[] };
+    inputTranscription?: { text?: string };
+    outputTranscription?: { text?: string };
+    interrupted?: boolean;
+    turnComplete?: boolean;
+    generationComplete?: boolean;
+  };
+  toolCall?: { functionCalls?: { id?: string; name?: string; args?: Record<string, unknown> }[] };
+  toolCallCancellation?: { ids?: unknown[] };
+  sessionResumptionUpdate?: { newHandle?: string; resumable?: boolean };
+  goAway?: { timeLeft?: string };
+  usageMetadata?: { totalTokenCount?: number };
+}

package/src/dtos/live-setup-request-dto.ts

@@ -0,0 +1,13 @@
+/**
+ * The one frame that opens a live session.
+ *
+ * It carries only the model. For a token minted WITH a setup — the way this
+ * package's token server mints them — the session's configuration (system
+ * instruction, tools, modality, transcription, compression, resumption) is
+ * fixed at mint time and anything sent here is discarded. Whether a token
+ * minted without one honours a client's setup is not yet measured. The frame
+ * is mandatory either way: without it the session never reaches `setupComplete`.
+ */
+export interface LiveSetupRequestDto {
+  setup: { model: string };
+}

package/src/gemini-live-credentials.ts

@@ -0,0 +1,21 @@
+/**
+ * What a Gemini Live session needs to connect.
+ *
+ * @remarks
+ * - **An ephemeral token, never an API key.** Your server holds the key and
+ *   mints a short-lived `auth_tokens/…` token per session; the device only ever
+ *   holds that.
+ * - **The session's configuration is baked into the token.** System
+ *   instruction, tools, voice and transcription are set when the token is
+ *   minted: measured against the live API, a client's own setup is discarded
+ *   for a token that carries one, and tools the token did not declare simply
+ *   do not exist — with no error saying so.
+ * - **`model` must be the one the token was minted for**, e.g.
+ *   `models/gemini-live-2.5-flash-preview`. `wsUrl` defaults to the constrained
+ *   endpoint, the only one an ephemeral token opens.
+ */
+export interface GeminiLiveCredentials {
+  readonly token: string;
+  readonly model: string;
+  readonly wsUrl?: string;
+}

package/src/gemini-live-session.ts

@@ -0,0 +1,235 @@
+import { AssistantFailureCode, SessionEventKind, fail, float32ToPcm16Base64, ok } from '@live-assistant/core';
+import type { AssistantFailure, AssistantSession, AudioFormat, Result, SessionEvent, ToolCall } from '@live-assistant/core';
+import type { LiveServerMessageDto } from './dtos/live-server-message-dto';
+import type { GeminiLiveCredentials } from './gemini-live-credentials';
+import { isString } from './guards';
+import { LiveProtocol } from './live-protocol';
+import { mapLiveServerMessage } from './live-message-mapper';
+import { toLiveSetupRequest } from './live-setup-request';
+
+/**
+ * The Live API transport: one WebSocket, its setup handshake, and the JSON
+ * frames in both directions.
+ *
+ * @remarks
+ * - **The token rides on the URL, and nothing else authenticates.** A browser
+ *   WebSocket cannot set a header, so the credential is a query parameter or it
+ *   is nowhere. Opened without it the handshake still completes and the server
+ *   then closes the socket — which looks, from the client, exactly like a
+ *   connection that hangs.
+ * - **Connected means `setupComplete`, not open.** The socket opens before the
+ *   server has accepted the model, the tool list or the modality, and audio
+ *   sent in that window is discarded silently rather than rejected. `connect`
+ *   resolves on the acknowledgement, so a caller that awaits it can start the
+ *   microphone knowing the frames will land.
+ * - **Listeners are notified in frame order, and one frame yields several
+ *   events.** The mapper decides that order — notably `interrupted` ahead of
+ *   any audio beside it — so this class must not reorder or batch them.
+ * - **A listener that throws must not kill the socket.** One consumer's bad
+ *   render would otherwise take down the audio session and every other
+ *   listener with it.
+ * - **The resumption handle is remembered but never acted on here.** It cannot
+ *   be: a handle put in the setup frame is discarded, so continuing a session
+ *   means minting a new token with it. Reconnecting also asks whether the user
+ *   still wants to be talking, which is a policy question either way; this
+ *   class only keeps the handle and reports the `goAway` that makes it matter.
+ * - **Whether a close was expected is tracked per socket**, not in a field. A
+ *   reconnect closes the old socket and opens a new one in the same tick, and a
+ *   single flag was read by the old socket's `onclose` after the new
+ *   connection had already reset it — reporting a deliberate close as a drop.
+ */
+// Injected so the whole state machine can be driven against a fake, which is
+// the only way any of this is testable without a network and a key.
+type SocketFactory = (url: string) => WebSocket;
+
+const SOCKET_OPEN = 1;
+const ARRAY_BUFFER = 'arraybuffer';
+/**
+ * How long a socket may take to reach `setupComplete` before it is abandoned.
+ *
+ * Without it a socket that opened, took the setup frame and then said nothing
+ * left `connect` pending forever — and a caller that opens the microphone
+ * first would hold the recording device open with nothing counting against it.
+ */
+const CONNECT_TIMEOUT_MS = 15_000;
+const QUERY_START = '?';
+const QUERY_JOIN = '&';
+
+/**
+ * The socket URL with the session's credential on it.
+ *
+ * The token is the ONLY thing that authenticates this connection — there is no
+ * header to put it in, because a browser WebSocket cannot set one. Opened
+ * without it the socket completes its handshake and is then closed by the
+ * server, which reads as "connecting, and then nothing".
+ *
+ * `access_token` is deliberately NOT percent-encoded. The name contains a
+ * slash (`auth_tokens/…`), and encoding it produced a socket the server
+ * refused — measured against the live API, along with the `key=` spelling,
+ * which it also refuses.
+ */
+function authenticatedUrl(credentials: GeminiLiveCredentials): string {
+  const wsUrl = credentials.wsUrl ?? LiveProtocol.constrainedWsUrl;
+  const separator = wsUrl.includes(QUERY_START) ? QUERY_JOIN : QUERY_START;
+  return `${wsUrl}${separator}access_token=${credentials.token}`;
+}
+
+/**
+ * Reads one incoming frame as text.
+ *
+ * The Live API sends its JSON as BINARY WebSocket frames, not text ones — every
+ * frame, including `setupComplete`. A transport that accepted only strings
+ * silently received nothing at all, and its unit tests passed because a fake
+ * socket naturally sends strings. `binaryType` is set to `arraybuffer` so this
+ * stays synchronous; a Blob would have to be awaited, and the mapper's ordering
+ * guarantee does not survive an await between frames.
+ */
+function decodeFrame(data: unknown): string | null {
+  if (isString(data)) return data;
+  if (data instanceof ArrayBuffer) return new TextDecoder().decode(data);
+  if (ArrayBuffer.isView(data)) return new TextDecoder().decode(data.buffer as ArrayBuffer);
+  return null;
+}
+
+export class GeminiLiveSession implements AssistantSession<GeminiLiveCredentials> {
+  readonly audioFormat: AudioFormat = {
+    inputSampleRate: LiveProtocol.inputSampleRate,
+    outputSampleRate: LiveProtocol.outputSampleRate,
+  };
+
+  private socket: WebSocket | null = null;
+  private readonly listeners = new Set<(event: SessionEvent) => void>();
+  private readonly deliberatelyClosed = new WeakSet<WebSocket>();
+  private resumptionHandle: string | null = null;
+
+  constructor(private readonly createSocket: SocketFactory = (url) => new WebSocket(url)) {}
+
+  /** The latest handle a new token can be minted with to continue after a `goAway`. */
+  get lastResumptionHandle(): string | null {
+    return this.resumptionHandle;
+  }
+
+  connect(credentials: GeminiLiveCredentials): Promise<Result<void, AssistantFailure>> {
+    this.close();
+
+    return new Promise((resolve) => {
+      let settled = false;
+      const timer = setTimeout(() => {
+        // Settled BEFORE closing: a runtime whose `close()` fires `onclose`
+        // synchronously would otherwise answer with "closed before ready" and
+        // this reason would never be the one anybody reads.
+        settle(fail({ code: AssistantFailureCode.ConnectTimedOut }));
+        this.close();
+      }, CONNECT_TIMEOUT_MS);
+
+      const settle = (result: Result<void, AssistantFailure>): void => {
+        if (settled) return;
+        settled = true;
+        clearTimeout(timer);
+        resolve(result);
+      };
+
+      const socket = this.createSocket(authenticatedUrl(credentials));
+      // The server sends its JSON in BINARY frames. Without this the runtime
+      // hands them over as Blob, which cannot be read synchronously.
+      socket.binaryType = ARRAY_BUFFER;
+      this.socket = socket;
+
+      socket.onopen = () => {
+        socket.send(JSON.stringify(toLiveSetupRequest({ model: credentials.model })));
+      };
+
+      socket.onmessage = (event) => {
+        for (const mapped of this.parse(event.data)) {
+          if (mapped.kind === SessionEventKind.Ready) settle(ok(undefined));
+          if (mapped.kind === SessionEventKind.Resumption) this.resumptionHandle = mapped.handle;
+          this.emit(mapped);
+        }
+      };
+
+      socket.onerror = () => {
+        settle(fail({ code: AssistantFailureCode.SocketFailed }));
+      };
+
+      socket.onclose = () => {
+        const expected = this.deliberatelyClosed.has(socket);
+        if (this.socket === socket) this.socket = null;
+        settle(fail({ code: AssistantFailureCode.ClosedBeforeReady }));
+        this.emit({ kind: SessionEventKind.Closed, expected });
+      };
+    });
+  }
+
+  sendAudio(samples: Float32Array<ArrayBuffer>): void {
+    if (samples.length === 0) return;
+    // Checked before encoding, not after: capture now starts before the socket
+    // does, so every frame in that window used to be converted to base64 and
+    // then dropped by `send`.
+    if (!this.isOpen) return;
+
+    this.send({
+      realtimeInput: { audio: { data: float32ToPcm16Base64(samples), mimeType: LiveProtocol.inputAudioMime } },
+    });
+  }
+
+  sendText(text: string): void {
+    if (text === '') return;
+
+    this.send({ clientContent: { turns: [{ role: LiveProtocol.userRole, parts: [{ text }] }], turnComplete: true } });
+  }
+
+  respondToTool(call: Pick<ToolCall, 'id' | 'name'>, response: Readonly<Record<string, unknown>>): void {
+    this.send({ toolResponse: { functionResponses: [{ id: call.id, name: call.name, response }] } });
+  }
+
+  subscribe(listener: (event: SessionEvent) => void): () => void {
+    this.listeners.add(listener);
+    return () => {
+      this.listeners.delete(listener);
+    };
+  }
+
+  close(): void {
+    const socket = this.socket;
+    this.socket = null;
+    if (socket === null) return;
+
+    this.deliberatelyClosed.add(socket);
+    socket.close();
+  }
+
+  private get isOpen(): boolean {
+    return this.socket !== null && this.socket.readyState === SOCKET_OPEN;
+  }
+
+  private send(message: unknown): void {
+    // A frame produced after the socket went away is dropped: it is one frame
+    // of audio, and there is nothing a caller could usefully do about it.
+    const socket = this.socket;
+    if (socket === null || socket.readyState !== SOCKET_OPEN) return;
+
+    socket.send(JSON.stringify(message));
+  }
+
+  private parse(data: unknown): SessionEvent[] {
+    const text = decodeFrame(data);
+    if (text === null) return [];
+
+    try {
+      return mapLiveServerMessage(JSON.parse(text) as LiveServerMessageDto);
+    } catch {
+      // A frame we cannot read is not a reason to drop a live conversation.
+      return [];
+    }
+  }
+
+  private emit(event: SessionEvent): void {
+    for (const listener of this.listeners) {
+      try {
+        listener(event);
+      } catch {
+        // One listener's failure must not take down the audio session.
+      }
+    }
+  }
+}

package/src/guards.ts

@@ -0,0 +1,4 @@
+/** Narrowing helpers for frames this package did not produce. */
+export const isString = (value: unknown): value is string => typeof value === 'string';
+
+export const isNonEmptyString = (value: unknown): value is string => isString(value) && value.length > 0;

package/src/index.ts

@@ -0,0 +1,2 @@
+export { GeminiLiveSession } from './gemini-live-session';
+export type { GeminiLiveCredentials } from './gemini-live-credentials';

package/src/live-message-mapper.ts

@@ -0,0 +1,92 @@
+import { SessionEventKind, Speaker, pcm16Base64ToFloat32 } from '@live-assistant/core';
+import type { SessionEvent } from '@live-assistant/core';
+import type { LiveServerMessageDto } from './dtos/live-server-message-dto';
+import { isNonEmptyString } from './guards';
+
+/**
+ * Turns one Live API frame into the events a consumer acts on.
+ *
+ * @remarks
+ * - **A frame is not an event; it is a bag of them.** A single `serverContent`
+ *   routinely carries a transcript fragment, several audio chunks and the end
+ *   of the turn at once, so this returns a list. Mapping one frame to one event
+ *   would have meant picking which of them to lose.
+ * - **Order within the frame is the order they must be handled.** `interrupted`
+ *   is emitted before any audio in the same frame: the server can mark a turn
+ *   interrupted and still include trailing chunks of it, and handling those
+ *   first would enqueue exactly the audio the flush was meant to drop.
+ * - **`turnComplete`, not `generationComplete`.** The latter fires when the
+ *   model stops generating, which is before the audio it generated has been
+ *   sent — treating it as the end of the turn cuts the last words off.
+ * - **`timeLeft` is a protobuf duration string** (`"9.5s"`), not a number, and
+ *   parsing it as one silently yields `NaN` for every value with a unit.
+ * - **A tool call keeps its name and raw `args`.** The package does not know
+ *   which tools a consumer declared, so it neither validates nor narrows them;
+ *   a call is dropped only when it has no id or name, because nothing could
+ *   answer it.
+ * - **Unknown frames map to nothing rather than to a failure.** The API adds
+ *   message types over time and a session that fell over on an unrecognised
+ *   one would be broken by a server-side release.
+ */
+const AUDIO_MIME_PREFIX = 'audio/';
+const SECONDS_SUFFIX = 's';
+const MS_PER_SECOND = 1000;
+
+function parseTimeLeftMs(timeLeft: string | undefined): number {
+  if (!isNonEmptyString(timeLeft)) return 0;
+
+  const seconds = Number.parseFloat(
+    timeLeft.endsWith(SECONDS_SUFFIX) ? timeLeft.slice(0, -SECONDS_SUFFIX.length) : timeLeft,
+  );
+  return Number.isFinite(seconds) ? seconds * MS_PER_SECOND : 0;
+}
+
+export function mapLiveServerMessage(dto: LiveServerMessageDto): SessionEvent[] {
+  const events: SessionEvent[] = [];
+
+  if (dto.setupComplete !== undefined) events.push({ kind: SessionEventKind.Ready });
+
+  const content = dto.serverContent;
+  if (content !== undefined) {
+    if (content.interrupted === true) events.push({ kind: SessionEventKind.Interrupted });
+
+    const heard = content.inputTranscription?.text;
+    if (isNonEmptyString(heard)) {
+      events.push({ kind: SessionEventKind.Transcript, speaker: Speaker.User, text: heard });
+    }
+    const said = content.outputTranscription?.text;
+    if (isNonEmptyString(said)) {
+      events.push({ kind: SessionEventKind.Transcript, speaker: Speaker.Assistant, text: said });
+    }
+
+    for (const part of content.modelTurn?.parts ?? []) {
+      const data = part.inlineData?.data;
+      if (isNonEmptyString(data) && (part.inlineData?.mimeType ?? '').startsWith(AUDIO_MIME_PREFIX)) {
+        events.push({ kind: SessionEventKind.Audio, samples: pcm16Base64ToFloat32(data) });
+      }
+    }
+
+    if (content.turnComplete === true) events.push({ kind: SessionEventKind.TurnComplete });
+  }
+
+  for (const call of dto.toolCall?.functionCalls ?? []) {
+    if (!isNonEmptyString(call.id) || !isNonEmptyString(call.name)) continue;
+
+    events.push({ kind: SessionEventKind.ToolCall, call: { id: call.id, name: call.name, args: call.args ?? {} } });
+  }
+
+  const cancelled = (dto.toolCallCancellation?.ids ?? []).filter(isNonEmptyString);
+  if (cancelled.length > 0) events.push({ kind: SessionEventKind.ToolCallCancelled, callIds: cancelled });
+
+  const handle = dto.sessionResumptionUpdate?.newHandle;
+  if (isNonEmptyString(handle)) events.push({ kind: SessionEventKind.Resumption, handle });
+
+  if (dto.goAway !== undefined) {
+    events.push({ kind: SessionEventKind.GoAway, timeLeftMs: parseTimeLeftMs(dto.goAway.timeLeft) });
+  }
+
+  const totalTokens = dto.usageMetadata?.totalTokenCount;
+  if (typeof totalTokens === 'number') events.push({ kind: SessionEventKind.Usage, totalTokens });
+
+  return events;
+}

package/src/live-protocol.ts

@@ -0,0 +1,21 @@
+/**
+ * The Live API's fixed wire values, defined once.
+ *
+ * @remarks
+ * - **The input rate is the client's to state; the output rate is not.** The
+ *   microphone frame declares 16 kHz because that is what the audio layer
+ *   resamples to. The model answers at 24 kHz regardless.
+ * - **`constrainedWsUrl` is the only socket an ephemeral token opens.** The
+ *   ordinary `BidiGenerateContent` method refuses one ("Method doesn't allow
+ *   unregistered callers"), measured against the live API.
+ */
+export const LiveProtocol = {
+  constrainedWsUrl:
+    'wss://generativelanguage.googleapis.com/ws/' +
+    'google.ai.generativelanguage.v1alpha.GenerativeService.BidiGenerateContentConstrained',
+  inputAudioMime: 'audio/pcm;rate=16000',
+  /** The wire `role` of a typed turn. Gemini's word, kept apart from `Speaker` so renaming one cannot break the other. */
+  userRole: 'user',
+  outputSampleRate: 24_000,
+  inputSampleRate: 16_000,
+} as const;

package/src/live-setup-request.ts

@@ -0,0 +1,10 @@
+import type { LiveSetupRequestDto } from './dtos/live-setup-request-dto';
+
+/**
+ * The first frame on the socket. It only names the model: for a token minted
+ * with a setup, the instruction, tools and voice are baked in at mint time and
+ * the Live API discards whatever a client puts here beyond the model.
+ */
+export const toLiveSetupRequest = (input: { model: string }): LiveSetupRequestDto => ({
+  setup: { model: input.model },
+});