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 successful turn completion was observed.
was_interrupted bool

True if the server confirmed an interrupted turn.

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.

CollaborationMode dataclass

Turn collaboration mode and settings.

CollaborationSettings dataclass

Settings associated with a collaboration mode.

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.
collaboration_mode CollaborationMode | dict[str, Any] | None | UnsetType

Optional collaboration mode configuration for this turn and subsequent turns.

UnsetType

Sentinel type representing an omitted configuration field.

UserInputAnswer dataclass

Answer payload for one question id.

UserInputOption dataclass

One selectable option for a user-input question.

UserInputQuestion dataclass

Question descriptor sent by item/tool/requestUserInput.

UserInputRequest dataclass

Server-initiated human-input request.

UserInputResponse dataclass

Response payload for item/tool/requestUserInput.

WorkspaceWriteSandboxPolicy

Bases: TypedDict

Workspace-write sandbox policy.