Skip to content

codex_app_server_sdk.models

models

CancelResult

Bases: BaseModel

Result of cancelling a running turn continuation.

Attributes:

Name Type Description
thread_id str

Thread id for the cancelled turn.
turn_id str

Turn id that was cancelled.
steps list[ConversationStep]

Unread completed step objects accumulated since continuation cursor.
raw_events list[dict[str, Any]]

Unread raw events accumulated since continuation cursor.
was_completed bool

True if the turn was already completed when cancelling.
was_interrupted bool

True if an interrupt request was sent.

ChatContinuation

Bases: BaseModel

Opaque continuation token for resuming a timed-out running turn.

Attributes:

Name Type Description
thread_id str

Thread that owns the running turn.
turn_id str

Running turn identifier.
cursor int

Number of turn events already consumed by caller.
mode Literal['once', 'stream']

API mode that produced this continuation.

ChatResult

Bases: BaseModel

Buffered result for a single chat turn.

Attributes:

Name Type Description
thread_id str

Thread identifier used for the turn.
turn_id str

Turn identifier returned by server.
final_text str

Best-effort final assistant text assembled from events.
raw_events list[dict[str, Any]]

Raw JSON-RPC notifications consumed for the turn.
assistant_item_id str | None

Assistant item id used for final text when known.
completion_source Literal['item_completed', 'thread_read_fallback'] | None

Source used to determine final text.

CommandApprovalRequest dataclass

Server-initiated approval request for one command execution item.

CommandApprovalWithExecpolicyAmendment dataclass

Approval decision carrying an execpolicy amendment prefix rule.

ConversationStep

Bases: BaseModel

A completed, non-delta conversation step emitted during a turn.

Attributes:

Name Type Description
thread_id str

Parent thread identifier.
turn_id str

Parent turn identifier.
item_id str | None

Underlying item identifier when provided.
step_type str

Canonical label for UI/clients (e.g. thinking/exec/codex).
item_type str | None

Raw protocol item type (e.g. reasoning/commandExecution/agentMessage).
status Literal['completed']

Step lifecycle status for this event.
text str | None

Human-readable text for the step when available.
data dict[str, Any]

Full item payload and metadata for advanced consumers.

DangerFullAccessSandboxPolicy

Bases: TypedDict

No sandbox restrictions.

ExternalSandboxPolicy

Bases: TypedDict

External sandbox policy with explicit network mode.

FileChangeApprovalRequest dataclass

Server-initiated approval request for one file-change item.

FullAccessReadOnlyAccess

Bases: TypedDict

Unrestricted read-only access policy.

InitializeResult

Bases: BaseModel

Parsed result for the initialize handshake response.

Attributes:

Name Type Description
protocol_version str | None

Protocol version echoed by server, if present.
server_info dict[str, Any] | None

Optional server identity/details object.
capabilities dict[str, Any] | None

Optional capability map returned by server.
raw dict[str, Any]

Full raw initialize result payload.

ReadOnlySandboxPolicy

Bases: TypedDict

Read-only sandbox policy.

RestrictedReadOnlyAccess

Bases: TypedDict

Restricted read-only access policy.

ThreadConfig dataclass

Thread-level configuration overrides used by thread start/resume/fork calls.

Use UNSET (default) to omit a field from the request payload. Use None to explicitly send JSON null where the protocol accepts it.

Attributes:

Name Type Description
cwd str | None | UnsetType

Thread working directory.
base_instructions str | None | UnsetType

Base instruction text for the thread.
developer_instructions str | None | UnsetType

Developer instruction text for the thread.
model str | None | UnsetType

Model id for thread-level default model selection.
model_provider str | None | UnsetType

Optional model provider name/identifier.
approval_policy ApprovalPolicy | None | UnsetType

Approval policy mode (untrusted, on-failure, on-request, never).
sandbox SandboxMode | None | UnsetType

Sandbox mode selector accepted by the server (read-only, workspace-write, danger-full-access).
personality str | None | UnsetType

Optional personality profile name.
ephemeral bool | None | UnsetType

Optional ephemeral-thread flag.
config dict[str, Any] | None | UnsetType

Optional thread-level config map forwarded to the server.

TurnOverrides dataclass

Per-turn override fields forwarded to turn/start.

Use UNSET (default) to omit a field from the request payload. Use None to explicitly send JSON null where the protocol accepts it.

Attributes:

Name Type Description
cwd str | None | UnsetType

Per-turn working directory override.
model str | None | UnsetType

Per-turn model override.
effort ReasoningEffort | None | UnsetType

Reasoning effort level (none..xhigh).
summary ReasoningSummary | None | UnsetType

Reasoning summary verbosity (auto, concise, detailed, none).
sandbox_policy SandboxPolicy | dict[str, Any] | None | UnsetType

Per-turn sandbox policy payload.
personality str | None | UnsetType

Per-turn personality override.
approval_policy ApprovalPolicy | None | UnsetType

Per-turn approval policy override.
output_schema dict[str, Any] | None | UnsetType

Optional structured-output schema override.

UnsetType

Sentinel type representing an omitted configuration field.

WorkspaceWriteSandboxPolicy

Bases: TypedDict

Workspace-write sandbox policy.