@makaio/adapter-codex-app-server 1.0.0-dev-1779051654000

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026-present Makaio GmbH
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,311 @@
+# @makaio/adapter-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
+
+```typescript
+import {
+  CodexAppServerAdapter,
+  createCodexAppServerAdapter,
+} from '@makaio/adapter-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/adapter-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
+
+```typescript
+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
+
+```bash
+# 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
+```

package/descriptor.json

@@ -0,0 +1,27 @@
+{
+  "name": "codex-app-server",
+  "displayName": "Codex App-Server",
+  "version": "0.1.0",
+  "makaio": {
+    "framework": ">=0.1.0"
+  },
+  "entrypoints": {
+    "server": true
+  },
+  "contributions": {
+    "adapters": [
+      {
+        "name": "codex-app-server",
+        "displayName": "Codex App-Server",
+        "description": "Direct integration with codex app-server via stdio subprocess using JSON-RPC 2.0 over JSONL",
+        "clients": [
+          {
+            "id": "codex",
+            "version": "^0.1.0"
+          }
+        ],
+        "protocols": ["openai"]
+      }
+    ]
+  }
+}

package/dist/chunk-DQk6qfdC.mjs

@@ -0,0 +1,18 @@
+//#region \0rolldown/runtime.js
+var __defProp = Object.defineProperty;
+var __exportAll = (all, no_symbols) => {
+	let target = {};
+	for (var name in all) {
+		__defProp(target, name, {
+			get: all[name],
+			enumerable: true
+		});
+	}
+	if (!no_symbols) {
+		__defProp(target, Symbol.toStringTag, { value: "Module" });
+	}
+	return target;
+};
+
+//#endregion
+export { __exportAll as t };