@kuralle-syrinx/grok 4.4.1 → 4.5.0

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,317 @@
+// 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,
+    });
+  });
+
+  it("cfg-flex: formats, transcription, temperature, modalities, toolChoice, sessionConfig reach session.update", async () => {
+    const mock = createMockSocketHarness();
+    const adapter = fromGrokRealtime({
+      apiKey: "test-key",
+      socketFactory: mock.factory,
+      url: () => "wss://example.test/realtime?model=grok-voice-latest",
+      inputAudioFormat: { type: "audio/pcmu", rate: 8000 },
+      outputAudioFormat: { type: "audio/pcmu", rate: 8000 },
+      inputTranscription: { model: "grok-asr" },
+      temperature: 0.55,
+      modalities: ["audio", "text"],
+      toolChoice: "required",
+      sessionConfig: { speed: 1.05, custom_field: "x" },
+    });
+
+    const openTask = adapter.open(new AbortController().signal);
+    await waitFor(() => mock.sent.length > 0);
+    mock.inject({ type: "session.updated" });
+    await openTask;
+
+    const session = (JSON.parse(mock.sent[0]!) as { session: Record<string, unknown> }).session;
+    expect(session["temperature"]).toBe(0.55);
+    expect(session["output_modalities"]).toEqual(["audio", "text"]);
+    expect(session["tool_choice"]).toBe("required");
+    expect(session["speed"]).toBe(1.05);
+    expect(session["custom_field"]).toBe("x");
+    // Default turn detection preserved when not overridden.
+    expect(session["turn_detection"]).toEqual({ type: "server_vad" });
+    expect(session["voice"]).toBe("eve");
+    const audio = session["audio"] as {
+      input: Record<string, unknown>;
+      output: Record<string, unknown>;
+    };
+    expect(audio.input["format"]).toEqual({ type: "audio/pcmu", rate: 8000 });
+    expect(audio.input["transcription"]).toEqual({ model: "grok-asr" });
+    expect(audio.output["format"]).toEqual({ type: "audio/pcmu", rate: 8000 });
+  });
+});