codex-executor 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 mrsekut
+
+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,78 @@
+# codex-executor
+
+A TypeScript client library for the [Codex CLI](https://github.com/openai/codex) app-server. Communicates via JSON-RPC 2.0 over stdio with a spawned Codex process.
+
+## Install
+
+```bash
+bun add codex-executor
+```
+
+## Requirements
+
+- [Bun](https://bun.sh/) runtime
+- [Codex CLI](https://github.com/openai/codex) installed and available in PATH
+
+## Usage
+
+```ts
+import { createCodexClient } from 'codex-executor';
+
+const client = createCodexClient();
+
+await client.initialize();
+
+const thread = await client.startThread({
+  model: 'o4-mini',
+  baseInstructions: 'You are a helpful assistant.',
+});
+
+const result = await client.startTurn(thread.id, [
+  { type: 'text', text: 'Hello!', text_elements: [] },
+]);
+
+console.log(result.message);
+console.log(result.tokenUsage);
+
+client.kill();
+```
+
+## API
+
+### `createCodexClient(options?): CodexClient`
+
+Creates a new Codex client instance.
+
+**Options:**
+
+| Field       | Type     | Description                                   |
+| ----------- | -------- | --------------------------------------------- |
+| `codexPath` | `string` | Path to the codex binary (default: `"codex"`) |
+| `cwd`       | `string` | Working directory for the codex process       |
+
+### `CodexClient`
+
+| Method                       | Returns               | Description                         |
+| ---------------------------- | --------------------- | ----------------------------------- |
+| `initialize()`               | `Promise<void>`       | Initialize the client connection    |
+| `startThread(params?)`       | `Promise<Thread>`     | Start a new conversation thread     |
+| `resumeThread(threadId)`     | `Promise<Thread>`     | Resume an existing thread           |
+| `startTurn(threadId, input)` | `Promise<TurnResult>` | Send user input and wait for result |
+| `kill()`                     | `void`                | Kill the codex process              |
+
+### JSON-RPC Utilities
+
+Low-level JSON-RPC 2.0 helpers are also exported:
+
+```ts
+import {
+  rpcRequest,
+  rpcNotification,
+  rpcResponse,
+  parseMessage,
+} from 'codex-executor';
+```
+
+## License
+
+MIT

package/index.ts

@@ -0,0 +1,21 @@
+export {
+  rpcRequest,
+  rpcNotification,
+  rpcResponse,
+  parseMessage,
+} from './src/jsonrpc';
+
+export type { ParsedMessage } from './src/jsonrpc';
+
+export type {
+  CodexClient,
+  CodexClientOptions,
+  Thread,
+  ThreadStartParams,
+  TokenUsage,
+  TurnResult,
+  UserInput,
+} from './src/types';
+
+export { createCodexClient } from './src/client';
+export type { CodexProcess } from './src/client';

package/package.json

@@ -0,0 +1,39 @@
+{
+  "name": "codex-executor",
+  "version": "0.1.0",
+  "description": "A TypeScript client library for Codex CLI app-server, communicating via JSON-RPC 2.0 over stdio",
+  "type": "module",
+  "license": "MIT",
+  "author": "mrsekut",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/mrsekut/codex-executor.git"
+  },
+  "homepage": "https://github.com/mrsekut/codex-executor#readme",
+  "bugs": {
+    "url": "https://github.com/mrsekut/codex-executor/issues"
+  },
+  "keywords": [
+    "codex",
+    "openai",
+    "json-rpc",
+    "cli",
+    "ai",
+    "agent"
+  ],
+  "exports": {
+    ".": "./index.ts"
+  },
+  "files": [
+    "src/*.ts",
+    "!src/*.test.ts",
+    "index.ts"
+  ],
+  "devDependencies": {
+    "@types/bun": "latest",
+    "prettier": "^3.8.1"
+  },
+  "peerDependencies": {
+    "typescript": "^5"
+  }
+}

package/src/client.ts

@@ -0,0 +1,283 @@
+/**
+ * Codex app-server client.
+ * Communicates via JSON-RPC 2.0 over stdio with a spawned codex process.
+ */
+
+import {
+  rpcRequest,
+  rpcNotification,
+  rpcResponse,
+  parseMessage,
+} from './jsonrpc';
+import type {
+  CodexClient,
+  CodexClientOptions,
+  Thread,
+  ThreadStartParams,
+  TokenUsage,
+  TurnResult,
+  UserInput,
+} from './types';
+
+const DEFAULT_CODEX_PATH = 'codex';
+
+/** @internal Process interface for dependency injection in tests */
+export type CodexProcess = {
+  stdin: { write(data: string | Uint8Array): unknown };
+  stdout: ReadableStream<Uint8Array>;
+  stderr: ReadableStream<Uint8Array>;
+  kill(): void;
+};
+
+type PendingRequest = {
+  resolve: (result: unknown) => void;
+  reject: (error: Error) => void;
+};
+
+export function createCodexClient(
+  options: CodexClientOptions & { _process?: CodexProcess } = {},
+): CodexClient {
+  return new CodexClientImpl(options);
+}
+
+class CodexClientImpl implements CodexClient {
+  private proc: CodexProcess;
+  private isExternalProcess: boolean;
+  private nextId = 0;
+  private pending = new Map<number, PendingRequest>();
+  private buffer = '';
+  private lastTokenUsage: TokenUsage | null = null;
+  private lastAgentMessage: string | null = null;
+  private turnResolve: ((result: TurnResult) => void) | null = null;
+
+  constructor(options: CodexClientOptions & { _process?: CodexProcess } = {}) {
+    const codexPath = options.codexPath ?? DEFAULT_CODEX_PATH;
+    const cwd = options.cwd;
+    this.isExternalProcess = options._process != null;
+
+    this.proc =
+      options._process ??
+      Bun.spawn([codexPath, 'app-server'], {
+        stdin: 'pipe',
+        stdout: 'pipe',
+        stderr: 'pipe',
+        ...(cwd ? { cwd } : {}),
+      });
+
+    this.startStderrLoop();
+    this.startStdoutLoop();
+  }
+
+  async initialize(): Promise<void> {
+    await this.request('initialize', {
+      clientInfo: { name: 'codex-executor', version: '0.1.0' },
+      capabilities: { experimentalApi: true },
+    });
+    this.notify('initialized');
+    if (!this.isExternalProcess) {
+      await Bun.sleep(500);
+    }
+  }
+
+  async startThread(params?: ThreadStartParams): Promise<Thread> {
+    const threadParams: Record<string, unknown> = {};
+    if (params?.cwd) threadParams['cwd'] = params.cwd;
+    if (params?.model) threadParams['model'] = params.model;
+    if (params?.baseInstructions)
+      threadParams['baseInstructions'] = params.baseInstructions;
+
+    const result = (await this.request('thread/start', threadParams)) as Record<
+      string,
+      unknown
+    >;
+    const thread = result['thread'] as Record<string, unknown>;
+    return { id: thread['id'] as string };
+  }
+
+  async resumeThread(threadId: string): Promise<Thread> {
+    const result = (await this.request('thread/resume', {
+      threadId,
+    })) as Record<string, unknown>;
+    const thread = result['thread'] as Record<string, unknown>;
+    return { id: thread['id'] as string };
+  }
+
+  async startTurn(threadId: string, input: UserInput[]): Promise<TurnResult> {
+    this.lastTokenUsage = null;
+    this.lastAgentMessage = null;
+
+    const turnPromise = new Promise<TurnResult>(resolve => {
+      this.turnResolve = resolve;
+    });
+
+    await this.request('turn/start', { threadId, input });
+
+    return turnPromise;
+  }
+
+  kill(): void {
+    this.proc.kill();
+  }
+
+  // --- Private methods ---
+
+  private send(data: string): void {
+    this.proc.stdin.write(data + '\n');
+  }
+
+  private request(
+    method: string,
+    params: Record<string, unknown> = {},
+  ): Promise<unknown> {
+    const id = ++this.nextId;
+    const payload = rpcRequest(id, method, params);
+    return new Promise((resolve, reject) => {
+      this.pending.set(id, { resolve, reject });
+      this.send(payload);
+    });
+  }
+
+  private notify(method: string, params: Record<string, unknown> = {}): void {
+    this.send(rpcNotification(method, params));
+  }
+
+  private handleServerRequest(
+    id: number,
+    method: string,
+    _params: unknown,
+  ): void {
+    if (
+      method === 'item/commandExecution/requestApproval' ||
+      method === 'execCommandApproval' ||
+      method === 'item/fileChange/requestApproval' ||
+      method === 'applyPatchApproval'
+    ) {
+      this.send(rpcResponse(id, { decision: 'accept' }));
+    } else if (method === 'item/tool/call') {
+      this.send(
+        rpcResponse(id, { output: 'No handler registered', success: false }),
+      );
+    } else {
+      this.send(
+        JSON.stringify({
+          jsonrpc: '2.0',
+          id,
+          error: { code: -32601, message: `Method not found: ${method}` },
+        }),
+      );
+    }
+  }
+
+  private handleNotification(method: string, params: unknown): void {
+    const p = params as Record<string, unknown> | undefined;
+
+    if (method === 'turn/completed') {
+      const turn = p?.['turn'] as Record<string, unknown> | undefined;
+      const status = turn?.['status'] as string | undefined;
+      const error = turn?.['error'] as
+        | Record<string, unknown>
+        | null
+        | undefined;
+
+      if (this.turnResolve) {
+        this.turnResolve({
+          success: status === 'completed',
+          message: this.lastAgentMessage,
+          tokenUsage: this.lastTokenUsage,
+          error: error
+            ? ((error['message'] as string) ?? 'Unknown error')
+            : null,
+        });
+        this.turnResolve = null;
+      }
+    } else if (method === 'thread/tokenUsage/updated') {
+      const usage = p?.['tokenUsage'] as Record<string, unknown> | undefined;
+      const total = usage?.['total'] as Record<string, unknown> | undefined;
+      if (total) {
+        this.lastTokenUsage = {
+          totalTokens: total['totalTokens'] as number,
+          inputTokens: total['inputTokens'] as number,
+          outputTokens: total['outputTokens'] as number,
+        };
+      }
+    } else if (method === 'codex/event/task_complete') {
+      const msg = p?.['msg'] as Record<string, unknown> | undefined;
+      this.lastAgentMessage = (msg?.['last_agent_message'] as string) ?? null;
+    }
+  }
+
+  private startStderrLoop(): void {
+    (async () => {
+      const reader = this.proc.stderr.getReader();
+      const decoder = new TextDecoder();
+      try {
+        while (true) {
+          const { done, value } = await reader.read();
+          if (done) break;
+          const text = decoder.decode(value, { stream: true });
+          if (!text.includes('failed to refresh available models')) {
+            process.stderr.write(`[codex] ${text}`);
+          }
+        }
+      } catch {
+        // process exited
+      }
+    })();
+  }
+
+  private startStdoutLoop(): void {
+    (async () => {
+      const reader = this.proc.stdout.getReader();
+      const decoder = new TextDecoder();
+      try {
+        while (true) {
+          const { done, value } = await reader.read();
+          if (done) break;
+          this.buffer += decoder.decode(value, { stream: true });
+
+          let newlineIdx: number;
+          while ((newlineIdx = this.buffer.indexOf('\n')) !== -1) {
+            const line = this.buffer.slice(0, newlineIdx).trim();
+            this.buffer = this.buffer.slice(newlineIdx + 1);
+            if (!line) continue;
+
+            try {
+              const raw = JSON.parse(line) as unknown;
+              const msg = parseMessage(raw);
+              if (!msg) continue;
+
+              switch (msg.kind) {
+                case 'response': {
+                  const p = this.pending.get(msg.id);
+                  if (p) {
+                    p.resolve(msg.result);
+                    this.pending.delete(msg.id);
+                  }
+                  break;
+                }
+                case 'error-response': {
+                  const p = this.pending.get(msg.id);
+                  if (p) {
+                    p.reject(new Error(msg.error.message));
+                    this.pending.delete(msg.id);
+                  }
+                  break;
+                }
+                case 'server-request':
+                  this.handleServerRequest(msg.id, msg.method, msg.params);
+                  break;
+                case 'notification':
+                  this.handleNotification(msg.method, msg.params);
+                  break;
+              }
+            } catch {
+              // skip unparseable lines
+            }
+          }
+        }
+      } catch {
+        // process exited
+      }
+    })();
+  }
+}

package/src/jsonrpc.ts

@@ -0,0 +1,78 @@
+/**
+ * JSON-RPC 2.0 protocol utilities for Codex app-server communication.
+ */
+
+export function rpcRequest(
+  id: number,
+  method: string,
+  params: Record<string, unknown> = {},
+): string {
+  return JSON.stringify({ jsonrpc: '2.0', id, method, params });
+}
+
+export function rpcNotification(
+  method: string,
+  params: Record<string, unknown> = {},
+): string {
+  return JSON.stringify({ jsonrpc: '2.0', method, params });
+}
+
+export function rpcResponse(id: number, result: unknown): string {
+  return JSON.stringify({ jsonrpc: '2.0', id, result });
+}
+
+// --- Message parsing ---
+
+export type ParsedMessage =
+  | { kind: 'response'; id: number; result: unknown }
+  | {
+      kind: 'error-response';
+      id: number;
+      error: { code: number; message: string };
+    }
+  | { kind: 'server-request'; id: number; method: string; params: unknown }
+  | { kind: 'notification'; method: string; params: unknown };
+
+export function parseMessage(raw: unknown): ParsedMessage | null {
+  if (typeof raw !== 'object' || raw === null) return null;
+  const msg = raw as Record<string, unknown>;
+
+  // Response (has id + result)
+  if ('id' in msg && 'result' in msg) {
+    return {
+      kind: 'response',
+      id: msg['id'] as number,
+      result: msg['result'],
+    };
+  }
+
+  // Error response (has id + error)
+  if ('id' in msg && 'error' in msg) {
+    return {
+      kind: 'error-response',
+      id: msg['id'] as number,
+      error: msg['error'] as { code: number; message: string },
+    };
+  }
+
+  // Server request (has id + method)
+  if ('id' in msg && 'method' in msg) {
+    return {
+      kind: 'server-request',
+      id: msg['id'] as number,
+      method: msg['method'] as string,
+      params: msg['params'],
+    };
+  }
+
+  // Notification (has method, no id)
+  if ('method' in msg && !('id' in msg)) {
+    return {
+      kind: 'notification',
+      method: msg['method'] as string,
+      params: msg['params'],
+    };
+  }
+
+  return null;
+}

package/src/types.ts

@@ -0,0 +1,51 @@
+/**
+ * Type definitions for Codex app-server client.
+ */
+
+export type CodexClientOptions = {
+  /** Path to the codex binary (default: "codex") */
+  codexPath?: string;
+
+  /** Working directory for the codex process */
+  cwd?: string;
+};
+
+export type ThreadStartParams = {
+  /** Override working directory for this thread */
+  cwd?: string;
+
+  /** Override model */
+  model?: string;
+
+  /** Base instructions (system prompt) */
+  baseInstructions?: string;
+};
+
+export type Thread = {
+  id: string;
+};
+
+export type TurnResult = {
+  success: boolean;
+  message: string | null;
+  tokenUsage: TokenUsage | null;
+  error: string | null;
+};
+
+export type TokenUsage = {
+  totalTokens: number;
+  inputTokens: number;
+  outputTokens: number;
+};
+
+export type UserInput =
+  | { type: 'text'; text: string; text_elements: [] }
+  | { type: 'skill'; name: string; path: string };
+
+export type CodexClient = {
+  initialize(): Promise<void>;
+  startThread(params?: ThreadStartParams): Promise<Thread>;
+  resumeThread(threadId: string): Promise<Thread>;
+  startTurn(threadId: string, input: UserInput[]): Promise<TurnResult>;
+  kill(): void;
+};