@makaio/ai-adapters-codex-app-server

OpenAI Codex App-Server adapter for the Makaio AI framework.

Communicates with codex app-server via stdio subprocess using JSON-RPC 2.0 over JSONL.

Quick Start

import {
  CodexAppServerAdapter,
  createCodexAppServerAdapter,
} from '@makaio/ai-adapters-codex-app-server';
import { MakaioBus } from '@makaio/bus-core';
import { AdapterSubjects } from '@makaio/contracts';

// Using the factory function (recommended)
const adapter = await createCodexAppServerAdapter();

const result = await MakaioBus.request(AdapterSubjects.startAgent, {
  adapterId: adapter.adapterId,
  role: 'lead',
  cwd: process.cwd(),
  initialMessage: 'Inspect this repository',
  model: 'gpt-5.1-codex-mini',
});

// Or using the class directly
const directAdapter = new CodexAppServerAdapter();
await directAdapter.init();

Architecture

This adapter follows the three-layer architecture pattern:

CodexAppServerAdapter extends AIAdapter
    -> creates via agentFactory()
CodexAppServerAgent extends AIAgent
    -> receives connector via connectorFactory()
CodexAppServerConnector extends AIAgentConnector
    -> JsonRpcClient
    -> StdioTransport
    -> [codex app-server subprocess]

Layers:

Layer	Class	Responsibility
Adapter	CodexAppServerAdapter	Factory for agents, handles adapter.startAgent RPC
Agent	CodexAppServerAgent	Wires events to global bus, manages lifecycle
Connector	CodexAppServerConnector	JSON-RPC bridge to codex app-server subprocess

Thread/Turn Management:

Class	Purpose
CodexAppServerThread	Thread lifecycle management
CodexAppServerTurn	Individual turn handling
UserMessageQueue	Internal connector queue from adapter core

Capabilities

• tools - Tool/function calling support (bash, patch)
• streaming - Streaming responses
• systemPrompt:override - Replace/set the system prompt
• systemPrompt:append - Append to the adapter’s default system prompt
• Tool approval workflow via agent wiring to AgentSubjects.toolApprove
• File change approval workflow
• Replace and interrupt delivery modes
• Reasoning support with configurable effort levels

Exports

Adapter

Export	Description
CodexAppServerAdapter	Main adapter class
createCodexAppServerAdapter	Factory function (creates and initializes)
CodexAppServerAdapterName	Adapter identifier constant

Agent & Connector

Export	Description
CodexAppServerAgent	Agent class (middle layer)
CodexAppServerConnector	Connector class (JSON-RPC bridge)

Thread Management

Export	Description
CodexAppServerThread	Thread abstraction
CodexAppServerTurn	Turn abstraction

Namespaces & Types

Export	Description
CodexAppServerNamespace	Bus namespace for connector events
CodexAppServerSubjects	Subject constants for bus messaging
CodexAppServerBus	Typed bus type

Tool Handling

Export	Description
registerToolApprovalHandler	Register handler for tool approval requests
toGlobalToolApproval	Convert to global tool approval format
toGlobalFileApproval	Convert to global file approval format
fromGlobalToolApproval	Convert from global approval format
ToolApprovalContext	Tool approval context type
CodexToolApprovalDecision	Approval decision type

Configuration & Schemas

Export	Description
CodexAppServerProviderConfigSchema	Zod schema for provider config
CodexAppServerProviderConfig	Provider config type
CodexAppServerConfig	Config factory

Runtime Contribution

Runtime registration is contributed by @makaio/ai-adapters-codex-app-server/server. That entrypoint default-exports the codexAppServerPackage MakaioExtension descriptor, whose adapters[] entry wraps the internal definition from src/definition.ts.

Utilities

Export	Description
createStdioTransport	Create stdio transport for subprocess
createJsonRpcClient	Create JSON-RPC client

Protocol Types

Export	Description
ThreadStartedNotification	Thread started event
TurnStartedNotification	Turn started event
TurnCompletedNotification	Turn completed event
AgentMessageDeltaNotification	Agent message delta event
CommandExecutionOutputDeltaNotification	Command output event
ReasoningTextDeltaNotification	Reasoning delta event
FileChangeOutputDeltaNotification	File change delta event
ThreadTokenUsageUpdatedNotification	Token usage event

Configuration Options

interface CodexAppServerProviderConfig {
  /**
   * Reasoning effort level.
   * Maps to ReasoningEffort in app-server protocol.
   */
  reasoningEffort?: 'low' | 'medium' | 'high';

