codex-grok-bridge 1.0.4 → 1.0.5

package/CHANGELOG.md

@@ -0,0 +1,32 @@
+# Changelog
+
+## 1.0.5 — 2026-09-12
+
+First npm cut that accepts **Linux** (`"os": ["darwin", "linux"]`). Windows stays rejected.
+
+- Input field allowlist for Grok Responses (`#10`) — drops `internal_*` and other fields Grok rejects.
+- Collapse `anyOf` / `oneOf` tool-parameter roots to a plain object (`#12`) — unblocks Linux GUI `invalid_client_tool_schema` 400s.
+- Linux desktop wrapper (`#11`) — `~/.local/share/codex-grok-bridge/app` plus a user `.desktop` file. Does not patch `/usr/lib/chatgpt`.
+- Docs: test gate **150/150**, coverage 97.30 / 87.70 / 90.57, Grok CLI verified **1.0.25**.
+
+Install: `npm install -g codex-grok-bridge@1.0.5`
+
+## 1.0.4 — 2026-09-09
+
+English and Korean README aligned. macOS-only npm package.
+
+## 1.0.3 — 2026-09-09
+
+See GitHub release `v1.0.3`.
+
+## 1.0.2 — 2026-09-09
+
+See GitHub release `v1.0.2`.
+
+## 1.0.1 — 2026-09-09
+
+See GitHub release `v1.0.1`.
+
+## 1.0.0 — 2026-09-09
+
+Initial publish. macOS only.

package/README.md

@@ -4,10 +4,6 @@ Run **Grok 4.6 as the model inside Codex**. Codex still owns tools, permissions,
 history and MCP. Inference uses the installed `grok` CLI login session — not an
 xAI API key.
 
-Codex 안에서 **Grok 4.6**을 모델로 씁니다. 도구·권한·히스토리·MCP는 Codex가
-그대로 가집니다. 추론은 설치된 `grok` CLI의 로그인 세션으로 하며 `XAI_API_KEY`는
-쓰지 않습니다.
-
 ```
 Codex UI/CLI → app-server → scripts/codex-wrapper.mjs (adds grok-4.6 to the model list)
              → localhost /v1/responses (the bridge)
@@ -15,16 +11,13 @@ Codex UI/CLI → app-server → scripts/codex-wrapper.mjs (adds grok-4.6 to the
              → Codex executes every tool call; results return as the next input
 ```
 
-The published package is **macOS-only** (`"os": ["darwin"]`). Linux and Windows
-installs are rejected by npm.
+The published npm package installs on **macOS and Linux** (`"os": ["darwin",
+"linux"]`). Windows installs are rejected by npm. The official ChatGPT/Codex
+`.deb` stays untouched; `scripts/install-codex-grok-app.sh` writes a separate
+wrapper.
 
-게시된 패키지는 **macOS 전용**입니다(`"os": ["darwin"]`). Linux·Windows는 npm이
-설치를 거절합니다.
 
 ---
-
-# English
-
 ## What this is
 
 A local bridge that puts Grok 4.6 on Codex’s model list and sends Codex
@@ -44,9 +37,9 @@ that tool the same way it calls any other Codex tool.
 
 ## Requirements
 
-- macOS
+- macOS, or Linux with the official ChatGPT/Codex desktop package
 - Node.js ≥ 22
-- `/Applications/Codex.app`
+- `/Applications/Codex.app` (macOS) or `/usr/lib/chatgpt/ChatGPT` (Linux)
 - `grok` CLI at `~/.grok/bin/grok`
 - a completed `grok login`
 
@@ -54,7 +47,7 @@ The `.command` launcher resolves paths from its own location, so moving the
 folder does not require edits. Set `NODE=/path/to/node` if `node` is not on
 `PATH`.
 
-Verified against: Codex 0.153.4 / app 26.901.51231, Grok CLI 1.0.24, Node 22.23.0.
+Verified against: Codex 0.153.4 / app 26.901.51231, Grok CLI 1.0.25, Node 22.23.0.
 An app update that changes `CODEX_CLI_PATH` or the app-server protocol needs
 re-verification.
 
