@kuralle-syrinx/grok 2.1.1 → 3.0.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@kuralle-syrinx/grok",
-  "version": "2.1.1",
+  "version": "3.0.0",
   "private": false,
   "type": "module",
   "license": "MIT",
@@ -13,9 +13,10 @@
     "./realtime": "./src/from-grok-realtime.ts"
   },
   "dependencies": {
-    "@kuralle-syrinx/core": "2.1.1",
-    "@kuralle-syrinx/ws": "2.1.1",
-    "@kuralle-syrinx/realtime": "2.1.1"
+    "@kuralle-syrinx/realtime": "3.0.0",
+    "@kuralle-syrinx/ws": "3.0.0",
+    "@kuralle-syrinx/tts-core": "3.0.0",
+    "@kuralle-syrinx/core": "3.0.0"
   },
   "devDependencies": {
     "@types/ws": "^8.5.0",

package/src/tts.ts

@@ -1,303 +1,143 @@
 // SPDX-License-Identifier: MIT
+//
+// Grok (xAI) TTS Plugin. The streaming lifecycle lives in @kuralle-syrinx/tts-core. This
+// file is the Grok wire protocol: single-context streaming (one active utterance at a time),
+// text.delta/text.done/text.clear out, base64 audio.delta in. Grok frames carry no key, so
+// inbound audio is attributed to the one current context. Raw PCM may split mid-sample, so
+// Grok relies on the engine's streaming carry.
 
-import type { PipelineBus } from "@kuralle-syrinx/core";
 import {
-  Route,
-  type AudioFormat,
-  type PluginConfig,
-  type RetryConfig,
-  type TextToSpeechAudioPacket,
-  type TextToSpeechEndPacket,
-  type TtsErrorPacket,
-  type VoicePlugin,
   assertAudioFormat,
-  assertAudioPayload,
-  categorizeTtsError,
-  isRecoverable,
   optionalStringConfig,
   readProviderRetryConfig,
   requireStringConfig,
+  type AudioFormat,
+  type PipelineBus,
+  type PluginConfig,
+  type VoicePlugin,
 } from "@kuralle-syrinx/core";
-import { WebSocketConnection, type SocketFactory } from "@kuralle-syrinx/ws";
-
+import {
+  attributionKey,
+  defaultNodeSocketFactory,
+  startStreamingTtsSession,
+  type AttributionKey,
+  type StreamingTtsSession,
+  type WireEvent,
+  type WireProtocol,
+} from "@kuralle-syrinx/tts-core";
+import type { SocketData, SocketFactory } from "@kuralle-syrinx/ws";
 import { base64ToBytes } from "@kuralle-syrinx/realtime";
 
 const KEEP_ALIVE_INTERVAL_MS = 10_000;
-const EMPTY = new Uint8Array(0);
 
-export class GrokTTSPlugin implements VoicePlugin {
-  constructor(private readonly socketFactory?: SocketFactory) {}
-
-  private bus: PipelineBus | null = null;
-  private conn: WebSocketConnection | null = null;
-  private apiKey = "";
-  private voiceId = "eve";
-  private language = "en";
-  private endpointUrl = "wss://api.x.ai/v1/tts";
-  private sampleRate = 16000;
-  private retryConfig: RetryConfig = readProviderRetryConfig({});
-  private currentContextId = "";
-  private carry: Uint8Array = EMPTY;
-  private activeContexts = new Set<string>();
-  private cancelledContexts = new Set<string>();
-  private clearedPending = false;
-  private finishTimers = new Map<string, ReturnType<typeof setTimeout>>();
-  private disposers: Array<() => void> = [];
-  private audioFormat: AudioFormat = { encoding: "pcm_s16le", sampleRateHz: 16000, channels: 1 };
-
-  async initialize(bus: PipelineBus, config: PluginConfig): Promise<void> {
-    this.bus = bus;
-    this.apiKey = requireStringConfig(config, "api_key");
-    this.voiceId = optionalStringConfig(config, "voice_id") ?? this.voiceId;
-    this.language = optionalStringConfig(config, "language") ?? this.language;
-    this.endpointUrl = optionalStringConfig(config, "endpoint_url") ?? this.endpointUrl;
-    this.sampleRate = readPositiveInteger(config["sample_rate"], this.sampleRate);
-    this.retryConfig = readProviderRetryConfig(config);
-    const finishTimeoutMs = readNonNegativeInteger(config["finish_timeout_ms"], 2000);
-    this.audioFormat = { encoding: "pcm_s16le", sampleRateHz: this.sampleRate, channels: 1 };
-    assertAudioFormat(this.audioFormat);
+class GrokWireProtocol implements WireProtocol {
+  // Grok streams one context at a time; inbound frames carry no key, so they're attributed
+  // to the current one. (Audio for an interrupted context is dropped by the engine's
+  // cancelled-key tracking, which subsumes Grok's old `clearedPending` race guard.)
+  private current: AttributionKey | null = null;
 
-    this.conn = new WebSocketConnection({
-      url: () => {
-        const params = new URLSearchParams({
-          language: this.language,
-          voice: this.voiceId,
-          codec: "pcm",
-          sample_rate: String(this.sampleRate),
-        });
-        const separator = this.endpointUrl.includes("?") ? "&" : "?";
-        return `${this.endpointUrl}${separator}${params.toString()}`;
-      },
-      headers: { Authorization: `Bearer ${this.apiKey}` },
-      retry: this.retryConfig,
-      socketFactory: this.socketFactory ?? (await defaultSocketFactory()),
-      replayBufferSize: (config["replay_buffer_size"] as number) ?? 32,
-      keepAliveIntervalMs: KEEP_ALIVE_INTERVAL_MS,
-      onMessage: (data) => this.handleProviderMessage(data),
-      onConnectionLost: (err) => this.failActiveContexts(err),
-      onUnrecoverable: (err) => this.failActiveContexts(err),
-    });
-    await this.conn.connect();
-
-    this.disposers.push(
-      bus.on("tts.text", async (pkt: unknown) => {
-        const textPkt = pkt as { text: string; contextId: string };
-        await this.speak(textPkt.text, textPkt.contextId);
-      }),
-      bus.on("tts.done", async (pkt: unknown) => {
-        const donePkt = pkt as { contextId: string };
-        if (finishTimeoutMs > 0 && this.activeContexts.has(donePkt.contextId)) {
-          this.scheduleFinishTimeout(donePkt.contextId, finishTimeoutMs);
-        }
-        await this.finishContext(donePkt.contextId);
-      }),
-      bus.on("interrupt.tts", () => {
-        this.cancelActiveContexts().catch(() => {
-          // Best-effort interruption.
-        });
-      }),
-    );
-  }
-
-  private async speak(text: string, contextId: string): Promise<void> {
-    if (!text.trim()) return;
-    if (this.cancelledContexts.has(contextId)) return;
-    this.activeContexts.add(contextId);
-    this.currentContextId = contextId;
-    const sent = await this.trySend(JSON.stringify({ type: "text.delta", delta: text }), contextId);
-    if (!sent) this.activeContexts.delete(contextId);
-  }
-
-  private async finishContext(contextId: string): Promise<void> {
-    if (this.cancelledContexts.has(contextId)) return;
-    if (!this.activeContexts.has(contextId)) {
-      this.emitEnd(contextId);
-      return;
-    }
-    if (!(await this.trySend(JSON.stringify({ type: "text.done" }), contextId))) {
-      this.activeContexts.delete(contextId);
-    }
+  attributionFor(contextId: string): { key: AttributionKey; contextId: string } {
+    this.current = attributionKey(contextId);
+    return { key: this.current, contextId };
   }
 
-  async flush(): Promise<void> {
-    await this.cancelActiveContexts();
+  encodeText(_key: AttributionKey, text: string): SocketData[] {
+    return [JSON.stringify({ type: "text.delta", delta: text })];
   }
 
-  async close(): Promise<void> {
-    for (const dispose of this.disposers.splice(0)) dispose();
-    this.activeContexts.clear();
-    this.cancelledContexts.clear();
-    for (const timer of this.finishTimers.values()) clearTimeout(timer);
-    this.finishTimers.clear();
-    this.currentContextId = "";
-    this.carry = EMPTY;
-    this.clearedPending = false;
-    await this.conn?.close();
-    this.conn = null;
-    this.bus = null;
+  encodeFinish(): SocketData[] {
+    return [JSON.stringify({ type: "text.done" })];
   }
 
-  private async cancelActiveContexts(): Promise<void> {
-    const contextIds = [...this.activeContexts];
-    for (const contextId of contextIds) this.cancelledContexts.add(contextId);
-    this.activeContexts.clear();
-    for (const contextId of contextIds) this.clearFinishTimeout(contextId);
-    this.currentContextId = "";
-    this.carry = EMPTY;
-    if (contextIds.length === 0) return;
-    this.clearedPending = await this.trySend(JSON.stringify({ type: "text.clear" }), contextIds.at(-1) ?? "");
+  encodeCancel(): SocketData[] {
+    return [JSON.stringify({ type: "text.clear" })];
   }
 
-  private async trySend(payload: string, contextId: string): Promise<boolean> {
-    try {
-      await this.conn?.ensureReady();
-      this.conn?.send(payload);
-      return true;
-    } catch (err) {
-      this.emitError(contextId, err instanceof Error ? err : new Error(String(err)));
-      return false;
-    }
+  encodeClose(): SocketData[] {
+    return [];
   }
 
-  private handleProviderMessage(data: unknown): void {
-    if (typeof data !== "string") return;
+  decode(data: SocketData): WireEvent[] {
+    if (typeof data !== "string") return [];
     let msg: Record<string, unknown>;
     try {
       msg = JSON.parse(data) as Record<string, unknown>;
     } catch {
-      return;
+      return []; // Grok ignores unparseable frames (does not fail the session).
     }
-
+    const key = this.current;
     switch (msg["type"]) {
-      case "audio.delta":
-        this.handleAudioDelta(msg);
-        return;
-      case "audio.done": {
-        const contextId = this.currentContextId;
-        this.carry = EMPTY;
-        if (contextId && this.activeContexts.has(contextId)) {
-          this.activeContexts.delete(contextId);
-          this.clearFinishTimeout(contextId);
-          this.emitEnd(contextId);
+      case "audio.delta": {
+        if (!key) return [];
+        const delta = typeof msg["delta"] === "string" ? msg["delta"] : "";
+        if (delta.length === 0) return [];
+        try {
+          return [{ type: "audio", key, pcm: base64ToBytes(delta) }];
+        } catch (err) {
+          return [{ type: "error", key, error: err instanceof Error ? err : new Error(String(err)) }];
         }
-        this.currentContextId = "";
-        return;
+      }
+      case "audio.done": {
+        this.current = null;
+        return key ? [{ type: "context_end", key }] : [];
       }
       case "audio.clear":
-        this.carry = EMPTY;
-        this.clearedPending = false;
-        return;
+        // Provider acknowledged a text.clear. Audio for the interrupted context is already
+        // dropped via the engine's cancelled tracking; nothing more to do.
+        return [];
       case "error":
-        this.emitError(this.currentContextId, grokProviderError(msg));
-        return;
+        return key ? [{ type: "error", key, error: grokProviderError(msg) }] : [];
       default:
-        return;
+        return [];
     }
   }
+}
 
-  private handleAudioDelta(msg: Record<string, unknown>): void {
-    const contextId = this.currentContextId;
-    if (!contextId || this.clearedPending || this.cancelledContexts.has(contextId)) return;
-    const delta = typeof msg["delta"] === "string" ? msg["delta"] : "";
-    if (delta.length === 0) return;
-
-    let frame: Uint8Array;
-    try {
-      frame = base64ToBytes(delta);
-    } catch (err) {
-      this.emitError(contextId, err instanceof Error ? err : new Error(String(err)));
-      return;
-    }
-    if (frame.byteLength === 0) return;
-
-    const buf = this.carry.byteLength === 0 ? frame : concatBytes(this.carry, frame);
-    const evenLen = buf.byteLength - (buf.byteLength % 2);
-    if (evenLen > 0) {
-      const audio = buf.subarray(0, evenLen);
-      try {
-        assertAudioPayload(this.audioFormat, audio);
-      } catch (err) {
-        this.emitError(contextId, err instanceof Error ? err : new Error(String(err)));
-        return;
-      }
-      const packet: TextToSpeechAudioPacket = {
-        kind: "tts.audio",
-        contextId,
-        timestampMs: Date.now(),
-        audio,
-        sampleRateHz: this.sampleRate,
-        provider: { name: "grok", model: this.voiceId, region: "global", cancelled: false },
-      };
-      this.bus?.push(Route.Main, packet);
-    }
-    this.carry = evenLen < buf.byteLength ? buf.subarray(evenLen) : EMPTY;
-  }
-
-  private emitError(contextId: string, err: Error): void {
-    const category = categorizeTtsError(err);
-    const packet: TtsErrorPacket = {
-      kind: "tts.error",
-      contextId,
-      timestampMs: Date.now(),
-      component: "tts",
-      category,
-      cause: err,
-      isRecoverable: isRecoverable(category),
-    };
-    this.bus?.push(Route.Critical, packet);
-  }
-
-  private failActiveContexts(err: Error): void {
-    const contextIds = [...this.activeContexts];
-    this.activeContexts.clear();
-    for (const contextId of contextIds) this.clearFinishTimeout(contextId);
-    this.currentContextId = "";
-    this.carry = EMPTY;
-    this.clearedPending = false;
-    for (const contextId of contextIds) this.emitError(contextId, err);
-  }
+export class GrokTTSPlugin implements VoicePlugin {
+  constructor(private readonly socketFactory?: SocketFactory) {}
 
-  private scheduleFinishTimeout(contextId: string, timeoutMs: number): void {
-    this.clearFinishTimeout(contextId);
-    const timer = setTimeout(() => {
-      this.finishTimers.delete(contextId);
-      if (!this.activeContexts.has(contextId)) return;
-      this.activeContexts.delete(contextId);
-      if (this.currentContextId === contextId) this.currentContextId = "";
-      this.carry = EMPTY;
-      this.emitEnd(contextId);
-    }, timeoutMs);
-    this.finishTimers.set(contextId, timer);
-  }
+  private session: StreamingTtsSession | null = null;
 
-  private clearFinishTimeout(contextId: string): void {
-    const timer = this.finishTimers.get(contextId);
-    if (!timer) return;
-    clearTimeout(timer);
-    this.finishTimers.delete(contextId);
+  async initialize(bus: PipelineBus, config: PluginConfig): Promise<void> {
+    const apiKey = requireStringConfig(config, "api_key");
+    const voiceId = optionalStringConfig(config, "voice_id") ?? "eve";
+    const language = optionalStringConfig(config, "language") ?? "en";
+    const endpointUrl = optionalStringConfig(config, "endpoint_url") ?? "wss://api.x.ai/v1/tts";
+    const sampleRate = readPositiveInteger(config["sample_rate"], 16000);
+    const audioFormat: AudioFormat = { encoding: "pcm_s16le", sampleRateHz: sampleRate, channels: 1 };
+    assertAudioFormat(audioFormat);
+
+    this.session = await startStreamingTtsSession(bus, {
+      protocol: new GrokWireProtocol(),
+      provider: { name: "grok", model: voiceId, region: "global" },
+      format: audioFormat,
+      sampleRateHz: sampleRate,
+      url: () => {
+        const params = new URLSearchParams({
+          language,
+          voice: voiceId,
+          codec: "pcm",
+          sample_rate: String(sampleRate),
+        });
+        const separator = endpointUrl.includes("?") ? "&" : "?";
+        return `${endpointUrl}${separator}${params.toString()}`;
+      },
+      headers: { Authorization: `Bearer ${apiKey}` },
+      retry: readProviderRetryConfig(config),
+      finishTimeoutMs: readNonNegativeInteger(config["finish_timeout_ms"], 2000),
+      metricPrefix: "tts.grok",
+      socketFactory: this.socketFactory ?? (await defaultNodeSocketFactory()),
+      replayBufferSize: (config["replay_buffer_size"] as number) ?? 32,
+      keepAliveIntervalMs: KEEP_ALIVE_INTERVAL_MS,
+    });
   }
 
-  private emitEnd(contextId: string): void {
-    this.bus?.push(Route.Main, {
-      kind: "tts.end",
-      contextId,
-      timestampMs: Date.now(),
-    } satisfies TextToSpeechEndPacket);
+  async close(): Promise<void> {
+    await this.session?.dispose();
+    this.session = null;
   }
 }
 
-async function defaultSocketFactory(): Promise<SocketFactory> {
-  const mod = await import("@kuralle-syrinx/ws/node");
-  return mod.createNodeWsSocket;
-}
-
-function concatBytes(a: Uint8Array, b: Uint8Array): Uint8Array {
-  const out = new Uint8Array(a.byteLength + b.byteLength);
-  out.set(a, 0);
-  out.set(b, a.byteLength);
-  return out;
-}
-
 function grokProviderError(msg: Record<string, unknown>): Error {
   const message =
     (typeof msg["message"] === "string" && msg["message"]) ||