CodexSession overview
Schemas for Codex CLI session JSONL logs. Codex writes each turn of a CLI interaction as a discrete JSON object; this module provides decoding and encoding guarantees so we can parse logs, perform migrations, and assert on historical behaviour with confidence.
Added in v0.0.0
Table of contents
- schema
- types
- Compacted (type alias)
- EventMessage (type alias)
- EventPayload (type alias)
- MessageFragment (type alias)
- ResponseItem (type alias)
- ResponsePayload (type alias)
- Session (type alias)
- SessionEntry (type alias)
- SessionHeader (type alias)
- SessionMeta (type alias)
- SummaryFragment (type alias)
- TurnContext (type alias)
schema
Compacted
Compacted session summaries emitted when Codex squashes a long log into a single message. These appear when the CLI rolls over old content but still wants to provide a human-readable synopsis.
Signature
export declare const Compacted: Schema.Struct<{
timestamp: typeof Schema.String
type: Schema.Literal<["compacted"]>
payload: Schema.Struct<{ message: typeof Schema.String }>
}>
Added in v0.0.0
EventMessage
Envelope for event_msg entries that carry operational telemetry and agent status updates alongside the core conversation stream.
Signature
export declare const EventMessage: Schema.Struct<{
timestamp: typeof Schema.String
type: Schema.Literal<["event_msg"]>
payload: Schema.Union<
[
Schema.Struct<{
type: Schema.Literal<["token_count"]>
info: Schema.NullOr<
Schema.Struct<{
total_token_usage: Schema.Struct<{
input_tokens: typeof Schema.Number
cached_input_tokens: typeof Schema.Number
output_tokens: typeof Schema.Number
reasoning_output_tokens: typeof Schema.Number
total_tokens: typeof Schema.Number
}>
last_token_usage: Schema.Struct<{
input_tokens: typeof Schema.Number
cached_input_tokens: typeof Schema.Number
output_tokens: typeof Schema.Number
reasoning_output_tokens: typeof Schema.Number
total_tokens: typeof Schema.Number
}>
model_context_window: typeof Schema.Number
}>
>
rate_limits: Schema.optional<
Schema.NullOr<
Schema.Struct<{
primary: Schema.optional<
Schema.Struct<{
used_percent: typeof Schema.Number
window_minutes: typeof Schema.Number
resets_in_seconds: typeof Schema.Number
}>
>
secondary: Schema.optional<
Schema.Struct<{
used_percent: typeof Schema.Number
window_minutes: typeof Schema.Number
resets_in_seconds: typeof Schema.Number
}>
>
}>
>
>
}>,
Schema.Struct<{ type: Schema.Literal<["turn_aborted"]>; reason: typeof Schema.String }>,
Schema.Struct<{ type: Schema.Literal<["agent_reasoning"]>; text: typeof Schema.String }>,
Schema.Struct<{ type: Schema.Literal<["agent_message"]>; message: typeof Schema.String }>,
Schema.Struct<{
type: Schema.Literal<["user_message"]>
message: typeof Schema.String
kind: typeof Schema.String
}>,
Schema.Struct<{
type: Schema.Literal<["entered_review_mode"]>
prompt: typeof Schema.String
user_facing_hint: typeof Schema.String
}>,
Schema.Struct<{ type: Schema.Literal<["exited_review_mode"]>; review_output: typeof Schema.String }>
]
>
}>
Added in v0.0.0
EventPayload
Union for the lower-level telemetry events that accompany a turn (token counts, agent diagnostics, review prompts, etc.).
Signature
export declare const EventPayload: Schema.Union<
[
Schema.Struct<{
type: Schema.Literal<["token_count"]>
info: Schema.NullOr<
Schema.Struct<{
total_token_usage: Schema.Struct<{
input_tokens: typeof Schema.Number
cached_input_tokens: typeof Schema.Number
output_tokens: typeof Schema.Number
reasoning_output_tokens: typeof Schema.Number
total_tokens: typeof Schema.Number
}>
last_token_usage: Schema.Struct<{
input_tokens: typeof Schema.Number
cached_input_tokens: typeof Schema.Number
output_tokens: typeof Schema.Number
reasoning_output_tokens: typeof Schema.Number
total_tokens: typeof Schema.Number
}>
model_context_window: typeof Schema.Number
}>
>
rate_limits: Schema.optional<
Schema.NullOr<
Schema.Struct<{
primary: Schema.optional<
Schema.Struct<{
used_percent: typeof Schema.Number
window_minutes: typeof Schema.Number
resets_in_seconds: typeof Schema.Number
}>
>
secondary: Schema.optional<
Schema.Struct<{
used_percent: typeof Schema.Number
window_minutes: typeof Schema.Number
resets_in_seconds: typeof Schema.Number
}>
>
}>
>
>
}>,
Schema.Struct<{ type: Schema.Literal<["turn_aborted"]>; reason: typeof Schema.String }>,
Schema.Struct<{ type: Schema.Literal<["agent_reasoning"]>; text: typeof Schema.String }>,
Schema.Struct<{ type: Schema.Literal<["agent_message"]>; message: typeof Schema.String }>,
Schema.Struct<{
type: Schema.Literal<["user_message"]>
message: typeof Schema.String
kind: typeof Schema.String
}>,
Schema.Struct<{
type: Schema.Literal<["entered_review_mode"]>
prompt: typeof Schema.String
user_facing_hint: typeof Schema.String
}>,
Schema.Struct<{ type: Schema.Literal<["exited_review_mode"]>; review_output: typeof Schema.String }>
]
>
Added in v0.0.0
MessageFragment
Represents the smallest atom of user or assistant prose. Codex stores rich messages as an ordered set of fragments so we preserve Markdown and other render hints verbatim when replaying logs.
Signature
export declare const MessageFragment: Schema.Struct<{
type: Schema.Literal<["input_text", "output_text"]>
text: typeof Schema.String
}>
Added in v0.0.0
ResponseItem
Envelope describing a single assistant response. The schema preserves the outer timestamp/type metadata and reuses {@link ResponsePayload} for the payload body.
Signature
export declare const ResponseItem: Schema.Struct<{
timestamp: typeof Schema.String
type: Schema.Literal<["response_item"]>
payload: Schema.Union<
[
Schema.Struct<{
type: Schema.Literal<["message"]>
role: typeof Schema.String
content: Schema.Array$<
Schema.Struct<{ type: Schema.Literal<["input_text", "output_text"]>; text: typeof Schema.String }>
>
}>,
Schema.Struct<{
type: Schema.Literal<["function_call"]>
name: typeof Schema.String
arguments: typeof Schema.String
call_id: typeof Schema.String
}>,
Schema.Struct<{
type: Schema.Literal<["function_call_output"]>
call_id: typeof Schema.String
output: typeof Schema.String
}>,
Schema.Struct<{
type: Schema.Literal<["reasoning"]>
summary: Schema.Array$<Schema.Struct<{ type: Schema.Literal<["summary_text"]>; text: typeof Schema.String }>>
content: typeof Schema.Unknown
encrypted_content: typeof Schema.String
}>
]
>
}>
Added in v0.0.0
ResponsePayload
Union of every response_item payload the CLI can emit: structured chat messages, tool invocations, tool results, and encrypted reasoning blocks. Use this schema when you only need the payload body, not the envelope.
Signature
export declare const ResponsePayload: Schema.Union<
[
Schema.Struct<{
type: Schema.Literal<["message"]>
role: typeof Schema.String
content: Schema.Array$<
Schema.Struct<{ type: Schema.Literal<["input_text", "output_text"]>; text: typeof Schema.String }>
>
}>,
Schema.Struct<{
type: Schema.Literal<["function_call"]>
name: typeof Schema.String
arguments: typeof Schema.String
call_id: typeof Schema.String
}>,
Schema.Struct<{
type: Schema.Literal<["function_call_output"]>
call_id: typeof Schema.String
output: typeof Schema.String
}>,
Schema.Struct<{
type: Schema.Literal<["reasoning"]>
summary: Schema.Array$<Schema.Struct<{ type: Schema.Literal<["summary_text"]>; text: typeof Schema.String }>>
content: typeof Schema.Unknown
encrypted_content: typeof Schema.String
}>
]
>
Added in v0.0.0
Session
Validates a complete session file. Each element is a {@link SessionEntry}, enabling bulk decode of JSONL exports directly into strongly typed structures.
Signature
export declare const Session: Schema.Array$<
Schema.Union<
[
Schema.Struct<{
id: typeof Schema.String
timestamp: typeof Schema.String
instructions: typeof Schema.String
git: Schema.optional<
Schema.Struct<{
commit_hash: typeof Schema.String
branch: typeof Schema.String
repository_url: typeof Schema.String
}>
>
}>,
Schema.Struct<{
timestamp: typeof Schema.String
type: Schema.Literal<["session_meta"]>
payload: Schema.Struct<{
id: typeof Schema.String
timestamp: typeof Schema.String
cwd: typeof Schema.String
originator: typeof Schema.String
cli_version: typeof Schema.String
instructions: typeof Schema.String
git: Schema.optional<
Schema.Struct<{
commit_hash: typeof Schema.String
branch: typeof Schema.String
repository_url: typeof Schema.String
}>
>
}>
}>,
Schema.Struct<{
timestamp: typeof Schema.String
type: Schema.Literal<["turn_context"]>
payload: Schema.Struct<{
cwd: typeof Schema.String
approval_policy: typeof Schema.String
model: typeof Schema.String
effort: Schema.NullOr<typeof Schema.String>
summary: Schema.optional<typeof Schema.String>
sandbox_policy: Schema.optional<
Schema.Struct<{
mode: typeof Schema.String
network_access: Schema.optional<typeof Schema.Boolean>
exclude_tmpdir_env_var: Schema.optional<typeof Schema.Boolean>
exclude_slash_tmp: Schema.optional<typeof Schema.Boolean>
}>
>
}>
}>,
Schema.Struct<{
timestamp: typeof Schema.String
type: Schema.Literal<["response_item"]>
payload: Schema.Union<
[
Schema.Struct<{
type: Schema.Literal<["message"]>
role: typeof Schema.String
content: Schema.Array$<
Schema.Struct<{ type: Schema.Literal<["input_text", "output_text"]>; text: typeof Schema.String }>
>
}>,
Schema.Struct<{
type: Schema.Literal<["function_call"]>
name: typeof Schema.String
arguments: typeof Schema.String
call_id: typeof Schema.String
}>,
Schema.Struct<{
type: Schema.Literal<["function_call_output"]>
call_id: typeof Schema.String
output: typeof Schema.String
}>,
Schema.Struct<{
type: Schema.Literal<["reasoning"]>
summary: Schema.Array$<
Schema.Struct<{ type: Schema.Literal<["summary_text"]>; text: typeof Schema.String }>
>
content: typeof Schema.Unknown
encrypted_content: typeof Schema.String
}>
]
>
}>,
Schema.Struct<{
timestamp: typeof Schema.String
type: Schema.Literal<["event_msg"]>
payload: Schema.Union<
[
Schema.Struct<{
type: Schema.Literal<["token_count"]>
info: Schema.NullOr<
Schema.Struct<{
total_token_usage: Schema.Struct<{
input_tokens: typeof Schema.Number
cached_input_tokens: typeof Schema.Number
output_tokens: typeof Schema.Number
reasoning_output_tokens: typeof Schema.Number
total_tokens: typeof Schema.Number
}>
last_token_usage: Schema.Struct<{
input_tokens: typeof Schema.Number
cached_input_tokens: typeof Schema.Number
output_tokens: typeof Schema.Number
reasoning_output_tokens: typeof Schema.Number
total_tokens: typeof Schema.Number
}>
model_context_window: typeof Schema.Number
}>
>
rate_limits: Schema.optional<
Schema.NullOr<
Schema.Struct<{
primary: Schema.optional<
Schema.Struct<{
used_percent: typeof Schema.Number
window_minutes: typeof Schema.Number
resets_in_seconds: typeof Schema.Number
}>
>
secondary: Schema.optional<
Schema.Struct<{
used_percent: typeof Schema.Number
window_minutes: typeof Schema.Number
resets_in_seconds: typeof Schema.Number
}>
>
}>
>
>
}>,
Schema.Struct<{ type: Schema.Literal<["turn_aborted"]>; reason: typeof Schema.String }>,
Schema.Struct<{ type: Schema.Literal<["agent_reasoning"]>; text: typeof Schema.String }>,
Schema.Struct<{ type: Schema.Literal<["agent_message"]>; message: typeof Schema.String }>,
Schema.Struct<{
type: Schema.Literal<["user_message"]>
message: typeof Schema.String
kind: typeof Schema.String
}>,
Schema.Struct<{
type: Schema.Literal<["entered_review_mode"]>
prompt: typeof Schema.String
user_facing_hint: typeof Schema.String
}>,
Schema.Struct<{ type: Schema.Literal<["exited_review_mode"]>; review_output: typeof Schema.String }>
]
>
}>,
Schema.Struct<{
timestamp: typeof Schema.String
type: Schema.Literal<["compacted"]>
payload: Schema.Struct<{ message: typeof Schema.String }>
}>,
Schema.Struct<{
type: Schema.Literal<["message"]>
timestamp: Schema.optional<typeof Schema.String>
id: Schema.NullOr<typeof Schema.String>
role: typeof Schema.String
content: Schema.Array$<
Schema.Struct<{ type: Schema.Literal<["input_text", "output_text"]>; text: typeof Schema.String }>
>
}>,
Schema.Struct<{
type: Schema.Literal<["reasoning"]>
timestamp: Schema.optional<typeof Schema.String>
id: typeof Schema.String
summary: Schema.Array$<Schema.Struct<{ type: Schema.Literal<["summary_text"]>; text: typeof Schema.String }>>
content: typeof Schema.Unknown
encrypted_content: typeof Schema.String
}>,
Schema.Struct<{
type: Schema.Literal<["function_call"]>
timestamp: Schema.optional<typeof Schema.String>
id: Schema.NullOr<typeof Schema.String>
name: typeof Schema.String
arguments: typeof Schema.String
call_id: typeof Schema.String
}>,
Schema.Struct<{
type: Schema.Literal<["function_call_output"]>
timestamp: Schema.optional<typeof Schema.String>
call_id: typeof Schema.String
output: typeof Schema.String
}>
]
>
>
Added in v0.0.0
SessionEntry
Master schema covering every JSON object Codex has written historically, including legacy top-level message/response forms. Decode with this union to safely traverse logs regardless of CLI version.
Signature
export declare const SessionEntry: Schema.Union<
[
Schema.Struct<{
id: typeof Schema.String
timestamp: typeof Schema.String
instructions: typeof Schema.String
git: Schema.optional<
Schema.Struct<{
commit_hash: typeof Schema.String
branch: typeof Schema.String
repository_url: typeof Schema.String
}>
>
}>,
Schema.Struct<{
timestamp: typeof Schema.String
type: Schema.Literal<["session_meta"]>
payload: Schema.Struct<{
id: typeof Schema.String
timestamp: typeof Schema.String
cwd: typeof Schema.String
originator: typeof Schema.String
cli_version: typeof Schema.String
instructions: typeof Schema.String
git: Schema.optional<
Schema.Struct<{
commit_hash: typeof Schema.String
branch: typeof Schema.String
repository_url: typeof Schema.String
}>
>
}>
}>,
Schema.Struct<{
timestamp: typeof Schema.String
type: Schema.Literal<["turn_context"]>
payload: Schema.Struct<{
cwd: typeof Schema.String
approval_policy: typeof Schema.String
model: typeof Schema.String
effort: Schema.NullOr<typeof Schema.String>
summary: Schema.optional<typeof Schema.String>
sandbox_policy: Schema.optional<
Schema.Struct<{
mode: typeof Schema.String
network_access: Schema.optional<typeof Schema.Boolean>
exclude_tmpdir_env_var: Schema.optional<typeof Schema.Boolean>
exclude_slash_tmp: Schema.optional<typeof Schema.Boolean>
}>
>
}>
}>,
Schema.Struct<{
timestamp: typeof Schema.String
type: Schema.Literal<["response_item"]>
payload: Schema.Union<
[
Schema.Struct<{
type: Schema.Literal<["message"]>
role: typeof Schema.String
content: Schema.Array$<
Schema.Struct<{ type: Schema.Literal<["input_text", "output_text"]>; text: typeof Schema.String }>
>
}>,
Schema.Struct<{
type: Schema.Literal<["function_call"]>
name: typeof Schema.String
arguments: typeof Schema.String
call_id: typeof Schema.String
}>,
Schema.Struct<{
type: Schema.Literal<["function_call_output"]>
call_id: typeof Schema.String
output: typeof Schema.String
}>,
Schema.Struct<{
type: Schema.Literal<["reasoning"]>
summary: Schema.Array$<
Schema.Struct<{ type: Schema.Literal<["summary_text"]>; text: typeof Schema.String }>
>
content: typeof Schema.Unknown
encrypted_content: typeof Schema.String
}>
]
>
}>,
Schema.Struct<{
timestamp: typeof Schema.String
type: Schema.Literal<["event_msg"]>
payload: Schema.Union<
[
Schema.Struct<{
type: Schema.Literal<["token_count"]>
info: Schema.NullOr<
Schema.Struct<{
total_token_usage: Schema.Struct<{
input_tokens: typeof Schema.Number
cached_input_tokens: typeof Schema.Number
output_tokens: typeof Schema.Number
reasoning_output_tokens: typeof Schema.Number
total_tokens: typeof Schema.Number
}>
last_token_usage: Schema.Struct<{
input_tokens: typeof Schema.Number
cached_input_tokens: typeof Schema.Number
output_tokens: typeof Schema.Number
reasoning_output_tokens: typeof Schema.Number
total_tokens: typeof Schema.Number
}>
model_context_window: typeof Schema.Number
}>
>
rate_limits: Schema.optional<
Schema.NullOr<
Schema.Struct<{
primary: Schema.optional<
Schema.Struct<{
used_percent: typeof Schema.Number
window_minutes: typeof Schema.Number
resets_in_seconds: typeof Schema.Number
}>
>
secondary: Schema.optional<
Schema.Struct<{
used_percent: typeof Schema.Number
window_minutes: typeof Schema.Number
resets_in_seconds: typeof Schema.Number
}>
>
}>
>
>
}>,
Schema.Struct<{ type: Schema.Literal<["turn_aborted"]>; reason: typeof Schema.String }>,
Schema.Struct<{ type: Schema.Literal<["agent_reasoning"]>; text: typeof Schema.String }>,
Schema.Struct<{ type: Schema.Literal<["agent_message"]>; message: typeof Schema.String }>,
Schema.Struct<{
type: Schema.Literal<["user_message"]>
message: typeof Schema.String
kind: typeof Schema.String
}>,
Schema.Struct<{
type: Schema.Literal<["entered_review_mode"]>
prompt: typeof Schema.String
user_facing_hint: typeof Schema.String
}>,
Schema.Struct<{ type: Schema.Literal<["exited_review_mode"]>; review_output: typeof Schema.String }>
]
>
}>,
Schema.Struct<{
timestamp: typeof Schema.String
type: Schema.Literal<["compacted"]>
payload: Schema.Struct<{ message: typeof Schema.String }>
}>,
Schema.Struct<{
type: Schema.Literal<["message"]>
timestamp: Schema.optional<typeof Schema.String>
id: Schema.NullOr<typeof Schema.String>
role: typeof Schema.String
content: Schema.Array$<
Schema.Struct<{ type: Schema.Literal<["input_text", "output_text"]>; text: typeof Schema.String }>
>
}>,
Schema.Struct<{
type: Schema.Literal<["reasoning"]>
timestamp: Schema.optional<typeof Schema.String>
id: typeof Schema.String
summary: Schema.Array$<Schema.Struct<{ type: Schema.Literal<["summary_text"]>; text: typeof Schema.String }>>
content: typeof Schema.Unknown
encrypted_content: typeof Schema.String
}>,
Schema.Struct<{
type: Schema.Literal<["function_call"]>
timestamp: Schema.optional<typeof Schema.String>
id: Schema.NullOr<typeof Schema.String>
name: typeof Schema.String
arguments: typeof Schema.String
call_id: typeof Schema.String
}>,
Schema.Struct<{
type: Schema.Literal<["function_call_output"]>
timestamp: Schema.optional<typeof Schema.String>
call_id: typeof Schema.String
output: typeof Schema.String
}>
]
>
Added in v0.0.0
SessionHeader
Validates the header stanza that Codex writes before streaming turn data. This entry records the session id and the full instruction block that guided the run; decoding it first lets tools decide whether the log matches their expectations before iterating further.
Signature
export declare const SessionHeader: Schema.Struct<{
id: typeof Schema.String
timestamp: typeof Schema.String
instructions: typeof Schema.String
git: Schema.optional<
Schema.Struct<{
commit_hash: typeof Schema.String
branch: typeof Schema.String
repository_url: typeof Schema.String
}>
>
}>
Added in v0.0.0
SessionMeta
Captures the first runtime payload produced by the CLI. It mirrors the session_meta JSON record that advertises the working directory, CLI version, and optional git metadata for the run.
Signature
export declare const SessionMeta: Schema.Struct<{
timestamp: typeof Schema.String
type: Schema.Literal<["session_meta"]>
payload: Schema.Struct<{
id: typeof Schema.String
timestamp: typeof Schema.String
cwd: typeof Schema.String
originator: typeof Schema.String
cli_version: typeof Schema.String
instructions: typeof Schema.String
git: Schema.optional<
Schema.Struct<{
commit_hash: typeof Schema.String
branch: typeof Schema.String
repository_url: typeof Schema.String
}>
>
}>
}>
Added in v0.0.0
SummaryFragment
Tagged summary snippet emitted by the reasoning trace. Consumers can render these lines to provide quick intent previews without exposing encrypted details.
Signature
export declare const SummaryFragment: Schema.Struct<{
type: Schema.Literal<["summary_text"]>
text: typeof Schema.String
}>
Added in v0.0.0
TurnContext
Describes the environment snapshot recorded for each turn. A turn context conveys sandbox settings (filesystem and network policy), the approval mode, and the model/effort knobs the operator selected.
Signature
export declare const TurnContext: Schema.Struct<{
timestamp: typeof Schema.String
type: Schema.Literal<["turn_context"]>
payload: Schema.Struct<{
cwd: typeof Schema.String
approval_policy: typeof Schema.String
model: typeof Schema.String
effort: Schema.NullOr<typeof Schema.String>
summary: Schema.optional<typeof Schema.String>
sandbox_policy: Schema.optional<
Schema.Struct<{
mode: typeof Schema.String
network_access: Schema.optional<typeof Schema.Boolean>
exclude_tmpdir_env_var: Schema.optional<typeof Schema.Boolean>
exclude_slash_tmp: Schema.optional<typeof Schema.Boolean>
}>
>
}>
}>
Added in v0.0.0
types
Compacted (type alias)
compacted summary entries.
Signature
export type Compacted = typeof CompactedSchema.Type
Added in v0.0.0
EventMessage (type alias)
event envelope entries.
Signature
export type EventMessage = typeof EventMessageSchema.Type
Added in v0.0.0
EventPayload (type alias)
The union of telemetry payloads.
Signature
export type EventPayload = typeof EventPayloadSchema.Type
Added in v0.0.0
MessageFragment (type alias)
The smallest message fragment stored in the log.
Signature
export type MessageFragment = typeof MessageFragmentSchema.Type
Added in v0.0.0
ResponseItem (type alias)
The response item envelope.
Signature
export type ResponseItem = typeof ResponseItemSchema.Type
Added in v0.0.0
ResponsePayload (type alias)
The union of assistant payload shapes.
Signature
export type ResponsePayload = typeof ResponsePayloadSchema.Type
Added in v0.0.0
Session (type alias)
Type produced when decoding {@link Session}.
Signature
export type Session = typeof SessionSchema.Type
Added in v0.0.0
SessionEntry (type alias)
A single decoded entry within a session log.
Signature
export type SessionEntry = typeof SessionEntrySchema.Type
Added in v0.0.0
SessionHeader (type alias)
The initial instruction header stanza.
Signature
export type SessionHeader = typeof SessionHeaderSchema.Type
Added in v0.0.0
SessionMeta (type alias)
The decoded session_meta header.
Signature
export type SessionMeta = typeof SessionMetaSchema.Type
Added in v0.0.0
SummaryFragment (type alias)
The reasoning summary fragment.
Signature
export type SummaryFragment = typeof SummaryFragmentSchema.Type
Added in v0.0.0
TurnContext (type alias)
Describes the decoded turn-context record.
Signature
export type TurnContext = typeof TurnContextSchema.Type
Added in v0.0.0