@kuralle-syrinx/grok 2.1.0

package/LICENSE

@@ -0,0 +1,22 @@
+MIT License
+
+Copyright (c) 2026 Kuralle
+
+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,116 @@
+# @kuralle-syrinx/grok
+
+xAI Grok voice provider for Syrinx — streaming STT, streaming TTS, and speech-to-speech realtime.
+
+## Install
+
+```bash
+pnpm add @kuralle-syrinx/grok
+```
+
+## Auth
+
+Pass `apiKey` in plugin config or adapter options. For local smokes, set `XAI_API_KEY` in the repo-root `.env`.
+
+## Streaming STT — `GrokSTTPlugin`
+
+```typescript
+import { GrokSTTPlugin } from "@kuralle-syrinx/grok/stt";
+import { createNodeWsSocket } from "@kuralle-syrinx/ws/node";
+
+const stt = new GrokSTTPlugin(createNodeWsSocket);
+await stt.initialize(bus, {
+  api_key: process.env.XAI_API_KEY!,
+  language: "en",
+  sample_rate: 16000,
+});
+```
+
+Connects to `wss://api.x.ai/v1/stt` with query-param config. Sends raw PCM16 frames after `transcript.created`, then `{"type":"audio.done"}` on finalize/shutdown. Emits `stt.interim`, `stt.result`, and `eos.turn_complete` (when `speech_final`).
+
+## Streaming TTS — `GrokTTSPlugin`
+
+```typescript
+import { GrokTTSPlugin } from "@kuralle-syrinx/grok/tts";
+
+const tts = new GrokTTSPlugin(createNodeWsSocket);
+await tts.initialize(bus, {
+  api_key: process.env.XAI_API_KEY!,
+  voice_id: "eve",
+  sample_rate: 16000,
+});
+```
+
+Connects to `wss://api.x.ai/v1/tts?codec=pcm&sample_rate=16000`. Consumes `tts.text` / `tts.done`, emits `tts.audio` + `tts.end`. Uses `text.delta` / `text.done` / `text.clear` on the wire.
+
+## Realtime S2S — `fromGrokRealtime`
+
+```typescript
+import { fromGrokRealtime } from "@kuralle-syrinx/grok/realtime";
+import { RealtimeBridge } from "@kuralle-syrinx/realtime";
+
+const adapter = fromGrokRealtime({
+  apiKey: process.env.XAI_API_KEY!,
+  socketFactory: createNodeWsSocket,
+  voice: "eve",
+  turnDetection: { type: "server_vad" },
+  tools: [/* caller-supplied RealtimeToolDef[] */],
+});
+const bridge = new RealtimeBridge(adapter);
+```
+
+OpenAI Realtime-compatible subset on `wss://api.x.ai/v1/realtime?model=grok-voice-latest`. Caps: `supportsTruncate: false`, `supportsConcurrentToolAudio: false`. Barge-in relies on client/kernel VAD plus `response.cancel` (no `speech_started` / truncate).
+
+## Deploy on Cloudflare Workers
+
+`@kuralle-syrinx/grok` is **edge-clean**: no `Buffer`, `process`, or `node:*` in `src/`. All three surfaces (STT, TTS, realtime S2S) accept an injectable `SocketFactory` — on Workers, outbound provider WebSockets that require auth headers use the fetch-upgrade path via `createWorkersSocket` (not the global `WebSocket` constructor, which cannot set headers).
+
+Wire secrets through the Worker **`env` binding** (Wrangler secrets / vars), not `process.env`. Pass `apiKey` as constructor/initialize config:
+
+```ts
+import { VoiceAgentSession } from "@kuralle-syrinx/core";
+import { GrokSTTPlugin } from "@kuralle-syrinx/grok/stt";
+import { GrokTTSPlugin } from "@kuralle-syrinx/grok/tts";
+import { fromGrokRealtime } from "@kuralle-syrinx/grok/realtime";
+import { RealtimeBridge } from "@kuralle-syrinx/realtime";
+import { createWorkersSocket } from "@kuralle-syrinx/ws/workers";
+
+/** Bound in wrangler.jsonc / dashboard — e.g. XAI_API_KEY secret. */
+export interface Env {
+  readonly XAI_API_KEY: string;
+}
+
+export function createGrokVoiceSession(env: Env): VoiceAgentSession {
+  const stt = new GrokSTTPlugin(createWorkersSocket);
+  const tts = new GrokTTSPlugin(createWorkersSocket);
+  const adapter = fromGrokRealtime({
+    apiKey: env.XAI_API_KEY,
+    socketFactory: createWorkersSocket,
+    voice: "eve",
+    turnDetection: { type: "server_vad" },
+  });
+
+  const session = new VoiceAgentSession({
+    endpointingOwner: "timer",
+    plugins: { stt: {}, tts: {}, realtime: {} },
+  });
+  session.registerPlugin("stt", stt);
+  session.registerPlugin("tts", tts);
+  session.registerPlugin("realtime", new RealtimeBridge(adapter));
+  return session;
+}
+```
+
+**Durable Object session shape** (see `packages/server-workers`): the Worker `fetch` handler routes `/ws?sessionId=…` to a `VoiceConversation` Durable Object. The DO accepts the client upgrade via `WebSocketPair`, constructs the `VoiceAgentSession` (cascade or bi-model realtime — same env-injection pattern), and pumps audio over the accepted socket. Provider outbound legs (Grok STT/TTS/realtime, Deepgram, Cartesia, …) all dial through `createWorkersSocket` so auth headers ride on the fetch upgrade.
+
+Regression lock: `edge-safety.test.ts` scans `src/` for Node-only primitives and runs the realtime audio path with a mock socket.
+
+## Live smokes
+
+From `examples/02-hello-voice-headless` (requires `XAI_API_KEY`):
+
+```bash
+pnpm smoke:grok-stt
+pnpm smoke:grok-tts
+pnpm smoke:grok-realtime
+```

