feat(agent): Default Codex to the native app-server harness

[charlesvien]

Problem

Codex ran through the Zed codex-acp ACP adapter, an extra translation layer that weakens native Codex capabilities (thread resume/fork, typed item and tool events, detailed usage, structured outputs, approvals).

Changes

1. Bundle the native codex CLI binary (download-binaries + vite copy)
2. Add CodexAppServerAgent speaking Codex's native app-server JSON-RPC under an unchanged ACP surface
3. Add the app-server JSON-RPC client, ACP event mapping, and spawn helper
4. Default createAcpConnection to the native agent, with POSTHOG_CODEX_USE_ACP=1 to fall back to codex-acp

How did you test this?

Manually

Automatic notifications

• Publish to changelog?
• Alert Sales and Marketing teams?

---

This is part 1 of 2 in a stack made with GitButler:

•  2  feat(codex): add codex app server adapter + e2e tests #2975
•  1  feat(agent): Default Codex to the native app-server harness #2723 👈

[charlesvien]

• feat(agent): Default Codex to the native app-server harness #2723 👈 (View in Graphite)
• fix(agent): Send cloud Claude reasoning effort without plugins #2722
• fix(agent): Preserve Codex base prompt via developer_instructions #2721
• main

This stack of pull requests is managed by Graphite. Learn more about stacking.

[github-actions]

React Doctor found 2 issues in 2 files · 2 warnings.

2 warnings

src/features/sessions/components/ContextBreakdownPopover.tsx

• ⚠️ src/features/sessions/components/ContextBreakdownPopover.tsx:35 Number before && renders stray 0 rendering-conditional-render

src/features/sessions/components/SteerQueueToggle.tsx

• ⚠️ src/features/sessions/components/SteerQueueToggle.tsx:19 Non-component export in component file only-export-components

_{Reviewed by React Doctor for commit 4cd9a00.}

[greptile-apps]

Comments Outside Diff (3)

1. packages/agent/src/adapters/codex-app-server/spawn.ts, line 1176-1184 (link)

   apiBaseUrl is not escaped in the config arg

   developerInstructions is carefully escaped (backslash, newlines, quotes) before being injected into the -c flag value, but apiBaseUrl and the other string literals (e.g. "posthog", "responses") are interpolated verbatim. If apiBaseUrl ever contains a " character (e.g. from a misconfigured env var), the produced config line will be malformed and silently misbehave. Consider applying the same escaping logic, or at minimum adding an assertion that the URL contains no double-quotes.

   Prompt To Fix With AI

   This is a comment left during a code review.
   Path: packages/agent/src/adapters/codex-app-server/spawn.ts
   Line: 1176-1184
   
   Comment:
   **`apiBaseUrl` is not escaped in the config arg**
   
   `developerInstructions` is carefully escaped (backslash, newlines, quotes) before being injected into the `-c` flag value, but `apiBaseUrl` and the other string literals (e.g. `"posthog"`, `"responses"`) are interpolated verbatim. If `apiBaseUrl` ever contains a `"` character (e.g. from a misconfigured env var), the produced config line will be malformed and silently misbehave. Consider applying the same escaping logic, or at minimum adding an assertion that the URL contains no double-quotes.
   
   How can I resolve this? If you propose a fix, please make it concise.

2. packages/agent/src/adapters/codex-app-server/codex-app-server-agent.ts, line 821-831 (link)

   pendingTurnResolve not cleared when turn/start request rejects

   pendingTurnResolve is assigned before await this.rpc.request(TURN_START, ...). If that request rejects (e.g. the server returns a JSON-RPC error), prompt() throws but pendingTurnResolve is left pointing at the abandoned completion promise's resolver. A subsequent prompt() call overwrites it correctly, but if the server had partially accepted the first turn and later emits turn/completed, handleNotification would call the stale resolver on the new call's promise, prematurely resolving it. Clearing pendingTurnResolve in a catch block around the request keeps the invariant that the field is only set while a live turn is in flight.

   Prompt To Fix With AI

   This is a comment left during a code review.
   Path: packages/agent/src/adapters/codex-app-server/codex-app-server-agent.ts
   Line: 821-831
   
   Comment:
   **`pendingTurnResolve` not cleared when `turn/start` request rejects**
   
   `pendingTurnResolve` is assigned before `await this.rpc.request(TURN_START, ...)`. If that request rejects (e.g. the server returns a JSON-RPC error), `prompt()` throws but `pendingTurnResolve` is left pointing at the abandoned completion promise's resolver. A subsequent `prompt()` call overwrites it correctly, but if the server had partially accepted the first turn and later emits `turn/completed`, `handleNotification` would call the stale resolver on the *new* call's promise, prematurely resolving it. Clearing `pendingTurnResolve` in a `catch` block around the request keeps the invariant that the field is only set while a live turn is in flight.
   
   How can I resolve this? If you propose a fix, please make it concise.

