codex-grok-bridge 1.7.2 → 1.8.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.
@@ -0,0 +1,212 @@
1
+ import { timingSafeEqual } from "node:crypto";
2
+ import tls from "node:tls";
3
+ import { GrokAuthError, readGrokBearerToken } from "./auth.mjs";
4
+ import { acceptLocalSideband, isLocalVoiceSideband } from "./voice.mjs";
5
+
6
+ // Codex posts the WebRTC SDP offer to the provider base
7
+ // (`POST /v1/realtime/calls`, and v3 `POST /v1/live`). The body is raw bytes
8
+ // (Content-Type application/sdp, or whatever Codex sent). xAI answers with
9
+ // the SDP body, its status, and a Location header. This is a byte pipe:
10
+ // nothing here parses JSON or writes an SDP answer.
11
+
12
+ export const DEFAULT_REALTIME_API_BASE = "https://api.x.ai/v1";
13
+
14
+ export async function forwardRealtime(options) {
15
+ const fetchImpl = options.fetchImpl ?? fetch;
16
+ const base = (options.baseUrl ?? DEFAULT_REALTIME_API_BASE).replace(/\/$/, "");
17
+ const headers = { authorization: `Bearer ${options.token}` };
18
+ if (typeof options.contentType === "string") headers["content-type"] = options.contentType;
19
+ const response = await fetchImpl(`${base}${options.path}${options.search ?? ""}`, {
20
+ method: "POST",
21
+ headers,
22
+ body: options.body,
23
+ redirect: "manual",
24
+ signal: options.signal,
25
+ });
26
+ const body = Buffer.from(await response.arrayBuffer());
27
+ return {
28
+ status: response.status,
29
+ body,
30
+ contentType: response.headers.get("content-type"),
31
+ location: response.headers.get("location"),
32
+ };
33
+ }
34
+
35
+ export function connectSideband() {
36
+ return tls.connect({ host: "api.x.ai", port: 443, servername: "api.x.ai" });
37
+ }
38
+
39
+ export function isSidebandUpgradePath(url) {
40
+ let pathname = "/";
41
+ try {
42
+ pathname = new URL(url ?? "/", "http://127.0.0.1").pathname;
43
+ } catch {
44
+ return false;
45
+ }
46
+ return (
47
+ pathname === "/v1/realtime" ||
48
+ pathname.startsWith("/v1/realtime/") ||
49
+ pathname === "/v1/live" ||
50
+ pathname.startsWith("/v1/live/")
51
+ );
52
+ }
53
+
54
+ function headerText(value) {
55
+ const text = Array.isArray(value) ? value.join(", ") : String(value ?? "");
56
+ if (!text || /[\r\n]/.test(text)) return null;
57
+ return text;
58
+ }
59
+
60
+ function bearerMatches(header, token) {
61
+ const expected = Buffer.from(`Bearer ${token}`);
62
+ const actual = Buffer.from(header ?? "");
63
+ return actual.length === expected.length && timingSafeEqual(actual, expected);
64
+ }
65
+
66
+ function upgradeRequest(url, headers, token) {
67
+ const lines = [
68
+ `GET ${url} HTTP/1.1`,
69
+ "Host: api.x.ai",
70
+ "Upgrade: websocket",
71
+ "Connection: Upgrade",
72
+ `Sec-WebSocket-Key: ${headers.key}`,
73
+ `Sec-WebSocket-Version: ${headers.version}`,
74
+ `Authorization: Bearer ${token}`,
75
+ ];
76
+ if (headers.protocol) lines.push(`Sec-WebSocket-Protocol: ${headers.protocol}`);
77
+ if (headers.extensions) lines.push(`Sec-WebSocket-Extensions: ${headers.extensions}`);
78
+ lines.push("", "");
79
+ return lines.join("\r\n");
80
+ }
81
+
82
+ function readHead(socket) {
83
+ return new Promise((resolve, reject) => {
84
+ let buf = Buffer.alloc(0);
85
+ const cleanup = () => {
86
+ socket.off("readable", onReadable);
87
+ socket.off("error", onError);
88
+ socket.off("close", onClose);
89
+ };
90
+ let reading = false;
91
+ const onReadable = () => {
92
+ if (reading) return;
93
+ reading = true;
94
+ let chunk = socket.read();
95
+ while (chunk) {
96
+ buf = Buffer.concat([buf, chunk]);
97
+ chunk = socket.read();
98
+ }
99
+ reading = false;
100
+ const end = buf.indexOf("\r\n\r\n");
101
+ if (end === -1) {
102
+ if (buf.length > 65536) {
103
+ cleanup();
104
+ reject(new Error("header too large"));
105
+ }
106
+ return;
107
+ }
108
+ cleanup();
109
+ resolve({ head: buf.subarray(0, end + 4), rest: buf.subarray(end + 4) });
110
+ };
111
+ const onError = (error) => {
112
+ cleanup();
113
+ reject(error);
114
+ };
115
+ const onClose = () => {
116
+ cleanup();
117
+ reject(new Error("closed"));
118
+ };
119
+ socket.on("readable", onReadable);
120
+ socket.on("error", onError);
121
+ socket.on("close", onClose);
122
+ onReadable();
123
+ });
124
+ }
125
+
126
+ function switching(head) {
127
+ const line = head.toString("latin1").split("\r\n", 1)[0] ?? "";
128
+ return /^HTTP\/1\.[01] 101\b/.test(line);
129
+ }
130
+
131
+ function fail(socket, upstream) {
132
+ socket.destroy();
133
+ upstream?.destroy();
134
+ }
135
+
136
+ export function attachSidebandUpgrade(server, options = {}) {
137
+ server.on("upgrade", (req, socket, head) => {
138
+ pipeSidebandUpgrade(req, socket, head, options).catch(() => fail(socket));
139
+ });
140
+ }
141
+
142
+ async function pipeSidebandUpgrade(req, socket, head, options) {
143
+ const url = String(req.url ?? "/");
144
+ if (!isSidebandUpgradePath(url) || req.headers.origin) return fail(socket);
145
+ if (!bearerMatches(req.headers.authorization, options.token)) return fail(socket);
146
+ const key = headerText(req.headers["sec-websocket-key"]);
147
+ if (isLocalVoiceSideband(url)) {
148
+ if (!key) return fail(socket);
149
+ acceptLocalSideband(socket, key, url, head);
150
+ return;
151
+ }
152
+ const version =
153
+ req.headers["sec-websocket-version"] == null
154
+ ? "13"
155
+ : headerText(req.headers["sec-websocket-version"]);
156
+ if (!key || !version) return fail(socket);
157
+ const protocol = headerText(req.headers["sec-websocket-protocol"]);
158
+ const extensions = headerText(req.headers["sec-websocket-extensions"]);
159
+ if (
160
+ (req.headers["sec-websocket-protocol"] && !protocol) ||
161
+ (req.headers["sec-websocket-extensions"] && !extensions)
162
+ ) {
163
+ return fail(socket);
164
+ }
165
+ let token;
166
+ try {
167
+ token = (options.grokSession ?? readGrokBearerToken(options.grokHome)).token;
168
+ } catch (error) {
169
+ if (error instanceof GrokAuthError) return fail(socket);
170
+ throw error;
171
+ }
172
+ const connect = options.sidebandConnect ?? connectSideband;
173
+ const upstream = connect();
174
+ if (!upstream) return fail(socket);
175
+ socket.on("error", () => upstream.destroy());
176
+ upstream.on("error", () => socket.destroy());
177
+ let settled = false;
178
+ const timer = setTimeout(() => {
179
+ if (settled) return;
180
+ settled = true;
181
+ fail(socket, upstream);
182
+ }, options.sidebandHandshakeMs ?? 10_000);
183
+ const finishHandshake = () => {
184
+ if (settled) return false;
185
+ settled = true;
186
+ clearTimeout(timer);
187
+ return true;
188
+ };
189
+ try {
190
+ socket.pause();
191
+ upstream.write(
192
+ upgradeRequest(url, { key, version, protocol, extensions }, token),
193
+ );
194
+ if (head?.length) upstream.write(head);
195
+ const response = await readHead(upstream);
196
+ if (!finishHandshake()) return;
197
+ if (!switching(response.head)) return fail(socket, upstream);
198
+ socket.write(response.head);
199
+ if (response.rest.length) socket.write(response.rest);
200
+ socket.resume();
201
+ upstream.pipe(socket);
202
+ socket.pipe(upstream);
203
+ socket.on("close", () => upstream.destroy());
204
+ upstream.on("close", () => socket.destroy());
205
+ } catch {
206
+ if (!settled) {
207
+ settled = true;
208
+ clearTimeout(timer);
209
+ }
210
+ fail(socket, upstream);
211
+ }
212
+ }
package/src/runtime.mjs CHANGED
@@ -43,6 +43,9 @@ export async function startRuntime(options = {}) {
43
43
  "-c",
44
44
  `model_providers.grok_build_cli.${key}=${tomlValue(value)}`,
45
45
  ]);
