@kernl-sdk/xai 0.1.0

package/dist/realtime.d.ts

@@ -0,0 +1,36 @@
+import type { RealtimeModel, RealtimeConnection, RealtimeConnectOptions, ClientCredential } from "@kernl-sdk/protocol";
+/**
+ * Options for creating a Grok realtime model.
+ */
+export interface GrokRealtimeOptions {
+    /**
+     * xAI API key. Defaults to XAI_API_KEY env var.
+     */
+    apiKey?: string;
+    /**
+     * Base URL for the realtime API.
+     */
+    baseUrl?: string;
+}
+/**
+ * Grok (xAI) realtime model implementation.
+ */
+export declare class GrokRealtimeModel implements RealtimeModel {
+    readonly spec: "1.0";
+    readonly provider = "xai";
+    readonly modelId: string;
+    private apiKey;
+    private baseUrl;
+    constructor(modelId: string, options?: GrokRealtimeOptions);
+    /**
+     * Create ephemeral credential for client-side connections.
+     *
+     * Must be called server-side where API key is available.
+     */
+    authenticate(): Promise<ClientCredential>;
+    /**
+     * Establish a WebSocket connection to the Grok realtime API.
+     */
+    connect(options?: RealtimeConnectOptions): Promise<RealtimeConnection>;
+}
+//# sourceMappingURL=realtime.d.ts.map

package/dist/realtime.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"realtime.d.ts","sourceRoot":"","sources":["../src/realtime.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EACV,aAAa,EACb,kBAAkB,EAElB,sBAAsB,EAGtB,gBAAgB,EAEjB,MAAM,qBAAqB,CAAC;AAQ7B;;GAEG;AACH,MAAM,WAAW,mBAAmB;IAClC;;OAEG;IACH,MAAM,CAAC,EAAE,MAAM,CAAC;IAEhB;;OAEG;IACH,OAAO,CAAC,EAAE,MAAM,CAAC;CAClB;AAED;;GAEG;AACH,qBAAa,iBAAkB,YAAW,aAAa;IACrD,QAAQ,CAAC,IAAI,EAAG,KAAK,CAAU;IAC/B,QAAQ,CAAC,QAAQ,SAAS;IAC1B,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IAEzB,OAAO,CAAC,MAAM,CAAgB;IAC9B,OAAO,CAAC,OAAO,CAAS;gBAEZ,OAAO,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,mBAAmB;IAS1D;;;;OAIG;IACG,YAAY,IAAI,OAAO,CAAC,gBAAgB,CAAC;IAgC/C;;OAEG;IACG,OAAO,CAAC,OAAO,CAAC,EAAE,sBAAsB,GAAG,OAAO,CAAC,kBAAkB,CAAC;CA4E7E"}

package/dist/realtime.js

