feat(acp): experimental ACP agent mode (Codex) via the Agent Client Protocol

[pjdoland]

Draft / request for feedback. I'm opening this early to start a conversation about the approach before polishing it, not to merge as-is. Feedback on the architecture, scope, and UX is very welcome.

Summary

This adds an opt-in, experimental ACP agent mode that drives the chat panel over the Agent Client Protocol, the way Claude mode drives it today, with Codex (OpenAI) as the first selectable agent type. It is off by default and gated behind an admin policy that defaults to force-off, so it has no effect unless explicitly enabled. Claude mode and ACP mode are mutually exclusive: enabling one turns the other off.

The goal of this first pass is to prove that an external coding agent can run the chat loop end to end (streaming replies, tool-call cards with diffs, per-tool approval) and invoke an NBI MCP tool, using ACP as the integration layer.

What's included

• ACP client backend (acp_agent.py): a persistent worker thread that launches the agent's ACP adapter and maps ACP events onto NBI's existing chat surfaces (markdown, tool-call cards, diffs, approvals). Turns are single-flight and the subprocess lifecycle is hardened. A small stdio MCP server (acp_mcp_server.py) exposes an NBI tool to the agent so the end-to-end tool path is exercised.
• Agent registry (acp_registry.py): agent types are registry entries (adapter package, display metadata, auth convention). Codex is the first entry; further agents (Pi, OpenCode) slot in once their adapters are validated. The chat header and message avatars show the selected agent's name and icon.
• Session management: the header's new-chat button starts a fresh agent session, and the history button lists and resumes the agent's stored sessions through ACP session/list / session/load (capability-gated), mirroring the Claude-mode UX.
• Settings + policy: an acp_settings block (with an agent-type dropdown) and an acp_mode admin policy that defaults to force-off, plus OPENAI_API_KEY / OPENAI_BASE_URL / NBI_ACP_CHAT_MODEL overrides, following the existing policy and settings-override conventions. Mutual exclusivity with Claude mode is enforced at the settings boundary (most-recent selection wins; a hand-edited config that enables both resolves to Claude).
• Admin gating parity with Claude: an acp_full_access policy (default force-off) pins Codex to approval_policy=untrusted so it asks before anything beyond trusted read-only commands, clamped server-side on read and write. user-choice exposes a "Full access" toggle that flips the launch to approval_policy=never. Documented in the README admin table and a new admin-guide section.

Testing

• Unit tests for the ACP-to-NBI mapping, approval (including fail-closed), the acp_mode / acp_full_access policy clamps, the mode-exclusivity resolution, the query assembly (attachment context), the approval-arg mapping, the session-preview cleanup, and the credential scrub.
• Verified live in a running JupyterLab against codex-acp 0.16.0 with a real OpenAI key: streaming renders as normal paragraphs, an attached file is read by the agent's own tool, new-session isolates context, resume recalls the prior conversation, and enabling one mode in Settings turns the other off.

Risks / follow-ups

• ACP session/list is an optional protocol extension (codex-acp implements it); agents without it get a friendly notice in the picker. Pagination (nextCursor) is not consumed yet.
• ACP streams token-sized deltas; a possible optimization is coalescing deltas server-side if long replies show sidebar lag.
• The Python ACP SDK trails the core schema in places; pinned to a known-good version here.
• Approval-pin precedence. The full-access gate pins the posture via codex-acp's -c approval_policy command-line override. In the API-key path NBI also isolates CODEX_HOME, so the config base is NBI-controlled; in the ChatGPT-auth path codex uses the user's own ~/.codex. The pin relies on codex honoring the -c override above any config it loads. On shared deployments, prefer API-key auth and keep NBI_ACP_MODE_POLICY=force-off unless needed.

Related

Relates to #378.

[mbektas]

hi @pjdoland thanks, I started doing some testing.

• I think if Codex mode is selected, Claude Mode should be disabled automatically. I think the agent drop-down on top is not necessary.
• Maybe this new mode should be called ACR and different agent types could be made available (Pi, Opencode). so it becomes Claude mode vs ACR mode. we can still show selected agent type (codex, Pi etc)
• I see that the response is not rendering properly

• File as context is not working

- New session button and session history are not available in Codex mode

[pjdoland]

Thanks for testing, Mehmet, this was really helpful feedback. All five items are addressed in the latest push:

1. Mutual exclusivity + dropdown removed. Enabling one mode now turns the other off automatically (enforced server-side), and the agent dropdown at the top is gone.
2. Renamed to ACP mode. It is now Claude mode vs ACP mode, with an agent-type dropdown in the ACP settings tab. Codex is the first agent type in a small registry, so Pi and OpenCode can slot in once their adapters are validated, and the chat still shows the selected agent's name and icon.
3. Rendering fixed. ACP streams token-sized deltas and each one was rendered as its own paragraph; they now stream as markdown parts that concatenate into one block.
4. File as context fixed. The ACP client was sending only the prompt and dropping the context lines NBI appends. It now assembles the turn's context like Claude mode does, and attachments use the same @-mention framing so the agent reads the file with its own tools.
5. New session and session history added. The new-chat button starts a fresh agent session, and the history button lists and resumes the agent's stored sessions through ACP session/list and session/load, same UX as Claude mode.

All verified live against codex-acp with an OpenAI API key (rendering, attachment read, new-session isolation, resume recall, and the settings exclusivity flip). The PR description is updated to match. Happy to adjust anything.

[mbektas]

@pjdoland I just tested the latest. I am running into issues with custom OPENAI_BASE_URL and OPENAI_API_KEY.

error in chat UI:
Falling back from WebSockets to HTTPS transport. unexpected status 401 Unauthorized: Incorrect API key provided: *********. You can find your API key at https://platform.openai.com/account/api-keys(opens in new tab)., url: wss://api.openai.com/v1/responses, cf-ray: ...

[pjdoland]

Thanks for testing this, and sorry for the wasted debugging time. I reproduced it and pushed a fix in aae3cef.

The root cause: ACP settings collected a base URL and a chat model, stored them, and displayed them in the settings panel, but nothing carried either value to the codex-acp subprocess. The launch passed only the API key, CODEX_HOME, and the approval-policy pin. Inheriting OPENAI_BASE_URL from the server environment doesn't help either, since codex ignores that variable; its documented mechanism is the openai_base_url config key. So every request went to api.openai.com no matter what you configured, which is exactly the 401 you saw: your proxy key presented to OpenAI.

The fix passes both settings as -c config overrides at launch, next to the existing approval_policy pin:

-c model="..." -c openai_base_url="..."

CLI overrides beat both the profile and $CODEX_HOME/config.toml, so this is a single delivery point and it works for API-key and ChatGPT-auth sessions alike. Settings that are empty add no flags, so anyone on the stock OpenAI endpoint keeps codex's own defaults.

Verified against a local OpenAI-compatible stub server: with a custom base URL configured, the ACP session now authenticates, reports the configured model back in session/new, and the prompt round-trips to the local endpoint instead of api.openai.com. Also verified live in JupyterLab through the chat sidebar.

One limitation worth flagging, since it may be what you hit next: openai_base_url rebases codex's built-in OpenAI provider, which speaks the Responses wire API. An endpoint that only implements chat completions will still fail, and supporting those needs a model_providers entry with wire_api = "chat". Happy to add that as a follow-up if it's a configuration you want to cover; I left it out here to keep this change scoped to the reported bug.