@@ -63,7 +56,7 @@ re-verification.
 ### Terminal (npm)
 
 ```sh
-npm install -g codex-grok-bridge   # macOS, Node ≥ 22
+npm install -g codex-grok-bridge   # macOS or Linux, Node ≥ 22
 codex-grok                         # launches Codex with Grok 4.6 available
 codex-grok exec --skip-git-repo-check --sandbox workspace-write 'your task'
 ```
@@ -76,15 +69,17 @@ starts, and tears the provider down with that process.
 ```sh
 git clone https://github.com/deximple/codex-grok-bridge.git
 cd codex-grok-bridge
-npm test                        # 132 tests, no network, no inference
+npm test                        # 150 tests, no network, no inference
 node scripts/codex-grok.mjs
 ```
 
 ### Desktop
 
 Double-click **Open Codex with Grok.command** in this folder, or keep a
-**separate** `Codex Grok.app` in sync with
+**separate** desktop wrapper in sync with
 `scripts/install-codex-grok-app.sh` (see [Desktop install and update](#desktop-install-and-update)).
+On Linux that wrapper is `~/.local/share/codex-grok-bridge/app` plus a user
+`.desktop` entry; the stock `/usr/lib/chatgpt` tree is not patched.
 
 In the new Codex window, **select Grok 4.6 / xAI before starting a new
 thread**. Existing GPT models stay on the list. A Codex window that was already
@@ -95,9 +90,9 @@ The dedicated window stores UI data under
 for account, threads and settings. Work and setting changes can show up in other
 Codex windows.
 
-The installer never writes the stock Codex.app bundle, its signature,
-`~/.codex/config.toml`, or Grok auth files. It does not register a launch
-agent or a global environment variable.
+The installer never writes the stock Codex.app bundle, `/usr/lib/chatgpt`,
+their signatures, `~/.codex/config.toml`, or Grok auth files. It does not
+register a launch agent or a global environment variable.
 
 Stop by closing the Codex window this extension opened. Ordinary Codex still
 launches from its usual icon.
@@ -163,7 +158,10 @@ not read Codex’s `imagegen` skill and do not send the picture to OpenAI.
 Plain-text summaries on Codex `reasoning` items are forwarded. Encrypted
 `encrypted_content` and Codex’s own item ids are stripped. This is so a
 multi-call turn can continue its own reasoning. The upstream has been observed
-to accept this shape.
+to accept this shape. The same pass keeps only the fields Grok’s Responses
+input accepts on each item and content part — `status`, unknown Codex keys,
+and every `internal_*` field are dropped so a new client field cannot 422 the
+upstream.
 
 ### Concurrency
 
@@ -280,12 +278,12 @@ Start here when something breaks. Do not open `~/.grok/auth.json` or
 | `GROK_BRIDGE_INFERENCE=cli` | Fall back to the CLI envelope path |
 | `GROK_BRIDGE_DIAGNOSTICS=off` | Do not write the JSONL log |
 | `NODE` | Absolute `node` binary for the `.command` launcher / desktop scripts |
-| `CODEX_GROK_APP` | Alternate app bundle path for `install-codex-grok-app.sh` (default `/Applications/Codex Grok.app`) |
+| `CODEX_GROK_APP` | Alternate app path for `install-codex-grok-app.sh` (macOS: `/Applications/Codex Grok.app`; Linux: `~/.local/share/codex-grok-bridge/app`) |
 
 ## Verify
 
 ```sh
-npm test                    # 132 tests, no remote inference
+npm test                    # 150 tests, no remote inference
 npm run test:coverage       # 80% line / branch / function gate
 npm run verify:app-server   # real app-server routing; also runs against an installed bundle
 npm audit --omit=dev
@@ -299,7 +297,7 @@ inference. A live CLI check spends the user’s quota.
 
 ```sh
 sh scripts/install-codex-grok-app.sh          # sync bridge JS only (default)
-sh scripts/install-codex-grok-app.sh --full   # also rebuild and sign the launcher applet
+sh scripts/install-codex-grok-app.sh --full   # macOS: rebuild and sign the launcher applet
 ```
 
 The default copies this checkout’s `src/` and `scripts/*.mjs` into the bundle,
@@ -308,8 +306,11 @@ never `rm -rf`s the live bundle. It refuses while a Codex Grok window is open
 (`--force` to override). ESM is not hot-reloaded: **reopen the window** after a
 sync.
 
-The script updates an existing `Codex Grok.app`. It does not create one, and it
-does not touch `/Applications/Codex.app`.
+On macOS the script updates an existing `Codex Grok.app`. It does not create
+one, and it does not touch `/Applications/Codex.app`. On Linux it creates
+`~/.local/share/codex-grok-bridge/app` and
+`~/.local/share/applications/codex-grok.desktop`, and it does not write
+`/usr/lib/chatgpt` or `/usr/share/applications/chatgpt.desktop`.
 
 ## Security notes
 
@@ -355,16 +356,16 @@ calling으로 옮기고, 상류 Responses 스트림을 전달한 뒤, Codex가
 
 ## 필요한 것
 
-- macOS
+- macOS, 또는 공식 ChatGPT/Codex 데스크톱 패키지가 있는 Linux
 - Node.js 22 이상
-- `/Applications/Codex.app`
+- `/Applications/Codex.app` (macOS) 또는 `/usr/lib/chatgpt/ChatGPT` (Linux)
 - `~/.grok/bin/grok`
 - 완료된 `grok login`
 
 `.command` 런처는 자기 위치를 기준으로 경로를 잡으므로 폴더를 옮겨도 수정할
 필요가 없습니다. `PATH`에 `node`가 없으면 `NODE=/path/to/node`로 지정합니다.
 
-검증 버전: Codex 0.153.4 / 앱 26.901.51231, Grok CLI 1.0.24, Node 22.23.0.
+검증 버전: Codex 0.153.4 / 앱 26.901.51231, Grok CLI 1.0.25, Node 22.23.0.
 앱 업데이트가 `CODEX_CLI_PATH`나 app-server 프로토콜을 바꾸면 재검증이
 필요합니다.
 
@@ -373,7 +374,7 @@ calling으로 옮기고, 상류 Responses 스트림을 전달한 뒤, Codex가
 ### 터미널 (npm)
 
 ```sh
-npm install -g codex-grok-bridge   # macOS, Node ≥ 22
+npm install -g codex-grok-bridge   # macOS or Linux, Node ≥ 22
 codex-grok                         # Grok 4.6이 있는 Codex를 띄움
 codex-grok exec --skip-git-repo-check --sandbox workspace-write '작업 내용'
 ```
@@ -386,15 +387,17 @@ codex-grok exec --skip-git-repo-check --sandbox workspace-write '작업 내용'
 ```sh
 git clone https://github.com/deximple/codex-grok-bridge.git
 cd codex-grok-bridge
-npm test                        # 132건, 네트워크·추론 없음
+npm test                        # 150건, 네트워크·추론 없음
 node scripts/codex-grok.mjs
 ```
 
 ### 데스크톱
 
 이 폴더의 **Open Codex with Grok.command**를 더블 클릭하거나,
-`scripts/install-codex-grok-app.sh`로 **별도의** `Codex Grok.app`을 체크아웃과
+`scripts/install-codex-grok-app.sh`로 **별도의** 데스크톱 래퍼를 체크아웃과
 맞춥니다([데스크톱 설치와 갱신](#데스크톱-설치와-갱신)).
+Linux에서는 `~/.local/share/codex-grok-bridge/app`과 사용자 `.desktop`이고,
+정품 `/usr/lib/chatgpt`는 패치하지 않습니다.
 
 새로 열린 Codex 창에서 **새 작업을 시작하기 전에 Grok 4.6 / xAI를 선택**하세요.
 기존 GPT 모델도 목록에 남습니다. 이미 열려 있던 일반 Codex 창에는 이 확장이
@@ -404,9 +407,9 @@ node scripts/codex-grok.mjs
 계정·작업·설정은 기존 Codex 홈을 **공유**합니다. 작업 내용과 설정 변경은 다른
 Codex 창에도 보일 수 있습니다.
 
-설치 스크립트는 정품 Codex.app 번들, 코드 서명, `~/.codex/config.toml`, Grok
-인증 파일을 수정하지 않습니다. 자동 시작 서비스나 전역 환경변수도 등록하지
-않습니다.
+설치 스크립트는 정품 Codex.app 번들, `/usr/lib/chatgpt`, 코드 서명,
+`~/.codex/config.toml`, Grok 인증 파일을 수정하지 않습니다. 자동 시작
+서비스나 전역 환경변수도 등록하지 않습니다.
 
 중지하려면 이 확장으로 연 Codex 창을 닫으면 됩니다. 일반 Codex는 기존 아이콘으로
 실행합니다.
@@ -468,7 +471,9 @@ OpenAI로 보내지 말라는 뜻입니다. `GROK_BRIDGE_IMAGE_GEN=off`면 도
 Codex `reasoning` 항목의 평문 요약은 상류로 전달합니다. 암호화된
 `encrypted_content`와 Codex 자체 아이템 id는 제거합니다. 여러 번 호출이 이어지는
 턴에서 모델이 자기 추론을 이어받게 하기 위한 것이며, 상류가 이 형태를 수락하는
-것을 확인했습니다.
+것을 확인했습니다. 같은 과정에서 아이템과 content part는 Grok Responses가
+받는 필드만 남깁니다. `status`, 알 수 없는 Codex 키, `internal_*` 필드는
+버려서 새 클라이언트 필드가 상류 422를 내지 않게 합니다.
 
 ### 동시성
 
@@ -580,12 +585,12 @@ provider에 Codex `request_max_retries` / `stream_max_retries`를 2로 두어
 | `GROK_BRIDGE_INFERENCE=cli` | CLI 봉투 경로로 폴백 |
 | `GROK_BRIDGE_DIAGNOSTICS=off` | JSONL 로그를 쓰지 않음 |
 | `NODE` | `.command` / 데스크톱 스크립트가 쓸 `node` 절대 경로 |
-| `CODEX_GROK_APP` | `install-codex-grok-app.sh`가 쓸 앱 번들 경로 (기본 `/Applications/Codex Grok.app`) |
+| `CODEX_GROK_APP` | `install-codex-grok-app.sh`가 쓸 앱 경로 (macOS: `/Applications/Codex Grok.app`; Linux: `~/.local/share/codex-grok-bridge/app`) |
 
 ## 검증
 
 ```sh
-npm test                    # 132건, 외부 추론 없음
+npm test                    # 150건, 외부 추론 없음
 npm run test:coverage       # line/branch/function 80% 게이트
 npm run verify:app-server   # 실제 app-server 라우팅. 설치된 앱 번들에서도 실행
 npm audit --omit=dev
@@ -599,7 +604,7 @@ CLI 검증은 사용자 계정 사용량을 씁니다.
 
 ```sh
 sh scripts/install-codex-grok-app.sh          # 브리지 JS만 동기화 (기본)
-sh scripts/install-codex-grok-app.sh --full   # 런처 applet 재빌드 + 서명
+sh scripts/install-codex-grok-app.sh --full   # macOS: 런처 applet 재빌드 + 서명
 ```
 
 기본 동작은 이 체크아웃의 `src/`와 `scripts/*.mjs`를 번들에 복사하고, 저장소에
@@ -607,8 +612,10 @@ sh scripts/install-codex-grok-app.sh --full   # 런처 applet 재빌드 + 서명
 `rm -rf`하지 않습니다. Codex Grok 창이 열려 있으면 거부합니다(`--force`로
 무시). ESM은 핫리로드되지 않으므로 **동기화 후 창을 다시 열어야** 합니다.
 
-이 스크립트는 이미 있는 `Codex Grok.app`을 갱신합니다. 번들을 새로 만들지
-않고, `/Applications/Codex.app`은 건드리지 않습니다.
+macOS에서는 이미 있는 `Codex Grok.app`을 갱신하며 `/Applications/Codex.app`은
+건드리지 않습니다. Linux에서는 `~/.local/share/codex-grok-bridge/app`과
+`~/.local/share/applications/codex-grok.desktop`을 만들고 `/usr/lib/chatgpt`와
+정품 `chatgpt.desktop`은 쓰지 않습니다.
 
 ## 보안
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "codex-grok-bridge",
-  "version": "1.0.4",
+  "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) {