LemonCliRunners.CodexSchema (lemon_cli_runners v0.1.0)

View Source

Codex CLI JSONL event schema definitions.

This module defines all the event types emitted by codex exec --json. Events are decoded from newline-delimited JSON (JSONL) format.

Event Categories

Session Lifecycle

  • ThreadStarted - Session has started with a thread_id
  • TurnStarted - New conversation turn has begun
  • TurnCompleted - Conversation turn has finished (includes usage)
  • TurnFailed - Turn failed with error

Stream Events

  • StreamError - Stream-level error or reconnection notice

Item Events

Items represent discrete work units within a turn:

  • ItemStarted - Item has begun
  • ItemUpdated - Item has progress update
  • ItemCompleted - Item has finished

Item Types

  • AgentMessageItem - Final text response from agent
  • ReasoningItem - Extended thinking/reasoning text
  • CommandExecutionItem - Shell command execution
  • FileChangeItem - File modifications
  • McpToolCallItem - MCP tool invocation
  • WebSearchItem - Web search query
  • TodoListItem - Task list
  • ErrorItem - Error message

Decoding

case CodexSchema.decode_event(json_line) do
  {:ok, %ThreadStarted{thread_id: id}} -> ...
  {:ok, %ItemCompleted{item: item}} -> ...
  {:error, reason} -> ...
end

Summary

Types

thread_event()

Union of all thread event types

thread_item()

Union of all thread item types

Functions

decode_event(json)

Decode a JSON line into a thread event struct.

decode_event_map(data)

Decode a map (already parsed JSON) into a thread event struct.

Types

thread_event()

@type thread_event() ::
  LemonCliRunners.CodexSchema.ThreadStarted.t()
  | LemonCliRunners.CodexSchema.TurnStarted.t()
  | LemonCliRunners.CodexSchema.TurnCompleted.t()
  | LemonCliRunners.CodexSchema.TurnFailed.t()
  | LemonCliRunners.CodexSchema.StreamError.t()
  | LemonCliRunners.CodexSchema.ItemStarted.t()
  | LemonCliRunners.CodexSchema.ItemUpdated.t()
  | LemonCliRunners.CodexSchema.ItemCompleted.t()

Union of all thread event types

thread_item()

@type thread_item() ::
  LemonCliRunners.CodexSchema.AgentMessageItem.t()
  | LemonCliRunners.CodexSchema.ReasoningItem.t()
  | LemonCliRunners.CodexSchema.CommandExecutionItem.t()
  | LemonCliRunners.CodexSchema.FileChangeItem.t()
  | LemonCliRunners.CodexSchema.McpToolCallItem.t()
  | LemonCliRunners.CodexSchema.WebSearchItem.t()
  | LemonCliRunners.CodexSchema.TodoListItem.t()
  | LemonCliRunners.CodexSchema.ErrorItem.t()

Union of all thread item types

Functions

decode_event(json)

@spec decode_event(String.t() | binary()) :: {:ok, thread_event()} | {:error, term()}

Decode a JSON line into a thread event struct.

Returns {:ok, event} on success or {:error, reason} on failure.

Examples

iex> CodexSchema.decode_event(~s|{"type":"thread.started","thread_id":"abc123"}|)
{:ok, %ThreadStarted{thread_id: "abc123"}}

iex> CodexSchema.decode_event(~s|{"type":"item.completed","item":{"type":"agent_message","id":"1","text":"Hello"}}|)
{:ok, %ItemCompleted{item: %AgentMessageItem{id: "1", text: "Hello"}}}

decode_event_map(data)

@spec decode_event_map(map()) :: {:ok, thread_event()} | {:error, term()}

Decode a map (already parsed JSON) into a thread event struct.