High-level SDK cannot authenticate current ACP adapters with dynamic auth methods #313

Summary

The high-level TypeScript SDK cannot authenticate ACP adapters whose advertised authentication methods differ from the three method IDs hard-coded in autoAuthenticate. It also does not expose a public way to send an arbitrary ACP authenticate request or advertise authentication-related client capabilities.

This currently breaks the official Codex adapter 1.x API-key flow and prevents clients from using the official Claude/Codex custom gateway authentication flow through the high-level SDK.

Versions tested

• sandbox-agent: 0.4.2
• acp-http-client: 0.4.2
• @agentclientprotocol/sdk: 0.16.1
• @agentclientprotocol/codex-acp: 1.10.0

The same hard-coded authentication logic is still present on main at the time of filing.

Current behavior

LiveAcpConnection.create() initializes the ACP connection and calls a private autoAuthenticate() helper. That helper only considers:

codex-api-key
openai-api-key
anthropic-api-key

Current Codex ACP 1.x advertises:

[
  { "id": "api-key" },
  { "id": "chat-gpt" }
]

As a result, the high-level SDK does not call authenticate, and session creation fails with Authentication required (or an equivalent wrapped ACP error), even when CODEX_API_KEY or OPENAI_API_KEY is available to the adapter process.

The high-level SDK also does not expose its AcpHttpClient, a generic authenticate(request) method, or an authentication callback. Consumers therefore cannot recover by selecting the advertised method themselves.

The authentication call is also best-effort and its error is swallowed, which makes diagnostics difficult.

Claude/custom gateway case

The maintained Claude ACP adapter advertises its gateway auth method only when the client sends the corresponding capability during initialize:

{
  "clientCapabilities": {
    "auth": {
      "_meta": {
        "gateway": true
      }
    }
  }
}

The client must then send an explicit request such as:

{
  "methodId": "gateway",
  "_meta": {
    "gateway": {
      "baseUrl": "https://gateway.example.com",
      "headers": {
        "Authorization": "Bearer <redacted>"
      }
    }
  }
}

The low-level acp-http-client supports both operations. The high-level SDK currently supplies no authentication-related clientCapabilities during initialization and provides no way to issue the explicit authentication request.

Minimal reproduction

1. Start an official sandbox-agent 0.4.2 server.
2. Install or use @agentclientprotocol/codex-acp 1.10.0.
3. Make CODEX_API_KEY available to the adapter process.
4. Connect with the high-level sandbox-agent TypeScript SDK.
5. Create a Codex session.

Observed initialize response:

{
  "authMethods": [
    { "id": "api-key", "name": "API Key" },
    { "id": "chat-gpt", "name": "ChatGPT" }
  ]
}

Observed result: session creation fails because no authentication method is selected.

Using the official low-level acp-http-client against the same server succeeds when calling:

await client.authenticate({ methodId: "api-key" });

Expected behavior

The high-level SDK should allow applications to handle the authentication methods advertised by the active adapter, without depending on a fixed list of adapter-specific method IDs.

Possible API shapes include:

1. Expose a public authenticate(agent, request) or connection-level authenticate(request) method.
2. Accept clientCapabilities and an authentication selector or callback in the connection options.
3. Optionally retain automatic authentication for known environment-backed methods, but derive it from advertised method metadata and keep aliases for older adapters.
4. Surface authentication failures instead of silently swallowing them, or expose them through a diagnostic callback.

Compatibility concern

sandbox-agent install-agent normally resolves adapters from the live ACP registry. Adapter versions therefore evolve independently of the high-level SDK release. A hard-coded method-ID list can become incompatible even when both components are installed through their documented, official paths.

Related

• Codex OAuth credentials present, but ACP auth intermittently selects codex-api-key (CODEX_API_KEY is not set) #187 requested an explicit SDK or session option to force the Codex auth method.
• E2B + codex auth using env vars #154 reported Codex credentials being detected while prompt authentication still failed.