Agent integrations
Codex
Talk to Codex through a Codex App Server thread, with structured tool activity and approval requests.
Setup
- Install the Codex CLI on the runtime host:
npm install -g @openai/codex@0.162.1. Ifcodexis missing, the setup wizard offers to run this for you. - Log Codex in on the runtime host.
- Run
sleeptalkand choose Codex, or let your agent runsleeptalk host ensure --agent codex.
The setup probe (sleeptalk host probe-runtime) starts codex app-server, checks the protocol version, reads the account with a token refresh, and reads the effective configuration for the workspace. It reports ready only when Codex is logged in and the effective approval policy is untrusted, on-failure, or on-request. A handshake alone is not enough. Codex 0.162.1 rejects the older approval_policy = "untrusted" configuration; use an approval-capable policy accepted by that version, such as on-request. Sleeptalk does not migrate that configuration automatically.
Connection and session
The adapter starts codex app-server and speaks JSON-RPC over stdio. Sleeptalk 0.1.0 includes version-specific App Server schemas for Codex 0.153.4 and 0.162.1, with 0.162.1 recommended for a fresh installation. At startup it selects the matching schema and refuses an unrecognized version. Existing installations are retained; review a version change before upgrading.
Each call creates a thread with thread/start. To resume a known thread instead, put its ID in the profile's agent.gateway_session_id; Sleeptalk then calls thread/resume. Voice does not attach to a Codex task you have open elsewhere.
Requests use turn/start. The thread identity is emitted as SessionIdentified. Experimental protocol methods are off.
Event mapping
| Upstream event | Sleeptalk handling | Caller experience |
|---|---|---|
item/agentMessage/delta | AssistantDelta and sentence streaming. Completed text is a fallback when no deltas arrived. | Incremental reply, without replaying the final text. |
item/started, item/completed | Command, file-change, MCP, and dynamic-tool items become ToolEvent start, completion, or failure. | Tool narration and activity. |
item/commandExecution/outputDelta | Updated tool detail. | Progress data, not verbatim speech. |
*/requestApproval | PermissionRequested plus a blocked status. | Deny, allow once, or allow for the session, where the destination shows it. |
turn/completed | Completed, cancelled, or failed status and usage. | The turn ends or reports an error. |
Permissions and sub-agents
Approval requests go to the caller. With permission_mode set to auto, skip, or never, Sleeptalk accepts them automatically; setup probes refuse those modes. Whether Codex asks at all depends on its own approval and sandbox configuration, so check that configuration rather than inferring a policy from the adapter.
This adapter does not report Codex sub-agents as Sleeptalk workers.
Voice and interruption
Assistant text passes through the shared sentence streamer before speech. Tool activity follows your narration setting; a tool result is not read aloud in full.
Abort sends turn/interrupt for the active thread and turn. Steering uses turn/steer. Neither rolls back completed tool effects.
Limits and troubleshooting
- "Complete Codex login privately on the runtime host." Log Codex in on the machine that runs Sleeptalk, then retry.
- The approval policy is not approval-capable. Set Codex's approval policy to one that asks, then retry the probe.
- "Installed Codex ... does not match supported schema." Install the Codex version named in the message.
- A resume fails. An invalid
gateway_session_idis a session problem, not a speech problem. Clear it to start a new thread.
Implementation: App Server adapter, pinned protocol version.