@kernl-sdk/xai 0.1.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (49) hide show
  1. package/.turbo/turbo-build.log +5 -0
  2. package/dist/__tests__/realtime.integration.test.d.ts +2 -0
  3. package/dist/__tests__/realtime.integration.test.d.ts.map +1 -0
  4. package/dist/__tests__/realtime.integration.test.js +157 -0
  5. package/dist/__tests__/realtime.test.d.ts +2 -0
  6. package/dist/__tests__/realtime.test.d.ts.map +1 -0
  7. package/dist/__tests__/realtime.test.js +263 -0
  8. package/dist/connection.d.ts +47 -0
  9. package/dist/connection.d.ts.map +1 -0
  10. package/dist/connection.js +138 -0
  11. package/dist/convert/event.d.ts +28 -0
  12. package/dist/convert/event.d.ts.map +1 -0
  13. package/dist/convert/event.js +314 -0
  14. package/dist/convert/types.d.ts +212 -0
  15. package/dist/convert/types.d.ts.map +1 -0
  16. package/dist/convert/types.js +1 -0
  17. package/dist/index.d.ts +36 -0
  18. package/dist/index.d.ts.map +1 -0
  19. package/dist/index.js +16 -0
  20. package/dist/model.d.ts +36 -0
  21. package/dist/model.d.ts.map +1 -0
  22. package/dist/model.js +112 -0
  23. package/dist/protocol.d.ts +212 -0
  24. package/dist/protocol.d.ts.map +1 -0
  25. package/dist/protocol.js +1 -0
  26. package/dist/realtime/connection.d.ts +47 -0
  27. package/dist/realtime/connection.d.ts.map +1 -0
  28. package/dist/realtime/connection.js +138 -0
  29. package/dist/realtime/convert/event.d.ts +28 -0
  30. package/dist/realtime/convert/event.d.ts.map +1 -0
  31. package/dist/realtime/convert/event.js +314 -0
  32. package/dist/realtime/model.d.ts +36 -0
  33. package/dist/realtime/model.d.ts.map +1 -0
  34. package/dist/realtime/model.js +111 -0
  35. package/dist/realtime/protocol.d.ts +212 -0
  36. package/dist/realtime/protocol.d.ts.map +1 -0
  37. package/dist/realtime/protocol.js +1 -0
  38. package/dist/realtime.d.ts +36 -0
  39. package/dist/realtime.d.ts.map +1 -0
  40. package/dist/realtime.js +250 -0
  41. package/package.json +55 -0
  42. package/src/__tests__/realtime.integration.test.ts +203 -0
  43. package/src/__tests__/realtime.test.ts +350 -0
  44. package/src/index.ts +41 -0
  45. package/src/realtime/connection.ts +167 -0
  46. package/src/realtime/convert/event.ts +388 -0
  47. package/src/realtime/model.ts +162 -0
  48. package/src/realtime/protocol.ts +286 -0
  49. package/tsconfig.json +13 -0
