🥮 mooncakes.io
    Sign in

    #Codex SDK CLI for MoonBit

    The totto2727/codex-sdk/cli package owns Codex client, thread, turn, event, item, and option types.

    Consumer prerequisites, installation, imports, and the basic buffered turn are documented in the root Setup and Usage.

    #Package role

    • Client::start_thread creates a persisted conversation, while Client::resume_thread continues one by its assigned identifier.
    • Thread::run returns buffered items, final response text, and token usage.
    • Thread::run_streamed delivers typed ThreadEvent values through an async callback.
    • ClientOptions, ThreadOptions, and TurnOptions configure the executable, environment, sandbox, approval, model, search behavior, and optional JSON output schema.
    • Cancelling the task that owns a turn terminates the Codex subprocess after temporary output-schema cleanup.

    #Usage

    See the checked thread flows for buffered turns, streamed events, resumed threads, structured output, and cancellation behavior.

    #API

    Mooncakes API reference for totto2727/codex-sdk/cli

    #Client and ClientOptions

    Client owns shared options and starts or resumes persisted threads. ClientOptions controls the executable path, environment, and configuration overrides.

    #Thread, ThreadOptions, and TurnOptions

    Thread runs buffered or streamed turns. ThreadOptions configures model, sandbox, approval, and web search behavior; TurnOptions adds a per-turn JSON output schema.

    #ThreadEvent and ThreadItem

    Streamed turns expose typed lifecycle events, while completed items represent agent messages, reasoning, command executions, file changes, MCP calls, web searches, errors, and to-do lists.

    This README was generated from the share-artifact skill and README template.

    ConfigObject

    source
    type ConfigObject = Map[String, Json]

    Upstream: https://github.com/openai/codex/blob/f201c30c52a35f819262865a53df94b6f4ea7a50/sdk/typescript/src/codexOptions.ts#L3

    RunStreamedResult

    source
    type RunStreamedResult = Unit

    Upstream: https://github.com/openai/codex/blob/f201c30c52a35f819262865a53df94b6f4ea7a50/sdk/typescript/src/thread.ts#L24-L25

    StreamedTurn

    source
    type StreamedTurn = Unit

    Async type difference: MoonBit has no AsyncGenerator, so streamed events are consumed by the callback and the result is Unit.

    SdkError

    source
    pub suberror SdkError {
      InvalidConfig(path~ : String, message~ : String)
      InvalidOutputSchema(message~ : String)
      InvalidEvent(message~ : String)
      TurnFailed(message~ : String)
      ExecFailed(code~ : Int, stderr~ : String)
    } derive(Eq, 
    Debug    )

    Type difference: named variants retain upstream failure boundaries while satisfying MoonBit's typed error system.

    AgentMessageItem

    source
    pub struct AgentMessageItem {
      id : String
      text : String
    } derive(Eq, 
    Debug    , 
    FromJson    )

    Upstream: https://github.com/openai/codex/blob/f201c30c52a35f819262865a53df94b6f4ea7a50/sdk/typescript/src/items.ts#L74-L80

    ApprovalMode

    source
    pub(all) enum ApprovalMode {
      Never
      OnRequest
      OnFailure
      Untrusted
    } derive(Eq, 
    Debug    )

    Type difference: MoonBit uses an enum instead of a string-literal union.

    ApprovalMode::to_string

    source
    fn ApprovalMode::to_string(self : ApprovalMode) -> String

    Type difference: the explicit conversion is required for the MoonBit enum.

    Client

    source
    pub struct Client {
      // private fields
    }

    Upstream: https://github.com/openai/codex/blob/f201c30c52a35f819262865a53df94b6f4ea7a50/sdk/typescript/src/codex.ts#L6-L13

    Client::Client

    source
    fn Client::Client(options? : ClientOptions) -> Client

    Upstream: https://github.com/openai/codex/blob/f201c30c52a35f819262865a53df94b6f4ea7a50/sdk/typescript/src/codex.ts#L15-L19

    Client::resume_thread

    source
    fn Client::resume_thread(self : Client, id : String, options? : ThreadOptions) -> Thread

    Upstream: https://github.com/openai/codex/blob/f201c30c52a35f819262865a53df94b6f4ea7a50/sdk/typescript/src/codex.ts#L29-L38

    Client::start_thread

    source
    fn Client::start_thread(self : Client, options? : ThreadOptions) -> Thread

    Upstream: https://github.com/openai/codex/blob/f201c30c52a35f819262865a53df94b6f4ea7a50/sdk/typescript/src/codex.ts#L21-L27

    ClientOptions

    source
    pub struct ClientOptions {
      executable_path_override : 
    Path    ?
      base_url : String?
      api_key : String?
      config : Map[String, Json]?
      env : Map[String, String]?
    } derive(Eq)

    Type difference: filesystem strings are represented by Path.

    ClientOptions::ClientOptions

    source
    fn ClientOptions::ClientOptions(executable_path_override? : 
    Path    , base_url? : String, api_key? : String, config? : Map[String, Json], env? : Map[String, String]) -> ClientOptions

    Type difference: MoonBit structs require a constructor to provide the upstream empty-object defaults.

    CommandExecutionItem

    source
    pub struct CommandExecutionItem {
      id : String
      command : String
      aggregated_output : String
      exit_code : Int?
      status : CommandExecutionStatus
    } derive(Eq, 
    Debug    )

    Upstream: https://github.com/openai/codex/blob/f201c30c52a35f819262865a53df94b6f4ea7a50/sdk/typescript/src/items.ts#L8-L20

    CommandExecutionStatus

    source
    pub enum CommandExecutionStatus {
      InProgress
      Completed
      Failed
    } derive(Eq, 
    Debug    )

    Type difference: MoonBit uses an enum instead of a string-literal union.

    ErrorItem

    source
    pub struct ErrorItem {
      id : String
      message : String
    } derive(Eq, 
    Debug    , 
    FromJson    )

    Upstream: https://github.com/openai/codex/blob/f201c30c52a35f819262865a53df94b6f4ea7a50/sdk/typescript/src/items.ts#L96-L101

    Exec

    source
    type Exec

    Upstream path type and bundled-directory resolution: https://github.com/openai/codex/blob/f201c30c52a35f819262865a53df94b6f4ea7a50/sdk/typescript/src/exec.ts#L58-L65 and https://github.com/openai/codex/blob/f201c30c52a35f819262865a53df94b6f4ea7a50/sdk/typescript/src/exec.ts#L412-L430

    FileChangeItem

    source
    pub struct FileChangeItem {
      id : String
      changes : ReadOnlyArray[FileUpdateChange]
      status : PatchApplyStatus
    } derive(Eq)

    Upstream: https://github.com/openai/codex/blob/f201c30c52a35f819262865a53df94b6f4ea7a50/sdk/typescript/src/items.ts#L34-L42

    FileUpdateChange

    source
    pub struct FileUpdateChange {
      path : 
    Path
      kind : PatchChangeKind
    } derive(Eq)

    Type difference: filesystem strings are represented by Path.

    Input

    source
    pub(all) enum Input {
      Prompt(String)
      UserInputs(Array[UserInput])
    } derive(Eq)

    Type difference: MoonBit uses an enum instead of the TypeScript string-or-array union. UserInputs joins text entries with a blank line and passes local images separately to the CLI.

    ItemCompletedEvent

    source
    pub struct ItemCompletedEvent {
      item : ThreadItem
    } derive(Eq, 
    FromJson    )

    Upstream: https://github.com/openai/codex/blob/f201c30c52a35f819262865a53df94b6f4ea7a50/sdk/typescript/src/events.ts#L58-L62

    ItemStartedEvent

    source
    pub struct ItemStartedEvent {
      item : ThreadItem
    } derive(Eq, 
    FromJson    )

    Upstream: https://github.com/openai/codex/blob/f201c30c52a35f819262865a53df94b6f4ea7a50/sdk/typescript/src/events.ts#L46-L50

    ItemUpdatedEvent

    source
    pub struct ItemUpdatedEvent {
      item : ThreadItem
    } derive(Eq, 
    FromJson    )

    Upstream: https://github.com/openai/codex/blob/f201c30c52a35f819262865a53df94b6f4ea7a50/sdk/typescript/src/events.ts#L52-L56

    McpToolCallError

    source
    pub struct McpToolCallError {
      message : String
    } derive(Eq, ToJson, 
    Debug    , 
    FromJson    )

    Type difference: explicit structs replace inline TypeScript object types.

    McpToolCallItem

    source
    pub struct McpToolCallItem {
      id : String
      server : String
      tool : String
      arguments : Json
      result : McpToolCallResult?
      error : McpToolCallError?
      status : McpToolCallStatus
    } derive(Eq, 
    Debug    )

    Upstream: https://github.com/openai/codex/blob/f201c30c52a35f819262865a53df94b6f4ea7a50/sdk/typescript/src/items.ts#L47-L72

    McpToolCallResult

    source
    pub struct McpToolCallResult {
      content : ReadOnlyArray[Json]
      meta : Json?
      structured_content : Json
    } derive(Eq, 
    Debug    )

    Type difference: explicit structs replace inline TypeScript object types.

    McpToolCallStatus

    source
    pub enum McpToolCallStatus {
      McpInProgress
      McpCompleted
      McpFailed
    } derive(Eq, 
    Debug    )

    Type difference: MoonBit uses an enum instead of a string-literal union.

    ModelReasoningEffort

    source
    pub(all) enum ModelReasoningEffort {
      Minimal
      Low
      Medium
      High
      XHigh
    } derive(Eq, 
    Debug    )

    Type difference: MoonBit uses an enum instead of a string-literal union.

    ModelReasoningEffort::to_string

    source
    fn ModelReasoningEffort::to_string(self : ModelReasoningEffort) -> String

    Type difference: the explicit conversion is required for the MoonBit enum.

    PatchApplyStatus

    source
    pub enum PatchApplyStatus {
      PatchCompleted
      PatchFailed
    } derive(Eq, 
    Debug    )

    Type difference: MoonBit uses an enum instead of a string-literal union.

    PatchChangeKind

    source
    pub enum PatchChangeKind {
      Add
      Delete
      Update
    } derive(Eq, 
    Debug    )

    Type difference: MoonBit uses an enum instead of a string-literal union.

    ReasoningItem

    source
    pub struct ReasoningItem {
      id : String
      text : String
    } derive(Eq, 
    Debug    , 
    FromJson    )

    Upstream: https://github.com/openai/codex/blob/f201c30c52a35f819262865a53df94b6f4ea7a50/sdk/typescript/src/items.ts#L82-L87

    SandboxMode

    source
    pub(all) enum SandboxMode {
      ReadOnly
      WorkspaceWrite
      DangerFullAccess
    } derive(Eq, 
    Debug    )

    Type difference: MoonBit uses an enum instead of a string-literal union.

    SandboxMode::to_string

    source
    fn SandboxMode::to_string(self : SandboxMode) -> String

    Type difference: the explicit conversion is required for the MoonBit enum.

    Thread

    source
    pub struct Thread {
      // private fields
    }

    Upstream: https://github.com/openai/codex/blob/f201c30c52a35f819262865a53df94b6f4ea7a50/sdk/typescript/src/thread.ts#L40-L45

    Thread::id

    source
    fn Thread::id(self : Thread) -> String?

    Upstream: https://github.com/openai/codex/blob/f201c30c52a35f819262865a53df94b6f4ea7a50/sdk/typescript/src/thread.ts#L47-L50

    Thread::run

    source
    async fn Thread::run(self : Thread, input : Input, turn_options? : TurnOptions) -> Turn

    Upstream: https://github.com/openai/codex/blob/f201c30c52a35f819262865a53df94b6f4ea7a50/sdk/typescript/src/thread.ts#L116-L140 The returned final_response is the text from the last completed agent-message item, and usage is populated from the completed-turn event.

    Thread::run_streamed

    source
    async fn Thread::run_streamed(self : Thread, input : Input, on_event : async (ThreadEvent) -> Unit, turn_options? : TurnOptions) -> Unit

    Async type difference: the callback parameter replaces StreamedTurn.events because MoonBit has no AsyncGenerator. Cancelling the task that owns this call cancels the Codex subprocess after temporary output-schema cleanup.

    async test "run_streamed has task-owned cancellation" {
      let streamed = async fn(thread : Thread) {
        thread.run_streamed(Input::Prompt("Cancel this turn"), async fn(_) {
          @async.pause()
        })
      }
      ignore(streamed)
    }

    ThreadError

    source
    pub struct ThreadError {
      message : String
    } derive(Eq, 
    Debug    , 
    FromJson    )

    Upstream: https://github.com/openai/codex/blob/f201c30c52a35f819262865a53df94b6f4ea7a50/sdk/typescript/src/events.ts#L64-L67

    ThreadErrorEvent

    source
    pub struct ThreadErrorEvent {
      message : String
    } derive(Eq, 
    Debug    , 
    FromJson    )

    Upstream: https://github.com/openai/codex/blob/f201c30c52a35f819262865a53df94b6f4ea7a50/sdk/typescript/src/events.ts#L69-L73

    ThreadEvent

    source
    pub enum ThreadEvent {
      ThreadStarted(ThreadStartedEvent)
      TurnStarted(TurnStartedEvent)
      TurnCompleted(TurnCompletedEvent)
      TurnFailed(TurnFailedEvent)
      ItemStarted(ItemStartedEvent)
      ItemUpdated(ItemUpdatedEvent)
      ItemCompleted(ItemCompletedEvent)
      StreamError(ThreadErrorEvent)
    } derive(Eq)

    Upstream: https://github.com/openai/codex/blob/f201c30c52a35f819262865a53df94b6f4ea7a50/sdk/typescript/src/events.ts#L75-L84

    ThreadItem

    source
    pub enum ThreadItem {
      AgentMessage(AgentMessageItem)
      Reasoning(ReasoningItem)
      CommandExecution(CommandExecutionItem)
      FileChange(FileChangeItem)
      McpToolCall(McpToolCallItem)
      WebSearch(WebSearchItem)
      TodoList(TodoListItem)
      Error(ErrorItem)
    } derive(Eq)

    Type difference: MoonBit uses an enum instead of a discriminated object union.

    ThreadOptions

    source
    pub struct ThreadOptions {
      model : String?
      sandbox_mode : SandboxMode?
      working_directory : 
    Path    ?
      skip_git_repo_check : Bool?
      model_reasoning_effort : ModelReasoningEffort?
      network_access_enabled : Bool?
      web_search_mode : WebSearchMode?
      web_search_enabled : Bool?
      approval_policy : ApprovalMode?
      additional_directories : Array[
    Path    ]
    } derive(Eq)

    Type difference: filesystem strings are represented by Path.

    ThreadOptions::ThreadOptions

    source
    fn ThreadOptions::ThreadOptions(model? : String, sandbox_mode? : SandboxMode, working_directory? : 
    Path    , skip_git_repo_check? : Bool, model_reasoning_effort? : ModelReasoningEffort, network_access_enabled? : Bool, web_search_mode? : WebSearchMode, web_search_enabled? : Bool, approval_policy? : ApprovalMode, additional_directories? : Array[
    Path    ]) -> ThreadOptions

    Type difference: MoonBit structs require a constructor to provide the upstream empty-object defaults.

    test "ThreadOptions configures a thread" {
      let options = ThreadOptions::ThreadOptions(
        model="gpt-5.6",
        sandbox_mode=ReadOnly,
        approval_policy=Never,
      )
      match options.model {
        Some(model) => assert_eq(model, "gpt-5.6")
        None => fail("model is required for this example")
      }
    }

    ThreadStartedEvent

    source
    pub struct ThreadStartedEvent {
      thread_id : String
    } derive(Eq, 
    Debug    , 
    FromJson    )

    Upstream: https://github.com/openai/codex/blob/f201c30c52a35f819262865a53df94b6f4ea7a50/sdk/typescript/src/events.ts#L5-L10

    TodoItem

    source
    pub struct TodoItem {
      text : String
      completed : Bool
    } derive(Eq, ToJson, 
    Debug    , 
    FromJson    )

    Upstream: https://github.com/openai/codex/blob/f201c30c52a35f819262865a53df94b6f4ea7a50/sdk/typescript/src/items.ts#L103-L107

    TodoListItem

    source
    pub struct TodoListItem {
      id : String
      items : ReadOnlyArray[TodoItem]
    } derive(Eq, 
    Debug    )

    Upstream: https://github.com/openai/codex/blob/f201c30c52a35f819262865a53df94b6f4ea7a50/sdk/typescript/src/items.ts#L109-L117

    Turn

    source
    #alias(RunResult)
    pub struct Turn {
      items : ReadOnlyArray[ThreadItem]
      final_response : String
      usage : Usage?
    } derive(Eq)

    Upstream: https://github.com/openai/codex/blob/f201c30c52a35f819262865a53df94b6f4ea7a50/sdk/typescript/src/thread.ts#L9-L14

    TurnCompletedEvent

    source
    pub struct TurnCompletedEvent {
      usage : Usage
    } derive(Eq, 
    Debug    , 
    FromJson    )

    Upstream: https://github.com/openai/codex/blob/f201c30c52a35f819262865a53df94b6f4ea7a50/sdk/typescript/src/events.ts#L34-L38

    TurnFailedEvent

    source

    Upstream: https://github.com/openai/codex/blob/f201c30c52a35f819262865a53df94b6f4ea7a50/sdk/typescript/src/events.ts#L40-L44

    TurnOptions

    source
    pub struct TurnOptions {
      output_schema : Json?
    } derive(Eq, 
    Debug    )

    Type difference: Json replaces TypeScript unknown, and cancelling the owning MoonBit task replaces AbortSignal.

    TurnOptions::TurnOptions

    source
    fn TurnOptions::TurnOptions(output_schema? : Json) -> TurnOptions

    Type difference: MoonBit structs require a constructor to provide the upstream empty-object default.

    test "TurnOptions accepts an output schema" {
      let schema = @json.parse("{\"type\":\"object\"}")
      let options = TurnOptions::TurnOptions(output_schema=schema)
      assert_true(options.output_schema is Some(_))
    }

    TurnStartedEvent

    source

    Upstream: https://github.com/openai/codex/blob/f201c30c52a35f819262865a53df94b6f4ea7a50/sdk/typescript/src/events.ts#L12-L18

    Usage

    source
    pub struct Usage {
      input_tokens : Int
      cached_input_tokens : Int
      cache_write_input_tokens : Int
      output_tokens : Int
      reasoning_output_tokens : Int
    } derive(Eq, 
    Debug    )

    Upstream: https://github.com/openai/codex/blob/f201c30c52a35f819262865a53df94b6f4ea7a50/sdk/typescript/src/events.ts#L20-L32
    impl FromJson for Usage

    UserInput

    source
    pub(all) enum UserInput {
      Text(String)
      LocalImage(
    Path    )
    } derive(Eq)

    Type difference: MoonBit uses an enum instead of a discriminated object union, and Path replaces filesystem strings.

    WebSearchItem

    source
    pub struct WebSearchItem {
      id : String
      query : String
    } derive(Eq, 
    Debug    , 
    FromJson    )

    Upstream: https://github.com/openai/codex/blob/f201c30c52a35f819262865a53df94b6f4ea7a50/sdk/typescript/src/items.ts#L89-L94

    WebSearchMode

    source
    pub(all) enum WebSearchMode {
      Disabled
      Cached
      Live
    } derive(Eq, 
    Debug    )

    Type difference: MoonBit uses an enum instead of a string-literal union.

    WebSearchMode::to_string

    source
    fn WebSearchMode::to_string(self : WebSearchMode) -> String

    Type difference: the explicit conversion is required for the MoonBit enum.

    Source Files

    Powered by MoonBit

    Site sourceReport issuePackagesBuild queueSkillsStatistics

    © 2026 mooncakes.io