ocpipe 0.6.7 → 0.6.9

package/README.md

@@ -1,5 +1,5 @@
 <p align="center"><strong>ocpipe</strong></p>
-<p align="center">Build LLM pipelines with <a href="https://github.com/sst/opencode">OpenCode</a>, <a href="https://github.com/anthropics/claude-code">Claude Code</a>, and <a href="https://zod.dev">Zod</a>.</p>
+<p align="center">Build LLM pipelines with <a href="https://github.com/sst/opencode">OpenCode</a>, <a href="https://github.com/anthropics/claude-code">Claude Code</a>, Pi, and <a href="https://zod.dev">Zod</a>.</p>
 <p align="center">Inspired by <a href="https://github.com/stanfordnlp/dspy">DSPy</a>.</p>
 <p align="center">
   <a href="https://www.npmjs.com/package/ocpipe"><img alt="npm" src="https://img.shields.io/npm/v/ocpipe?style=flat-square" /></a>
@@ -11,7 +11,7 @@
 - **Type-safe** Define inputs and outputs with Zod schemas
 - **Modular** Compose modules into complex pipelines
 - **Checkpoints** Resume from any step
-- **Multi-backend** Choose between OpenCode (75+ providers) or Claude Code SDK
+- **Multi-backend** Choose between OpenCode (75+ providers), Claude Code SDK, Codex SDK, or Pi
 - **Auto-correction** Fixes schema mismatches automatically
 
 ### Quick Start
@@ -49,7 +49,7 @@ type GreetOut = InferOutputs<typeof Greet> // { greeting: string }
 
 ### Backends
 
-ocpipe supports three backends for running LLM agents:
+ocpipe supports four backends for running LLM agents:
 
 **OpenCode** (default) - Requires `opencode` CLI in your PATH. Supports 75+ providers.
 
@@ -83,6 +83,13 @@ defaultModel: { backend: 'codex', modelID: 'gpt-5.4' },
 codex: { sandbox: 'read-only', reasoningEffort: 'high' },
 ```
 
+**Pi** - Uses the `pi` coding-agent CLI JSONL RPC mode.
+
+```typescript
+defaultModel: { backend: 'pi', modelID: 'gemma' },
+pi: { command: 'pi' },
+```
+
 ### Requirements
 
 **For OpenCode backend:** Currently requires [this OpenCode fork](https://github.com/paralin/opencode). Once the following PRs are merged, the official release will work:

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "ocpipe",
-  "version": "0.6.7",
+  "version": "0.6.9",
   "description": "SDK for LLM pipelines with OpenCode, Codex, and Zod",
   "type": "module",
   "main": "src/index.ts",
@@ -31,8 +31,8 @@
   },
   "peerDependencies": {
     "zod": "4.4.3",
-    "@anthropic-ai/claude-agent-sdk": "0.2.126",
-    "@openai/codex-sdk": "0.130.0"
+    "@anthropic-ai/claude-agent-sdk": "0.3.185",
+    "@openai/codex-sdk": "0.141.0"
   },
   "peerDependenciesMeta": {
     "@anthropic-ai/claude-agent-sdk": {
@@ -43,9 +43,9 @@
     }
   },
   "devDependencies": {
-    "@anthropic-ai/claude-agent-sdk": "^0.2.132",
+    "@anthropic-ai/claude-agent-sdk": "^0.3.0",
     "@eslint/js": "^10.0.1",
-    "@openai/codex-sdk": "0.130.0",
+    "@openai/codex-sdk": "0.141.0",
     "@typescript/native-preview": "^7.0.0-dev.20260506.1",
     "bun-types": "^1.3.13",
     "eslint": "^10.3.0",

package/src/agent.ts

@@ -1,7 +1,7 @@
 /**
  * ocpipe agent integration.
  *
- * Dispatches to OpenCode CLI, Claude Code SDK, or Codex SDK based on backend
+ * Dispatches to OpenCode CLI, Claude Code SDK, Codex SDK, or Pi based on backend
  * configuration.
  */
 
@@ -33,6 +33,11 @@ export async function runAgent(
     return runCodexAgent(options)
   }
 
+  if (backend === 'pi') {
+    const { runPiAgent } = await import('./pi.js')
+    return runPiAgent(options)
+  }
+
   return runOpencodeAgent(options)
 }
 

package/src/codex.ts

@@ -7,10 +7,16 @@
 import {
   Codex,
   type CodexOptions as CodexSdkClientOptions,
+  type RunResult,
   type ThreadOptions,
 } from '@openai/codex-sdk'
 import { PROJECT_ROOT } from './paths.js'
-import type { CodexOptions, RunAgentOptions, RunAgentResult } from './types.js'
+import type {
+  CodexOptions,
+  CodexRunSummary,
+  RunAgentOptions,
+  RunAgentResult,
+} from './types.js'
 
 class CodexLogFilter {
   private buf = ''
@@ -121,13 +127,15 @@ export async function runCodexAgent(
 
     const nextSessionId = codex?.ephemeral ? '' : (thread.id ?? '')
     const sessionStr = nextSessionId || 'none'
+    const runSummary = buildCodexRunSummary(result)
     console.error(
-      `<<< Codex SDK done (${response.length} chars) [thread:${sessionStr}]`,
+      `<<< Codex SDK done [thread:${sessionStr}]\n${formatCodexRunSummary(runSummary)}`,
     )
 
     return {
       text: response,
       sessionId: nextSessionId,
+      runSummary,
     }
   } catch (err) {
     if (timedOut) {
@@ -143,6 +151,101 @@ export async function runCodexAgent(
   }
 }
 
+/** buildCodexRunSummary projects a Codex turn into a parent-readable summary. */
+export function buildCodexRunSummary(result: RunResult): CodexRunSummary {
+  const commands: CodexRunSummary['commands'] = []
+  const fileChanges: CodexRunSummary['fileChanges'] = []
+  let errorMessage = ''
+  let finalMessage = result.finalResponse.trim()
+
+  for (const item of result.items) {
+    switch (item.type) {
+      case 'agent_message':
+        if (item.text) finalMessage = item.text
+        break
+      case 'command_execution':
+        commands.push({
+          command: item.command,
+          status: item.status,
+          exitCode: item.exit_code ?? null,
+        })
+        break
+      case 'file_change':
+        for (const change of item.changes) {
+          fileChanges.push({
+            path: change.path,
+            kind: change.kind,
+            status: item.status,
+          })
+        }
+        break
+      case 'error':
+        errorMessage = item.message
+        break
+    }
+  }
+
+  const usage = result.usage
+  return {
+    status: errorMessage ? 'failed' : 'completed',
+    finalMessage: finalMessage.trim(),
+    errorMessage,
+    commands,
+    fileChanges,
+    tokens:
+      usage ?
+        {
+          input: usage.input_tokens,
+          cached: usage.cached_input_tokens,
+          output: usage.output_tokens,
+          reasoning: usage.reasoning_output_tokens,
+        }
+      : null,
+  }
+}
+
+/** formatCodexRunSummary renders a Codex run summary as a clean text block. */
+export function formatCodexRunSummary(summary: CodexRunSummary): string {
+  const lines: string[] = [`status: ${summary.status}`]
+  if (summary.errorMessage) {
+    lines.push(`error: ${summary.errorMessage}`)
+  }
+  if (summary.commands.length > 0) {
+    const failed = summary.commands.filter(isFailedCommand).length
+    lines.push(
+      `commands: ${summary.commands.length} completed, ${failed} failed`,
+    )
+  }
+  if (summary.fileChanges.length > 0) {
+    let add = 0
+    let update = 0
+    let del = 0
+    for (const change of summary.fileChanges) {
+      if (change.kind === 'add') add++
+      else if (change.kind === 'delete') del++
+      else update++
+    }
+    lines.push(`files: add=${add} update=${update} delete=${del}`)
+  }
+  if (summary.tokens) {
+    const t = summary.tokens
+    lines.push(
+      `tokens: input=${t.input} cached=${t.cached} output=${t.output} reasoning=${t.reasoning}`,
+    )
+  }
+  if (summary.finalMessage) {
+    lines.push(`final_message:\n${summary.finalMessage}`)
+  }
+  return lines.join('\n')
+}
+
+function isFailedCommand(command: CodexRunSummary['commands'][number]): boolean {
+  return (
+    command.status === 'failed' ||
+    (command.exitCode !== null && command.exitCode !== 0)
+  )
+}
+
 function buildCodexClientOptions(
   codex: CodexOptions | undefined,
 ): CodexSdkClientOptions {

package/src/index.ts

@@ -50,6 +50,7 @@ export { createSessionId, createBaseState, extendBaseState } from './state.js'
 
 // Agent integration
 export { runAgent, logStep } from './agent.js'
+export { buildCodexRunSummary, formatCodexRunSummary } from './codex.js'
 
 // Response parsing
 export {
@@ -91,6 +92,7 @@ export type {
   BackendType,
   PermissionMode,
   ClaudeCodeOptions,
+  PiOptions,
   CodexApprovalPolicy,
   CodexConfigValue,
   CodexOptions,
@@ -116,6 +118,10 @@ export type {
   // Agent types
   RunAgentOptions,
   RunAgentResult,
+  CodexRunSummary,
+  CodexRunCommand,
+  CodexRunFileChange,
+  CodexRunTokens,
   // Correction types
   CorrectionMethod,
   CorrectionConfig,

package/src/pi.ts

@@ -0,0 +1,383 @@
+/**
+ * ocpipe Pi coding-agent integration.
+ *
+ * Runs Pi through its JSONL RPC mode.
+ */
+
+import { spawn, type ChildProcess } from 'child_process'
+import { createInterface } from 'readline'
+import { join } from 'path'
+import { homedir } from 'os'
+import { PROJECT_ROOT } from './paths.js'
+import type { PiOptions, RunAgentOptions, RunAgentResult } from './types.js'
+
+interface PiProcessRequest {
+  command: string
+  args: string[]
+  cwd: string
+  env: NodeJS.ProcessEnv
+}
+
+export interface PiConnection {
+  send(line: string): void
+  recv(signal?: AbortSignal): Promise<string>
+  close(): void
+}
+
+export interface PiProcess {
+  start(req: PiProcessRequest): PiConnection
+}
+
+interface PiRPCState {
+  sessionID: string
+  modelSummary: string
+}
+
+const defaultPiCommand = 'pi'
+
+/** runPiAgent executes a Pi coding-agent turn over JSONL RPC. */
+export async function runPiAgent(
+  options: RunAgentOptions,
+  processRunner: PiProcess = commandPiProcess,
+): Promise<RunAgentResult> {
+  const {
+    prompt,
+    model,
+    sessionId,
+    timeoutSec = 3600,
+    workdir,
+    pi,
+    signal,
+  } = options
+
+  if (signal?.aborted) {
+    throw new Error('Request aborted')
+  }
+
+  const cwd = workdir ?? PROJECT_ROOT
+  const sessionInfo = sessionId ? `[session:${sessionId}]` : '[new session]'
+  const promptPreview = prompt.slice(0, 50).replace(/\n/g, ' ')
+  console.error(
+    `\n>>> Pi [${model.modelID}] ${sessionInfo}: ${promptPreview}...`,
+  )
+
+  const abort = new AbortController()
+  const abortHandler = () => abort.abort()
+  signal?.addEventListener('abort', abortHandler, { once: true })
+  let timedOut = false
+  const timeout =
+    timeoutSec > 0 ?
+      setTimeout(() => {
+        timedOut = true
+        abort.abort()
+      }, timeoutSec * 1000)
+    : null
+
+  const conn = processRunner.start({
+    command: pi?.command ?? defaultPiCommand,
+    args: buildPiArgs(model.modelID, sessionId, pi),
+    cwd,
+    env: buildPiEnv(pi),
+  })
+  const client = new PiRPCClient(conn)
+
+  try {
+    const initial = await client.getState(abort.signal)
+    await client.prompt(prompt, abort.signal)
+    await client.waitAgentEnd(abort.signal)
+    const response = await client.getLastAssistantText(abort.signal)
+    const final = await client.getState(abort.signal)
+    const nextSessionId = firstNonEmpty(
+      final.sessionID,
+      initial.sessionID,
+      sessionId ?? '',
+    )
+    if (!nextSessionId) {
+      throw new Error('Pi RPC did not emit a provider session ID')
+    }
+    if (!response) {
+      throw new Error('Pi RPC returned an empty final message')
+    }
+    const modelSummary =
+      final.modelSummary ? ` model=${final.modelSummary}` : ''
+    console.error(
+      `<<< Pi done (${response.length} chars) [session:${nextSessionId}]${modelSummary}`,
+    )
+    return {
+      text: response,
+      sessionId: nextSessionId,
+    }
+  } catch (err) {
+    if (timedOut) {
+      throw new Error(`Timeout after ${timeoutSec}s`, { cause: err })
+    }
+    if (signal?.aborted) {
+      throw new Error('Request aborted', { cause: err })
+    }
+    throw err
+  } finally {
+    if (timeout) clearTimeout(timeout)
+    signal?.removeEventListener('abort', abortHandler)
+    conn.close()
+  }
+}
+
+function buildPiArgs(
+  modelID: string,
+  sessionId: string | undefined,
+  pi: PiOptions | undefined,
+): string[] {
+  const args = ['--mode', 'rpc', '--approve']
+  const sessionDir = piSessionDir(pi)
+  if (sessionDir) {
+    args.push('--session-dir', sessionDir)
+  }
+  if (sessionId) {
+    args.push('--session-id', sessionId)
+  }
+  if (modelID) {
+    args.push('--model', modelID)
+  }
+  return args
+}
+
+function buildPiEnv(pi: PiOptions | undefined): NodeJS.ProcessEnv {
+  const providerHome = piProviderHome(pi)
+  const sessionDir = piSessionDir(pi)
+  return {
+    ...process.env,
+    ...pi?.env,
+    PI_CODING_AGENT_DIR: providerHome,
+    PI_CODING_AGENT_SESSION_DIR: sessionDir,
+    ...(pi?.baseUrl ? { LLAMA_BASE_URL: pi.baseUrl } : {}),
+  }
+}
+
+function piProviderHome(pi: PiOptions | undefined): string {
+  return pi?.providerHome ?? join(homedir(), '.pi-coding-agent')
+}
+
+function piSessionDir(pi: PiOptions | undefined): string {
+  return pi?.sessionDir ?? join(piProviderHome(pi), 'sessions')
+}
+
+class PiRPCClient {
+  private nextID = 0
+
+  constructor(private readonly conn: PiConnection) {}
+
+  async prompt(message: string, signal?: AbortSignal): Promise<void> {
+    const response = await this.request('prompt', { message }, signal)
+    const command = piString(response.command)
+    if (command && command !== 'prompt') {
+      throw new Error(`Pi RPC command mismatch: expected prompt got ${command}`)
+    }
+  }
+
+  async getState(signal?: AbortSignal): Promise<PiRPCState> {
+    const response = await this.request('get_state', {}, signal)
+    const data = piObject(response.data, 'Pi get_state response missing data')
+    return {
+      sessionID: piString(data.sessionId),
+      modelSummary: piModelSummary(data.model),
+    }
+  }
+
+  async getLastAssistantText(signal?: AbortSignal): Promise<string> {
+    const response = await this.request('get_last_assistant_text', {}, signal)
+    const data = piObject(
+      response.data,
+      'Pi get_last_assistant_text response missing data',
+    )
+    return piString(data.text)
+  }
+
+  async waitAgentEnd(signal?: AbortSignal): Promise<void> {
+    for (;;) {
+      const { value } = await this.recv(signal)
+      if (piString(value.type) === 'agent_end') {
+        return
+      }
+    }
+  }
+
+  private async request(
+    type: string,
+    fields: Record<string, string>,
+    signal?: AbortSignal,
+  ): Promise<Record<string, unknown>> {
+    this.nextID++
+    const id = `ocpipe-pi-${this.nextID}`
+    this.conn.send(JSON.stringify({ type, id, ...fields }))
+    for (;;) {
+      const { value, line } = await this.recv(signal)
+      if (piString(value.type) !== 'response' || piString(value.id) !== id) {
+        continue
+      }
+      if (value.success !== true) {
+        const errorText = piString(value.error) || line
+        throw new Error(`Pi RPC ${type} failed: ${errorText}`)
+      }
+      return value
+    }
+  }
+
+  private async recv(
+    signal?: AbortSignal,
+  ): Promise<{ value: Record<string, unknown>; line: string }> {
+    const line = await this.conn.recv(signal)
+    let parsed: unknown
+    try {
+      parsed = JSON.parse(line)
+    } catch (err) {
+      throw new Error(`Parse Pi RPC JSONL failed: ${line}`, { cause: err })
+    }
+    return { value: piObject(parsed, 'Pi RPC line must be an object'), line }
+  }
+}
+
+const commandPiProcess: PiProcess = {
+  start(req) {
+    const child = spawn(req.command, req.args, {
+      cwd: req.cwd,
+      env: req.env,
+      stdio: ['pipe', 'pipe', 'inherit'],
+    })
+    return new CommandPiConnection(child)
+  },
+}
+
+class CommandPiConnection implements PiConnection {
+  private readonly lines: string[] = []
+  private readonly waiters: Array<{
+    resolve: (line: string) => void
+    reject: (err: Error) => void
+    signal?: AbortSignal
+    abort?: () => void
+  }> = []
+  private closedError: Error | null = null
+
+  constructor(private readonly child: ChildProcess) {
+    if (!child.stdout || !child.stdin) {
+      throw new Error('Pi RPC process pipes were not opened')
+    }
+    const rl = createInterface({ input: child.stdout })
+    rl.on('line', (line) => this.push(line))
+    child.on('error', (err) => this.closeWith(err))
+    child.on('close', (code, signal) => {
+      if (this.closedError) return
+      if (code === 0) {
+        this.closeWith(new Error('Pi RPC closed'))
+        return
+      }
+      const detail = signal ? `signal ${signal}` : `status ${code}`
+      this.closeWith(new Error(`Pi RPC exited with ${detail}`))
+    })
+  }
+
+  send(line: string): void {
+    if (!this.child.stdin) {
+      throw new Error('Pi RPC stdin is closed')
+    }
+    this.child.stdin.write(line.trimEnd() + '\n')
+  }
+
+  recv(signal?: AbortSignal): Promise<string> {
+    if (this.lines.length > 0) {
+      return Promise.resolve(this.lines.shift() ?? '')
+    }
+    if (this.closedError) {
+      return Promise.reject(this.closedError)
+    }
+    if (signal?.aborted) {
+      return Promise.reject(new Error('Request aborted'))
+    }
+    return new Promise((resolve, reject) => {
+      const waiter = {
+        resolve,
+        reject,
+        signal,
+        abort: undefined as (() => void) | undefined,
+      }
+      waiter.abort = () => {
+        this.removeWaiter(waiter)
+        reject(new Error('Request aborted'))
+      }
+      signal?.addEventListener('abort', waiter.abort, { once: true })
+      this.waiters.push(waiter)
+    })
+  }
+
+  close(): void {
+    this.child.stdin?.destroy()
+    this.child.kill()
+  }
+
+  private push(line: string): void {
+    const waiter = this.waiters.shift()
+    if (!waiter) {
+      this.lines.push(line)
+      return
+    }
+    if (waiter.abort) {
+      waiter.signal?.removeEventListener('abort', waiter.abort)
+    }
+    waiter.resolve(line)
+  }
+
+  private closeWith(err: Error): void {
+    this.closedError = err
+    for (const waiter of this.waiters.splice(0)) {
+      if (waiter.abort) {
+        waiter.signal?.removeEventListener('abort', waiter.abort)
+      }
+      waiter.reject(err)
+    }
+  }
+
+  private removeWaiter(waiter: (typeof this.waiters)[number]): void {
+    const idx = this.waiters.indexOf(waiter)
+    if (idx >= 0) {
+      this.waiters.splice(idx, 1)
+    }
+  }
+}
+
+function piObject(value: unknown, message: string): Record<string, unknown> {
+  if (typeof value !== 'object' || value === null || Array.isArray(value)) {
+    throw new Error(message)
+  }
+  return value as Record<string, unknown>
+}
+
+function piString(value: unknown): string {
+  return typeof value === 'string' ? value.trim() : ''
+}
+
+function piModelSummary(value: unknown): string {
+  if (typeof value !== 'object' || value === null || Array.isArray(value)) {
+    return ''
+  }
+  const model = value as Record<string, unknown>
+  const provider = firstNonEmpty(
+    piString(model.provider),
+    piString(model.providerId),
+  )
+  const id = firstNonEmpty(
+    piString(model.id),
+    piString(model.model),
+    piString(model.name),
+  )
+  if (provider && id) {
+    return `${provider}/${id}`
+  }
+  return firstNonEmpty(id, provider)
+}
+
+function firstNonEmpty(...values: string[]): string {
+  for (const value of values) {
+    const trimmed = value.trim()
+    if (trimmed) return trimmed
+  }
+  return ''
+}

package/src/pipeline.ts

@@ -35,6 +35,7 @@ export class Pipeline<S extends BaseState> {
       workdir: config.workdir,
       claudeCode: config.claudeCode,
       codex: config.codex,
+      pi: config.pi,
     }
   }
 

package/src/predict.ts

@@ -78,6 +78,7 @@ export class Predict<S extends AnySignature> {
       workdir: ctx.workdir,
       claudeCode: ctx.claudeCode,
       codex: ctx.codex,
+      pi: ctx.pi,
       signal: ctx.signal,
     })
 
@@ -209,6 +210,7 @@ export class Predict<S extends AnySignature> {
         workdir: ctx.workdir,
         claudeCode: ctx.claudeCode,
         codex: ctx.codex,
+        pi: ctx.pi,
         signal: ctx.signal,
       })
 
@@ -287,6 +289,7 @@ export class Predict<S extends AnySignature> {
         workdir: ctx.workdir,
         claudeCode: ctx.claudeCode,
         codex: ctx.codex,
+        pi: ctx.pi,
         signal: ctx.signal,
       })
 

package/src/types.ts

@@ -9,7 +9,7 @@ import type { z } from 'zod/v4'
 // ============================================================================
 
 /** Backend type for running agents. */
-export type BackendType = 'opencode' | 'claude-code' | 'codex'
+export type BackendType = 'opencode' | 'claude-code' | 'codex' | 'pi'
 
 /** Reasoning effort for Codex SDK threads. */
 export type CodexReasoningEffort =
@@ -119,6 +119,20 @@ export interface CodexOptions {
   webSearchEnabled?: boolean
 }
 
+/** Pi coding agent specific session options. */
+export interface PiOptions {
+  /** Path to the Pi executable (default: `pi` from PATH). */
+  command?: string
+  /** Pi runtime home passed as PI_CODING_AGENT_DIR. */
+  providerHome?: string
+  /** Pi session directory passed by flag and PI_CODING_AGENT_SESSION_DIR. */
+  sessionDir?: string
+  /** Base URL passed as LLAMA_BASE_URL. */
+  baseUrl?: string
+  /** Extra environment variables passed to the Pi subprocess. */
+  env?: Record<string, string>
+}
+
 /** Model configuration for LLM backends. */
 export interface ModelConfig {
   /** Backend to use (default: 'opencode'). */
@@ -152,6 +166,8 @@ export interface ExecutionContext {
   claudeCode?: ClaudeCodeOptions
   /** Codex SDK specific options. */
   codex?: CodexOptions
+  /** Pi coding agent specific options. */
+  pi?: PiOptions
   /** AbortSignal for cancelling in-flight backend requests. */
   signal?: AbortSignal
 }
@@ -372,6 +388,8 @@ export interface PipelineConfig {
   claudeCode?: ClaudeCodeOptions
   /** Codex SDK specific options. */
   codex?: CodexOptions
+  /** Pi coding agent specific options. */
+  pi?: PiOptions
 }
 
 /** Options for running a pipeline step. */
@@ -408,6 +426,8 @@ export interface RunAgentOptions {
   claudeCode?: ClaudeCodeOptions
   /** Codex SDK specific options. */
   codex?: CodexOptions
+  /** Pi coding agent specific options. */
+  pi?: PiOptions
   /** AbortSignal for cancelling the request. */
   signal?: AbortSignal
 }
@@ -418,4 +438,38 @@ export interface RunAgentResult {
   text: string
   /** Session ID (for continuing the conversation). */
   sessionId: string
+  /** Clean run summary, set for the Codex backend. */
+  runSummary?: CodexRunSummary
+}
+
+/** CodexRunCommand records one command the Codex agent executed. */
+export interface CodexRunCommand {
+  command: string
+  status: string
+  exitCode: number | null
+}
+
+/** CodexRunFileChange records one file the Codex agent changed. */
+export interface CodexRunFileChange {
+  path: string
+  kind: 'add' | 'update' | 'delete'
+  status: string
+}
+
+/** CodexRunTokens records token usage for a Codex turn. */
+export interface CodexRunTokens {
+  input: number
+  cached: number
+  output: number
+  reasoning: number
+}
+
+/** CodexRunSummary is the parent-readable projection of a Codex turn. */
+export interface CodexRunSummary {
+  status: 'completed' | 'failed' | 'unknown'
+  finalMessage: string
+  errorMessage: string
+  commands: CodexRunCommand[]
+  fileChanges: CodexRunFileChange[]
+  tokens: CodexRunTokens | null
 }