Xcode 27.3 ACP Integration Bug: protocolVersion Type Mismatch Between Xcode and @agentclientprotocol/codex-acp

[elisezhu123]

I'm trying to connect my custom Codex CLI (configured with a custom model, endpoint URL, and API key — e.g. cc-swith) to Xcode 27.3 as an ACP Agent. My setup is M1 Max running macOS 27.0 beta 4, with Codex CLI installed via Homebrew.

Steps I followed:

Downloaded the Xcode 27.3 beta.
Opened Settings → Apple Intelligence, added a new ACP Agent, filled in the configuration, and saved.

Sent a test message: "hi"

This triggered the following error in Xcode:

JSON-RPC request with ID JSONRPCID(rawValue: "EE5F0535-A002-4D8F-9711-624984CDAFEB", intValue: nil) failed to produce a response

Root cause (after 3 hours of investigation with the help of AI agents):

The handshake fails at the initialize step due to a type mismatch in protocolVersion:

Xcode sends protocolVersion: "1.0.0" (a string)
@agentclientprotocol/codex-acp@1.1.4 expects protocolVersion: 1 (a number)

This is confirmed by the following tests:

bash

Fails — string protocolVersion rejected

printf '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"1.0.0","capabilities":{}}}\n'
| CODEX_PATH=/opt/homebrew/bin/codex NO_BROWSER=1 /opt/homebrew/bin/npx -y @agentclientprotocol/codex-acp

→ {"error":{"message":"Invalid params","data":{"protocolVersion":{"_errors":["Invalid input: expected number, received string"]}}}}

Works — @zed-industries/codex-acp accepts the string form

printf '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"1.0.0","capabilities":{}}}\n'
| CODEX_PATH=/opt/homebrew/bin/codex NO_BROWSER=1 npx -y @zed-industries/codex-acp

→ Valid InitializeResponse ✅

Question:

Would it be possible to add support for protocolVersion: "1.0.0" (string) in addition to protocolVersion: 1 (number) in @agentclientprotocol/codex-acp? Since Xcode's ACP client currently sends the string form, accepting both types during the initialize handshake would allow Xcode users to connect without falling back to the older @zed-industries/codex-acp adapter.

[benbrandt]

Hmm I will try to reach out to the Xcode team if I can. It hasn't been a string in the schema since early prototypes... pre-release. We may be able to fallback here and default to 1... but it is also a bit risky to make assumptions on protocol versions so we should tread carefully