@kuralle-syrinx/gemini 4.4.1 → 4.5.0

package/dist/index.d.ts

@@ -0,0 +1,31 @@
+import type { PipelineBus } from "@kuralle-syrinx/core";
+import { type VoicePlugin, type PluginConfig } from "@kuralle-syrinx/core";
+export type GeminiVoice = "Kore" | "Puck" | "Charon" | "Fenrir" | "Leda" | "Aoede" | "Zephyr" | "Orus";
+export type GeminiTTSModel = "gemini-3.1-flash-tts-preview" | "gemini-2.5-flash-preview-tts" | "gemini-2.5-pro-preview-tts";
+export declare class GeminiTTSPlugin implements VoicePlugin {
+    private bus;
+    private apiKey;
+    private model;
+    private voiceName;
+    private instruction;
+    private languageCode;
+    private timeoutMs;
+    private sampleRate;
+    private generationConfig;
+    private readonly abortControllers;
+    private textByContextId;
+    /** Synthesized character counts per contextId — billed on successful tts.end. */
+    private charactersByContextId;
+    private retryConfig;
+    private disposers;
+    private audioFormat;
+    initialize(bus: PipelineBus, config: PluginConfig): Promise<void>;
+    private synthesize;
+    private synthesizeWithRetry;
+    private emitEnd;
+    private synthesizeOnce;
+    /** Flush/cancel all in-flight synthesis (called on interrupt/shutdown). */
+    flush(): void;
+    close(): Promise<void>;
+}
+//# 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":"AAWA,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,sBAAsB,CAAC;AACxD,OAAO,EAGL,KAAK,WAAW,EAChB,KAAK,YAAY,EAWlB,MAAM,sBAAsB,CAAC;AAM9B,MAAM,MAAM,WAAW,GACnB,MAAM,GACN,MAAM,GACN,QAAQ,GACR,QAAQ,GACR,MAAM,GACN,OAAO,GACP,QAAQ,GACR,MAAM,CAAC;AAEX,MAAM,MAAM,cAAc,GACtB,8BAA8B,GAC9B,8BAA8B,GAC9B,4BAA4B,CAAC;AAUjC,qBAAa,eAAgB,YAAW,WAAW;IACjD,OAAO,CAAC,GAAG,CAA4B;IACvC,OAAO,CAAC,MAAM,CAAc;IAC5B,OAAO,CAAC,KAAK,CAAyB;IACtC,OAAO,CAAC,SAAS,CAAyB;IAC1C,OAAO,CAAC,WAAW,CAAM;IACzB,OAAO,CAAC,YAAY,CAAqB;IACzC,OAAO,CAAC,SAAS,CAAU;IAC3B,OAAO,CAAC,UAAU,CAAuB;IACzC,OAAO,CAAC,gBAAgB,CAAsC;IAI9D,OAAO,CAAC,QAAQ,CAAC,gBAAgB,CAAsC;IACvE,OAAO,CAAC,eAAe,CAA6B;IACpD,iFAAiF;IACjF,OAAO,CAAC,qBAAqB,CAA6B;IAC1D,OAAO,CAAC,WAAW,CAAoC;IACvD,OAAO,CAAC,SAAS,CAAyB;IAC1C,OAAO,CAAC,WAAW,CAIjB;IAEI,UAAU,CAAC,GAAG,EAAE,WAAW,EAAE,MAAM,EAAE,YAAY,GAAG,OAAO,CAAC,IAAI,CAAC;YAmDzD,UAAU;YAiBV,mBAAmB;IA+CjC,OAAO,CAAC,OAAO;YAqBD,cAAc;IAwD5B,2EAA2E;IAC3E,KAAK,IAAI,IAAI;IAMP,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC;CAO7B"}

package/dist/index.js

