Problem
acp-tui's connect lifecycle is hardcoded: initialize → session/new → enable the prompt input. It never inspects the initialize response for authMethods and never calls the authenticate request, so any ACP agent that requires authentication will reject the first session/new (or the first session/prompt) with an auth error and the TUI will surface it as a generic JSON-RPC failure.
Hermes-as-agent doesn't require this (its acp_adapter doesn't gate on auth), which is why we haven't hit it yet. But the ACP spec has had authenticate as a standard agent method since v0.1, and the published Python SDK lists it as the first entry in AGENT_METHODS. Agents in the wild that do gate (some Copilot-style hosted backends, some enterprise deployments of Zed agents) would fail to connect.
Proposed solution
After initialize returns, check result.authMethods:
init = await self.client.request("initialize", {...})
auth_methods = (init or {}).get("authMethods") or []
if auth_methods:
# Pick the first declared method (or surface a chooser if there are
# multiple). Issue: authenticate(methodId).
chosen = auth_methods[0]
method_id = chosen.get("id") or chosen.get("methodId")
log.write(f"[dim]→ authenticate (method={method_id})[/]")
await self.client.request("authenticate", {"methodId": method_id})
log.write(f"[dim]← authenticated[/]")
# Then proceed with session/new as today.
For v1 this is enough — most agents declare exactly one method (typically an API-key-derived token already configured on the agent side, requiring no input from the client). If the method requires the client to supply credentials (uncommon but possible), the request will fail with a structured error and we surface it to the user with a clear message rather than the current generic failure.
Out of scope
- Multi-method UX (let the user pick from a list of advertised methods). One method covers all known agents today; add a chooser when we encounter an agent that needs it.
- Storing credentials. acp-tui is a debugger TUI, not a credential vault. If an agent's
authenticate ever requires client-supplied secrets, those should be passed via env or CLI flag rather than prompted interactively in the TUI.
- Re-auth on token expiry mid-session. Out of scope until we have a real agent that does this.
References
- ACP method registry:
acp/meta.py AGENT_METHODS["authenticate"] = "authenticate" (Python SDK v0.11.2)
- ACP spec: https://agentclientprotocol.com — see
initialize.authMethods and the authenticate method
Problem
acp-tui's connect lifecycle is hardcoded:
initialize→session/new→ enable the prompt input. It never inspects theinitializeresponse forauthMethodsand never calls theauthenticaterequest, so any ACP agent that requires authentication will reject the firstsession/new(or the firstsession/prompt) with an auth error and the TUI will surface it as a generic JSON-RPC failure.Hermes-as-agent doesn't require this (its acp_adapter doesn't gate on auth), which is why we haven't hit it yet. But the ACP spec has had
authenticateas a standard agent method since v0.1, and the published Python SDK lists it as the first entry inAGENT_METHODS. Agents in the wild that do gate (some Copilot-style hosted backends, some enterprise deployments of Zed agents) would fail to connect.Proposed solution
After
initializereturns, checkresult.authMethods:For v1 this is enough — most agents declare exactly one method (typically an API-key-derived token already configured on the agent side, requiring no input from the client). If the method requires the client to supply credentials (uncommon but possible), the request will fail with a structured error and we surface it to the user with a clear message rather than the current generic failure.
Out of scope
authenticateever requires client-supplied secrets, those should be passed via env or CLI flag rather than prompted interactively in the TUI.References
acp/meta.pyAGENT_METHODS["authenticate"] = "authenticate"(Python SDK v0.11.2)initialize.authMethodsand theauthenticatemethod