@kernl-sdk/xai 0.1.0

package/dist/model.js

@@ -0,0 +1,112 @@
+import { GrokRealtimeConnection } from "./connection.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;
+    }
+}

package/dist/protocol.d.ts

@@ -0,0 +1,212 @@
+import type { JSONSchema7 } from "json-schema";
+/**
+ * Grok (xAI) Realtime API wire types.
+ *
+ * Based on https://docs.x.ai/docs/guides/voice/agent
+ */
+export type GrokClientEvent = GrokSessionUpdate | GrokInputAudioBufferAppend | GrokInputAudioBufferCommit | GrokInputAudioBufferClear | GrokConversationItemCreate | GrokResponseCreate;
+export interface GrokSessionUpdate {
+    type: "session.update";
+    session: GrokSessionConfig;
+}
+export interface GrokInputAudioBufferAppend {
+    type: "input_audio_buffer.append";
+    audio: string;
+}
+export interface GrokInputAudioBufferCommit {
+    type: "input_audio_buffer.commit";
+}
+export interface GrokInputAudioBufferClear {
+    type: "input_audio_buffer.clear";
+}
+export interface GrokConversationItemCreate {
+    type: "conversation.item.create";
+    item: GrokItem;
+    previous_item_id?: string;
+}
+export interface GrokResponseCreate {
+    type: "response.create";
+}
+export type GrokServerEvent = GrokConversationCreated | GrokSessionUpdated | GrokInputAudioBufferCommitted | GrokInputAudioBufferCleared | GrokInputAudioBufferSpeechStarted | GrokInputAudioBufferSpeechStopped | GrokConversationItemAdded | GrokConversationItemInputAudioTranscriptionCompleted | GrokResponseCreated | GrokResponseOutputItemAdded | GrokResponseDone | GrokResponseOutputAudioDelta | GrokResponseOutputAudioDone | GrokResponseOutputAudioTranscriptDelta | GrokResponseOutputAudioTranscriptDone | GrokResponseFunctionCallArgumentsDone;
+export interface GrokConversationCreated {
+    type: "conversation.created";
+    event_id: string;
+    conversation: {
+        id: string;
+        object: "realtime.conversation";
+    };
+}
+export interface GrokSessionUpdated {
+    type: "session.updated";
+    event_id: string;
+    session: GrokSession;
+}
+export interface GrokInputAudioBufferCommitted {
+    type: "input_audio_buffer.committed";
+    event_id: string;
+    previous_item_id?: string;
+    item_id: string;
+}
+export interface GrokInputAudioBufferCleared {
+    type: "input_audio_buffer.cleared";
+    event_id: string;
+}
+export interface GrokInputAudioBufferSpeechStarted {
+    type: "input_audio_buffer.speech_started";
+    event_id: string;
+    item_id: string;
+}
+export interface GrokInputAudioBufferSpeechStopped {
+    type: "input_audio_buffer.speech_stopped";
+    event_id: string;
+    item_id: string;
+}
+export interface GrokConversationItemAdded {
+    type: "conversation.item.added";
+    event_id: string;
+    previous_item_id?: string;
+    item: GrokItemWithId;
+}
+export interface GrokConversationItemInputAudioTranscriptionCompleted {
+    type: "conversation.item.input_audio_transcription.completed";
+    event_id: string;
+    item_id: string;
+    transcript: string;
+}
+export interface GrokResponseCreated {
+    type: "response.created";
+    event_id: string;
+    response: {
+        id: string;
+        object: "realtime.response";
+        status: "in_progress";
+        output: unknown[];
+    };
+}
+export interface GrokResponseOutputItemAdded {
+    type: "response.output_item.added";
+    event_id: string;
+    response_id: string;
+    output_index: number;
+    item: GrokItemWithId;
+}
+export interface GrokResponseDone {
+    type: "response.done";
+    event_id: string;
+    response: {
+        id: string;
+        object: "realtime.response";
+        status: "completed" | "cancelled" | "failed";
+    };
+}
+export interface GrokResponseOutputAudioDelta {
+    type: "response.output_audio.delta";
+    event_id: string;
+    response_id: string;
+    item_id: string;
+    output_index: number;
+    content_index: number;
+    delta: string;
+}
+export interface GrokResponseOutputAudioDone {
+    type: "response.output_audio.done";
+    event_id: string;
+    response_id: string;
+    item_id: string;
+}
+export interface GrokResponseOutputAudioTranscriptDelta {
+    type: "response.output_audio_transcript.delta";
+    event_id: string;
+    response_id: string;
+    item_id: string;
+    delta: string;
+}
+export interface GrokResponseOutputAudioTranscriptDone {
+    type: "response.output_audio_transcript.done";
+    event_id: string;
+    response_id: string;
+    item_id: string;
+}
+export interface GrokResponseFunctionCallArgumentsDone {
+    type: "response.function_call_arguments.done";
+    event_id: string;
+    response_id?: string;
+    item_id?: string;
+    call_id: string;
+    name: string;
+    arguments: string;
+}
+export interface GrokSession {
+    instructions?: string;
+    voice?: GrokVoice;
+    turn_detection?: GrokTurnDetection;
+}
+export interface GrokSessionConfig {
+    instructions?: string;
+    voice?: GrokVoice;
+    turn_detection?: GrokTurnDetection | null;
+    audio?: GrokAudioConfig;
+    tools?: GrokTool[];
+}
+/**
+ * Available Grok voices.
+ */
+export type GrokVoice = "Ara" | "Rex" | "Sal" | "Eve" | "Leo";
+export interface GrokTurnDetection {
+    type: "server_vad" | null;
+}
+export interface GrokAudioConfig {
+    input?: {
+        format?: GrokAudioFormat;
+    };
+    output?: {
+        format?: GrokAudioFormat;
+    };
+}
+export interface GrokAudioFormat {
+    type: "audio/pcm" | "audio/pcmu" | "audio/pcma";
+    rate?: number;
+}
+export type GrokTool = GrokFunctionTool | GrokWebSearchTool | GrokXSearchTool | GrokFileSearchTool;
+export interface GrokFunctionTool {
+    type: "function";
+    name: string;
+    description?: string;
+    parameters?: JSONSchema7;
+}
+export interface GrokWebSearchTool {
+    type: "web_search";
+}
+export interface GrokXSearchTool {
+    type: "x_search";
+    allowed_x_handles?: string[];
+}
+export interface GrokFileSearchTool {
+    type: "file_search";
+    vector_store_ids: string[];
+    max_num_results?: number;
+}
+export type GrokItem = GrokMessageItem | GrokFunctionCallOutputItem;
+export interface GrokMessageItem {
+    type: "message";
+    role: "user" | "assistant";
+    content: GrokContentPart[];
+}
+export interface GrokFunctionCallOutputItem {
+    type: "function_call_output";
+    call_id: string;
+    output: string;
+}
+export type GrokItemWithId = GrokItem & {
+    id: string;
+    object: "realtime.item";
+    status: "completed" | "in_progress";
+};
+export type GrokContentPart = {
+    type: "input_text";
+    text: string;
+} | {
+    type: "input_audio";
+    transcript?: string;
+};
+//# sourceMappingURL=protocol.d.ts.map

package/dist/protocol.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"protocol.d.ts","sourceRoot":"","sources":["../src/protocol.ts"],"names":[],"mappings":"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"}

package/dist/protocol.js

@@ -0,0 +1 @@
+export {};

package/dist/realtime/connection.d.ts

@@ -0,0 +1,47 @@
+import { Emitter } from "@kernl-sdk/shared";
+import { type RealtimeConnection, type RealtimeConnectionEvents, type RealtimeClientEvent, type TransportStatus, type WebSocketLike } from "@kernl-sdk/protocol";
+/**
+ * Grok realtime connection implementation.
+ */
+export declare class GrokRealtimeConnection extends Emitter<RealtimeConnectionEvents> implements RealtimeConnection {
+    private ws;
+    private _status;
+    private _muted;
+    private _sessionId;
+    private currid;
+    private faudtime;
+    private audlenms;
+    private responding;
+    constructor(socket: WebSocketLike);
+    get status(): TransportStatus;
+    get muted(): boolean;
+    get sessionId(): string | null;
+    /**
+     * Send a client event to the Grok realtime API.
+     */
+    send(event: RealtimeClientEvent): void;
+    /**
+     * Close the WebSocket connection.
+     */
+    close(): void;
+    /**
+     * Mute audio input.
+     */
+    mute(): void;
+    /**
+     * Unmute audio input.
+     */
+    unmute(): void;
+    /**
+     * 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(): void;
+    /**
+     * Reset audio tracking state.
+     */
+    private reset;
+}
+//# sourceMappingURL=connection.d.ts.map

package/dist/realtime/connection.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"connection.d.ts","sourceRoot":"","sources":["../../src/realtime/connection.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,OAAO,EAAE,MAAM,mBAAmB,CAAC;AAC5C,OAAO,EAEL,KAAK,kBAAkB,EACvB,KAAK,wBAAwB,EAC7B,KAAK,mBAAmB,EACxB,KAAK,eAAe,EACpB,KAAK,aAAa,EACnB,MAAM,qBAAqB,CAAC;AAK7B;;GAEG;AACH,qBAAa,sBACX,SAAQ,OAAO,CAAC,wBAAwB,CACxC,YAAW,kBAAkB;IAE7B,OAAO,CAAC,EAAE,CAAgB;IAC1B,OAAO,CAAC,OAAO,CAAiC;IAChD,OAAO,CAAC,MAAM,CAAS;IACvB,OAAO,CAAC,UAAU,CAAuB;IAGzC,OAAO,CAAC,MAAM,CAAqB;IACnC,OAAO,CAAC,QAAQ,CAAqB;IACrC,OAAO,CAAC,QAAQ,CAAa;IAC7B,OAAO,CAAC,UAAU,CAAkB;gBAExB,MAAM,EAAE,aAAa;IA4DjC,IAAI,MAAM,IAAI,eAAe,CAE5B;IAED,IAAI,KAAK,IAAI,OAAO,CAEnB;IAED,IAAI,SAAS,IAAI,MAAM,GAAG,IAAI,CAE7B;IAED;;OAEG;IACH,IAAI,CAAC,KAAK,EAAE,mBAAmB,GAAG,IAAI;IAOtC;;OAEG;IACH,KAAK,IAAI,IAAI;IAKb;;OAEG;IACH,IAAI,IAAI,IAAI;IAIZ;;OAEG;IACH,MAAM,IAAI,IAAI;IAId;;;;;OAKG;IACH,SAAS,IAAI,IAAI;IASjB;;OAEG;IACH,OAAO,CAAC,KAAK;CAKd"}

package/dist/realtime/connection.js

@@ -0,0 +1,138 @@
+import { Emitter } from "@kernl-sdk/shared";
+import { WS_OPEN, } from "@kernl-sdk/protocol";
+import { CLIENT_EVENT, SERVER_EVENT } from "./convert/event.js";
+/**
+ * Grok realtime connection implementation.
+ */
+export 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/dist/realtime/convert/event.d.ts

@@ -0,0 +1,28 @@
+import type { Codec } from "@kernl-sdk/shared/lib";
+import type { RealtimeClientEvent, RealtimeServerEvent, RealtimeSessionConfig, TurnDetectionConfig, LanguageModelItem, AudioConfig } from "@kernl-sdk/protocol";
+import type { GrokClientEvent, GrokServerEvent, GrokSessionConfig, GrokTurnDetection, GrokItem, GrokAudioConfig } from "../protocol.js";
+/**
+ * Codec for turn detection config.
+ */
+export declare const TURN_DETECTION: Codec<TurnDetectionConfig, GrokTurnDetection | null>;
+/**
+ * Codec for audio config.
+ */
+export declare const AUDIO_CONFIG: Codec<AudioConfig, GrokAudioConfig>;
+/**
+ * Codec for session config.
+ */
+export declare const SESSION_CONFIG: Codec<RealtimeSessionConfig, GrokSessionConfig>;
+/**
+ * Codec for conversation items.
+ */
+export declare const ITEM: Codec<LanguageModelItem, GrokItem>;
+/**
+ * Codec for client events (kernl → Grok).
+ */
+export declare const CLIENT_EVENT: Codec<RealtimeClientEvent, GrokClientEvent | null>;
+/**
+ * Codec for server events (Grok → kernl).
+ */
+export declare const SERVER_EVENT: Codec<RealtimeServerEvent | null, GrokServerEvent>;
+//# sourceMappingURL=event.d.ts.map

package/dist/realtime/convert/event.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"event.d.ts","sourceRoot":"","sources":["../../../src/realtime/convert/event.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,KAAK,EAAE,MAAM,uBAAuB,CAAC;AAEnD,OAAO,KAAK,EACV,mBAAmB,EACnB,mBAAmB,EACnB,qBAAqB,EACrB,mBAAmB,EACnB,iBAAiB,EACjB,WAAW,EACZ,MAAM,qBAAqB,CAAC;AAE7B,OAAO,KAAK,EACV,eAAe,EACf,eAAe,EACf,iBAAiB,EACjB,iBAAiB,EACjB,QAAQ,EAER,eAAe,EAGhB,MAAM,aAAa,CAAC;AAcrB;;GAEG;AACH,eAAO,MAAM,cAAc,EAAE,KAAK,CAChC,mBAAmB,EACnB,iBAAiB,GAAG,IAAI,CAazB,CAAC;AAEF;;GAEG;AACH,eAAO,MAAM,YAAY,EAAE,KAAK,CAAC,WAAW,EAAE,eAAe,CAyC5D,CAAC;AAEF;;GAEG;AACH,eAAO,MAAM,cAAc,EAAE,KAAK,CAAC,qBAAqB,EAAE,iBAAiB,CAgC1E,CAAC;AAEF;;GAEG;AACH,eAAO,MAAM,IAAI,EAAE,KAAK,CAAC,iBAAiB,EAAE,QAAQ,CA8DnD,CAAC;AAEF;;GAEG;AACH,eAAO,MAAM,YAAY,EAAE,KAAK,CAAC,mBAAmB,EAAE,eAAe,GAAG,IAAI,CAuDzE,CAAC;AAEJ;;GAEG;AACH,eAAO,MAAM,YAAY,EAAE,KAAK,CAAC,mBAAmB,GAAG,IAAI,EAAE,eAAe,CAuHzE,CAAC"}