@@ -0,0 +1,250 @@
+import { Emitter } from "@kernl-sdk/shared";
+import { CLIENT_EVENT, SERVER_EVENT } from "./convert/event.js";
+const XAI_REALTIME_URL = "wss://api.x.ai/v1/realtime";
+const XAI_CLIENT_SECRETS_URL = "https://api.x.ai/v1/realtime/client_secrets";
+/**
+ * Grok (xAI) realtime model implementation.
+ */
+export class GrokRealtimeModel {
+    spec = "1.0";
+    provider = "xai";
+    modelId;
+    apiKey;
+    baseUrl;
+    constructor(modelId, options) {
+        this.modelId = modelId;
+        this.apiKey =
+            options?.apiKey ??
+                (typeof process !== "undefined" ? process.env?.XAI_API_KEY : null) ??
+                null;
+        this.baseUrl = options?.baseUrl ?? XAI_REALTIME_URL;
+    }
+    /**
+     * Create ephemeral credential for client-side connections.
+     *
+     * Must be called server-side where API key is available.
+     */
+    async authenticate() {
+        if (!this.apiKey) {
+            throw new Error("API key required for authenticate(). " +
+                "Call this server-side where XAI_API_KEY is available.");
+        }
+        const res = await fetch(XAI_CLIENT_SECRETS_URL, {
+            method: "POST",
+            headers: {
+                Authorization: `Bearer ${this.apiKey}`,
+                "Content-Type": "application/json",
+            },
+            body: JSON.stringify({
+                expires_after: { seconds: 300 },
+            }),
+        });
+        if (!res.ok) {
+            const text = await res.text();
+            throw new Error(`Failed to create credential: ${res.status} ${text}`);
+        }
+        const data = (await res.json());
+        return {
+            kind: "token",
+            token: data.value,
+            expiresAt: new Date(Date.now() + 300_000), // 5 min TTL
+        };
+    }
+    /**
+     * Establish a WebSocket connection to the Grok realtime API.
+     */
+    async connect(options) {
+        const credential = options?.credential;
+        if (credential && credential.kind !== "token") {
+            throw new Error(`Grok requires token credentials, got "${credential.kind}".`);
+        }
+        const authToken = credential?.token ?? this.apiKey;
+        if (!authToken) {
+            throw new Error("No API key or credential provided. " +
+                "Either set XAI_API_KEY or pass a credential from authenticate().");
+        }
+        // Use injectable WebSocket or globalThis.WebSocket
+        const WS = options?.websocket ?? globalThis.WebSocket;
+        if (!WS) {
+            throw new Error("No WebSocket available. In Node.js <22, use WebSocketTransport with the 'ws' package:\n" +
+                "  import WebSocket from 'ws';\n" +
+                "  import { WebSocketTransport } from 'kernl';\n" +
+                "  new RealtimeSession(agent, { transport: new WebSocketTransport({ websocket: WebSocket }), ... })");
+        }
+        // Grok uses standard Authorization header via protocols
+        // Browser WebSocket doesn't support custom headers, so we pass token in subprotocol
+        const url = this.baseUrl;
+        // For browser: use subprotocol to pass auth (similar pattern to OpenAI)
+        // For Node.js with 'ws' package: headers can be passed directly
+        const protocols = [`token.${authToken}`];
+        const ws = new WS(url, protocols);
+        const connection = new GrokRealtimeConnection(ws);
+        await new Promise((resolve, reject) => {
+            if (options?.abort?.aborted) {
+                return reject(new Error("Connection aborted"));
+            }
+            const onOpen = () => {
+                cleanup();
+                resolve();
+            };
+            const onError = (event) => {
+                cleanup();
+                const err = event instanceof Error
+                    ? event
+                    : new Error("WebSocket connection failed");
+                reject(err);
+            };
+            const onAbort = () => {
+                cleanup();
+                ws.close();
+                reject(new Error("Connection aborted"));
+            };
+            const cleanup = () => {
+                ws.removeEventListener("open", onOpen);
+                ws.removeEventListener("error", onError);
+                options?.abort?.removeEventListener("abort", onAbort);
+            };
+            ws.addEventListener("open", onOpen);
+            ws.addEventListener("error", onError);
+            options?.abort?.addEventListener("abort", onAbort);
+        });
+        return connection;
+    }
+}
+// WebSocket readyState constants
+const WS_OPEN = 1;
+/**
+ * Grok realtime connection implementation.
+ */
+class GrokRealtimeConnection extends Emitter {
+    ws;
+    _status = "connecting";
+    _muted = false;
+    _sessionId = null;
+    // Audio state tracking for interruption
+    currid;
+    faudtime;
+    audlenms = 0;
+    responding = false;
+    constructor(socket) {
+        super();
+        this.ws = socket;
+        socket.addEventListener("message", (event) => {
+            try {
+                const data = event && typeof event === "object" && "data" in event
+                    ? event.data
+                    : String(event);
+                const raw = JSON.parse(data);
+                // Track audio state for interruption handling
+                if (raw.type === "response.output_audio.delta") {
+                    this.currid = raw.item_id;
+                    if (this.faudtime === undefined) {
+                        this.faudtime = Date.now();
+                        this.audlenms = 0;
+                    }
+                    // Calculate audio length assuming 24kHz PCM16
+                    const bytes = base64ByteLength(raw.delta);
+                    this.audlenms += (bytes / 2 / 24000) * 1000;
+                }
+                else if (raw.type === "response.created") {
+                    this.responding = true;
+                }
+                else if (raw.type === "response.done") {
+                    this.responding = false;
+                    this.reset();
+                }
+                else if (raw.type === "input_audio_buffer.speech_started") {
+                    this.interrupt();
+                }
+                const event_ = SERVER_EVENT.decode(raw);
+                if (event_) {
+                    if (event_.kind === "session.created") {
+                        this._sessionId = event_.session.id;
+                    }
+                    this.emit("event", event_);
+                }
+            }
+            catch (err) {
+                this.emit("error", err instanceof Error ? err : new Error(String(err)));
+            }
+        });
+        socket.addEventListener("open", () => {
+            this._status = "connected";
+            this.emit("status", this._status);
+        });
+        socket.addEventListener("close", () => {
+            this._status = "closed";
+            this.reset();
+            this.emit("status", this._status);
+        });
+        socket.addEventListener("error", (event) => {
+            const err = event instanceof Error ? event : new Error("WebSocket error");
+            this.emit("error", err);
+        });
+    }
+    get status() {
+        return this._status;
+    }
+    get muted() {
+        return this._muted;
+    }
+    get sessionId() {
+        return this._sessionId;
+    }
+    /**
+     * Send a client event to the Grok realtime API.
+     */
+    send(event) {
+        const encoded = CLIENT_EVENT.encode(event);
+        if (encoded && this.ws.readyState === WS_OPEN) {
+            this.ws.send(JSON.stringify(encoded));
+        }
+    }
+    /**
+     * Close the WebSocket connection.
+     */
+    close() {
+        this.reset();
+        this.ws.close();
+    }
+    /**
+     * Mute audio input.
+     */
+    mute() {
+        this._muted = true;
+    }
+    /**
+     * Unmute audio input.
+     */
+    unmute() {
+        this._muted = false;
+    }
+    /**
+     * Interrupt the current response.
+     *
+     * Note: Grok doesn't support response.cancel or item.truncate,
+     * so we just reset local state and emit the interrupted event.
+     */
+    interrupt() {
+        if (this.responding) {
+            this.responding = false;
+        }
+        this.emit("interrupted");
+        this.reset();
+    }
+    /**
+     * Reset audio tracking state.
+     */
+    reset() {
+        this.currid = undefined;
+        this.faudtime = undefined;
+        this.audlenms = 0;
+    }
+}
+/**
+ * Get byte length from base64 string without decoding.
+ */
+function base64ByteLength(b64) {
+    const padding = b64.endsWith("==") ? 2 : b64.endsWith("=") ? 1 : 0;
+    return (b64.length * 3) / 4 - padding;
+}

package/package.json

@@ -0,0 +1,55 @@
+{
+  "name": "@kernl-sdk/xai",
+  "version": "0.1.0",
+  "description": "xAI (Grok) realtime voice provider for kernl",
+  "keywords": [
+    "kernl",
+    "xai",
+    "grok",
+    "realtime",
+    "voice",
+    "ai"
+  ],
+  "author": "dremnik",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/kernl-sdk/kernl.git",
+    "directory": "packages/providers/xai"
+  },
+  "homepage": "https://github.com/kernl-sdk/kernl#readme",
+  "bugs": {
+    "url": "https://github.com/kernl-sdk/kernl/issues"
+  },
+  "type": "module",
+  "publishConfig": {
+    "access": "public"
+  },
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "scripts": {
+    "build": "tsc && tsc-alias --resolve-full-paths",
+    "dev": "tsc --watch",
+    "check-types": "tsc --noEmit",
+    "test": "vitest",
+    "test:watch": "vitest --watch",
+    "test:run": "vitest run"
+  },
+  "dependencies": {
+    "@kernl-sdk/protocol": "workspace:*",
+    "@kernl-sdk/shared": "workspace:*",
+    "ws": "^8.18.0"
+  },
+  "devDependencies": {
+    "@types/json-schema": "^7.0.15",
+    "@types/node": "^24.10.0",
+    "@types/ws": "^8.18.0",
+    "tsc-alias": "^1.8.10",
+    "typescript": "5.9.2",
+    "vitest": "^4.0.8"
+  }
+}

package/src/__tests__/realtime.integration.test.ts

@@ -0,0 +1,203 @@
+import { describe, it, expect, beforeAll, afterAll } from "vitest";
+
+import type {
+  RealtimeServerEvent,
+  RealtimeConnection,
+} from "@kernl-sdk/protocol";
+import { GrokRealtimeModel } from "../realtime/model";
+
+const XAI_API_KEY = process.env.XAI_API_KEY;
+
+describe.skipIf(!XAI_API_KEY)("Grok Realtime Integration", () => {
+  let model: GrokRealtimeModel;
+
+  beforeAll(() => {
+    model = new GrokRealtimeModel({
+      apiKey: XAI_API_KEY,
+    });
+  });
+
+  it("should connect and receive conversation.created", async () => {
+    const conn = await model.connect();
+    const events: RealtimeServerEvent[] = [];
+
+    const sessionCreated = new Promise<void>((resolve, reject) => {
+      const timeout = setTimeout(() => reject(new Error("timeout")), 10000);
+      conn.on("event", (e: RealtimeServerEvent) => {
+        events.push(e);
+        if (e.kind === "session.created") {
+          clearTimeout(timeout);
+          resolve();
+        }
+      });
+    });
+
+    await sessionCreated;
+    conn.close();
+
+    expect(events.some((e) => e.kind === "session.created")).toBe(true);
+    expect(conn.sessionId).toBeTruthy();
+  });
+
+  it("should complete text round-trip", async () => {
+    const conn = await model.connect();
+    const events: RealtimeServerEvent[] = [];
+
+    conn.on("event", (e: RealtimeServerEvent) => {
+      events.push(e);
+    });
+
+    // wait for session
+    await waitFor(conn, "session.created");
+
+    // configure text-only mode
+    conn.send({
+      kind: "session.update",
+      config: {
+        instructions: "You are a helpful assistant. Be very brief.",
+      },
+    });
+
+    await waitFor(conn, "session.updated");
+
+    // add user message
+    conn.send({
+      kind: "item.create",
+      item: {
+        kind: "message",
+        id: "test-msg-1",
+        role: "user",
+        content: [{ kind: "text", text: "Say exactly: hello world" }],
+      },
+    });
+
+    // trigger response
+    conn.send({ kind: "response.create" });
+
+    // wait for response to complete
+    await waitFor(conn, "response.done", 15000);
+
+    conn.close();
+
+    // verify event flow
+    const kinds = events.map((e) => e.kind);
+    expect(kinds).toContain("session.created");
+    expect(kinds).toContain("session.updated");
+    expect(kinds).toContain("response.created");
+    expect(kinds).toContain("response.done");
+
+    // verify response completed successfully
+    const done = events.find((e) => e.kind === "response.done");
+    if (done?.kind === "response.done") {
+      expect(done.status).toBe("completed");
+    }
+  });
+
+  it("should handle tool calling", { timeout: 20000 }, async () => {
+    const conn = await model.connect();
+    const events: RealtimeServerEvent[] = [];
+
+    conn.on("event", (e: RealtimeServerEvent) => {
+      events.push(e);
+    });
+
+    await waitFor(conn, "session.created");
+
+    // configure with a tool
+    conn.send({
+      kind: "session.update",
+      config: {
+        instructions: "You have access to tools. Use them when appropriate.",
+        tools: [
+          {
+            kind: "function",
+            name: "get_weather",
+            description: "Get the current weather for a location",
+            parameters: {
+              type: "object",
+              properties: {
+                location: { type: "string", description: "City name" },
+              },
+              required: ["location"],
+            },
+          },
+        ],
+      },
+    });
+
+    await waitFor(conn, "session.updated");
+
+    // ask about weather
+    conn.send({
+      kind: "item.create",
+      item: {
+        kind: "message",
+        id: "test-msg-2",
+        role: "user",
+        content: [{ kind: "text", text: "What is the weather in Tokyo?" }],
+      },
+    });
+
+    conn.send({ kind: "response.create" });
+
+    // wait for tool call
+    const toolCall = await waitFor(conn, "tool.call", 15000);
+
+    expect(toolCall.kind).toBe("tool.call");
+    if (toolCall.kind !== "tool.call") {
+      throw new Error("Expected tool.call");
+    }
+
+    expect(toolCall.toolId).toBe("get_weather");
+    const args = JSON.parse(toolCall.arguments);
+    expect(args.location.toLowerCase()).toContain("tokyo");
+
+    // wait for first response to complete before sending tool result
+    await waitFor(conn, "response.done", 15000);
+
+    // send tool result
+    conn.send({
+      kind: "tool.result",
+      callId: toolCall.callId,
+      result: JSON.stringify({ temperature: 22, condition: "sunny" }),
+    });
+
+    // trigger follow-up response
+    conn.send({ kind: "response.create" });
+
+    // wait for second response to complete
+    await waitFor(conn, "response.done", 15000);
+
+    conn.close();
+
+    // verify we got multiple response.done events (initial + follow-up)
+    const doneEvents = events.filter((e) => e.kind === "response.done");
+    expect(doneEvents.length).toBeGreaterThanOrEqual(2);
+  });
+});
+
+/**
+ * Wait for a specific event kind.
+ */
+function waitFor(
+  conn: RealtimeConnection,
+  kind: RealtimeServerEvent["kind"],
+  timeout = 10000,
+): Promise<RealtimeServerEvent> {
+  return new Promise((resolve, reject) => {
+    const timer = setTimeout(() => {
+      conn.off("event", handler);
+      reject(new Error(`timeout waiting for ${kind}`));
+    }, timeout);
+
+    const handler = (e: RealtimeServerEvent) => {
+      if (e.kind === kind) {
+        clearTimeout(timer);
+        conn.off("event", handler);
+        resolve(e);
+      }
+    };
+
+    conn.on("event", handler);
+  });
+}