Skip to content

RFC: migrate Codex ACP adapter to agentclientprotocol/codex-acp #1352

Closed
#1353
Closed
RFC: migrate Codex ACP adapter to agentclientprotocol/codex-acp#1352
#1353
Labels
incompleteneeds-triage

Description

@vixenclawsastraagent
vixenclawsastraagent
opened on Jul 11, 2026

Proposal

建議評估將 OpenAB 的 Codex ACP integration，從 @zed-industries/codex-acp 遷移至 @agentclientprotocol/codex-acp。在確認相容性前，先以 canary image 驗證，並保留舊 image 作為 rollback 路徑，不直接切換正式 agent。

Discord 討論：

https://discord.com/channels/1491295327620169908/1525352558829371483

Implementation PR：

背景與問題

截至以下 OpenAB 版本，Codex image 仍安裝 Zed adapter：

目前 image 固定安裝：

@zed-industries/codex-acp@0.16.0
@openai/codex@0.141.0

已驗證的行為

[verified] 在同一個執行環境中，直接使用新版 Codex CLI 可以執行：

codex exec -m gpt-5.6-sol ...

但經由 OpenAB 的 Codex ACP agent path 執行相同模型時會失敗：

The 'gpt-5.6-sol' model requires a newer version of Codex.
Please upgrade to the latest app or CLI and try again.

同時可觀察到 models cache 的 client_version 是 0.137.0。

[verified] @zed-industries/codex-acp@0.16.0 的 lockfile 使用 Codex core 0.137.0：

因此，單獨升級 image 內全域安裝的 Codex CLI，不會更新實際處理 ACP turn 的 Zed adapter runtime。

建議的 migration target

建議先測試：

@agentclientprotocol/codex-acp@1.1.2

新版 adapter：

  • 同樣提供 codex-acp binary name。
  • 依賴 @openai/codex ^0.144.0；implementation PR 另外將可執行版本固定為 0.144.1。
  • 啟動 codex app-server，再將 ACP request 轉成 Codex operation。
  • 支援以 CODEX_PATH 明確指定 Codex executable。

來源：

Zed maintainer 已說明，同時長期維護兩套 adapter 並不可持續；缺少的功能應優先補到 agentclientprotocol/codex-acp，而不是繼續擴充舊 implementation。

相容性評估

目前判斷：核心 ACP wire contract 看起來相容，但 package replacement 仍有中等程度的行為與設定相容風險，不應先視為零風險的 drop-in replacement。

預期可相容的 ACP methods

新版仍提供 OpenAB 目前使用的核心 methods：

  • initialize
  • session/new
  • session/load
  • session/set_config_option
  • session/prompt
  • session/cancel

參考：

已識別的 migration risks

1. Mode ID 已改名

舊 adapter：

read-only
auto
full-access

新版 adapter：

read-only
agent
agent-full-access

來源：

既有部署、持久化 session 或 [pool].default_config_options 若使用舊值，migration 後可能失效。需要決定是否提供相容 alias 或轉換：

auto        -> agent
full-access -> agent-full-access

2. Sandbox 與 approval 預設可能改變

[assumed] 新 adapter 的預設 agent mode 不一定等同於舊 adapter 從既有 Codex config 推導出的權限狀態。若部署依賴 full access，可能需要明確設定 INITIAL_AGENT_MODE=agent-full-access。

OpenAB 會處理 session/request_permission，但自動選擇 permission option 不代表 filesystem、writable roots 與 network policy 一定維持不變：

3. Image 可能同時存在兩個 Codex version

新版 adapter 帶有相容的 @openai/codex dependency，但 OpenAB image 目前另外全域安裝 Codex CLI。若未明確決定版本來源：

  • codex login 可能使用 global CLI。
  • ACP adapter 預設可能使用 package dependency。
  • 設定 CODEX_PATH 後又可能指回較舊的 global CLI。

Canary 必須確認實際啟動的 executable 與 client version。若使用 CODEX_PATH，它必須來自 image 中明確安裝且經過驗證的 Codex binary；否則應讓 adapter 使用自己的 dependency，避免模糊的 resolution path。

4. OpenAB 的 clientInfo 需要實測

OpenAB initialize 目前固定傳送：

{"name":"openab","version":"0.1.0"}

[assumed] 因這次錯誤涉及 client/version gate，canary 必須確認 openab/0.1.0 不會觸發另一層 server-side gating。若會，OpenAB 應改用實際 app version，而不是持續硬編碼 0.1.0。

5. Error payload 可能不同

OpenAB 優先讀取 JSON-RPC error.data.message，但程式碼也註明這是 adapter 慣例，不是 ACP 規格要求：

[assumed] 新 adapter 的 error shape 可能造成使用者看到的錯誤細節退化，因此需要 regression coverage。

建議實作與 rollout

  1. WHEN OpenAB 建置 Codex canary image，DO 將 package source 固定為已驗證版本的 @agentclientprotocol/codex-acp，並明確決定 Codex executable 的唯一來源；THEN image build log 與 runtime version inspection 必須能指出實際 adapter 和 Codex client version，否則停止 rollout。
  2. WHEN 既有 config 或 session 使用 auto／full-access，DO 套用相容 alias、migration mapping，或在驗證失敗時明確拒絕並顯示可操作的錯誤；THEN 不得無聲降級到不同的 sandbox mode。
  3. WHEN canary 收到 ACP turn，DO 依序驗證 initialize、session lifecycle、model selection、prompt、tool、permission、cancel 與 error propagation；THEN 只有全部 acceptance criteria 通過後，才提議切換正式 image。
  4. WHEN canary 發生 protocol、authentication、permission 或 model regression，DO 將部署切回保留的 Zed image tag；THEN 同一個 session path 應恢復到 migration 前的已知行為，並記錄 rollback 結果。

