codex-grok-bridge 1.6.0 → 1.7.0

package/CHANGELOG.md

@@ -2,6 +2,15 @@
 
 ## Unreleased
 
+## 1.7.0 — 2026-09-29
+
+- One `x-grok-conv-id` per Codex thread, and the forwarded transcript prefix stays byte-stable so prompt cache can hit. The full transcript is still sent.
+- Upstream `cached_prompt_tokens` and `cache_read_input_tokens` are copied onto `response.completed` usage and the diagnostics log when the proxy sends them, including `0`. Missing counters are not invented.
+
+## 1.6.1 — 2026-09-28
+
+- Darwin bundled CLI resolves `Codex.app/Contents/Resources/codex-cli/bin/codex` when that file exists (Codex 26.924). The legacy `Contents/Resources/codex` path remains the fallback. `CODEX_BINARY` still wins. Linux and Windows layouts are unchanged.
+
 ## 1.6.0 — 2026-09-27
 
 - Default catalog model is `grok-4.7` (`Grok 4.7 / xAI`). `grok-4.6` stays listed so existing threads still resolve.

package/README.md

@@ -130,8 +130,11 @@ older CLI envelope. That path pastes the whole JSON into a prompt each turn, so
 it is slower and more expensive, has no token-by-token streaming, and is capped
 at three minutes per request.
 
-The default Responses path streams. Codex `prompt_cache_key` is forwarded as
-`x-grok-conv-id`.
+The default Responses path streams. One Codex thread keeps a single
+`x-grok-conv-id`: the `thread-id` header when Codex sends it, otherwise
+`prompt_cache_key`. That same id is written into `prompt_cache_key`. An
+unchanged transcript prefix is resent byte-for-byte; the new items are
+appended, not substituted for the history.
 
 ## What works and what does not
 
@@ -453,8 +456,10 @@ Responses 경로가 이상하면 `GROK_BRIDGE_INFERENCE=cli`로 이전 CLI 봉
 씁니다. 매 턴 전체 JSON을 프롬프트로 넣으므로 더 느리고 비싸며, 토큰 단위
 실시간 출력이 없고, 요청당 3분 제한입니다.
 
-기본 Responses 경로는 스트림을 전달합니다. Codex `prompt_cache_key`는
-`x-grok-conv-id`로 넘깁니다.
+기본 Responses 경로는 스트림을 전달합니다. Codex 스레드마다 `x-grok-conv-id`는
+하나입니다. `thread-id` 헤더가 있으면 그 값이고, 없으면 `prompt_cache_key`입니다.
+같은 id를 `prompt_cache_key`에도 넣습니다. 바뀌지 않은 트랜스크립트 접두는
+바이트 그대로 다시 보내고, 새 항목은 그 뒤에 붙입니다.
 
 ## 확인된 동작과 제한
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "codex-grok-bridge",
-  "version": "1.6.0",
+  "version": "1.7.0",
   "description": "Run Grok 4.7 as the model inside Codex, with Codex still owning tools, permissions, history and MCP. Uses the grok login session, not an API key.",
   "type": "module",
   "license": "MIT",

package/src/bridge.mjs

@@ -9,6 +9,12 @@ import {
   runGrok,
 } from "./cli-inference.mjs";
 import { openProxyStreamWithRetry, pipeProxySse } from "./proxy.mjs";
+import {
+  applyCacheUsage,
+  createPrefixMemory,
+  readCacheUsage,
+  stableConvId,
+} from "./prefix.mjs";
 import { toProxyRequest } from "./tools.mjs";
 import { classifyBridgeError, errorSignature, bridgeErrorMessage } from "./errors.mjs";
 import { createDiagnostics } from "./diagnostics.mjs";
@@ -36,6 +42,7 @@ export function createBridgeServer(options = {}) {
     limit: options.maxConcurrentInference,
     queueLimit: options.maxQueuedInference,
   });
+  const prefixes = createPrefixMemory();
   return http.createServer(async (req, res) => {
     const json = (status, data) => {
       res.writeHead(status, { "content-type": "application/json" });
@@ -112,6 +119,7 @@ export function createBridgeServer(options = {}) {
     const queuedAt = Date.now();
     let acquired = false;
     let queuedMs = 0;
+    let cacheUsage = null;
     try {
       await slots.acquire(controller.signal);
       acquired = true;
@@ -135,14 +143,18 @@ export function createBridgeServer(options = {}) {
             parsed.usage?.input_tokens ?? parsed.usage?.inputTokens ?? 0,
           outputTokens =
             parsed.usage?.output_tokens ?? parsed.usage?.outputTokens ?? 0;
+        const usage = {
+          input_tokens: inputTokens,
+          output_tokens: outputTokens,
+          total_tokens: inputTokens + outputTokens,
+        };
+        cacheUsage = readCacheUsage(parsed.usage);
+        if (cacheUsage) Object.assign(usage, cacheUsage);
+        applyCacheUsage(usage);
         event("response.completed", {
           response: {
             id,
-            usage: {
-              input_tokens: inputTokens,
-              output_tokens: outputTokens,
-              total_tokens: inputTokens + outputTokens,
-            },
+            usage,
           },
         });
       } else {
@@ -150,7 +162,15 @@ export function createBridgeServer(options = {}) {
         // Grok takes input_image blocks natively; only unusable attachments
         // are swapped for an explanation, so one bad image cannot make the
         // upstream reject the whole conversation.
-        const { request, map } = toProxyRequest(sanitizeImages(body));
+        const threadId = req.headers["thread-id"];
+        const convId = stableConvId(
+          Array.isArray(threadId) ? threadId[0] : threadId,
+          body.prompt_cache_key,
+        );
+        const { request, map, projected } = toProxyRequest(sanitizeImages(body));
+        if (convId) request.prompt_cache_key = convId;
+        request.input = prefixes.reuse(convId, projected);
+        const usageBox = {};
         const proxy = await openProxyStreamWithRetry({
           token: session.token,
           userId: session.userId,
@@ -158,8 +178,8 @@ export function createBridgeServer(options = {}) {
           signal: controller.signal,
           fetchImpl: options.proxyFetch,
           baseUrl: options.proxyBaseUrl,
-          convId: body.prompt_cache_key,
-          sessionId: req.headers["thread-id"],
+          convId,
+          sessionId: Array.isArray(threadId) ? threadId[0] : threadId,
           onRetry: ({ attempt, kind }) =>
             diagnostics.record({
               event: "turn_retried",
@@ -168,11 +188,16 @@ export function createBridgeServer(options = {}) {
               elapsedMs: Date.now() - startedAt,
             }),
         });
-        await pipeProxySse(proxy.body, res, map);
+        try {
+          await pipeProxySse(proxy.body, res, map, usageBox);
+        } finally {
+          cacheUsage = usageBox.cacheUsage ?? null;
+        }
       }
       diagnostics.record({
         event: "turn_ok",
         ...shape,
+        ...(cacheUsage ?? {}),
         queuedMs,
         elapsedMs: Date.now() - startedAt,
       });
@@ -183,6 +208,7 @@ export function createBridgeServer(options = {}) {
         kind,
         signature: errorSignature(error),
         ...shape,
+        ...(cacheUsage ?? {}),
         queuedMs,
         elapsedMs: Date.now() - startedAt,
         detail: error?.message,

package/src/paths.mjs

@@ -4,6 +4,8 @@ import { homedir } from "node:os";
 
 export const LINUX_CODEX_BINARY = "/usr/lib/chatgpt/resources/codex";
 export const LINUX_CHATGPT_BIN = "/usr/lib/chatgpt/ChatGPT";
+export const DARWIN_CODEX_CLI_BINARY =
+  "/Applications/Codex.app/Contents/Resources/codex-cli/bin/codex";
 export const DARWIN_CODEX_BINARY = "/Applications/Codex.app/Contents/Resources/codex";
 export const DARWIN_CODEX_APP = "/Applications/Codex.app";
 export const LINUX_STOCK_PREFIX = "/usr/lib/chatgpt";
@@ -54,6 +56,8 @@ export function resolveCodexBinary(options = {}) {
   if (platform === "win32") {
     return resolveWin32Binary("codex.exe", "store-codex.txt", { ...options, env });
   }
+  const exists = options.existsSync ?? existsSync;
+  if (exists(DARWIN_CODEX_CLI_BINARY)) return DARWIN_CODEX_CLI_BINARY;
   return DARWIN_CODEX_BINARY;
 }
 

package/src/prefix.mjs

@@ -0,0 +1,163 @@
+import { createHash } from "node:crypto";
+
+// xAI prompt cache hits only when later requests repeat the same prefix
+// unchanged, on the same x-grok-conv-id. Codex resends the whole transcript,
+// but a fresh rewrite (new ids, encrypted reasoning, tool index names) makes
+// that prefix differ. This module pins the conv id and reuses the exact
+// items already forwarded.
+
+const CACHE_USAGE_FIELDS = [
+  "cached_prompt_tokens",
+  "cache_read_input_tokens",
+  "cache_creation_input_tokens",
+];
+
+const VOLATILE_KEYS = new Set([
+  "id",
+  "status",
+  "encrypted_content",
+  "encrypted_function_args",
+]);
+
+export function stableConvId(threadId, promptCacheKey) {
+  const thread = typeof threadId === "string" ? threadId.trim() : "";
+  if (thread) return thread;
+  const cache = typeof promptCacheKey === "string" ? promptCacheKey.trim() : "";
+  return cache || null;
+}
+
+export function stableProxyName(spec, sanitizedName) {
+  const basis = `${spec.kind}\0${spec.namespace ?? ""}\0${spec.name ?? ""}`;
+  const hash = createHash("sha256").update(basis).digest("hex").slice(0, 8);
+  return `codex_${hash}_${sanitizedName}`;
+}
+
+function normalizeForFingerprint(value) {
+  if (Array.isArray(value)) return value.map(normalizeForFingerprint);
+  if (!value || typeof value !== "object") return value;
+  if (
+    value.type === "input_text" ||
+    value.type === "output_text" ||
+    value.type === "summary_text"
+  ) {
+    return {
+      type: value.type,
+      text: typeof value.text === "string" ? value.text : "",
+    };
+  }
+  if (value.type === "input_image") {
+    const url =
+      value.image_url && typeof value.image_url === "object"
+        ? value.image_url.url
+        : value.image_url;
+    const image = { type: "input_image" };
+    if (url !== undefined) image.image_url = url;
+    if (value.detail !== undefined) image.detail = value.detail;
+    return image;
+  }
+  const out = {};
+  for (const key of Object.keys(value).sort()) {
+    if (VOLATILE_KEYS.has(key) || key.startsWith("internal_")) continue;
+    const child = value[key];
+    if (child === undefined || child === null) continue;
+    out[key] = normalizeForFingerprint(child);
+  }
+  if (
+    out.role &&
+    out.content !== undefined &&
+    (out.type == null || out.type === "message")
+  ) {
+    out.type = "message";
+    if (typeof out.content === "string")
+      out.content = [{ type: "input_text", text: out.content }];
+  }
+  return out;
+}
+
+export function logicalFingerprint(item) {
+  return JSON.stringify(normalizeForFingerprint(item));
+}
+
+// Object key order is part of the cached prefix. Codex does not promise it.
+export function stableJsonValue(value) {
+  if (Array.isArray(value)) return value.map(stableJsonValue);
+  if (!value || typeof value !== "object") return value;
+  const out = {};
+  for (const key of Object.keys(value).sort())
+    out[key] = stableJsonValue(value[key]);
+  return out;
+}
+
+const MAX_THREADS = 64;
+
+export function createPrefixMemory() {
+  const threads = new Map();
+  return {
+    reuse(convId, pairs) {
+      const fresh = pairs.map((pair) => pair.item);
+      if (!convId || pairs.length === 0) return fresh;
+      const previous = threads.get(convId);
+      let reused = 0;
+      if (previous) {
+        const limit = Math.min(previous.length, pairs.length);
+        while (
+          reused < limit &&
+          previous[reused].fingerprint === pairs[reused].fingerprint
+        )
+          reused += 1;
+      }
+      const stored =
+        reused > 0
+          ? [...previous.slice(0, reused), ...pairs.slice(reused)]
+          : pairs.slice();
+      if (threads.has(convId)) threads.delete(convId);
+      threads.set(
+        convId,
+        stored.map((pair) => ({
+          fingerprint: pair.fingerprint,
+          item: structuredClone(pair.item),
+        })),
+      );
+      while (threads.size > MAX_THREADS) {
+        const oldest = threads.keys().next().value;
+        threads.delete(oldest);
+      }
+      if (!previous || reused === 0) return fresh;
+      return [
+        ...previous.slice(0, reused).map((pair) => structuredClone(pair.item)),
+        ...pairs.slice(reused).map((pair) => pair.item),
+      ];
+    },
+  };
+}
+
+// Copy only cache counters the upstream actually sent. Zero is a real miss.
+// Absence is not a miss, so it must not become 0.
+export function readCacheUsage(usage) {
+  if (!usage || typeof usage !== "object") return null;
+  const out = {};
+  for (const key of CACHE_USAGE_FIELDS) {
+    const value = usage[key];
+    if (typeof value === "number" && Number.isFinite(value)) out[key] = value;
+  }
+  return Object.keys(out).length ? out : null;
+}
+
+export function applyCacheUsage(usage) {
+  const cache = readCacheUsage(usage);
+  if (!cache) return usage;
+  const cached =
+    typeof cache.cached_prompt_tokens === "number"
+      ? cache.cached_prompt_tokens
+      : cache.cache_read_input_tokens;
+  if (typeof cached !== "number") return usage;
+  const details =
+    usage.input_tokens_details && typeof usage.input_tokens_details === "object"
+      ? usage.input_tokens_details
+      : {};
+  if (typeof details.cached_tokens !== "number") {
+    details.cached_tokens = cached;
+    usage.input_tokens_details = details;
+  }
+  return usage;
+}

package/src/proxy.mjs

@@ -138,7 +138,7 @@ export async function openProxyStreamWithRetry(options, attempts = 2) {
   throw lastError;
 }
 
-export async function pipeProxySse(stream, output, map) {
+export async function pipeProxySse(stream, output, map, usageBox) {
   const reader = stream.getReader();
   const decoder = new TextDecoder();
   let buffer = "";
@@ -166,5 +166,7 @@ export async function pipeProxySse(stream, output, map) {
     // unread holds the upstream socket open for the rest of the response.
     await reader.cancel(error).catch(() => {});
     throw error;
+  } finally {
+    if (usageBox) usageBox.cacheUsage = rewrite.cacheUsage ?? null;
   }
 }

package/src/tools.mjs

@@ -5,6 +5,13 @@ import {
   saveGeneratedImage,
 } from "./imagegen.mjs";
 import { DEFAULT_GROK_MODEL, resolveGrokModel } from "./models.mjs";
+import {
+  applyCacheUsage,
+  logicalFingerprint,
+  readCacheUsage,
+  stableJsonValue,
+  stableProxyName,
+} from "./prefix.mjs";
 
 const OBJECT_SCHEMA = { type: "object", properties: {} };
 
@@ -227,7 +234,14 @@ function decodeCustomInput(argumentsValue) {
 }
 
 function addFunction(flattened, map, spec) {
-  const proxyName = `codex_${flattened.length}_${sanitize(spec.name)}`;
+  // Index names change when Codex reorders tools, which rewrites every
+  // earlier function_call and breaks the prompt-cache prefix.
+  let proxyName = stableProxyName(spec, sanitize(spec.name));
+  if (map.has(proxyName)) {
+    let n = 2;
+    while (map.has(`${proxyName}_${n}`)) n += 1;
+    proxyName = `${proxyName}_${n}`;
+  }
   map.set(proxyName, {
     kind: spec.kind,
     namespace: spec.namespace,
@@ -239,10 +253,11 @@ function addFunction(flattened, map, spec) {
     description: spec.namespace
       ? `[${spec.namespace}] ${spec.description || spec.name}`
       : spec.description || spec.name,
-    parameters:
+    parameters: stableJsonValue(
       spec.kind === "custom"
         ? structuredClone(CUSTOM_INPUT_SCHEMA)
         : usableParameters(spec.parameters),
+    ),
   });
 }
 
@@ -284,7 +299,7 @@ export function flattenCodexTools(tools = []) {
       }
       continue;
     }
-    flattened.push(structuredClone(tool));
+    flattened.push(stableJsonValue(structuredClone(tool)));
   }
   return { tools: flattened, map };
 }
@@ -392,17 +407,36 @@ function toProxyInputNode(node, map, state) {
   return whitelistInputNode(next);
 }
 
-function toProxyInput(input, map) {
-  const items = toProxyInputNode(input, map, { callIds: new Map() });
-  if (!Array.isArray(items)) return items;
-  return items.filter(
-    (item) =>
-      item &&
-      typeof item === "object" &&
-      (item.type == null || GROK_INPUT_ITEM_TYPES.has(item.type)),
+function isForwardedItem(item) {
+  return (
+    item &&
+    item !== DROP &&
+    typeof item === "object" &&
+    !Array.isArray(item) &&
+    (item.type == null || GROK_INPUT_ITEM_TYPES.has(item.type))
   );
 }
 
+function projectInput(input, map) {
+  if (!Array.isArray(input)) {
+    const items = toProxyInputNode(input, map, { callIds: new Map() });
+    return { items, pairs: [] };
+  }
+  const state = { callIds: new Map() };
+  const pairs = [];
+  for (const item of input) {
+    const fingerprint = logicalFingerprint(item);
+    const next = toProxyInputNode(item, map, state);
+    if (!isForwardedItem(next)) continue;
+    pairs.push({ fingerprint, item: next });
+  }
+  return { items: pairs.map((pair) => pair.item), pairs };
+}
+
+function toProxyInput(input, map) {
+  return projectInput(input, map).items;
+}
+
 // Only the bridge knows a request is being served by the bridge. Codex does not
 // put the provider or model into the prompt, so without this line the model has
 // no way to answer "is Grok actually attached?" and either hedges or goes
@@ -432,9 +466,10 @@ export const IMAGE_GENERATION_PROVENANCE =
 export function toProxyRequest(body) {
   const { tools, map } = flattenCodexTools(body.tools ?? []);
   const effort = EFFORT[body.reasoning?.effort] ?? "high";
+  const projected = projectInput(body.input, map);
   const request = {
     model: resolveGrokModel(body.model),
-    input: toProxyInput(body.input, map),
+    input: projected.items,
     tools,
     reasoning: { effort },
     stream: true,
@@ -463,7 +498,7 @@ export function toProxyRequest(body) {
       : provenance;
   if (typeof body.prompt_cache_key === "string" && body.prompt_cache_key)
     request.prompt_cache_key = body.prompt_cache_key;
-  return { request, map };
+  return { request, map, projected: projected.pairs };
 }
 
 function rememberProxyItem(item, origin, state) {
@@ -508,8 +543,19 @@ function absorbGeneratedImage(item, state) {
   };
 }
 
+const USAGE_EVENTS = new Set(["response.completed", "response.incomplete"]);
+
 function rewriteResponseEvent(value, map, state) {
   if (!value || typeof value !== "object") return value;
+  if (
+    USAGE_EVENTS.has(value.type) &&
+    value.response &&
+    typeof value.response.usage === "object"
+  ) {
+    applyCacheUsage(value.response.usage);
+    const cache = readCacheUsage(value.response.usage);
+    if (cache) state.cacheUsage = cache;
+  }
   if (
     typeof value.item === "object" &&
     value.item &&
@@ -569,6 +615,13 @@ export function createSseRewriter(map, options = {}) {
     callIds: new Map(),
     itemIds: new Map(),
     imageOptions: options.imageOptions,
+    cacheUsage: null,
   };
-  return (block) => rewriteSseBlock(block, map, state);
+  const rewrite = (block) => rewriteSseBlock(block, map, state);
+  Object.defineProperty(rewrite, "cacheUsage", {
+    get() {
+      return state.cacheUsage;
+    },
+  });
+  return rewrite;
 }