codex-grok-bridge 1.0.3 → 1.0.5

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "codex-grok-bridge",
-  "version": "1.0.3",
+  "version": "1.0.5",
   "description": "Run Grok 4.6 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",
@@ -9,7 +9,8 @@
     "node": ">=22"
   },
   "os": [
-    "darwin"
+    "darwin",
+    "linux"
   ],
   "bin": {
     "codex-grok": "scripts/codex-grok.mjs"
@@ -38,6 +39,7 @@
     "scripts/launch-desktop.mjs",
     "Open Codex with Grok.command",
     "README.md",
+    "CHANGELOG.md",
     "LICENSE"
   ],
   "scripts": {

package/scripts/codex-grok.mjs

@@ -1,6 +1,7 @@
 #!/usr/bin/env node
 import { spawn } from "node:child_process";
 import { startRuntime } from "../src/runtime.mjs";
+import { resolveCodexBinary } from "../src/paths.mjs";
 const runtime = await startRuntime();
 const userArgs = process.argv.slice(2);
 const overrides = [
@@ -16,7 +17,7 @@ const args =
   userArgs[0] === "exec"
     ? [userArgs[0], ...overrides, ...userArgs.slice(1)]
     : [...overrides, ...userArgs];
-const child = spawn("/Applications/Codex.app/Contents/Resources/codex", args, {
+const child = spawn(resolveCodexBinary(), args, {
   stdio: "inherit",
   env: { ...process.env, CODEX_GROK_BRIDGE_TOKEN: runtime.token },
 });

package/scripts/codex-wrapper.mjs

@@ -4,8 +4,9 @@ import { createInterface } from "node:readline";
 import { randomUUID } from "node:crypto";
 import { startRuntime } from "../src/runtime.mjs";
 import { Router } from "../src/router.mjs";
+import { resolveCodexBinary } from "../src/paths.mjs";
 
-const binary = "/Applications/Codex.app/Contents/Resources/codex";
+const binary = resolveCodexBinary();
 const args = process.argv.slice(2);
 if (!args.includes("app-server")) {
   const child = spawn(binary, args, { stdio: "inherit" });

package/scripts/install-codex-grok-app.sh

@@ -1,14 +1,12 @@
 #!/bin/sh
-# Install or update the bridge inside /Applications/Codex Grok.app.
+# Install or update the dedicated Codex Grok desktop wrapper.
 #
-# Default is a JS-only sync: the bundle's scripts/ and src/ are brought in line
-# with this checkout, in place. The previous version began with `rm -rf` on the
-# directory that CODEX_CLI_PATH points into, which destroys a running app's
-# entrypoint; nothing here removes a directory, and stale files are pruned one
-# by one only when the repo no longer has them.
+# macOS: sync JS into /Applications/Codex Grok.app (must already exist).
+# Linux: create ~/.local/share/codex-grok-bridge/app and a user .desktop.
+# Never writes /Applications/Codex.app or /usr/lib/chatgpt.
 #
 #   install-codex-grok-app.sh            sync bridge JS (safe, fast)
-#   install-codex-grok-app.sh --full     also rebuild the launcher applet and sign
+#   install-codex-grok-app.sh --full     macOS: rebuild applet; Linux: rewrite launcher
 #   install-codex-grok-app.sh --force    proceed even if a Codex Grok window is open
 #
 # ESM is not hot-reloaded: an open Codex Grok window keeps running the code it
@@ -16,11 +14,20 @@
 set -eu
 
 ROOT="$(CDPATH= cd -- "$(dirname "$0")/.." && pwd)"
-# CODEX_GROK_APP exists so this script can be exercised against a scratch copy
-# instead of the installed app.
-APP="${CODEX_GROK_APP:-/Applications/Codex Grok.app}"
-BRIDGE="$APP/Contents/Resources/bridge"
 USER_DATA="$HOME/.local/share/codex-grok-bridge/desktop"
+PLATFORM="${CODEX_GROK_PLATFORM:-$(uname -s)}"
+case "$PLATFORM" in
+  Linux|linux) PLATFORM=linux ;;
+  Darwin|darwin) PLATFORM=darwin ;;
+esac
+
+if [ "$PLATFORM" = linux ]; then
+  APP="${CODEX_GROK_APP:-$HOME/.local/share/codex-grok-bridge/app}"
+  BRIDGE="$APP"
+else
+  APP="${CODEX_GROK_APP:-/Applications/Codex Grok.app}"
+  BRIDGE="$APP/Contents/Resources/bridge"
+fi
 
 FULL=0
 FORCE=0
@@ -33,7 +40,14 @@ for arg in "$@"; do
   esac
 done
 
-if [ ! -d "$APP/Contents" ]; then
+case "$APP" in
+  /usr/lib/chatgpt|/usr/lib/chatgpt/*|/usr/bin/chatgpt|/Applications/Codex.app|/Applications/Codex.app/*)
+    echo "refusing to install into the stock ChatGPT/Codex prefix: $APP" >&2
+    exit 1
+    ;;
+esac
+
+if [ "$PLATFORM" != linux ] && [ ! -d "$APP/Contents" ]; then
   echo "missing $APP" >&2
   exit 1
 fi
@@ -71,7 +85,44 @@ for dir in scripts src; do
 done
 [ "$status" -eq 0 ] || { echo "bundle did not match the checkout" >&2; exit 1; }
 
-if [ "$FULL" -eq 1 ]; then
+write_linux_wrapper() {
+  NODE="${NODE:-$(command -v node || true)}"
+  [ -n "$NODE" ] || { echo "no node on PATH; set NODE=/path/to/node" >&2; exit 1; }
+  if [ -L "$NODE" ]; then
+    NODE="$(python3 -c 'import os,sys; print(os.path.realpath(sys.argv[1]))' "$NODE")"
+  fi
+  mkdir -p "$APP/bin"
+  LAUNCHER="$APP/bin/codex-grok-desktop"
+  NODE_Q=$(printf "%s" "$NODE" | sed "s/'/'\\\\''/g")
+  cat > "$LAUNCHER" <<EOF
+#!/bin/sh
+set -eu
+ROOT="\$(CDPATH= cd -- "\$(dirname "\$0")/.." && pwd)"
+exec '$NODE_Q' "\$ROOT/scripts/launch-desktop.mjs" "\$@"
+EOF
+  chmod +x "$LAUNCHER"
+  APPS_DIR="${XDG_DATA_HOME:-$HOME/.local/share}/applications"
+  mkdir -p "$APPS_DIR"
+  DESKTOP="$APPS_DIR/codex-grok.desktop"
+  cat > "$DESKTOP" <<EOF
+[Desktop Entry]
+Type=Application
+Name=Codex Grok
+Comment=Codex desktop with Grok via the local bridge
+Exec="$LAUNCHER" %U
+Icon=chatgpt
+Terminal=false
+Categories=Development;
+StartupWMClass=ChatGPT
+EOF
+  update-desktop-database "$APPS_DIR" >/dev/null 2>&1 || true
+  echo "linux wrapper $LAUNCHER"
+  echo "desktop entry $DESKTOP"
+}
+
+if [ "$PLATFORM" = linux ]; then
+  write_linux_wrapper
+elif [ "$FULL" -eq 1 ]; then
   NODE="${NODE:-$(command -v node || true)}"
   [ -n "$NODE" ] || { echo "no node on PATH; set NODE=/path/to/node" >&2; exit 1; }
   if [ -L "$NODE" ]; then

package/scripts/launch-desktop.mjs

@@ -1,11 +1,19 @@
 import { execFileSync, spawn } from "node:child_process";
 import { appendFileSync, mkdirSync } from "node:fs";
-import { homedir } from "node:os";
 import path from "node:path";
 import { fileURLToPath } from "node:url";
+import {
+  desktopLaunchArgs,
+  desktopLaunchEnv,
+  desktopUserDataDir,
+  isGrokDesktopProcess,
+  resolveDesktopApp,
+  resolvePlatform,
+} from "../src/paths.mjs";
 
-const userData = path.join(homedir(), ".local/share/codex-grok-bridge/desktop");
-const logFile = path.join(homedir(), ".local/share/codex-grok-bridge/launch.log");
+const platform = resolvePlatform();
+const userData = desktopUserDataDir();
+const logFile = path.join(userData, "..", "launch.log");
 mkdirSync(userData, { recursive: true, mode: 0o700 });
 mkdirSync(path.dirname(logFile), { recursive: true, mode: 0o700 });
 
@@ -18,12 +26,7 @@ function grokPid() {
     encoding: "utf8",
   });
   for (const line of out.split("\n")) {
-    if (
-      line.includes(`--user-data-dir=${userData}`) &&
-      /MacOS\/(ChatGPT|Codex)(\s|$)/.test(line) &&
-      !line.includes("Helper") &&
-      !line.includes("crashpad")
-    )
+    if (isGrokDesktopProcess(line, userData))
       return Number(line.trim().split(/\s+/)[0]);
   }
   return null;
@@ -41,6 +44,7 @@ function activate(pid) {
 }
 
 function notify(text) {
+  if (platform !== "darwin") return;
   try {
     execFileSync("/usr/bin/osascript", [
       "-e",
@@ -49,19 +53,28 @@ function notify(text) {
   } catch {}
 }
 
-const wrapper = fileURLToPath(new URL("./codex-wrapper.mjs", import.meta.url));
-try {
-  const running = grokPid();
-  if (running) {
-    log(`activate pid=${running}`);
-    try {
-      activate(running);
-      notify("Codex Grok 창을 앞으로 가져왔습니다.");
-      process.exit(0);
-    } catch (error) {
-      log(`activate failed: ${error.message}`);
-    }
-  }
+function startLinux(wrapper) {
+  const app = resolveDesktopApp();
+  const pathPrefix = `${path.dirname(process.execPath)}:/usr/local/bin:/usr/bin:/bin`;
+  log(`start linux app=${app} wrapper=${wrapper}`);
+  const child = spawn(app, desktopLaunchArgs(userData), {
+    stdio: "inherit",
+    env: {
+      ...process.env,
+      ...desktopLaunchEnv({ wrapper, userData, pathPrefix }),
+    },
+  });
+  child.on("error", (error) => {
+    log(`spawn failed: ${error.message}`);
+    process.exit(1);
+  });
+  child.on("exit", (code) => {
+    log(`chatgpt exit=${code}`);
+    process.exit(code ?? 1);
+  });
+}
+
+function startDarwin(wrapper) {
   log(`start wrapper=${wrapper}`);
   const child = spawn(
     "/usr/bin/open",
@@ -95,6 +108,26 @@ try {
     }
     process.exit(code ?? 1);
   });
+}
+
+const wrapper = fileURLToPath(new URL("./codex-wrapper.mjs", import.meta.url));
+try {
+  const running = grokPid();
+  if (running) {
+    log(`activate pid=${running}`);
+    if (platform !== "darwin") {
+      process.exit(0);
+    }
+    try {
+      activate(running);
+      notify("Codex Grok 창을 앞으로 가져왔습니다.");
+      process.exit(0);
+    } catch (error) {
+      log(`activate failed: ${error.message}`);
+    }
+  }
+  if (platform === "linux") startLinux(wrapper);
+  else startDarwin(wrapper);
 } catch (error) {
   log(`fatal: ${error.message}`);
   notify(error.message);

package/src/paths.mjs

@@ -0,0 +1,94 @@
+import path from "node:path";
+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_BINARY = "/Applications/Codex.app/Contents/Resources/codex";
+export const DARWIN_CODEX_APP = "/Applications/Codex.app";
+export const LINUX_STOCK_PREFIX = "/usr/lib/chatgpt";
+
+export function resolvePlatform(options = {}) {
+  const env = options.env ?? process.env;
+  return options.platform ?? env.CODEX_GROK_PLATFORM ?? process.platform;
+}
+
+export function resolveCodexBinary(options = {}) {
+  const env = options.env ?? process.env;
+  if (env.CODEX_BINARY) return env.CODEX_BINARY;
+  return resolvePlatform({ ...options, env }) === "linux"
+    ? LINUX_CODEX_BINARY
+    : DARWIN_CODEX_BINARY;
+}
+
+export function resolveDesktopApp(options = {}) {
+  const env = options.env ?? process.env;
+  if (env.CODEX_DESKTOP_APP) return env.CODEX_DESKTOP_APP;
+  return resolvePlatform({ ...options, env }) === "linux"
+    ? LINUX_CHATGPT_BIN
+    : DARWIN_CODEX_APP;
+}
+
+export function desktopUserDataDir(home = homedir()) {
+  return path.join(home, ".local/share/codex-grok-bridge/desktop");
+}
+
+export function linuxAppDir(home = homedir()) {
+  return path.join(home, ".local/share/codex-grok-bridge/app");
+}
+
+export function linuxDesktopEntryPath(home = homedir(), xdgDataHome) {
+  const dataHome = xdgDataHome || path.join(home, ".local/share");
+  return path.join(dataHome, "applications", "codex-grok.desktop");
+}
+
+export function desktopLaunchEnv({ wrapper, userData, pathPrefix }) {
+  const env = {
+    CODEX_CLI_PATH: wrapper,
+    CODEX_APP_SERVER_FORCE_CLI: "1",
+    CODEX_ELECTRON_USER_DATA_PATH: userData,
+  };
+  if (pathPrefix) env.PATH = pathPrefix;
+  return env;
+}
+
+export function desktopLaunchArgs(userData) {
+  return [`--user-data-dir=${userData}`];
+}
+
+export function isGrokDesktopProcess(line, userData, options = {}) {
+  if (!line.includes(`--user-data-dir=${userData}`)) return false;
+  if (line.includes("Helper") || line.includes("crashpad")) return false;
+  const app = resolveDesktopApp(options);
+  if (line.includes(app)) return true;
+  return resolvePlatform(options) === "linux"
+    ? line.includes(LINUX_CHATGPT_BIN)
+    : /MacOS\/(ChatGPT|Codex)(\s|$)/.test(line);
+}
+
+export function isForbiddenInstallDir(app) {
+  const resolved = path.resolve(app);
+  const forbidden = [
+    LINUX_STOCK_PREFIX,
+    "/usr/bin/chatgpt",
+    "/usr/share/applications/chatgpt.desktop",
+    DARWIN_CODEX_APP,
+  ];
+  return forbidden.some(
+    (prefix) => resolved === prefix || resolved.startsWith(`${prefix}/`),
+  );
+}
+
+export function linuxDesktopEntry({ exec, icon = "chatgpt" }) {
+  return [
+    "[Desktop Entry]",
+    "Type=Application",
+    "Name=Codex Grok",
+    "Comment=Codex desktop with Grok via the local bridge",
+    `Exec=${exec}`,
+    `Icon=${icon}`,
+    "Terminal=false",
+    "Categories=Development;",
+    "StartupWMClass=ChatGPT",
+    "",
+  ].join("\n");
+}

package/src/tools.mjs

@@ -56,16 +56,145 @@ const GROK_INPUT_ITEM_TYPES = new Set([
   "function_call_output",
   "shell_call",
 ]);
+// Codex item ids, status, and new client metadata have 422'd the upstream.
+// Keep only the fields Grok's Responses input is known to accept.
+const INPUT_ITEM_FIELDS = {
+  message: ["type", "role", "content"],
+  reasoning: ["type", "summary"],
+  function_call: ["type", "name", "call_id", "arguments"],
+  function_call_output: ["type", "name", "call_id", "output"],
+  shell_call: ["type", "name", "call_id", "action"],
+};
+const CONTENT_PART_FIELDS = {
+  input_text: ["type", "text"],
+  output_text: ["type", "text"],
+  summary_text: ["type", "text"],
+  input_image: ["type", "image_url", "detail"],
+};
+
+function pickKeys(node, keys) {
+  const next = {};
+  for (const key of keys) {
+    if (node[key] !== undefined) next[key] = node[key];
+  }
+  return next;
+}
+
+function whitelistContentPart(part) {
+  if (!part || typeof part !== "object" || Array.isArray(part)) return part;
+  const keys = CONTENT_PART_FIELDS[part.type];
+  if (!keys) return part;
+  const next = pickKeys(part, keys);
+  if (next.image_url && typeof next.image_url === "object")
+    next.image_url = pickKeys(next.image_url, ["url", "detail"]);
+  return next;
+}
+
+function whitelistInputNode(node) {
+  if (!node || typeof node !== "object" || Array.isArray(node)) return node;
+  const itemKeys = INPUT_ITEM_FIELDS[node.type];
+  if (itemKeys) {
+    const next = pickKeys(node, itemKeys);
+    if (Array.isArray(next.content))
+      next.content = next.content.map(whitelistContentPart);
+    return next;
+  }
+  if (node.type == null && node.role != null && node.content !== undefined) {
+    const next = pickKeys(node, ["role", "content"]);
+    if (Array.isArray(next.content))
+      next.content = next.content.map(whitelistContentPart);
+    return next;
+  }
+  return whitelistContentPart(node);
+}
+
+function isObjectFragment(schema) {
+  return (
+    schema &&
+    typeof schema === "object" &&
+    !Array.isArray(schema) &&
+    (schema.type === "object" || schema.type == null)
+  );
+}
+
+function mergeObjectFragments(fragments) {
+  const properties = {};
+  let required;
+  for (const fragment of fragments) {
+    if (fragment.properties && typeof fragment.properties === "object")
+      Object.assign(properties, fragment.properties);
+    if (Array.isArray(fragment.required)) {
+      required =
+        required === undefined
+          ? fragment.required.slice()
+          : required.filter((key) => fragment.required.includes(key));
+    }
+  }
+  return { properties, required };
+}
+
+function emitObjectParameters(source, overrides = {}) {
+  const properties =
+    overrides.properties ??
+    (source.properties && typeof source.properties === "object"
+      ? source.properties
+      : {});
+  const required =
+    overrides.required !== undefined
+      ? overrides.required
+      : Array.isArray(source.required)
+        ? source.required
+        : undefined;
+  const next = { type: "object", properties: { ...properties } };
+  if (required?.length) next.required = required.slice();
+  if (source.additionalProperties !== undefined)
+    next.additionalProperties = source.additionalProperties;
+  if (source.description !== undefined) next.description = source.description;
+  return next;
+}
 
 function usableParameters(parameters) {
-  if (!parameters || typeof parameters !== "object") return OBJECT_SCHEMA;
-  if (
-    parameters.type === "object" ||
-    Array.isArray(parameters.oneOf) ||
-    Array.isArray(parameters.anyOf)
-  )
-    return parameters;
-  return OBJECT_SCHEMA;
+  if (!parameters || typeof parameters !== "object" || Array.isArray(parameters))
+    return OBJECT_SCHEMA;
+  const variants = Array.isArray(parameters.oneOf)
+    ? parameters.oneOf
+    : Array.isArray(parameters.anyOf)
+      ? parameters.anyOf
+      : null;
+  if (!variants) {
+    return parameters.type === "object"
+      ? emitObjectParameters(parameters)
+      : OBJECT_SCHEMA;
+  }
+  const fragments = variants.filter(isObjectFragment);
+  if (fragments.length === 0) {
+    return parameters.type === "object"
+      ? emitObjectParameters(parameters)
+      : OBJECT_SCHEMA;
+  }
+  const merged = mergeObjectFragments(fragments);
+  const properties = {
+    ...(parameters.properties && typeof parameters.properties === "object"
+      ? parameters.properties
+      : {}),
+    ...merged.properties,
+  };
+  let required = merged.required;
+  if (Array.isArray(parameters.required)) {
+    required =
+      required === undefined
+        ? parameters.required.slice()
+        : required.filter((key) => parameters.required.includes(key));
+  }
+  const first = fragments[0];
+  return emitObjectParameters(
+    {
+      additionalProperties:
+        parameters.additionalProperties ?? first.additionalProperties,
+      description: parameters.description ?? first.description,
+    },
+    { properties, required },
+  );
 }
 
 function sanitize(name) {
@@ -189,7 +318,7 @@ function toProxyInputNode(node, map, state) {
     if (
       key === "encrypted_content" ||
       key === "encrypted_function_args" ||
-      key === "internal_chat_message_metadata_passthrough"
+      key.startsWith("internal_")
     )
       continue;
     const converted = toProxyInputNode(value, map, state);
@@ -204,7 +333,7 @@ function toProxyInputNode(node, map, state) {
       (part) => part && typeof part.text === "string" && part.text.trim(),
     );
     if (!summary.length) return DROP;
-    return { type: "reasoning", summary };
+    return whitelistInputNode({ type: "reasoning", summary });
   }
 
   if (next.type === "agent_message") {
@@ -214,7 +343,7 @@ function toProxyInputNode(node, map, state) {
         ? [{ type: "input_text", text: next.text }]
         : [];
     if (!content.length) return DROP;
-    return { type: "message", role: "assistant", content };
+    return whitelistInputNode({ type: "message", role: "assistant", content });
   }
 
   if (
@@ -227,10 +356,7 @@ function toProxyInputNode(node, map, state) {
       delete next.namespace;
       if (typeof next.call_id === "string") state.callIds.set(next.call_id, proxyName);
     }
-    return next;
-  }
-
-  if (
+  } else if (
     next.type === "custom_tool_call" &&
     typeof next.name === "string"
   ) {
@@ -244,10 +370,7 @@ function toProxyInputNode(node, map, state) {
       delete next.input;
       if (typeof next.call_id === "string") state.callIds.set(next.call_id, proxyName);
     }
-    return next;
-  }
-
-  if (
+  } else if (
     next.type === "function_call_output" ||
     next.type === "custom_tool_call_output"
   ) {
@@ -262,10 +385,9 @@ function toProxyInputNode(node, map, state) {
       next.name = proxyName;
       delete next.namespace;
     }
-    return next;
   }
 
-  return next;
+  return whitelistInputNode(next);
 }
 
 function toProxyInput(input, map) {