Skip to main content

​
Overview

The CodexSdkAdapter captures events from Codex SDK live runs, streaming them through the ingest pipeline in real-time.

​
Class: CodexSdkAdapter

​
Constructor

constructor(
  pipeline: IngestPipeline,
  codex?: Codex
)
​
pipeline
IngestPipeline
required
Ingest pipeline for event processing
​
codex
Codex
Optional Codex SDK instance. If not provided, creates a new instance using CODAPH_CODEX_PATH or CODEX_PATH environment variables.

​
Methods

​
runAndCapture

Runs a Codex session and captures all events. 
async runAndCapture(
  options: AdapterRunOptions,
  onEvent?: (event: CapturedEventEnvelope) => Promise<void> | void
): Promise<AdapterRunResult>
​
options
AdapterRunOptions
required
Run configuration options
​
options.prompt
string
required
User prompt to send to agent
​
options.cwd
string
required
Working directory for the agent
​
options.repoId
string
Repository ID (auto-generated from cwd if not provided)
​
options.model
string
Model name to use
​
options.resumeThreadId
string
Thread ID to resume existing conversation
​
onEvent
(event: CapturedEventEnvelope) => Promise<void> | void
Callback invoked for each captured event
​
sessionId
string
UUID for the capture session
​
threadId
string | null
Codex thread ID, or null if not available
​
finalResponse
string | null
Final agent message text, or null if not available

​
Supporting Types

​
CodexSdkAdapterInit

interface CodexSdkAdapterInit {
  pipeline: IngestPipeline;
  codex?: Codex;
}

​
AdapterRunOptions

interface AdapterRunOptions {
  prompt: string;
  cwd: string;
  repoId?: string;
  model?: string;
  resumeThreadId?: string;
}

​
AdapterRunResult

interface AdapterRunResult {
  sessionId: string;
  threadId: string | null;
  finalResponse: string | null;
}

​
Implementation Details

​
Event Flow

  1. Session initialization: Creates a new UUID session ID
  2. Prompt submission: Emits prompt.submitted event
  3. Thread creation: Starts or resumes Codex thread
  4. Event streaming: Captures all thread events in real-time:
    • thread.started - Thread initialization
    • item.completed - Completed reasoning, messages, tool calls
    • Other Codex SDK events
  5. Error handling: Emits error events on failure

​
Codex Path Resolution

The adapter resolves the Codex CLI path in the following order:
  1. CODAPH_CODEX_PATH environment variable
  2. CODEX_PATH environment variable
  3. System PATH lookup using which codex (Unix) or where codex (Windows)

​
Usage Example

import { CodexSdkAdapter } from './lib/adapter-codex-sdk';
import { IngestPipeline } from './lib/ingest-pipeline';
import { JsonlMirror } from './lib/mirror-jsonl';

const mirror = new JsonlMirror('.codaph');
const pipeline = new IngestPipeline(mirror);
const adapter = new CodexSdkAdapter(pipeline);

const result = await adapter.runAndCapture(
  {
    prompt: 'Fix the authentication bug',
    cwd: process.cwd(),
    model: 'gpt-4',
  },
  async (event) => {
    console.log('Event:', event.eventType);
  }
);

await pipeline.flush();

console.log('Session ID:', result.sessionId);
console.log('Final response:', result.finalResponse);

​
Error Handling

The adapter captures and records errors: 
try {
  await adapter.runAndCapture({ prompt: 'test', cwd: '.' });
} catch (error) {
  // Error event already ingested into pipeline
  console.error('Run failed:', error);
}

Build docs developers (and LLMs) love

Get started for freeTalk to us