@@ -0,0 +1,266 @@
+// SPDX-License-Identifier: MIT
+//
+// Syrinx Kernel v2 — Gemini TTS Plugin
+//
+// Uses Google Gemini's multimodal API (`responseModalities: ['AUDIO']`) to
+// synthesize speech. Non-streaming (chunked) — sends full text, receives
+// complete audio. Modeled after LiveKit's google.gemini.TTS implementation.
+//
+// Reference: LiveKit agents-js plugins/google/src/beta/gemini_tts.ts
+// Reference: Rapida transformer/google/tts.go (GCP TTS API, not Gemini)
+import { Route, assertAudioFormat, assertAudioPayload, requireStringConfig, optionalStringConfig, categorizeTtsError, isRecoverable, readRetryConfig, waitForRetryDelay, } from "@kuralle-syrinx/core";
+const DEFAULT_MODEL = "gemini-3.1-flash-tts-preview";
+const DEFAULT_VOICE = "Kore";
+const DEFAULT_SAMPLE_RATE = 24000;
+// =============================================================================
+// Plugin
+// =============================================================================
+export class GeminiTTSPlugin {
+    bus = null;
+    apiKey = "";
+    model = DEFAULT_MODEL;
+    voiceName = DEFAULT_VOICE;
+    instruction = "";
+    languageCode;
+    timeoutMs = 45_000;
+    sampleRate = DEFAULT_SAMPLE_RATE;
+    generationConfig;
+    // One controller per in-flight turn. A single shared field let a second turn's
+    // synthesize() overwrite the first's controller, so a barge-in on turn N aborted
+    // only turn N+1 and turn N's stale audio could still stream after the interrupt.
+    abortControllers = new Map();
+    textByContextId = new Map();
+    /** Synthesized character counts per contextId — billed on successful tts.end. */
+    charactersByContextId = new Map();
+    retryConfig = readRetryConfig({});
+    disposers = [];
+    audioFormat = {
+        encoding: "pcm_s16le",
+        sampleRateHz: DEFAULT_SAMPLE_RATE,
+        channels: 1,
+    };
+    async initialize(bus, config) {
+        this.bus = bus;
+        this.apiKey = requireStringConfig(config, "api_key");
+        this.model = optionalStringConfig(config, "model") ?? DEFAULT_MODEL;
+        this.voiceName = optionalStringConfig(config, "voice_name") ?? DEFAULT_VOICE;
+        this.instruction = optionalStringConfig(config, "instruction") ?? "";
+        this.languageCode =
+            optionalStringConfig(config, "language_code") ?? optionalStringConfig(config, "language");
+        this.timeoutMs = readPositiveInteger(config["timeout_ms"], 45_000);
+        this.sampleRate = readPositiveInteger(config["sample_rate"], DEFAULT_SAMPLE_RATE);
+        this.generationConfig = readPlainObject(config["generation_config"]);
+        this.retryConfig = readRetryConfig(config);
+        this.audioFormat = { encoding: "pcm_s16le", sampleRateHz: this.sampleRate, channels: 1 };
+        assertAudioFormat(this.audioFormat);
+        // Accumulate streaming text deltas; Gemini TTS returns chunked audio for
+        // complete text, not true token-by-token low-latency streaming.
+        this.disposers.push(bus.on("tts.text", (pkt) => {
+            const textPkt = pkt;
+            const current = this.textByContextId.get(textPkt.contextId) ?? "";
+            this.textByContextId.set(textPkt.contextId, current + textPkt.text);
+        }), bus.on("tts.done", async (pkt) => {
+            const donePkt = pkt;
+            const buffered = this.textByContextId.get(donePkt.contextId) ?? "";
+            this.textByContextId.delete(donePkt.contextId);
+            const text = donePkt.text || buffered;
+            if (!text.trim()) {
+                this.charactersByContextId.delete(donePkt.contextId);
+                this.emitEnd(donePkt.contextId);
+                return;
+            }
+            this.charactersByContextId.set(donePkt.contextId, text.length);
+            await this.synthesize(text, donePkt.contextId);
+        }), 
+        // Listen for TTS interrupts — abort only the interrupted turn's synthesis.
+        bus.on("interrupt.tts", (pkt) => {
+            const ctxId = pkt.contextId;
+            this.charactersByContextId.delete(ctxId);
+            const controller = this.abortControllers.get(ctxId);
+            if (controller) {
+                controller.abort();
+                this.abortControllers.delete(ctxId);
+            }
+        }));
+    }
+    async synthesize(text, contextId) {
+        if (!this.bus)
+            return;
+        const controller = new AbortController();
+        this.abortControllers.set(contextId, controller);
+        const signal = controller.signal;
+        try {
+            await this.synthesizeWithRetry(text, contextId, signal);
+        }
+        finally {
+            // Only clear if still ours — an interrupt may have already removed it.
+            if (this.abortControllers.get(contextId) === controller) {
+                this.abortControllers.delete(contextId);
+            }
+        }
+    }
+    async synthesizeWithRetry(text, contextId, signal) {
+        for (let attempt = 1; attempt <= this.retryConfig.maxAttempts; attempt += 1) {
+            try {
+                const audioChunks = await this.synthesizeOnce(text, contextId, signal);
+                if (signal.aborted) {
+                    this.charactersByContextId.delete(contextId);
+                    return;
+                }
+                if (audioChunks > 0) {
+                    this.emitEnd(contextId);
+                    return;
+                }
+                throw new Error("Gemini TTS returned no audio chunks");
+            }
+            catch (err) {
+                if (signal.aborted) {
+                    this.charactersByContextId.delete(contextId);
+                    return;
+                }
+                const category = categorizeTtsError(err);
+                const recoverable = isRecoverable(category);
+                if (!recoverable || attempt >= this.retryConfig.maxAttempts) {
+                    this.charactersByContextId.delete(contextId);
+                    this.bus?.push(Route.Critical, {
+                        kind: "tts.error",
+                        contextId,
+                        timestampMs: Date.now(),
+                        component: "tts",
+                        category,
+                        cause: err instanceof Error ? err : new Error(String(err)),
+                        isRecoverable: recoverable,
+                    });
+                    return;
+                }
+                this.bus?.push(Route.Background, {
+                    kind: "metric.conversation",
+                    contextId,
+                    timestampMs: Date.now(),
+                    name: "tts.retry",
+                    value: String(attempt + 1),
+                });
+                await waitForRetryDelay(attempt, this.retryConfig, signal);
+            }
+        }
+    }
+    emitEnd(contextId) {
+        const characters = this.charactersByContextId.get(contextId) ?? 0;
+        this.charactersByContextId.delete(contextId);
+        if (characters > 0) {
+            this.bus?.push(Route.Background, {
+                kind: "usage.recorded",
+                contextId,
+                timestampMs: Date.now(),
+                stage: "tts",
+                provider: "gemini",
+                model: this.model,
+                characters,
+            });
+        }
+        this.bus?.push(Route.Main, {
+            kind: "tts.end",
+            contextId,
+            timestampMs: Date.now(),
+        });
+    }
+    async synthesizeOnce(text, contextId, signal) {
+        // Dynamic import — @google/genai is heavy, only load when used
+        const { GoogleGenAI } = await import("@google/genai");
+        const client = new GoogleGenAI({ apiKey: this.apiKey });
+        const speechConfig = {
+            voiceConfig: {
+                prebuiltVoiceConfig: {
+                    voiceName: this.voiceName,
+                },
+            },
+        };
+        if (this.languageCode)
+            speechConfig["languageCode"] = this.languageCode;
+        const response = await withTimeout(client.models.generateContent({
+            model: this.model,
+            contents: [{ parts: [{ text: this.instruction ? `${this.instruction}: ${text}` : text }] }],
+            config: {
+                responseModalities: ["AUDIO"],
+                speechConfig,
+                ...this.generationConfig,
+                abortSignal: signal,
+            },
+        }), this.timeoutMs, signal);
+        let audioChunks = 0;
+        const candidate = response.candidates?.[0];
+        if (!candidate?.content?.parts)
+            return audioChunks;
+        for (const part of candidate.content.parts) {
+            if (signal.aborted)
+                return audioChunks;
+            if (part.inlineData?.data && part.inlineData.mimeType?.startsWith("audio/")) {
+                const audioBytes = Buffer.from(part.inlineData.data, "base64");
+                const audioUint8 = new Uint8Array(audioBytes);
+                assertAudioPayload(this.audioFormat, audioUint8);
+                this.bus?.push(Route.Main, {
+                    kind: "tts.audio",
+                    contextId,
+                    timestampMs: Date.now(),
+                    audio: audioUint8,
+                    sampleRateHz: this.sampleRate,
+                });
+                audioChunks++;
+            }
+        }
+        return audioChunks;
+    }
+    /** Flush/cancel all in-flight synthesis (called on interrupt/shutdown). */
+    flush() {
+        for (const controller of this.abortControllers.values())
+            controller.abort();
+        this.abortControllers.clear();
+        this.charactersByContextId.clear();
+    }
+    async close() {
+        this.flush();
+        for (const dispose of this.disposers.splice(0))
+            dispose();
+        this.textByContextId.clear();
+        this.charactersByContextId.clear();
+        this.bus = null;
+    }
+}
+async function withTimeout(promise, timeoutMs, signal) {
+    return await new Promise((resolve, reject) => {
+        if (signal.aborted) {
+            reject(new Error("Gemini TTS aborted"));
+            return;
+        }
+        const timeout = setTimeout(() => {
+            reject(new Error(`Gemini TTS request timeout after ${String(timeoutMs)}ms`));
+        }, timeoutMs);
+        const onAbort = () => {
+            clearTimeout(timeout);
+            reject(new Error("Gemini TTS aborted"));
+        };
+        signal.addEventListener("abort", onAbort, { once: true });
+        promise.then((value) => {
+            clearTimeout(timeout);
+            signal.removeEventListener("abort", onAbort);
+            resolve(value);
+        }, (err) => {
+            clearTimeout(timeout);
+            signal.removeEventListener("abort", onAbort);
+            reject(err);
+        });
+    });
+}
+function readPositiveInteger(value, fallback) {
+    if (typeof value !== "number" || !Number.isFinite(value))
+        return fallback;
+    const integer = Math.floor(value);
+    return integer > 0 ? integer : fallback;
+}
+function readPlainObject(value) {
+    if (value !== null && typeof value === "object" && !Array.isArray(value)) {
+        return value;
+    }
+    return undefined;
+}
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@kuralle-syrinx/gemini",
-  "version": "4.4.1",
+  "version": "4.5.0",
   "private": false,
   "description": "Google Gemini TTS adapter for Syrinx",
   "keywords": [
@@ -22,18 +22,25 @@
     "url": "https://github.com/kuralle/syrinx/issues"
   },
   "type": "module",
-  "main": "./src/index.ts",
-  "types": "./src/index.ts",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
   "dependencies": {
     "@google/genai": "^1.0.0",
-    "@kuralle-syrinx/core": "4.4.1"
+    "@kuralle-syrinx/core": "4.5.0"
   },
   "devDependencies": {
+    "@types/node": "^22.0.0",
     "typescript": "^5.7.0",
     "vitest": "^3.2.6"
   },
+  "files": [
+    "dist",
+    "src",
+    "README.md"
+  ],
   "scripts": {
     "typecheck": "tsc --noEmit",
-    "test": "vitest run"
+    "test": "vitest run",
+    "build": "tsc -p tsconfig.build.json"
   }
 }

package/src/index.test.ts

@@ -0,0 +1,319 @@
+// SPDX-License-Identifier: MIT
+
+import { afterEach, describe, expect, it, vi } from "vitest";
+import {
+  PipelineBusImpl,
+  Route,
+  type TextToSpeechAudioPacket,
+  type TextToSpeechEndPacket,
+  type TtsErrorPacket,
+  type UsageRecordedPacket,
+} from "@kuralle-syrinx/core";
+import { GeminiTTSPlugin } from "./index.js";
+
+const generateContent = vi.fn();
+
+vi.mock("@google/genai", () => ({
+  GoogleGenAI: vi.fn().mockImplementation(() => ({
+    models: { generateContent },
+  })),
+}));
+
+afterEach(() => {
+  generateContent.mockReset();
+});
+
+describe("GeminiTTSPlugin", () => {
+  it("emits tts.error for odd-length PCM16 without throwing into the bus pump", async () => {
+    generateContent.mockResolvedValue({
+      candidates: [{
+        content: {
+          parts: [{
+            inlineData: {
+              mimeType: "audio/pcm",
+              data: Buffer.from(new Uint8Array([1, 2, 3])).toString("base64"),
+            },
+          }],
+        },
+      }],
+    });
+
+    const bus = new PipelineBusImpl();
+    const started = bus.start();
+    const plugin = new GeminiTTSPlugin();
+    const audio: TextToSpeechAudioPacket[] = [];
+    const errors: TtsErrorPacket[] = [];
+    bus.on("tts.audio", (pkt) => {
+      audio.push(pkt as TextToSpeechAudioPacket);
+    });
+    bus.on("tts.error", (pkt) => {
+      errors.push(pkt as TtsErrorPacket);
+    });
+
+    await plugin.initialize(bus, { api_key: "test-gemini-key" });
+    bus.push(Route.Main, {
+      kind: "tts.done",
+      contextId: "turn-odd-pcm",
+      timestampMs: Date.now(),
+      text: "Hello.",
+    });
+    await new Promise((resolve) => setTimeout(resolve, 50));
+
+    expect(audio).toEqual([]);
+    expect(errors).toEqual([
+      expect.objectContaining({
+        kind: "tts.error",
+        contextId: "turn-odd-pcm",
+        component: "tts",
+        cause: expect.objectContaining({
+          message: expect.stringMatching(/even number of bytes/i),
+        }),
+      }),
+    ]);
+
+    await plugin.close();
+    bus.stop();
+    await started;
+  });
+
+  it("sends the raw text to Gemini by default (no hardcoded persona lead-in)", async () => {
+    generateContent.mockResolvedValue({
+      candidates: [{ content: { parts: [{ inlineData: { mimeType: "audio/pcm", data: Buffer.from(new Uint8Array([1, 2, 3, 4])).toString("base64") } }] } }],
+    });
+    const bus = new PipelineBusImpl();
+    const started = bus.start();
+    const plugin = new GeminiTTSPlugin();
+    await plugin.initialize(bus, { api_key: "test-gemini-key" });
+    bus.push(Route.Main, { kind: "tts.done", contextId: "t1", timestampMs: Date.now(), text: "Add Biology 101." });
+    await new Promise((resolve) => setTimeout(resolve, 50));
+
+    expect(generateContent).toHaveBeenCalledTimes(1);
+    const arg = generateContent.mock.calls[0]![0] as { contents: Array<{ parts: Array<{ text: string }> }> };
+    expect(arg.contents[0]!.parts[0]!.text).toBe("Add Biology 101.");
+
+    await plugin.close();
+    bus.stop();
+    await started;
+  });
+
+  it("prepends a configured instruction lead-in when provided", async () => {
+    generateContent.mockResolvedValue({
+      candidates: [{ content: { parts: [{ inlineData: { mimeType: "audio/pcm", data: Buffer.from(new Uint8Array([1, 2, 3, 4])).toString("base64") } }] } }],
+    });
+    const bus = new PipelineBusImpl();
+    const started = bus.start();
+    const plugin = new GeminiTTSPlugin();
+    await plugin.initialize(bus, { api_key: "test-gemini-key", instruction: "Read aloud warmly" });
+    bus.push(Route.Main, { kind: "tts.done", contextId: "t2", timestampMs: Date.now(), text: "Hi." });
+    await new Promise((resolve) => setTimeout(resolve, 50));
+
+    const arg = generateContent.mock.calls[0]![0] as { contents: Array<{ parts: Array<{ text: string }> }> };
+    expect(arg.contents[0]!.parts[0]!.text).toBe("Read aloud warmly: Hi.");
+
+    await plugin.close();
+    bus.stop();
+    await started;
+  });
+
+  it("honors voice_name, language_code, sample_rate, and generation_config on generateContent", async () => {
+    generateContent.mockResolvedValue({
+      candidates: [{
+        content: {
+          parts: [{
+            inlineData: {
+              mimeType: "audio/pcm",
+              data: Buffer.from(new Uint8Array([1, 2, 3, 4])).toString("base64"),
+            },
+          }],
+        },
+      }],
+    });
+
+    const bus = new PipelineBusImpl();
+    const started = bus.start();
+    const plugin = new GeminiTTSPlugin();
+    const audio: TextToSpeechAudioPacket[] = [];
+    bus.on("tts.audio", (pkt) => {
+      audio.push(pkt as TextToSpeechAudioPacket);
+    });
+
+    await plugin.initialize(bus, {
+      api_key: "test-gemini-key",
+      voice_name: "Puck",
+      language_code: "en-IN",
+      sample_rate: 24000,
+      generation_config: { temperature: 0.4 },
+    });
+    bus.push(Route.Main, {
+      kind: "tts.done",
+      contextId: "turn-cfg",
+      timestampMs: Date.now(),
+      text: "Hello.",
+    });
+    await new Promise((resolve) => setTimeout(resolve, 50));
+
+    expect(generateContent).toHaveBeenCalledTimes(1);
+    const arg = generateContent.mock.calls[0]![0] as {
+      config: {
+        responseModalities: string[];
+        speechConfig: {
+          languageCode?: string;
+          voiceConfig: { prebuiltVoiceConfig: { voiceName: string } };
+        };
+        temperature?: number;
+      };
+    };
+    expect(arg.config.responseModalities).toEqual(["AUDIO"]);
+    expect(arg.config.speechConfig.voiceConfig.prebuiltVoiceConfig.voiceName).toBe("Puck");
+    expect(arg.config.speechConfig.languageCode).toBe("en-IN");
+    expect(arg.config.temperature).toBe(0.4);
+    expect(audio[0]?.sampleRateHz).toBe(24000);
+
+    await plugin.close();
+    bus.stop();
+    await started;
+  });
+
+  it("emits usage.recorded with stage tts and characters equal to synthesized text length", async () => {
+    const text = "Hello there.";
+    generateContent.mockResolvedValue({
+      candidates: [{
+        content: {
+          parts: [{
+            inlineData: {
+              mimeType: "audio/pcm",
+              data: Buffer.from(new Uint8Array([1, 2, 3, 4])).toString("base64"),
+            },
+          }],
+        },
+      }],
+    });
+
+    const bus = new PipelineBusImpl();
+    const started = bus.start();
+    const plugin = new GeminiTTSPlugin();
+    const ends: TextToSpeechEndPacket[] = [];
+    const usage: UsageRecordedPacket[] = [];
+    bus.on("tts.end", (pkt) => {
+      ends.push(pkt as TextToSpeechEndPacket);
+    });
+    bus.on("usage.recorded", (pkt) => {
+      usage.push(pkt as UsageRecordedPacket);
+    });
+
+    await plugin.initialize(bus, {
+      api_key: "test-gemini-key",
+      model: "gemini-2.5-flash-preview-tts",
+    });
+    bus.push(Route.Main, {
+      kind: "tts.done",
+      contextId: "turn-usage",
+      timestampMs: Date.now(),
+      text,
+    });
+    await new Promise((resolve) => setTimeout(resolve, 50));
+
+    expect(ends).toEqual([expect.objectContaining({ contextId: "turn-usage" })]);
+    expect(usage).toEqual([
+      expect.objectContaining({
+        kind: "usage.recorded",
+        contextId: "turn-usage",
+        stage: "tts",
+        provider: "gemini",
+        model: "gemini-2.5-flash-preview-tts",
+        characters: text.length,
+      }),
+    ]);
+
+    await plugin.close();
+    bus.stop();
+    await started;
+  });
+
+  it("does not emit usage.recorded when synthesis is cancelled mid-flight", async () => {
+    let resolveGen!: (value: unknown) => void;
+    generateContent.mockImplementation(
+      () =>
+        new Promise((resolve) => {
+          resolveGen = resolve;
+        }),
+    );
+
+    const bus = new PipelineBusImpl();
+    const started = bus.start();
+    const plugin = new GeminiTTSPlugin();
+    const usage: UsageRecordedPacket[] = [];
+    bus.on("usage.recorded", (pkt) => {
+      usage.push(pkt as UsageRecordedPacket);
+    });
+
+    await plugin.initialize(bus, { api_key: "test-gemini-key" });
+    bus.push(Route.Main, {
+      kind: "tts.done",
+      contextId: "turn-cancel",
+      timestampMs: Date.now(),
+      text: "This will be cancelled.",
+    });
+    // Wait until generateContent is in-flight (controller registered).
+    for (let i = 0; i < 50 && !resolveGen; i += 1) {
+      await new Promise((resolve) => setTimeout(resolve, 10));
+    }
+    // Abort synchronously (same path as interrupt.tts handler) so it wins the race
+    // against a late generateContent resolution on the microtask queue.
+    plugin.flush();
+    resolveGen!({
+      candidates: [{
+        content: {
+          parts: [{
+            inlineData: {
+              mimeType: "audio/pcm",
+              data: Buffer.from(new Uint8Array([1, 2, 3, 4])).toString("base64"),
+            },
+          }],
+        },
+      }],
+    });
+    await new Promise((resolve) => setTimeout(resolve, 50));
+
+    expect(usage).toEqual([]);
+
+    await plugin.close();
+    bus.stop();
+    await started;
+  });
+
+  it("does not emit usage.recorded when synthesis fails", async () => {
+    generateContent.mockRejectedValue(new Error("upstream 500"));
+
+    const bus = new PipelineBusImpl();
+    const started = bus.start();
+    const plugin = new GeminiTTSPlugin();
+    const usage: UsageRecordedPacket[] = [];
+    const errors: TtsErrorPacket[] = [];
+    bus.on("usage.recorded", (pkt) => {
+      usage.push(pkt as UsageRecordedPacket);
+    });
+    bus.on("tts.error", (pkt) => {
+      errors.push(pkt as TtsErrorPacket);
+    });
+
+    await plugin.initialize(bus, {
+      api_key: "test-gemini-key",
+      max_attempts: 1,
+    });
+    bus.push(Route.Main, {
+      kind: "tts.done",
+      contextId: "turn-fail",
+      timestampMs: Date.now(),
+      text: "This will fail.",
+    });
+    await new Promise((resolve) => setTimeout(resolve, 50));
+
+    expect(errors.length).toBeGreaterThanOrEqual(1);
+    expect(usage).toEqual([]);
+
+    await plugin.close();
+    bus.stop();
+    await started;
+  });
+});