@@ -0,0 +1,314 @@
1
+ import { randomID } from "@kernl-sdk/shared/lib";
2
+ /**
3
+ * Map kernl voice ID to Grok voice name.
4
+ * Falls back to "Ara" (default) if not a valid Grok voice.
5
+ */
6
+ function toGrokVoice(voiceId) {
7
+ if (!voiceId)
8
+ return undefined;
9
+ const validVoices = ["Ara", "Rex", "Sal", "Eve", "Leo"];
10
+ return validVoices.includes(voiceId)
11
+ ? voiceId
12
+ : "Ara";
13
+ }
14
+ /**
15
+ * Codec for turn detection config.
16
+ */
17
+ export const TURN_DETECTION = {
18
+ encode(config) {
19
+ return {
20
+ type: config.mode === "manual" ? null : "server_vad",
21
+ };
22
+ },
23
+ decode(config) {
24
+ return {
25
+ mode: config?.type === "server_vad" ? "server_vad" : "manual",
26
+ };
27
+ },
28
+ };
29
+ /**
30
+ * Codec for audio config.
31
+ */
32
+ export const AUDIO_CONFIG = {
33
+ encode(config) {
34
+ const result = {};
35
+ if (config.inputFormat) {
36
+ result.input = {
37
+ format: {
38
+ type: config.inputFormat.mimeType || "audio/pcm",
39
+ rate: config.inputFormat.sampleRate,
40
+ },
41
+ };
42
+ }
43
+ if (config.outputFormat) {
44
+ result.output = {
45
+ format: {
46
+ type: config.outputFormat.mimeType || "audio/pcm",
47
+ rate: config.outputFormat.sampleRate,
48
+ },
49
+ };
50
+ }
51
+ return result;
52
+ },
53
+ decode(config) {
54
+ return {
55
+ inputFormat: config.input?.format
56
+ ? {
57
+ mimeType: config.input.format.type,
58
+ sampleRate: config.input.format.rate,
59
+ }
60
+ : undefined,
61
+ outputFormat: config.output?.format
62
+ ? {
63
+ mimeType: config.output.format.type,
64
+ sampleRate: config.output.format.rate,
65
+ }
66
+ : undefined,
67
+ };
68
+ },
69
+ };
70
+ /**
71
+ * Codec for session config.
72
+ */
73
+ export const SESSION_CONFIG = {
74
+ encode(config) {
75
+ const tools = config.tools
76
+ ?.filter((t) => t.kind === "function")
77
+ .map((t) => ({
78
+ type: "function",
79
+ name: t.name,
80
+ description: t.description,
81
+ parameters: t.parameters,
82
+ }));
83
+ return {
84
+ instructions: config.instructions,
85
+ voice: toGrokVoice(config.voice?.voiceId),
86
+ turn_detection: config.turnDetection
87
+ ? TURN_DETECTION.encode(config.turnDetection)
88
+ : undefined,
89
+ audio: config.audio ? AUDIO_CONFIG.encode(config.audio) : undefined,
90
+ tools: tools?.length ? tools : undefined,
91
+ };
92
+ },
93
+ decode(config) {
94
+ return {
95
+ instructions: config.instructions,
96
+ voice: config.voice ? { voiceId: config.voice } : undefined,
97
+ turnDetection: config.turn_detection
98
+ ? TURN_DETECTION.decode(config.turn_detection)
99
+ : undefined,
100
+ audio: config.audio ? AUDIO_CONFIG.decode(config.audio) : undefined,
101
+ };
102
+ },
103
+ };
104
+ /**
105
+ * Codec for conversation items.
106
+ */
107
+ export const ITEM = {
108
+ encode(item) {
109
+ switch (item.kind) {
110
+ case "message": {
111
+ const content = item.content.map((c) => {
112
+ switch (c.kind) {
113
+ case "text":
114
+ return { type: "input_text", text: c.text };
115
+ default:
116
+ return { type: "input_text", text: "" };
117
+ }
118
+ });
119
+ return {
120
+ type: "message",
121
+ role: item.role,
122
+ content,
123
+ };
124
+ }
125
+ case "tool-result":
126
+ return {
127
+ type: "function_call_output",
128
+ call_id: item.callId,
129
+ output: item.error ?? JSON.stringify(item.result) ?? "",
130
+ };
131
+ default:
132
+ throw new Error(`Unsupported item kind: ${item.kind}`);
133
+ }
134
+ },
135
+ decode(item) {
136
+ switch (item.type) {
137
+ case "message":
138
+ return {
139
+ kind: "message",
140
+ id: randomID(),
141
+ role: item.role,
142
+ content: item.content.map((c) => ({
143
+ kind: "text",
144
+ text: "text" in c ? c.text : "",
145
+ })),
146
+ };
147
+ case "function_call_output":
148
+ return {
149
+ kind: "tool-result",
150
+ callId: item.call_id,
151
+ toolId: "",
152
+ state: "completed",
153
+ result: item.output,
154
+ error: null,
155
+ };
156
+ default:
157
+ throw new Error(`Unsupported Grok item type: ${item.type}`);
158
+ }
159
+ },
160
+ };
161
+ /**
162
+ * Codec for client events (kernl → Grok).
163
+ */
164
+ export const CLIENT_EVENT = {
165
+ encode(event) {
166
+ switch (event.kind) {
167
+ case "session.update":
168
+ return {
169
+ type: "session.update",
170
+ session: SESSION_CONFIG.encode(event.config),
171
+ };
172
+ case "audio.input.append":
173
+ return { type: "input_audio_buffer.append", audio: event.audio };
174
+ case "audio.input.commit":
175
+ return { type: "input_audio_buffer.commit" };
176
+ case "audio.input.clear":
177
+ return { type: "input_audio_buffer.clear" };
178
+ case "item.create":
179
+ return {
180
+ type: "conversation.item.create",
181
+ item: ITEM.encode(event.item),
182
+ previous_item_id: event.previousItemId,
183
+ };
184
+ case "response.create":
185
+ return { type: "response.create" };
186
+ case "tool.result":
187
+ return {
188
+ type: "conversation.item.create",
189
+ item: {
190
+ type: "function_call_output",
191
+ call_id: event.callId,
192
+ output: event.error ?? event.result ?? "",
193
+ },
194
+ };
195
+ // Unsupported by Grok
196
+ case "item.delete":
197
+ case "item.truncate":
198
+ case "response.cancel":
199
+ case "activity.start":
200
+ case "activity.end":
201
+ return null;
202
+ default:
203
+ return null;
204
+ }
205
+ },
206
+ decode() {
207
+ throw new Error("CLIENT_EVENT.decode: use SERVER_EVENT instead");
208
+ },
209
+ };
210
+ /**
211
+ * Codec for server events (Grok → kernl).
212
+ */
213
+ export const SERVER_EVENT = {
214
+ encode() {
215
+ throw new Error("SERVER_EVENT.encode: use CLIENT_EVENT instead");
216
+ },
217
+ decode(event) {
218
+ switch (event.type) {
219
+ case "conversation.created":
220
+ // Grok sends conversation.created instead of session.created
221
+ return {
222
+ kind: "session.created",
223
+ session: {
224
+ id: event.conversation.id,
225
+ config: {},
226
+ },
227
+ };
228
+ case "session.updated":
229
+ return {
230
+ kind: "session.updated",
231
+ session: {
232
+ id: event.event_id,
233
+ config: SESSION_CONFIG.decode(event.session),
234
+ },
235
+ };
236
+ case "input_audio_buffer.committed":
237
+ return { kind: "audio.input.committed", itemId: event.item_id };
238
+ case "input_audio_buffer.cleared":
239
+ return { kind: "audio.input.cleared" };
240
+ case "input_audio_buffer.speech_started":
241
+ return {
242
+ kind: "speech.started",
243
+ audioStartMs: 0, // Grok doesn't provide this
244
+ itemId: event.item_id,
245
+ };
246
+ case "input_audio_buffer.speech_stopped":
247
+ return {
248
+ kind: "speech.stopped",
249
+ audioEndMs: 0, // Grok doesn't provide this
250
+ itemId: event.item_id,
251
+ };
252
+ case "conversation.item.added":
253
+ return {
254
+ kind: "item.created",
255
+ item: ITEM.decode(event.item),
256
+ previousItemId: event.previous_item_id,
257
+ };
258
+ case "conversation.item.input_audio_transcription.completed":
259
+ return {
260
+ kind: "transcript.input",
261
+ itemId: event.item_id,
262
+ text: event.transcript,
263
+ };
264
+ case "response.created":
265
+ return { kind: "response.created", responseId: event.response.id };
266
+ case "response.output_item.added":
267
+ // Could emit tool.start here for function calls
268
+ return null;
269
+ case "response.done":
270
+ return {
271
+ kind: "response.done",
272
+ responseId: event.response.id,
273
+ status: event.response.status === "completed" ? "completed" : "failed",
274
+ usage: undefined,
275
+ };
276
+ case "response.output_audio.delta":
277
+ return {
278
+ kind: "audio.output.delta",
279
+ responseId: event.response_id,
280
+ itemId: event.item_id,
281
+ audio: event.delta,
282
+ };
283
+ case "response.output_audio.done":
284
+ return {
285
+ kind: "audio.output.done",
286
+ responseId: event.response_id,
287
+ itemId: event.item_id,
288
+ };
289
+ case "response.output_audio_transcript.delta":
290
+ return {
291
+ kind: "transcript.output.delta",
292
+ responseId: event.response_id,
293
+ itemId: event.item_id,
294
+ delta: event.delta,
295
+ };
296
+ case "response.output_audio_transcript.done":
297
+ return {
298
+ kind: "transcript.output",
299
+ responseId: event.response_id,
300
+ itemId: event.item_id,
301
+ text: "", // Grok doesn't include final text in done event
302
+ };
303
+ case "response.function_call_arguments.done":
304
+ return {
305
+ kind: "tool.call",
306
+ callId: event.call_id,
307
+ toolId: event.name,
308
+ arguments: event.arguments,
309
+ };
310
+ default:
311
+ return null;
312
+ }
313
+ },
314
+ };
@@ -0,0 +1,36 @@
1
+ import type { RealtimeModel, RealtimeConnection, RealtimeConnectOptions, ClientCredential } from "@kernl-sdk/protocol";
2
+ /**
3
+ * Options for creating a Grok realtime model.
4
+ */
5
+ export interface GrokRealtimeOptions {
6
+ /**
7
+ * xAI API key. Defaults to XAI_API_KEY env var.
8
+ */
9
+ apiKey?: string;
10
+ /**
11
+ * Base URL for the realtime API.
12
+ */
13
+ baseUrl?: string;
14
+ }
15
+ /**
16
+ * Grok (xAI) realtime model implementation.
17
+ */
18
+ export declare class GrokRealtimeModel implements RealtimeModel {
19
+ readonly spec: "1.0";
20
+ readonly provider = "xai";
21
+ readonly modelId = "grok-realtime";
22
+ private apiKey;
23
+ private baseUrl;
24
+ constructor(options?: GrokRealtimeOptions);
25
+ /**
26
+ * Create ephemeral credential for client-side connections.
27
+ *
28
+ * Must be called server-side where API key is available.
29
+ */
30
+ authenticate(): Promise<ClientCredential>;
31
+ /**
32
+ * Establish a WebSocket connection to the Grok realtime API.
33
+ */
34
+ connect(options?: RealtimeConnectOptions): Promise<RealtimeConnection>;
35
+ }
36
+ //# sourceMappingURL=model.d.ts.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"model.d.ts","sourceRoot":"","sources":["../../src/realtime/model.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EACV,aAAa,EACb,kBAAkB,EAClB,sBAAsB,EACtB,gBAAgB,EACjB,MAAM,qBAAqB,CAAC;AAO7B;;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,mBAAmB;IAEnC,OAAO,CAAC,MAAM,CAAgB;IAC9B,OAAO,CAAC,OAAO,CAAS;gBAEZ,OAAO,CAAC,EAAE,mBAAmB;IAQzC;;;;OAIG;IACG,YAAY,IAAI,OAAO,CAAC,gBAAgB,CAAC;IAgC/C;;OAEG;IACG,OAAO,CAAC,OAAO,CAAC,EAAE,sBAAsB,GAAG,OAAO,CAAC,kBAAkB,CAAC;CA2E7E"}
@@ -0,0 +1,111 @@
1
+ import { GrokRealtimeConnection } from "./connection.js";
2
+ const XAI_REALTIME_URL = "wss://api.x.ai/v1/realtime";
3
+ const XAI_CLIENT_SECRETS_URL = "https://api.x.ai/v1/realtime/client_secrets";
4
+ /**
5
+ * Grok (xAI) realtime model implementation.
6
+ */
7
+ export class GrokRealtimeModel {
8
+ spec = "1.0";
9
+ provider = "xai";
10
+ modelId = "grok-realtime";
11
+ apiKey;
12
+ baseUrl;
13
+ constructor(options) {
14
+ this.apiKey =
15
+ options?.apiKey ??
16
+ (typeof process !== "undefined" ? process.env?.XAI_API_KEY : null) ??
17
+ null;
18
+ this.baseUrl = options?.baseUrl ?? XAI_REALTIME_URL;
19
+ }
20
+ /**
21
+ * Create ephemeral credential for client-side connections.
22
+ *
23
+ * Must be called server-side where API key is available.
24
+ */
25
+ async authenticate() {
26
+ if (!this.apiKey) {
27
+ throw new Error("API key required for authenticate(). " +
28
+ "Call this server-side where XAI_API_KEY is available.");
29
+ }
30
+ const res = await fetch(XAI_CLIENT_SECRETS_URL, {
31
+ method: "POST",
32
+ headers: {
33
+ Authorization: `Bearer ${this.apiKey}`,
34
+ "Content-Type": "application/json",
35
+ },
36
+ body: JSON.stringify({
37
+ expires_after: { seconds: 300 },
38
+ }),
39
+ });
40
+ if (!res.ok) {
41
+ const text = await res.text();
42
+ throw new Error(`Failed to create credential: ${res.status} ${text}`);
43
+ }
44
+ const data = (await res.json());
45
+ return {
46
+ kind: "token",
47
+ token: data.value,
48
+ expiresAt: new Date(Date.now() + 300_000), // 5 min TTL
49
+ };
50
+ }
51
+ /**
52
+ * Establish a WebSocket connection to the Grok realtime API.
53
+ */
54
+ async connect(options) {
55
+ const credential = options?.credential;
56
+ if (credential && credential.kind !== "token") {
57
+ throw new Error(`Grok requires token credentials, got "${credential.kind}".`);
58
+ }
59
+ const authToken = credential?.token ?? this.apiKey;
60
+ if (!authToken) {
61
+ throw new Error("No API key or credential provided. " +
62
+ "Either set XAI_API_KEY or pass a credential from authenticate().");
63
+ }
64
+ // Use injectable WebSocket or globalThis.WebSocket
65
+ const WS = options?.websocket ?? globalThis.WebSocket;
66
+ if (!WS) {
67
+ throw new Error("No WebSocket available. In Node.js <22, use WebSocketTransport with the 'ws' package:\n" +
68
+ " import WebSocket from 'ws';\n" +
69
+ " import { WebSocketTransport } from 'kernl';\n" +
70
+ " new RealtimeSession(agent, { transport: new WebSocketTransport({ websocket: WebSocket }), ... })");
71
+ }
72
+ // xAI uses OpenAI-compatible subprotocols for browser WebSocket auth
73
+ const protocols = [
74
+ "realtime",
75
+ `openai-insecure-api-key.${authToken}`,
76
+ "openai-beta.realtime-v1",
77
+ ];
78
+ const ws = new WS(this.baseUrl, protocols);
79
+ const connection = new GrokRealtimeConnection(ws);
80
+ await new Promise((resolve, reject) => {
81
+ if (options?.abort?.aborted) {
82
+ return reject(new Error("Connection aborted"));
83
+ }
84
+ const onOpen = () => {
85
+ cleanup();
86
+ resolve();
87
+ };
88
+ const onError = (event) => {
89
+ cleanup();
90
+ const err = event instanceof Error
91
+ ? event
92
+ : new Error("WebSocket connection failed");
93
+ reject(err);
94
+ };
95
+ const onAbort = () => {
96
+ cleanup();
97
+ ws.close();
98
+ reject(new Error("Connection aborted"));
99
+ };
100
+ const cleanup = () => {
101
+ ws.removeEventListener("open", onOpen);
102
+ ws.removeEventListener("error", onError);
103
+ options?.abort?.removeEventListener("abort", onAbort);
104
+ };
105
+ ws.addEventListener("open", onOpen);
106
+ ws.addEventListener("error", onError);
107
+ options?.abort?.addEventListener("abort", onAbort);
108
+ });
109
+ return connection;
110
+ }
111
+ }
@@ -0,0 +1,212 @@
1
+ import type { JSONSchema7 } from "json-schema";
2
+ /**
3
+ * Grok (xAI) Realtime API wire types.
4
+ *
5
+ * Based on https://docs.x.ai/docs/guides/voice/agent
6
+ */
7
+ export type GrokClientEvent = GrokSessionUpdate | GrokInputAudioBufferAppend | GrokInputAudioBufferCommit | GrokInputAudioBufferClear | GrokConversationItemCreate | GrokResponseCreate;
8
+ export interface GrokSessionUpdate {
9
+ type: "session.update";
10
+ session: GrokSessionConfig;
11
+ }
12
+ export interface GrokInputAudioBufferAppend {
13
+ type: "input_audio_buffer.append";
14
+ audio: string;
15
+ }
16
+ export interface GrokInputAudioBufferCommit {
17
+ type: "input_audio_buffer.commit";
18
+ }
19
+ export interface GrokInputAudioBufferClear {
20
+ type: "input_audio_buffer.clear";
21
+ }
22
+ export interface GrokConversationItemCreate {
23
+ type: "conversation.item.create";
24
+ item: GrokItem;
25
+ previous_item_id?: string;
26
+ }
27
+ export interface GrokResponseCreate {
28
+ type: "response.create";
29
+ }
30
+ export type GrokServerEvent = GrokConversationCreated | GrokSessionUpdated | GrokInputAudioBufferCommitted | GrokInputAudioBufferCleared | GrokInputAudioBufferSpeechStarted | GrokInputAudioBufferSpeechStopped | GrokConversationItemAdded | GrokConversationItemInputAudioTranscriptionCompleted | GrokResponseCreated | GrokResponseOutputItemAdded | GrokResponseDone | GrokResponseOutputAudioDelta | GrokResponseOutputAudioDone | GrokResponseOutputAudioTranscriptDelta | GrokResponseOutputAudioTranscriptDone | GrokResponseFunctionCallArgumentsDone;
31
+ export interface GrokConversationCreated {
32
+ type: "conversation.created";
33
+ event_id: string;
34
+ conversation: {
35
+ id: string;
36
+ object: "realtime.conversation";
37
+ };
38
+ }
39
+ export interface GrokSessionUpdated {
40
+ type: "session.updated";
41
+ event_id: string;
42
+ session: GrokSession;
43
+ }
44
+ export interface GrokInputAudioBufferCommitted {
45
+ type: "input_audio_buffer.committed";
46
+ event_id: string;
47
+ previous_item_id?: string;
48
+ item_id: string;
49
+ }
50
+ export interface GrokInputAudioBufferCleared {
51
+ type: "input_audio_buffer.cleared";
52
+ event_id: string;
53
+ }
54
+ export interface GrokInputAudioBufferSpeechStarted {
55
+ type: "input_audio_buffer.speech_started";
56
+ event_id: string;
57
+ item_id: string;
58
+ }
59
+ export interface GrokInputAudioBufferSpeechStopped {
60
+ type: "input_audio_buffer.speech_stopped";
61
+ event_id: string;
62
+ item_id: string;
63
+ }
64
+ export interface GrokConversationItemAdded {
65
+ type: "conversation.item.added";
66
+ event_id: string;
67
+ previous_item_id?: string;
68
+ item: GrokItemWithId;
69
+ }
70
+ export interface GrokConversationItemInputAudioTranscriptionCompleted {
71
+ type: "conversation.item.input_audio_transcription.completed";
72
+ event_id: string;
73
+ item_id: string;
74
+ transcript: string;
75
+ }
76
+ export interface GrokResponseCreated {
77
+ type: "response.created";
78
+ event_id: string;
79
+ response: {
80
+ id: string;
81
+ object: "realtime.response";
82
+ status: "in_progress";
83
+ output: unknown[];
84
+ };
85
+ }
86
+ export interface GrokResponseOutputItemAdded {
87
+ type: "response.output_item.added";
88
+ event_id: string;
89
+ response_id: string;
90
+ output_index: number;
91
+ item: GrokItemWithId;
92
+ }
93
+ export interface GrokResponseDone {
94
+ type: "response.done";
95
+ event_id: string;
96
+ response: {
97
+ id: string;
98
+ object: "realtime.response";
99
+ status: "completed" | "cancelled" | "failed";
100
+ };
101
+ }
102
+ export interface GrokResponseOutputAudioDelta {
103
+ type: "response.output_audio.delta";
104
+ event_id: string;
105
+ response_id: string;
106
+ item_id: string;
107
+ output_index: number;
108
+ content_index: number;
109
+ delta: string;
110
+ }
111
+ export interface GrokResponseOutputAudioDone {
112
+ type: "response.output_audio.done";
113
+ event_id: string;
114
+ response_id: string;
115
+ item_id: string;
116
+ }
117
+ export interface GrokResponseOutputAudioTranscriptDelta {
118
+ type: "response.output_audio_transcript.delta";
119
+ event_id: string;
120
+ response_id: string;
121
+ item_id: string;
122
+ delta: string;
123
+ }
124
+ export interface GrokResponseOutputAudioTranscriptDone {
125
+ type: "response.output_audio_transcript.done";
126
+ event_id: string;
127
+ response_id: string;
128
+ item_id: string;
129
+ }
130
+ export interface GrokResponseFunctionCallArgumentsDone {
131
+ type: "response.function_call_arguments.done";
132
+ event_id: string;
133
+ response_id?: string;
134
+ item_id?: string;
135
+ call_id: string;
136
+ name: string;
137
+ arguments: string;
138
+ }
139
+ export interface GrokSession {
140
+ instructions?: string;
141
+ voice?: GrokVoice;
142
+ turn_detection?: GrokTurnDetection;
143
+ }
144
+ export interface GrokSessionConfig {
145
+ instructions?: string;
146
+ voice?: GrokVoice;
147
+ turn_detection?: GrokTurnDetection | null;
148
+ audio?: GrokAudioConfig;
149
+ tools?: GrokTool[];
150
+ }
151
+ /**
152
+ * Available Grok voices.
153
+ */
154
+ export type GrokVoice = "Ara" | "Rex" | "Sal" | "Eve" | "Leo";
155
+ export interface GrokTurnDetection {
156
+ type: "server_vad" | null;
157
+ }
158
+ export interface GrokAudioConfig {
159
+ input?: {
160
+ format?: GrokAudioFormat;
161
+ };
162
+ output?: {
163
+ format?: GrokAudioFormat;
164
+ };
165
+ }
166
+ export interface GrokAudioFormat {
167
+ type: "audio/pcm" | "audio/pcmu" | "audio/pcma";
168
+ rate?: number;
169
+ }
170
+ export type GrokTool = GrokFunctionTool | GrokWebSearchTool | GrokXSearchTool | GrokFileSearchTool;
171
+ export interface GrokFunctionTool {
172
+ type: "function";
173
+ name: string;
174
+ description?: string;
175
+ parameters?: JSONSchema7;
176
+ }
177
+ export interface GrokWebSearchTool {
178
+ type: "web_search";
179
+ }
180
+ export interface GrokXSearchTool {
181
+ type: "x_search";
182
+ allowed_x_handles?: string[];
183
+ }
184
+ export interface GrokFileSearchTool {
185
+ type: "file_search";
186
+ vector_store_ids: string[];
187
+ max_num_results?: number;
188
+ }
189
+ export type GrokItem = GrokMessageItem | GrokFunctionCallOutputItem;
190
+ export interface GrokMessageItem {
191
+ type: "message";
192
+ role: "user" | "assistant";
193
+ content: GrokContentPart[];
194
+ }
195
+ export interface GrokFunctionCallOutputItem {
196
+ type: "function_call_output";
197
+ call_id: string;
198
+ output: string;
199
+ }
200
+ export type GrokItemWithId = GrokItem & {
201
+ id: string;
202
+ object: "realtime.item";
203
+ status: "completed" | "in_progress";
204
+ };
205
+ export type GrokContentPart = {
206
+ type: "input_text";
207
+ text: string;
208
+ } | {
209
+ type: "input_audio";
210
+ transcript?: string;
211
+ };
212
+ //# sourceMappingURL=protocol.d.ts.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"protocol.d.ts","sourceRoot":"","sources":["../../src/realtime/protocol.ts"],"names":[],"mappings":"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"}
@@ -0,0 +1 @@
1
+ export {};