3. packages/agent/src/adapters/codex-app-server/codex-app-server-agent.test.ts, line 567 (link)

   Test mocks use as unknown as to bypass required interface properties

   init, NewSessionRequest, and PromptRequest stubs are cast via as unknown as InterfaceType rather than supplying all required fields. This sidesteps TypeScript's property checks and can mask breakage when the real interface gains a required field that the agent code reads. The same pattern appears across the three describe blocks. Prefer building the minimal complete objects the agent actually reads, which makes the test contract explicit and keeps it safe under future interface changes.

   Rule Used: When creating mock objects for tests, include all ... (source)

   Learned From
   PostHog/posthog#32521

   Prompt To Fix With AI

   This is a comment left during a code review.
   Path: packages/agent/src/adapters/codex-app-server/codex-app-server-agent.test.ts
   Line: 567
   
   Comment:
   **Test mocks use `as unknown as` to bypass required interface properties**
   
   `init`, `NewSessionRequest`, and `PromptRequest` stubs are cast via `as unknown as InterfaceType` rather than supplying all required fields. This sidesteps TypeScript's property checks and can mask breakage when the real interface gains a required field that the agent code reads. The same pattern appears across the three `describe` blocks. Prefer building the minimal complete objects the agent actually reads, which makes the test contract explicit and keeps it safe under future interface changes.
   
   **Rule Used:** When creating mock objects for tests, include all ... ([source](https://app.greptile.com/posthog-org-19734/-/custom-context?memory=693b8339-f300-4cf5-bacb-3f1630384594))
   
   **Learned From**
   [PostHog/posthog#32521](https://github.com/PostHog/posthog/pull/32521)
   
   How can I resolve this? If you propose a fix, please make it concise.

   Note: If this suggestion doesn't match your team's coding style, reply to this and let me know. I'll remember it for next time!

Prompt To Fix All With AI

Fix the following 3 code review issues. Work through them one at a time, proposing concise fixes.

---

### Issue 1 of 3
packages/agent/src/adapters/codex-app-server/spawn.ts:1176-1184
**`apiBaseUrl` is not escaped in the config arg**

`developerInstructions` is carefully escaped (backslash, newlines, quotes) before being injected into the `-c` flag value, but `apiBaseUrl` and the other string literals (e.g. `"posthog"`, `"responses"`) are interpolated verbatim. If `apiBaseUrl` ever contains a `"` character (e.g. from a misconfigured env var), the produced config line will be malformed and silently misbehave. Consider applying the same escaping logic, or at minimum adding an assertion that the URL contains no double-quotes.

### Issue 2 of 3
packages/agent/src/adapters/codex-app-server/codex-app-server-agent.ts:821-831
**`pendingTurnResolve` not cleared when `turn/start` request rejects**

`pendingTurnResolve` is assigned before `await this.rpc.request(TURN_START, ...)`. If that request rejects (e.g. the server returns a JSON-RPC error), `prompt()` throws but `pendingTurnResolve` is left pointing at the abandoned completion promise's resolver. A subsequent `prompt()` call overwrites it correctly, but if the server had partially accepted the first turn and later emits `turn/completed`, `handleNotification` would call the stale resolver on the *new* call's promise, prematurely resolving it. Clearing `pendingTurnResolve` in a `catch` block around the request keeps the invariant that the field is only set while a live turn is in flight.

### Issue 3 of 3
packages/agent/src/adapters/codex-app-server/codex-app-server-agent.test.ts:567
**Test mocks use `as unknown as` to bypass required interface properties**

`init`, `NewSessionRequest`, and `PromptRequest` stubs are cast via `as unknown as InterfaceType` rather than supplying all required fields. This sidesteps TypeScript's property checks and can mask breakage when the real interface gains a required field that the agent code reads. The same pattern appears across the three `describe` blocks. Prefer building the minimal complete objects the agent actually reads, which makes the test contract explicit and keeps it safe under future interface changes.

_{Reviews (1): Last reviewed commit: "default codex to native app-server harne..." | Re-trigger Greptile}

[greptile-apps]

Prompt To Fix All With AI

Fix the following 1 code review issue. Work through them one at a time, proposing concise fixes.

---

### Issue 1 of 1
packages/agent/src/adapters/codex-app-server/app-server-client.ts:104-106
**Unexpected process exit leaves pending promises hanging forever**

When the codex process crashes, the stdout stream closes and `readLoop` detects `done` and exits silently. At that point `AppServerClient.pending` still holds any in-flight RPC requests, and more critically `CodexAppServerAgent.pendingTurnResolve` is still set (waiting for `turn/completed` that will never arrive). Neither is ever rejected, so `prompt()` hangs indefinitely.

`close()` already does the right thing — rejects all `pending` calls and clears state — but it is never triggered by a transport EOF. The loop should call `void this.close()` (or a dedicated `onClose` callback) when `done` is `true` and `!this.closed`.

_{Reviews (2): Last reviewed commit: "default codex to native app-server harne..." | Re-trigger Greptile}

[greptile-apps]

Comments Outside Diff (1)

1. packages/agent/src/adapters/codex-app-server/codex-app-server-agent.ts, line 1676-1688 (link)

   Unhandled promise rejection when codex crashes during turn/start

   When the codex process exits while turn/start is in-flight, AppServerClient.readLoop's finally block (1) rejects the pending TURN_START call and (2) immediately and synchronously calls onClose() → handleServerClosed() → pendingTurn.reject(...). Because (1) causes rpc.request(TURN_START) to throw, the await completion line is never reached. The completion promise ends up in a rejected state with no attached handler, which triggers an unhandled promise rejection. In Electron (Node.js ≥ 15), unhandled rejections terminate the process by default, so a codex crash during a session handshake can also crash the host app.

   The test "rejects the pending turn when the app-server stream closes" doesn't reproduce this because the stub's request() resolves synchronously, so await completion is already active when triggerClose() fires. The fix is to attach a no-op .catch() to completion immediately after creating it, so Node.js considers the rejection handled regardless of whether await completion is ever reached.

_{Reviews (3): Last reviewed commit: "harden codex app-server turn lifecycle" | Re-trigger Greptile}