@kuralle-syrinx/grok 4.2.0 → 4.3.0

package/src/edge-safety.test.ts

@@ -1,146 +0,0 @@
-// 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

@@ -1,279 +0,0 @@
-// 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/stt.test.ts

@@ -1,244 +0,0 @@
-// SPDX-License-Identifier: MIT
-
-import { afterEach, describe, expect, it } from "vitest";
-import { WebSocketServer, type WebSocket } from "ws";
-import {
-  PipelineBusImpl,
-  Route,
-  type SttErrorPacket,
-  type SttInterimPacket,
-  type SttResultPacket,
-} from "@kuralle-syrinx/core";
-
-import { GrokSTTPlugin } from "./stt.js";
-
-let servers: WebSocketServer[] = [];
-
-afterEach(async () => {
-  await Promise.all(
-    servers.splice(0).map(
-      (server) =>
-        new Promise<void>((resolve) => {
-          for (const client of server.clients) client.terminate();
-          server.close(() => resolve());
-        }),
-    ),
-  );
-});
-
-async function createLocalServer(onConnection: (socket: WebSocket) => void): Promise<string> {
-  const server = await new Promise<WebSocketServer>((resolve) => {
-    let nextServer: WebSocketServer;
-    nextServer = new WebSocketServer({ port: 0 }, () => {
-      resolve(nextServer);
-    });
-  });
-  servers.push(server);
-  server.on("connection", onConnection);
-  const address = server.address();
-  if (!address || typeof address === "string") throw new Error("Expected TCP server address");
-  return `ws://127.0.0.1:${address.port}/stt`;
-}
-
-async function waitFor<T>(items: T[], count = 1): Promise<void> {
-  for (let i = 0; i < 50; i += 1) {
-    if (items.length >= count) return;
-    await new Promise((resolve) => setTimeout(resolve, 10));
-  }
-}
-
-describe("GrokSTTPlugin", () => {
-  it("waits for transcript.created before sending binary audio", async () => {
-    const binaryFrames: Uint8Array[] = [];
-    const controlMessages: string[] = [];
-    const endpointUrl = await createLocalServer((socket) => {
-      socket.on("message", (data, isBinary) => {
-        if (isBinary) {
-          binaryFrames.push(new Uint8Array(data as Buffer));
-          return;
-        }
-        controlMessages.push(data.toString());
-      });
-      socket.send(JSON.stringify({ type: "transcript.created" }));
-    });
-
-    const bus = new PipelineBusImpl();
-    const started = bus.start();
-    const plugin = new GrokSTTPlugin();
-
-    await plugin.initialize(bus, {
-      api_key: "test",
-      endpoint_url: endpointUrl,
-      sample_rate: 16000,
-    });
-    bus.push(Route.Main, {
-      kind: "stt.audio",
-      contextId: "turn-1",
-      timestampMs: Date.now(),
-      audio: new Uint8Array(640),
-    });
-    await waitFor(binaryFrames);
-
-    expect(binaryFrames).toEqual([new Uint8Array(640)]);
-    expect(controlMessages).toEqual([]);
-
-    await plugin.close();
-    await waitFor(controlMessages);
-    expect(controlMessages).toContain(JSON.stringify({ type: "audio.done" }));
-    bus.stop();
-    await started;
-  });
-
-  it("maps transcript.partial to stt.interim and stt.result", async () => {
-    const endpointUrl = await createLocalServer((socket) => {
-      socket.send(JSON.stringify({ type: "transcript.created" }));
-      socket.on("message", (data, isBinary) => {
-        if (!isBinary) return;
-        socket.send(JSON.stringify({
-          type: "transcript.partial",
-          text: "hello",
-          is_final: false,
-        }));
-        socket.send(JSON.stringify({
-          type: "transcript.partial",
-          text: "hello world",
-          is_final: true,
-          speech_final: false,
-          words: [{ word: "hello" }, { word: "world" }],
-          start: 0,
-          duration: 1.2,
-          end_of_turn_confidence: 0.91,
-        }));
-        socket.send(JSON.stringify({
-          type: "transcript.partial",
-          text: "hello world",
-          is_final: true,
-          speech_final: true,
-          end_of_turn_confidence: 0.95,
-        }));
-      });
-    });
-
-    const bus = new PipelineBusImpl();
-    const started = bus.start();
-    const plugin = new GrokSTTPlugin();
-    const interims: Array<{ text: string }> = [];
-    const finals: SttResultPacket[] = [];
-    const turnCompletes: Array<{ kind: string }> = [];
-    bus.on("stt.interim", (pkt) => {
-      interims.push({ text: (pkt as SttInterimPacket).text });
-    });
-    bus.on("stt.result", (pkt) => {
-      finals.push(pkt as SttResultPacket);
-    });
-    bus.on("eos.turn_complete", (pkt) => {
-      turnCompletes.push(pkt as { kind: string });
-    });
-
-    await plugin.initialize(bus, {
-      api_key: "test",
-      endpoint_url: endpointUrl,
-      sample_rate: 16000,
-    });
-    bus.push(Route.Main, {
-      kind: "user.audio_received",
-      contextId: "turn-2",
-      timestampMs: Date.now(),
-      audio: new Uint8Array(320),
-    });
-    await waitFor(finals, 2);
-    await waitFor(turnCompletes);
-
-    expect(interims).toEqual([{ text: "hello" }]);
-    expect(finals[0]).toEqual(
-      expect.objectContaining({
-        kind: "stt.result",
-        contextId: "turn-2",
-        text: "hello world",
-        confidence: 0.91,
-        provider: expect.objectContaining({
-          name: "grok",
-          speechFinal: false,
-          words: [{ word: "hello" }, { word: "world" }],
-          start: 0,
-          duration: 1.2,
-        }),
-      }),
-    );
-    expect(finals[1]).toEqual(
-      expect.objectContaining({
-        text: "hello world",
-        confidence: 0.95,
-        provider: expect.objectContaining({ speechFinal: true }),
-      }),
-    );
-    expect(turnCompletes).toHaveLength(1);
-
-    await plugin.close();
-    bus.stop();
-    await started;
-  });
-
-  it("sends audio.done on stt.finalize", async () => {
-    const controlMessages: string[] = [];
-    const endpointUrl = await createLocalServer((socket) => {
-      socket.send(JSON.stringify({ type: "transcript.created" }));
-      socket.on("message", (data, isBinary) => {
-        if (!isBinary) controlMessages.push(data.toString());
-      });
-    });
-
-    const bus = new PipelineBusImpl();
-    const started = bus.start();
-    const plugin = new GrokSTTPlugin();
-
-    await plugin.initialize(bus, {
-      api_key: "test",
-      endpoint_url: endpointUrl,
-      sample_rate: 16000,
-    });
-    bus.push(Route.Main, {
-      kind: "stt.finalize",
-      contextId: "turn-3",
-      timestampMs: Date.now(),
-    });
-    await waitFor(controlMessages);
-
-    expect(JSON.parse(controlMessages[0]!)).toEqual({ type: "audio.done" });
-
-    await plugin.close();
-    bus.stop();
-    await started;
-  });
-
-  it("maps provider error frames to stt.error", async () => {
-    const endpointUrl = await createLocalServer((socket) => {
-      socket.send(JSON.stringify({ type: "error", message: "bad audio format" }));
-    });
-    const bus = new PipelineBusImpl();
-    const started = bus.start();
-    const plugin = new GrokSTTPlugin();
-    const errors: SttErrorPacket[] = [];
-    bus.on("stt.error", (pkt) => {
-      errors.push(pkt as SttErrorPacket);
-    });
-
-    await plugin.initialize(bus, {
-      api_key: "test",
-      endpoint_url: endpointUrl,
-      sample_rate: 16000,
-    });
-    await waitFor(errors);
-
-    expect(errors[0]).toEqual(
-      expect.objectContaining({
-        kind: "stt.error",
-        cause: expect.objectContaining({ message: "bad audio format" }),
-      }),
-    );
-
-    await plugin.close();
-    bus.stop();
-    await started;
-  });
-});