package/package.json

@@ -0,0 +1,30 @@
+{
+  "name": "@kuralle-syrinx/grok",
+  "version": "2.1.0",
+  "private": false,
+  "type": "module",
+  "license": "MIT",
+  "main": "./src/index.ts",
+  "types": "./src/index.ts",
+  "exports": {
+    ".": "./src/index.ts",
+    "./stt": "./src/stt.ts",
+    "./tts": "./src/tts.ts",
+    "./realtime": "./src/from-grok-realtime.ts"
+  },
+  "dependencies": {
+    "@kuralle-syrinx/core": "2.1.0",
+    "@kuralle-syrinx/ws": "2.1.0",
+    "@kuralle-syrinx/realtime": "2.1.0"
+  },
+  "devDependencies": {
+    "@types/ws": "^8.5.0",
+    "typescript": "^5.7.0",
+    "vitest": "^2.1.0",
+    "ws": "^8.18.0"
+  },
+  "scripts": {
+    "typecheck": "tsc --noEmit",
+    "test": "vitest run"
+  }
+}

package/src/edge-safety.test.ts

@@ -0,0 +1,146 @@
+// SPDX-License-Identifier: MIT
+//
+// Regression gate — the grok package must run on workerd without Buffer, process,
+// or node:* imports. Reintroducing any Node-only primitive in src/ should fail.
+
+import { readFileSync, readdirSync } from "node:fs";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+
+import { describe, expect, it } from "vitest";
+
+import type { ManagedSocket, SocketData, SocketFactory } from "@kuralle-syrinx/ws";
+
+import { bytesToBase64, fromGrokRealtime } from "./from-grok-realtime.js";
+import type { RealtimeEvent } from "@kuralle-syrinx/realtime";
+
+const srcDir = path.dirname(fileURLToPath(import.meta.url));
+
+interface EdgeMockHarness {
+  readonly factory: SocketFactory;
+  readonly sent: string[];
+  inject(msg: Record<string, unknown>): void;
+}
+
+function createEdgeMockHarness(): EdgeMockHarness {
+  const sent: string[] = [];
+  let messageHandler: ((data: SocketData, isBinary: boolean) => void) | null = null;
+
+  const socket: ManagedSocket = {
+    get isOpen() {
+      return true;
+    },
+    send: (data: SocketData) => {
+      sent.push(typeof data === "string" ? data : "");
+    },
+    keepAlivePing: () => {},
+    verify: async () => true,
+    dispose: () => {},
+    onOpen: (handler) => {
+      queueMicrotask(() => handler());
+    },
+    onMessage: (handler) => {
+      messageHandler = handler;
+    },
+    onClose: () => {},
+    onError: () => {},
+  };
+
+  return {
+    factory: () => socket,
+    sent,
+    inject: (msg) => messageHandler?.(JSON.stringify(msg), false),
+  };
+}
+
+function collectSourceFiles(dir: string): string[] {
+  const out: string[] = [];
+  for (const entry of readdirSync(dir, { withFileTypes: true })) {
+    const full = path.join(dir, entry.name);
+    if (entry.isDirectory()) {
+      out.push(...collectSourceFiles(full));
+      continue;
+    }
+    if (entry.name.endsWith(".ts") && !entry.name.endsWith(".test.ts")) {
+      out.push(full);
+    }
+  }
+  return out;
+}
+
+async function collectEvents(
+  events: AsyncIterable<RealtimeEvent>,
+  max = 2,
+): Promise<RealtimeEvent[]> {
+  const out: RealtimeEvent[] = [];
+  for await (const event of events) {
+    out.push(event);
+    if (out.length >= max) break;
+  }
+  return out;
+}
+
+async function waitFor(predicate: () => boolean, timeoutMs = 2000): Promise<void> {
+  const startedAt = Date.now();
+  while (Date.now() - startedAt < timeoutMs) {
+    if (predicate()) return;
+    await new Promise((resolve) => setTimeout(resolve, 5));
+  }
+  throw new Error("Timed out waiting for condition");
+}
+
+describe("edge safety (grok)", () => {
+  it("src/ contains no Buffer, process, or node:* imports", () => {
+    const forbidden = [
+      /\bfrom\s+["']node:/,
+      /\brequire\s*\(\s*["']node:/,
+      /\bglobalThis\.Buffer\b/,
+      /\bglobalThis\.process\b/,
+      /\bprocess\.env\b/,
+      /\bBuffer\.from\b/,
+      /\bBuffer\.alloc\b/,
+    ];
+    const hits: string[] = [];
+    for (const file of collectSourceFiles(srcDir)) {
+      const text = readFileSync(file, "utf8");
+      for (const pattern of forbidden) {
+        if (pattern.test(text)) {
+          hits.push(`${path.relative(srcDir, file)}: ${pattern.source}`);
+        }
+      }
+    }
+    expect(hits).toEqual([]);
+  });
+
+  it("fromGrokRealtime round-trips audio via runtime-agnostic helpers", async () => {
+    const mock = createEdgeMockHarness();
+    const adapter = fromGrokRealtime({
+      apiKey: "edge-test-key",
+      socketFactory: mock.factory,
+      url: () => "wss://example.test/realtime?model=grok-voice-latest",
+    });
+
+    const eventsTask = collectEvents(adapter.events, 2);
+    const openTask = adapter.open(new AbortController().signal);
+    await waitFor(() => mock.sent.length > 0);
+    mock.inject({ type: "session.updated" });
+    await openTask;
+
+    const providerPcm = new Uint8Array([100, 200, 300, 400]);
+    mock.inject({ type: "response.created" });
+    mock.inject({
+      type: "response.output_audio.delta",
+      delta: bytesToBase64(providerPcm),
+    });
+
+    const events = await eventsTask;
+    expect(events[0]).toEqual({ type: "response_started" });
+    expect(events[1]).toEqual({
+      type: "audio",
+      pcm16: providerPcm,
+      sampleRateHz: 24_000,
+    });
+
+    await adapter.close();
+  });
+});

package/src/from-grok-realtime.test.ts

@@ -0,0 +1,279 @@
+// SPDX-License-Identifier: MIT
+
+import { describe, expect, it } from "vitest";
+
+import type { ManagedSocket, SocketData, SocketFactory } from "@kuralle-syrinx/ws";
+
+import type { RealtimeEvent } from "@kuralle-syrinx/realtime";
+
+import { bytesToBase64, fromGrokRealtime } from "./from-grok-realtime.js";
+
+interface MockSocketHarness {
+  readonly factory: SocketFactory;
+  readonly sent: string[];
+  inject(msg: Record<string, unknown>): void;
+}
+
+function createMockSocketHarness(): MockSocketHarness {
+  const sent: string[] = [];
+  let messageHandler: ((data: SocketData, isBinary: boolean) => void) | null = null;
+
+  const socket: ManagedSocket = {
+    get isOpen() {
+      return true;
+    },
+    send: (data: SocketData) => {
+      sent.push(typeof data === "string" ? data : "");
+    },
+    keepAlivePing: () => {},
+    verify: async () => true,
+    dispose: () => {},
+    onOpen: (handler) => {
+      queueMicrotask(() => handler());
+    },
+    onMessage: (handler) => {
+      messageHandler = handler;
+    },
+    onClose: () => {},
+    onError: () => {},
+  };
+
+  return {
+    factory: () => socket,
+    sent,
+    inject: (msg) => messageHandler?.(JSON.stringify(msg), false),
+  };
+}
+
+async function collectEvents(
+  events: AsyncIterable<RealtimeEvent>,
+  max = 8,
+): Promise<RealtimeEvent[]> {
+  const out: RealtimeEvent[] = [];
+  for await (const event of events) {
+    out.push(event);
+    if (out.length >= max) break;
+  }
+  return out;
+}
+
+async function waitFor(predicate: () => boolean, timeoutMs = 2000): Promise<void> {
+  const startedAt = Date.now();
+  while (Date.now() - startedAt < timeoutMs) {
+    if (predicate()) return;
+    await new Promise((resolve) => setTimeout(resolve, 5));
+  }
+  throw new Error("Timed out waiting for condition");
+}
+
+describe("fromGrokRealtime", () => {
+  it("sends Grok session.update and client control messages", async () => {
+    const mock = createMockSocketHarness();
+    const adapter = fromGrokRealtime({
+      apiKey: "test-key",
+      socketFactory: mock.factory,
+      url: () => "wss://example.test/realtime?model=grok-voice-latest",
+      voice: "eve",
+      instructions: "Be concise.",
+      turnDetection: { type: "server_vad" },
+      tools: [
+        {
+          name: "lookup",
+          description: "Look up facts.",
+          parameters: { type: "object", properties: { q: { type: "string" } }, required: ["q"] },
+        },
+      ],
+    });
+
+    const openTask = adapter.open(new AbortController().signal);
+    await waitFor(() => mock.sent.length > 0);
+    mock.inject({ type: "session.updated" });
+    await openTask;
+
+    expect(JSON.parse(mock.sent[0]!)).toEqual({
+      type: "session.update",
+      session: {
+        voice: "eve",
+        instructions: "Be concise.",
+        turn_detection: { type: "server_vad" },
+        tools: [
+          {
+            type: "function",
+            name: "lookup",
+            description: "Look up facts.",
+            parameters: { type: "object", properties: { q: { type: "string" } }, required: ["q"] },
+          },
+        ],
+        audio: {
+          input: { format: { type: "audio/pcm", rate: 24000 } },
+          output: { format: { type: "audio/pcm", rate: 24000 }, voice: "eve" },
+        },
+      },
+    });
+
+    const pcm = new Uint8Array([0, 1, 2, 3]);
+    adapter.sendAudio(pcm);
+    expect(JSON.parse(mock.sent[1]!)).toEqual({
+      type: "input_audio_buffer.append",
+      audio: bytesToBase64(pcm),
+    });
+
+    mock.inject({ type: "response.created" });
+    adapter.cancelResponse(420);
+    expect(JSON.parse(mock.sent[2]!)).toEqual({ type: "response.cancel" });
+    expect(
+      mock.sent
+        .map((raw) => JSON.parse(raw) as Record<string, unknown>)
+        .some((msg) => msg["type"] === "conversation.item.truncate"),
+    ).toBe(false);
+
+    adapter.injectToolResult("call_abc", "result text");
+    expect(JSON.parse(mock.sent[3]!)).toEqual({
+      type: "conversation.item.create",
+      item: {
+        type: "function_call_output",
+        call_id: "call_abc",
+        output: "result text",
+      },
+    });
+    expect(mock.sent).toHaveLength(4);
+
+    mock.inject({ type: "response.done", response: {} });
+    expect(JSON.parse(mock.sent[4]!)).toEqual({ type: "response.create" });
+  });
+
+  it("normalizes provider server events into RealtimeEvent", async () => {
+    const mock = createMockSocketHarness();
+    const adapter = fromGrokRealtime({
+      apiKey: "test-key",
+      socketFactory: mock.factory,
+      url: () => "wss://example.test/realtime?model=grok-voice-latest",
+    });
+
+    const eventsTask = collectEvents(adapter.events, 7);
+    const openTask = adapter.open(new AbortController().signal);
+    await waitFor(() => mock.sent.length > 0);
+    mock.inject({ type: "session.updated" });
+    await openTask;
+
+    const audioBytes = new Uint8Array([9, 10, 11, 12]);
+    mock.inject({ type: "response.created" });
+    mock.inject({ type: "response.output_audio.delta", delta: bytesToBase64(audioBytes) });
+    mock.inject({
+      type: "conversation.item.input_audio_transcription.updated",
+      transcript: "hello there",
+    });
+    mock.inject({ type: "response.output_audio_transcript.delta", delta: "Sure, " });
+    mock.inject({
+      type: "response.output_audio_transcript.done",
+      transcript: "Sure, I can help.",
+    });
+    mock.inject({
+      type: "response.done",
+      response: {
+        output: [
+          {
+            type: "function_call",
+            call_id: "call_123",
+            name: "lookup",
+            arguments: JSON.stringify({ q: "hours" }),
+          },
+        ],
+      },
+    });
+
+    const events = await eventsTask;
+    expect(events.slice(0, 6)).toEqual([
+      { type: "response_started" },
+      { type: "audio", pcm16: audioBytes, sampleRateHz: 24000 },
+      { type: "transcript", role: "user", text: "hello there", final: true },
+      { type: "transcript", role: "assistant", text: "Sure, ", final: false },
+      { type: "transcript", role: "assistant", text: "Sure, I can help.", final: true },
+      {
+        type: "tool_call",
+        toolId: "call_123",
+        toolName: "lookup",
+        args: { q: "hours" },
+      },
+    ]);
+    expect(events[6]).toEqual({ type: "response_done" });
+  });
+
+  it("B1: does not send response.create while response is active (cancel-in-flight, no truncate)", async () => {
+    const mock = createMockSocketHarness();
+    const adapter = fromGrokRealtime({
+      apiKey: "test-key",
+      socketFactory: mock.factory,
+      url: () => "wss://example.test/realtime?model=grok-voice-latest",
+    });
+
+    const openTask = adapter.open(new AbortController().signal);
+    await waitFor(() => mock.sent.length > 0);
+    mock.inject({ type: "session.updated" });
+    await openTask;
+
+    mock.inject({ type: "response.created" });
+    adapter.cancelResponse(420);
+    expect(JSON.parse(mock.sent[1]!)).toEqual({ type: "response.cancel" });
+    expect(
+      mock.sent
+        .map((raw) => JSON.parse(raw) as Record<string, unknown>)
+        .some((msg) => msg["type"] === "conversation.item.truncate"),
+    ).toBe(false);
+
+    adapter.injectToolResult("call_abc", "result text");
+    const typesAfterInject = mock.sent.map(
+      (raw) => (JSON.parse(raw) as Record<string, unknown>)["type"],
+    );
+    expect(typesAfterInject).toContain("conversation.item.create");
+    expect(typesAfterInject).not.toContain("response.create");
+
+    mock.inject({ type: "response.done", response: {} });
+    expect(JSON.parse(mock.sent[mock.sent.length - 1]!)).toEqual({ type: "response.create" });
+  });
+
+  it("B1: does not send response.create while response is active (direct inject without cancel)", async () => {
+    const mock = createMockSocketHarness();
+    const adapter = fromGrokRealtime({
+      apiKey: "test-key",
+      socketFactory: mock.factory,
+      url: () => "wss://example.test/realtime?model=grok-voice-latest",
+    });
+
+    const openTask = adapter.open(new AbortController().signal);
+    await waitFor(() => mock.sent.length > 0);
+    mock.inject({ type: "session.updated" });
+    await openTask;
+
+    mock.inject({ type: "response.created" });
+
+    adapter.injectToolResult("call_xyz", "inline result");
+    const typesAfterInject = mock.sent.map(
+      (raw) => (JSON.parse(raw) as Record<string, unknown>)["type"],
+    );
+    expect(typesAfterInject).toContain("conversation.item.create");
+    expect(typesAfterInject).not.toContain("response.create");
+
+    mock.inject({ type: "response.done", response: {} });
+    expect(
+      mock.sent.map((raw) => (JSON.parse(raw) as Record<string, unknown>)["type"]),
+    ).toContain("response.create");
+  });
+
+  it("exposes Grok capability flags", () => {
+    const mock = createMockSocketHarness();
+    const adapter = fromGrokRealtime({
+      apiKey: "test-key",
+      socketFactory: mock.factory,
+      inputRateHz: 16000,
+      outputRateHz: 16000,
+    });
+    expect(adapter.caps).toEqual({
+      inputSampleRateHz: 16000,
+      outputSampleRateHz: 16000,
+      supportsConcurrentToolAudio: false,
+      supportsTruncate: false,
+      emitsServerSpeechStarted: false,
+    });
+  });
+});

package/src/from-grok-realtime.ts

@@ -0,0 +1,94 @@
+// SPDX-License-Identifier: MIT
+
+import type { SocketFactory } from "@kuralle-syrinx/ws";
+import {
+  base64ToBytes,
+  bytesToBase64,
+  createOpenAiCompatibleRealtimeAdapter,
+  type RealtimeAdapter,
+  type RealtimeToolDef,
+} from "@kuralle-syrinx/realtime";
+
+const DEFAULT_MODEL = "grok-voice-latest";
+const DEFAULT_VOICE = "eve";
+const DEFAULT_SAMPLE_RATE_HZ = 24_000;
+
+export interface GrokRealtimeOptions {
+  readonly apiKey: string;
+  readonly model?: string;
+  readonly voice?: string;
+  readonly socketFactory: SocketFactory;
+  readonly url?: () => string;
+  readonly turnDetection?: Record<string, unknown> | null;
+  readonly tools?: readonly RealtimeToolDef[];
+  readonly debug?: boolean;
+  readonly instructions?: string;
+  readonly inputRateHz?: number;
+  readonly outputRateHz?: number;
+}
+
+export function fromGrokRealtime(opts: GrokRealtimeOptions): RealtimeAdapter {
+  const inputRateHz = opts.inputRateHz ?? DEFAULT_SAMPLE_RATE_HZ;
+  const outputRateHz = opts.outputRateHz ?? DEFAULT_SAMPLE_RATE_HZ;
+  const voice = opts.voice ?? DEFAULT_VOICE;
+
+  return createOpenAiCompatibleRealtimeAdapter({
+    apiKey: opts.apiKey,
+    socketFactory: opts.socketFactory,
+    debug: opts.debug,
+    debugLogPrefix: "[grok-raw]",
+    defaultModel: DEFAULT_MODEL,
+    model: opts.model,
+    url: opts.url,
+    buildUrl: (model) => `wss://api.x.ai/v1/realtime?model=${encodeURIComponent(model)}`,
+    caps: {
+      inputSampleRateHz: inputRateHz,
+      outputSampleRateHz: outputRateHz,
+      supportsConcurrentToolAudio: false,
+      supportsTruncate: false,
+      emitsServerSpeechStarted: false,
+    },
+    buildSessionUpdate: () => {
+      const turnDetection =
+        "turnDetection" in opts ? opts.turnDetection : { type: "server_vad" };
+
+      const session: Record<string, unknown> = {
+        voice,
+        turn_detection: turnDetection,
+        tools: (opts.tools ?? []).map((t) => ({
+          type: "function" as const,
+          name: t.name,
+          description: t.description,
+          parameters: t.parameters,
+        })),
+        audio: {
+          input: { format: { type: "audio/pcm", rate: inputRateHz } },
+          output: { format: { type: "audio/pcm", rate: outputRateHz }, voice },
+        },
+      };
+
+      if (opts.instructions !== undefined) {
+        session["instructions"] = opts.instructions;
+      }
+
+      return session;
+    },
+    supportsTruncate: false,
+    defaultErrorMessage: "Grok Realtime error",
+    extendServerMessage: (type, msg, ctx) => {
+      if (type !== "conversation.item.input_audio_transcription.updated") return false;
+      const transcript = typeof msg["transcript"] === "string" ? msg["transcript"] : "";
+      if (transcript.length > 0) {
+        ctx.push({
+          type: "transcript",
+          role: "user",
+          text: transcript,
+          final: true,
+        });
+      }
+      return true;
+    },
+  });
+}
+
+export { base64ToBytes, bytesToBase64 };

package/src/index.ts

@@ -0,0 +1,5 @@
+// SPDX-License-Identifier: MIT
+
+export { GrokSTTPlugin } from "./stt.js";
+export { GrokTTSPlugin } from "./tts.js";
+export { fromGrokRealtime, type GrokRealtimeOptions } from "./from-grok-realtime.js";