  /**
   * Approval policy for tool execution.
   * Maps to AskForApproval in app-server protocol.
   */
  approvalPolicy?: 'untrusted' | 'on-failure' | 'on-request' | 'never';

  /**
   * Sandbox mode for command execution.
   */
  sandboxMode?: 'read-only' | 'workspace-write' | 'danger-full-access';
}

cwd, model, and env are runtime/adapter options supplied on adapter.startAgent, not provider config fields. Hosts should resolve the selected provider/model before calling startAgent and pass that model explicitly. The current adapter fallback is gpt-5.1-codex-mini for low-level tests and direct construction paths.

Prerequisites

This adapter requires a Codex CLI build with app-server support.

Installation

# Install Codex by the distribution method supported by your host.
# The adapter supports:
# - a host-managed absolute binary path
# - PATH lookup for `codex`
# - test/fetcher paths that spawn `codex app-server` directly

# Verify installation
codex --version
codex app-server --help

Configuration

The adapter will spawn codex app-server as a subprocess via stdio. Ensure:

• The codex binary is host-resolved or available in PATH
• You have appropriate permissions for the working directory

Protocol Methods

The adapter communicates with codex app-server using JSON-RPC 2.0 over JSONL:

The package exports generated protocol types from src/protocol/generated/index.ts. Prefer the v2 namespace for app-server protocol types when importing generated definitions.

Client Requests

• initialize - Initialize connection handshake
• thread/start - Start new conversation thread (v2)
• turn/start - Send user message to agent (v2)
• turn/interrupt - Cancel current turn (v2)
• model/list - Fetch available Codex models

Client Notifications

• initialized - Acknowledge successful initialization

Server Notifications (Events)

• thread/started - Thread created
• turn/started - Agent begins processing turn
• turn/completed - Agent finished turn
• item/started - Item (message/tool/reasoning) started
• item/completed - Item completed
• item/agentMessage/delta - Streaming message content
• item/commandExecution/outputDelta - Streaming command output
• item/reasoning/textDelta - Streaming reasoning content
• item/fileChange/outputDelta - Streaming file change output
• thread/tokenUsage/updated - Token usage metrics

Server Requests

• item/commandExecution/requestApproval - Request approval for command execution
• item/fileChange/requestApproval - Request approval for file changes

Troubleshooting

Subprocess fails to start

Error: codex app-server exited with code 1

Solution:

• Verify codex CLI is installed: codex --version
• Check the working directory is accessible
• Review stderr logs for subprocess errors

JSONL parsing errors

Error: Failed to parse JSONL

Solution:

• This may indicate a protocol mismatch
• Ensure you’re using the correct version of codex
• Check the subprocess logs for protocol errors

Approval handling issues

Error: Tool approval timeout

Solution:

• Increase timeout in config
• Ensure the host has an AgentSubjects.toolApprove handler registered
• Check that the agent is initialized so its scoped approval wiring is active

Connection issues

Error: Failed to initialize connection

Solution:

• Verify stdio transport is working
• Check that codex app-server is responding
• Ensure JSON-RPC handshake completes

File Structure

src/
├── index.ts              # Package exports
├── adapter.ts            # CodexAppServerAdapter class
├── agent.ts              # CodexAppServerAgent class
├── connector.ts          # CodexAppServerConnector class
├── thread.ts             # Thread management
├── turn.ts               # Turn management
├── config.ts             # Configuration utilities
├── constants.ts          # Adapter constants
├── definition.ts         # Internal adapter definition
├── package.ts            # MakaioExtension package descriptor
├── server.ts             # Server entrypoint exporting the package descriptor
├── provider.ts           # Provider registration
├── provider.fetcher.ts   # Codex model/list fetcher
├── schemas.ts            # Zod schemas
├── tool-handling.ts      # Tool approval utilities
├── dynamic-tool-handling.ts # Registry tool declaration and routing
├── event-normalizers.ts  # Event normalization
├── connector/            # JSON-RPC connection, lifecycle, and approval handlers
├── namespaces/           # Bus namespace definitions
│   ├── index.ts          # Namespace export
│   └── schemas/          # Message schemas
├── protocol/generated/   # Generated protocol types
│   ├── index.ts          # Protocol exports
│   └── v2/               # V2 protocol definitions
└── utils/                # Utility functions
    ├── createStdioTransport.ts
    └── jsonRpcClient.ts

---

Part of the Makaio AI Framework