#MoonBit Codex SDK

pnpm install -g @openai/codex@0.128.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 --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))
}

#Connect to Codex app-server

• start_thread and resume_thread return thread handles that own their thread id.
• Session-level RPCs such as plugin_list, marketplace_add, config_read, and fs_read_file are available directly on the session without exposing the raw shared event stream.
• CodexAppThread::run_streamed starts a turn and returns a per-turn stream. It registers the stream before sending turn/start, so early notifications are not lost while the RPC response is in flight.
• Turn-scoped server requests, such as approvals and user-input requests, are routed to the handler passed to the thread's streamed turn.
• Thread-scoped server requests fall back to the handler set on the thread.
• Session-level server requests fall back to the optional request_handler passed to with_app_server_session.
• next_global_event on the session receives non-turn or unregistered app-server notifications.

///|
#skip
async test {
  @codex.Codex::new().with_app_server_session(async fn(session) {
    let _ = session.plugin_list(@codex.AppPluginListParams::{
      cwds: None,
      marketplace_kinds: None,
    })
    let thread = session.start_thread()
    let review_thread = session.start_thread()
    let turn_input = [@codex.AppUserInput::AppInputText(text="hello")]
    let turn = thread.run_streamed(turn_input, request_handler=fn(request) {
      match request.details {
        @codex.AppServerRequestDetails::AppCommandExecutionApprovalRequest(_) =>
          @codex.AppServerResponse::AppCommandExecutionApprovalResponse(
            decision=@codex.AppCommandExecutionApprovalDecision::AppCommandDecline,
          )
        @codex.AppServerRequestDetails::AppFileChangeApprovalRequest(_) =>
          @codex.AppServerResponse::AppFileChangeApprovalResponse(
            decision=@codex.AppFileChangeApprovalDecision::AppFileChangeDecline,
          )
        @codex.AppServerRequestDetails::AppToolRequestUserInputRequest(_) =>
          @codex.AppServerResponse::AppToolRequestUserInputResponse(answers={})
        @codex.AppServerRequestDetails::AppDynamicToolCallRequest(_) =>
          @codex.AppServerResponse::AppDynamicToolCallResponse(
            content_items=[
              @codex.AppDynamicToolCallOutputContentItem::AppDynamicToolCallOutputText(
                text="declined",
              ),
            ],
            success=false,
          )
        @codex.AppServerRequestDetails::AppPermissionsRequestApprovalRequest(_) =>
          @codex.AppServerResponse::AppPermissionsRequestApprovalResponse(
            permissions=@codex.AppGrantedPermissionProfile::{
              network: None,
              file_system: None,
            },
            scope=@codex.AppPermissionGrantScope::AppPermissionGrantTurn,
            strict_auto_review=None,
          )
        @codex.AppServerRequestDetails::AppChatgptAuthTokensRefreshRequest(_) =>
          @codex.AppServerResponse::AppChatgptAuthTokensRefreshResponse(
            access_token="",
            chatgpt_account_id="",
            chatgpt_plan_type=None,
          )
        @codex.AppServerRequestDetails::AppAttestationGenerateRequest(_) =>
          @codex.AppServerResponse::AppAttestationGenerateResponse(token="")
        @codex.AppServerRequestDetails::AppMcpServerElicitationRequest(_) =>
          @codex.AppServerResponse::AppMcpServerElicitationResponse(
            action=@codex.AppMcpServerElicitationAction::AppMcpElicitationDecline,
            content=None,
            meta=None,
          )
      }
    })
    let review_turn = review_thread.run_streamed([
      @codex.AppUserInput::AppInputText(text="review this"),
    ])

    while turn.next() is Some(event) {
      match event.thread_event() {
        Some(@codex.Event::ItemStarted(item)) =>
          println(item.to_json().stringify())
        _ => ()
      }
    }
    review_turn.close()

    while session.next_global_event() is Some(event) {
      ignore(event)
    }
  })
}

///|
#skip
async test {
  @codex.Codex::new().with_app_server(async fn(connection) {
    while connection.next_event() is Some(event) {
      ignore(event)
    }
  })
}