Implementation progress（2026-07-11）

  • [verified] PR feat(codex)!: migrate ACP adapter #1353 已在三條 Codex image build path 改用 @agentclientprotocol/codex-acp@1.1.2 與 @openai/codex@0.144.1。
  • [verified] 同一個 npm transaction 會將 adapter 的 @openai/codex ^0.144.0 dependency dedupe 至固定的 0.144.1；global CLI 仍供 codex login --device-auth 使用。
  • [verified] Per-agent 與 unified image 均以 protocolVersion: 1、clientInfo: openab/0.1.0 完成 ACP initialize。
  • [verified] 透過新版 adapter 建立 ACP session、設定 gpt-5.6-sol 並送出實際 prompt，結果為 stopReason: end_turn、response ACP_OK。
  • [verified] OpenAB 會依 adapter advertise 的 capabilities，將 pool default auto 映射成 agent、full-access 映射成 agent-full-access；其他 agent 與 custom values 不變，並有 regression tests。
  • [assumed] PR Preview Build 與 shared-environment canary 尚待 maintainer 執行。Contributor 嘗試 dispatch upstream workflow 時收到 HTTP 403（repository admin permission required）。

Canary execution schedule and acceptance criteria

Canary 沒有預先承諾的 calendar date，而是依下列 gates 執行。Gate 2
需 maintainer 核准 fork Actions／dispatch preview workflow；Gate 3 必須在
正式 Codex agents 擴大切換前完成。

Gate 1 — Local pre-PR evidence（completed；owner: contributor）

  • 三種 Codex image build path 均固定 adapter 1.1.2 與 Codex
    0.144.1，npm list 不再包含 Zed adapter，且 dependency dedupe
    至同一 Codex version。
  • Per-agent 與 unified containers 均以 protocolVersion: 1、
    clientInfo: openab/0.1.0 完成 ACP initialize。
  • 使用既有 Codex authentication 建立新版 adapter session、選擇
    gpt-5.6-sol 並完成 live turn；結果為 end_turn／ACP_OK。

Gate 2 — PR preview（pre-merge；owner: maintainer + contributor）

Trigger: maintainer 核准 fork workflows，並從 upstream main 對
PR 1353、variant codex dispatch PR Preview Build。目前
contributor 直接 dispatch 會收到 HTTP 403，因此本 gate 尚未開始。

  • PR Preview Build conclusion 為 success，run URL 記錄於 PR
    validation section。
  • 以 preview image 啟動 OpenAB；adapter process 正常存活，ACP
    initialize 成功，log 無 ACP_TURN_FAILED 或 JSON-RPC init error。
  • 執行 session/new、至少兩個連續 turns、gateway restart 與
    session/load；restart 後延續同一個 session。
  • 經由 OpenAB 選擇 gpt-5.6-sol 並完成純文字 turn；log 無
    requires a newer version of Codex。
  • 在 read-only、agent、agent-full-access 驗證讀檔、
    寫檔、shell command 與 permission request。
  • 發出長時間 turn 後執行 session/cancel；turn 結束且下一個
    prompt 能正常開始。
  • 模擬 adapter error；Discord／gateway 收到可除錯內容，而不是只有
    無上下文的 Internal error。
  • 使用既有 CODEX_HOME／auth.json 或 device login 完成
    preview authentication，不依賴 login shell 或未明列的 env vars。

Gate 3 — Deployment canary（post-merge, pre-rollout；owner: maintainer/operator）

Trigger: merge 後的新 Codex image tag 可供部署。此 gate 完成前不得
將所有正式 Codex agents 切換至新 adapter。

  • 以不同於正式 agent 的 bot token 部署單一 canary agent，完成
    ACP initialize 與至少一個 gpt-5.6-sol turn。
  • 驗證既有 /home/node/.codex/ authentication、session persistence
    與 restart 後的 session/load。
  • 將 canary 切回保留的 Zed image tag，再完成 ACP initialize 與一個
    baseline turn；將 image tag 與 log／workflow evidence 記錄於 PR。

Maintainer alignment 與 implementation decisions（2026-07-11）

  1. ✅ Maintainer 已同意以 @agentclientprotocol/codex-acp 作為 migration target，實作見 feat(codex)!: migrate ACP adapter #1353。
  2. 保留目前 clientInfo.version = "0.1.0"。新版 adapter 的 ACP initialize 與 gpt-5.6-sol live turn 均已成功；若未來證明 client version 會影響 compatibility，再以獨立 issue 修正，避免本 PR 擴張 scope。
  3. Mode migration 採 capability-gated mapping：OpenAB pool defaults 自動轉換 auto -> agent、full-access -> agent-full-access；每次套用 alias 時會以 warning 顯示舊值、新值與設定更新方式。直接呼叫 ACP 的 custom clients 必須改用新 ID。
  4. Image 在同一個 npm transaction 固定 adapter 1.1.2 與 global Codex CLI 0.144.1，讓 npm dedupe 成單一實際版本。保留 global CLI 供既有 device login 使用，不設定 CODEX_PATH；OpenAB 的 minimal child environment 不會自動傳遞 Docker ENV。
  5. 正式 release 起點與舊 image 保留期間仍由 maintainer 決定。feat(codex)!: migrate ACP adapter #1353 採 image-tag canary，並以 migration 前的 Codex image tag 作為 rollback boundary。

PR #1353 已進入 review。正式切換前仍須完成 PR Preview Build、shared-environment canary 與 rollback 演練。

Metadata

Metadata

Assignees

No one assigned

    Labels

    incompleteneeds-triage

    Type

    No type

    Fields

    No fields configured for issues without a type.

    Projects

    No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions