#MoonBit Codex SDK

pnpm install -g @openai/codex@0.79.0

#Usage

///|
#skip
async test {
  let codex = @codex.Codex::new()
  let thread = codex.start_thread()
  let turn = thread.run("Hello, what model are you using?")
  // I’m `GPT-5.2`, running inside the Codex CLI harness in your repo (`/Users/../codex-sdk`).
  println(turn.final_response)
  println(turn.items.to_json().stringify())
  println(turn.usage.to_json().stringify())
}

///|
#skip
async test {
  let codex = @codex.Codex::new(
    options=@codex.CodexOptions::new(base_url="https://openrouter.ai/api/v1"),
  )
  let thread = codex.start_thread(
    options=@codex.ThreadOptions::new(model="anthropic/claude-sonnet-4.5"),
  )
  let turn = thread.run("Hello?")
  println(turn.final_response)
  println(turn.items.to_json().stringify())
  println(turn.usage.to_json().stringify())
}

///|
#skip
async test {
  let codex = @codex.Codex::new(
    options=@codex.CodexOptions::new(base_url="https://openrouter.ai/api/v1"),
  )
  let thread = codex.start_thread(
    options=@codex.ThreadOptions::new(model="anthropic/claude-sonnet-4.5"),
  )
  @async.with_task_group(tg => {
    let streamed_turn = thread.run_streamed("Hello?", tg)
    while streamed_turn.events.next() is Some(event) {
      println(event.to_json().stringify())
    }
  }) catch {
    e => println(e)
  }
}

#Architecture Overview

#Process boundary and transport

1. @codex.CodexExec::run spawns the CLI with --experimental-json, automatically wiring API endpoint overrides, API keys, sandbox flags, working directory overrides, and thread resumption arguments.
2. The CLI's JSONL stream is fed through @generator.AsyncGenerator so the SDK can yield events as soon as they arrive. This keeps Codex long-running commands responsive while avoiding blocking MoonBit's async runtime.
3. Each line is decoded into the rich @codex.Event / @codex.ThreadItem hierarchy (events.mbt and items.mbt), which means MoonBit callers never manipulate raw JSON.

#Thread lifecycle and safety

• Thread::run_streamed owns the async generator returned by CodexExec::run. The method updates the cached thread id when ThreadStarted surfaces, so a later Thread::run call automatically resumes the same conversation.
• Thread::run is implemented on top of the streaming primitive. It drains the generator, records AgentMessageItem content as the Turn.final_response, retains the full item history for post-processing (e.g., capturing diffs or tool invocations), and surfaces TurnFailed by raising an error after draining the iterator to prevent resource leaks.
• Structured cleanup exists everywhere a temporary artifact is created; for example, @codex::create_output_schema_file creates /tmp/codex-output-schema-* directories and ensures they are removed even when errors occur.

#Events, items, and observability

• Event::ThreadStarted, TurnStarted, TurnCompleted, and TurnFailed make it trivial to instrument throughput, retries, and token usage.
• ThreadItem variants capture everything the agent does: CommandExecutionItem surfaces shell commands with exit codes, FileChangeItem contains per-file diffs, McpToolCallItem shows MCP tool usage, and TodoListItem exposes the agent's internal plan.
• All enums (sandbox mode, approval mode, command status, etc.) expose ToJson/FromJson so you can persist structured logs or forward them to observability backends without lossy string manipulation.

#Structured output and schema enforcement

1. Creates a temporary schema file on disk.
2. Passes --output-schema /tmp/.../schema.json to the CLI.
3. Deletes the schema file after the turn completes or fails (even if exceptions arise).

#Configuration layers

• CodexOptions sets global API concerns (binary override, base URL, API key) once per process.
• ThreadOptions controls per-thread concerns such as the model, sandbox levels (read-only, workspace-write, danger-full-access), working directory routing, and Git safety checks.
• TurnOptions tunes per-turn behavior, currently focusing on structured output but intentionally keeping room for future features (e.g., custom completion criteria). Because configuration objects implement ToJson/FromJson, they can be marshalled into other systems (task schedulers, Codex automation) without reimplementing serialization.

#Advanced Usage Patterns

#Instrument streaming events

///|
#skip
async test {
  let codex = @codex.Codex::new()
  let thread = codex.start_thread()
  @async.with_task_group(tg => {
    let turn = thread.run_streamed("Summarize today's commits", tg)
    while turn.events.next() is Some(event) {
      match event {
        ItemStarted(item) => println("started: \{item.to_json().stringify()}")
        ItemCompleted(AgentMessageItem(text~, ..)) =>
          println("assistant: \{text}")
        TurnCompleted(usage) =>
          println("tokens in/out: \{usage.input_tokens}/\{usage.output_tokens}")
        TurnFailed(error) => fail("codex turn failed: \{error.message}")
        _ => ()
      }
    }
  })
}

#Enforce structured responses

///|
#skip
async test {
  let codex = @codex.Codex::new()
  let thread = codex.start_thread()
  let turn = thread.run(
    "Plan the next refactor as JSON",
    turn_options=@codex.TurnOptions::new(output_schema={
      "type": "object",
      "properties": {
        "summary": { "type": "string" },
        "files_to_touch": { "type": "array", "items": { "type": "string" } },
      },
      "required": ["summary", "files_to_touch"],
      "additionalProperties": false, // required to be supplied as valid schema
    }),
  )
  println(turn.final_response)
  let plan_json = @json.parse(turn.final_response)
  println(plan_json.stringify(indent=2))
}