codex-app-server-bridge/openspec/specs/agent-shell-shared-codex-connection/spec.md

Purpose

Defines how Emacs agent-shell launches every Codex ACP session against the common externally managed Codex App Server through the installed transport bridge.

Requirements

Requirement: Codex agent-shell uses the shared server exclusively

Every Codex agent-shell launch SHALL use stock codex-acp with CODEX_PATH set to the absolute path of codex-app-server-bridge and CODEX_APP_SERVER_URL set to ws://127.0.0.1:4500. The integration MUST NOT provide a path that starts or falls back to a private App Server.

Scenario: Codex agent-shell starts successfully

• WHEN the bridge executable is installed and the configured shared App Server is available
• THEN agent-shell starts stock codex-acp, which invokes <resolved-bridge-path> app-server and connects through the bridge to the shared server

Scenario: bridge executable is missing

• WHEN Emacs cannot resolve codex-app-server-bridge with executable-find
• THEN the Codex launcher reports a clear error before starting codex-acp

Scenario: shared server is unavailable

• WHEN agent-shell launches Codex while the configured shared App Server is unavailable
• THEN the launch fails clearly without starting a private App Server

Requirement: Endpoint settings remain separate

The agent-shell bridge endpoint and the shared App Server launcher endpoint SHALL remain independently configured in version 1. The agent-shell environment SHALL explicitly inject its bridge endpoint rather than depend on the environment inherited when Emacs started.

Scenario: agent-shell environment is constructed

• WHEN Emacs prepares the environment for a Codex ACP process
• THEN it adds CODEX_APP_SERVER_URL=ws://127.0.0.1:4500 directly to that process environment

Scenario: shared server launcher is retained

• WHEN the user launches the common App Server through the existing CLI helper
• THEN that helper continues to use its own endpoint configuration without reading the agent-shell bridge setting

Requirement: Codex launcher has one authentication scope

The Emacs agent-shell configuration SHALL expose only the normal Codex launcher and SHALL remove the capital C-c p X binding and the agent-shell-specific privileged Codex launcher path. The tool-auth CLI helper used to launch the shared App Server MUST remain available. This requirement applies only to Codex and MUST NOT alter Pi or Claude launcher behavior.

Scenario: normal Codex binding is used

• WHEN the user invokes C-c p x
• THEN Emacs launches a Codex ACP session through the shared-server bridge

Scenario: removed capital binding is inspected

• WHEN the user checks C-c p X
• THEN it is not bound to the former privileged Codex agent-shell launcher

Scenario: shared server needs tool authentication

• WHEN the user launches the common App Server with the existing tool-auth CLI helper
• THEN the helper remains available and defines the authentication environment inherited by the shared server

Scenario: another agent provider is launched

• WHEN the user starts Pi or Claude from agent-shell
• THEN its existing authentication and launcher behavior is unchanged

Requirement: Agent sessions are distinct shared-server threads

Each stock codex-acp process SHALL use one bridge process and one shared-server WebSocket connection. Starting a new Codex agent-shell session SHALL create its own Emacs-owned Codex thread on the shared App Server rather than live-peer into or resume an existing Codex TUI thread.

Scenario: multiple agent-shell sessions run concurrently

• WHEN the user starts two Codex agent-shell sessions
• THEN each session has its own codex-acp and bridge process and both connect independently to the same shared App Server

Scenario: a TUI thread already exists

• WHEN the user starts an agent-shell Codex session while a Codex TUI thread is active on the shared server
• THEN agent-shell creates a distinct thread instead of attaching to the active TUI thread

Requirement: Agent-shell does not manage server lifecycle

Starting, restarting, or stopping a Codex agent-shell session SHALL affect only its codex-acp and bridge processes. It MUST NOT start, restart, stop, or supervise the common App Server.

Scenario: agent-shell buffer is restarted

• WHEN the user invokes the existing agent-shell restart command
• THEN Emacs replaces the session's adapter and bridge connection while the shared App Server continues running

Scenario: agent-shell buffer is closed

• WHEN the user closes a Codex agent-shell buffer
• THEN its bridge connection ends without terminating the shared App Server

Requirement: Shared authentication effects are explicit

Authentication state SHALL be owned by the shared App Server. Documentation for the agent-shell integration MUST state that logout requests are global to that shared server and therefore affect all clients connected to it.

Scenario: account logout is requested from agent-shell

• WHEN the user invokes the codex-acp logout behavior from an agent-shell session
• THEN the request reaches the shared App Server and the documented shared authentication scope applies to every client