46
+ // Desktop WebRTC reads this for the sideband. Unset, Codex keeps
47
+ // https://api.openai.com/v1. The value is this bridge, not xAI.
48
+ args.push("-c", `experimental_realtime_ws_base_url=${tomlValue(provider.base_url)}`);
46
49
  return {
47
50
  server,
48
51
  token,
package/src/tools.mjs CHANGED
@@ -85,6 +85,14 @@ function pickKeys(node, keys) {
85
85
 
86
86
  function whitelistContentPart(part) {
87
87
  if (!part || typeof part !== "object" || Array.isArray(part)) return part;
88
+ // Chat audio is not a Responses content part Grok accepts. Leaving the bytes
89
+ // in history makes the upstream reject the turn, and every later turn with it.
90
+ if (part.type === "input_audio") {
91
+ return {
92
+ type: "input_text",
93
+ text: "[An audio attachment was not sent to the model. Say so if the user asks about it.]",
94
+ };
95
+ }
88
96
  const keys = CONTENT_PART_FIELDS[part.type];
89
97
  if (!keys) return part;
90
98
  const next = pickKeys(part, keys);
@@ -494,12 +502,95 @@ function droppedItemInputTexts(node) {
494
502
  rememberTextValue(texts, seen, action.queries);
495
503
  rememberText(texts, seen, action.url);
496
504
  rememberText(texts, seen, action.pattern);
505
+ if (Array.isArray(action.sources)) {
506
+ for (const source of action.sources) {
507
+ if (typeof source === "string") {
508
+ rememberText(texts, seen, source);
509
+ continue;
510
+ }
511
+ if (!source || typeof source !== "object") continue;
512
+ rememberText(texts, seen, source.url);
513
+ rememberText(texts, seen, source.title);
514
+ rememberText(texts, seen, source.snippet);
515
+ rememberText(texts, seen, source.text);
516
+ }
517
+ }
497
518
  }
498
519
  rememberArguments(texts, seen, node.arguments);
499
520
  rememberTools(texts, seen, node.tools);
521
+ const aggregated = readableString(node.aggregated_output) ?? readableString(node.formatted_output);
522
+ if (aggregated) rememberText(texts, seen, aggregated);
523
+ else {
524
+ rememberText(texts, seen, node.stdout);
525
+ rememberText(texts, seen, node.stderr);
526
+ }
527
+ const rememberExit = (value) => {
528
+ if (Number.isInteger(value) && value !== 0) rememberText(texts, seen, `exit ${value}`);
529
+ };
530
+ rememberExit(node.exit_code);
531
+ const output = node.output;
532
+ if (Array.isArray(output)) {
533
+ for (const row of output) {
534
+ if (!row || typeof row !== "object") continue;
535
+ rememberExit(row.exit_code);
536
+ rememberExit(row.outcome?.exit_code);
537
+ }
538
+ } else if (output && typeof output === "object") {
539
+ rememberExit(output.exit_code);
540
+ rememberExit(output.outcome?.exit_code);
541
+ }
500
542
  return texts;
501
543
  }
502
544
 
545
+ const INLINE_IMAGE = /^data:image\/(?:png|jpeg|webp);base64,/i;
546
+
547
+ function functionOutputParts(output) {
548
+ if (typeof output === "string") return { text: output, images: [] };
549
+ const parts = [];
550
+ const images = [];
551
+ const push = (value) => {
552
+ if (typeof value === "string" && value.trim()) parts.push(value.trim());
553
+ };
554
+ const visit = (value) => {
555
+ if (typeof value === "string") {
556
+ push(value);
557
+ return;
558
+ }
559
+ if (Array.isArray(value)) {
560
+ for (const part of value) visit(part);
561
+ return;
562
+ }
563
+ if (!value || typeof value !== "object") return;
564
+ push(value.text);
565
+ push(value.stdout);
566
+ push(value.stderr);
567
+ const image = value.image_url;
568
+ const url =
569
+ typeof image === "string"
570
+ ? image
571
+ : image && typeof image === "object" && typeof image.url === "string"
572
+ ? image.url
573
+ : "";
574
+ if (url && INLINE_IMAGE.test(url)) {
575
+ const part = { type: "input_image", image_url: url };
576
+ const detail =
577
+ typeof value.detail === "string"
578
+ ? value.detail
579
+ : image && typeof image === "object" && typeof image.detail === "string"
580
+ ? image.detail
581
+ : "";
582
+ if (detail) part.detail = detail;
583
+ images.push(part);
584
+ push("[An image from this tool result follows.]");
585
+ } else if (url) {
586
+ push(url);
587
+ }
588
+ if (Array.isArray(value.content)) visit(value.content);
589
+ };
590
+ visit(output);
591
+ return { text: parts.join("\n"), images };
592
+ }
593
+
503
594
  function userInputTextMessage(texts) {
504
595
  return whitelistInputNode({
505
596
  type: "message",
@@ -510,11 +601,13 @@ function userInputTextMessage(texts) {
510
601
 
511
602
  function toProxyInputNode(node, map, state, salvage = false) {
512
603
  if (!node || typeof node !== "object") return node;
513
- if (Array.isArray(node)) {
604
+ if (Array.isArray(node)) {
514
605
  const items = [];
515
606
  for (const item of node) {
516
607
  const next = toProxyInputNode(item, map, state);
517
- if (next !== DROP) items.push(next);
608
+ if (next === DROP) continue;
609
+ if (Array.isArray(next)) items.push(...next);
610
+ else items.push(next);
518
611
  }
519
612
  return items;
520
613
  }
@@ -547,12 +640,19 @@ function toProxyInputNode(node, map, state, salvage = false) {
547
640
  if (next.type === "reasoning") {
548
641
  // Forward the summary and nothing else. Codex's own item id and null
549
642
  // content fields mean nothing to the upstream and only widen the surface
550
- // for a schema rejection.
551
- const summary = (Array.isArray(next.summary) ? next.summary : []).filter(
552
- (part) => part && typeof part.text === "string" && part.text.trim(),
553
- );
554
- if (!summary.length) return DROP;
555
- return whitelistInputNode({ type: "reasoning", summary });
643
+ // for a schema rejection. When the summary is empty, the plain text in
644
+ // content is the only readable reasoning left.
645
+ const readable = (parts) =>
646
+ (Array.isArray(parts) ? parts : []).filter(
647
+ (part) => part && typeof part.text === "string" && part.text.trim() && part.type !== "encrypted_content",
648
+ );
649
+ const summary = readable(next.summary);
650
+ const chosen = summary.length ? summary : readable(next.content);
651
+ if (!chosen.length) return DROP;
652
+ return whitelistInputNode({
653
+ type: "reasoning",
654
+ summary: chosen.map((part) => ({ type: "summary_text", text: part.text.trim() })),
655
+ });
556
656
  }
557
657
 
558
658
  if (next.type === "agent_message") {
@@ -606,8 +706,28 @@ function toProxyInputNode(node, map, state, salvage = false) {
606
706
  }
607
707
  }
608
708
 
709
+ // Codex sends a string or a list of content parts. Grok accepts the string.
710
+ // An inline image in that list is attached after the tool result so the
711
+ // model can see it; a remote URL stays as text and is not fetched.
712
+ let attachedImages = [];
713
+ if (next.type === "function_call_output" && typeof next.output !== "string") {
714
+ const parts = functionOutputParts(next.output);
715
+ next.output = parts.text;
716
+ attachedImages = parts.images;
717
+ }
718
+
609
719
  const whitelisted = whitelistInputNode(next);
610
- if (!salvage || isForwardedItem(whitelisted)) return whitelisted;
720
+ if (!salvage || isForwardedItem(whitelisted)) {
721
+ if (!attachedImages.length) return whitelisted;
722
+ return [
723
+ whitelisted,
724
+ whitelistInputNode({
725
+ type: "message",
726
+ role: "user",
727
+ content: attachedImages,
728
+ }),
729
+ ];
730
+ }
611
731
  // Grok rejects these Codex item types. Keep the readable text as a user
612
732
  // message, the same shape as a compaction summary. An item with nothing
613
733
  // left but an encrypted blob, image bytes, or ids is dropped.
@@ -629,15 +749,21 @@ function isForwardedItem(item) {
629
749
  function projectInput(input, map) {
630
750
  if (!Array.isArray(input)) {
631
751
  const items = toProxyInputNode(input, map, { callIds: new Map() }, true);
632
- return { items, pairs: [] };
752
+ return { items: Array.isArray(items) ? items : items === DROP ? [] : [items], pairs: [] };
633
753
  }
634
754
  const state = { callIds: new Map() };
635
755
  const pairs = [];
636
756
  for (const item of input) {
637
757
  const fingerprint = logicalFingerprint(item);
638
- const next = toProxyInputNode(item, map, state, true);
639
- if (!isForwardedItem(next)) continue;
640
- pairs.push({ fingerprint, item: next });
758
+ const produced = toProxyInputNode(item, map, state, true);
759
+ const list = Array.isArray(produced) ? produced : [produced];
760
+ list.forEach((next, index) => {
761
+ if (!isForwardedItem(next)) return;
762
+ pairs.push({
763
+ fingerprint: index === 0 ? fingerprint : logicalFingerprint(next),
764
+ item: next,
765
+ });
766
+ });
641
767
  }
642
768
  return { items: pairs.map((pair) => pair.item), pairs };
643
769
  }
@@ -677,8 +803,8 @@ export const IMAGE_GENERATION_PROVENANCE =
677
803
  export const VIDEO_GENERATION_PROVENANCE =
678
804
  "Videos: clips on this transport are generated by the grok_bridge_generate_video " +
679
805
  "function, which is already on the request. The bridge calls Grok's videos API " +
680
- "with the grok login and returns the video URL. Do not ask for an API key and " +
681
- "do not send the clip to another vendor.";
806
+ "with the grok login, saves the temporary file locally, and returns that path. " +
807
+ "Do not ask for an API key and do not send the clip to another vendor.";
682
808
 
683
809
  export function toProxyRequest(body) {
684
810
  const { tools, map } = flattenCodexTools(body.tools ?? []);
@@ -741,14 +867,29 @@ function restoreOriginName(node, origin) {
741
867
  else delete node.namespace;
742
868
  }
743
869
 
870
+ function originForResponseName(map, name) {
871
+ if (typeof name !== "string") return null;
872
+ if (map.has(name)) return map.get(name);
873
+ let found = null;
874
+ for (const origin of map.values()) {
875
+ if (origin.name !== name) continue;
876
+ if (found) return null;
877
+ found = origin;
878
+ }
879
+ return found;
880
+ }
881
+
744
882
  function rewriteResponseItem(node, map, state) {
745
883
  if (!node || typeof node !== "object") return;
746
- if (typeof node.name === "string" && map.has(node.name)) {
747
- const origin = map.get(node.name);
884
+ const origin =
885
+ originForResponseName(map, node.name) ??
886
+ (typeof node.call_id === "string" ? state.callIds.get(node.call_id) : null);
887
+ if (origin) {
748
888
  rememberProxyItem(node, origin, state);
749
889
  restoreOriginName(node, origin);
750
890
  if (origin.kind === "custom") {
751
891
  if (node.type === "function_call") node.type = "custom_tool_call";
892
+ if (node.type === "function_call_output") node.type = "custom_tool_call_output";
752
893
  if (node.type === "custom_tool_call") {
753
894
  if (node.input == null) node.input = decodeCustomInput(node.arguments);
754
895
  delete node.arguments;
@@ -762,14 +903,27 @@ function rewriteResponseItem(node, map, state) {
762
903
  // and no place to put them, so the bridge writes the file and hands back an
763
904
  // ordinary assistant message naming it.
764
905
  function absorbGeneratedImage(item, state) {
906
+ const key = typeof item.id === "string" ? item.id : "";
907
+ if (key && state.savedImages?.has(key)) return state.savedImages.get(key);
765
908
  const saved = saveGeneratedImage(item, state.imageOptions);
766
- return {
909
+ const described = describeGeneratedImage(
910
+ typeof item.prompt === "string" && item.prompt.trim()
911
+ ? item
912
+ : { ...item, prompt: item.revised_prompt },
913
+ saved,
914
+ );
915
+ const message = {
767
916
  type: "message",
768
- id: typeof item.id === "string" ? item.id : undefined,
917
+ id: key || undefined,
769
918
  role: "assistant",
770
919
  status: "completed",
771
- content: [{ type: "output_text", text: describeGeneratedImage(item, saved) }],
920
+ content: [{ type: "output_text", text: described }],
772
921
  };
922
+ if (key) {
923
+ if (!state.savedImages) state.savedImages = new Map();
924
+ state.savedImages.set(key, message);
925
+ }
926
+ return message;
773
927
  }
774
928
 
775
929
  const USAGE_EVENTS = new Set(["response.completed", "response.incomplete"]);
@@ -785,6 +939,24 @@ function rewriteResponseEvent(value, map, state) {
785
939
  const cache = readCacheUsage(value.response.usage);
786
940
  if (cache) state.cacheUsage = cache;
787
941
  }
942
+ if (Array.isArray(value.response?.output)) {
943
+ for (let i = 0; i < value.response.output.length; i += 1) {
944
+ const item = value.response.output[i];
945
+ if (isImageGenerationItem(item))
946
+ value.response.output[i] = absorbGeneratedImage(item, state);
947
+ else rewriteResponseItem(item, map, state);
948
+ }
949
+ }
950
+ if (
951
+ value.type === "response.function_call_arguments.delta" ||
952
+ value.type === "response.function_call_arguments.done"
953
+ ) {
954
+ const origin = originForResponseName(map, value.name);
955
+ if (origin) {
956
+ rememberProxyItem(value, origin, state);
957
+ value.name = origin.name;
958
+ }
959
+ }
788
960
  if (
789
961
  typeof value.item === "object" &&
790
962
  value.item &&
@@ -843,6 +1015,7 @@ export function createSseRewriter(map, options = {}) {
843
1015
  const state = {
844
1016
  callIds: new Map(),
845
1017
  itemIds: new Map(),
1018
+ savedImages: new Map(),
846
1019
  imageOptions: options.imageOptions,
847
1020
  cacheUsage: null,
848
1021
  };