Struct CodexThread 

pub struct CodexThread { /* private fields */ }

Implementations

impl CodexThread

Conduit for the bidirectional stream of messages that compose a thread (formerly called a conversation) in Codex.

pub async fn submit(&self, op: Op) -> CodexResult<String>

pub fn session_telemetry(&self) -> SessionTelemetry

Returns the session telemetry handle for thread-scoped production instrumentation.

pub async fn shutdown_and_wait(&self) -> CodexResult<()>

pub async fn wait_until_terminated(&self)

Wait until the underlying session loop has terminated.

pub async fn emit_thread_idle_lifecycle_if_idle(&self)

pub async fn submit_with_trace( &self, op: Op, trace: Option<W3cTraceContext>, ) -> CodexResult<String>

pub async fn submit_user_input_with_client_user_message_id( &self, op: Op, trace: Option<W3cTraceContext>, client_user_message_id: Option<String>, ) -> CodexResult<String>

pub async fn set_thread_memory_mode(&self, mode: ThreadMemoryMode) -> Result<()>

Persist whether this thread is eligible for future memory generation.

pub async fn steer_input( &self, input: Vec<UserInput>, additional_context: BTreeMap<String, AdditionalContextEntry>, expected_turn_id: Option<&str>, client_user_message_id: Option<String>, responsesapi_client_metadata: Option<HashMap<String, String>>, ) -> Result<String, SteerInputError>

pub async fn inject_if_running( &self, items: Vec<ResponseItem>, ) -> Result<(), Vec<ResponseItem>>

Injects model-visible items into the currently active turn.

This is the thread-level bridge to Session::inject_if_running for callers that only hold a CodexThread. It returns the unchanged items when this thread has no active turn.

pub async fn try_start_turn_if_idle( &self, items: Vec<ResponseItem>, ) -> Result<(), TryStartTurnIfIdleError>

Starts an automatic regular turn with model-visible items only when idle work is allowed for this thread.

This is the required entry point for extensions that want to launch model-visible work from ThreadLifecycleContributor::on_thread_idle. The call succeeds only if no user/client-triggered turn is queued, no task is currently active, and the thread is not in Plan mode. Active Review tasks are rejected by the active-task check because Review turns are not steerable.

On rejection, the returned error includes a stable reason and carries the original items unchanged so the caller can decide whether to drop them, retry later, or log why no automatic turn was started.

pub async fn set_app_server_client_info( &self, app_server_client_name: Option<String>, app_server_client_version: Option<String>, mcp_elicitations_auto_deny: bool, ) -> ConstraintResult<()>

pub async fn set_openai_form_elicitation_support( &self, supported: bool, ) -> Result<()>

pub async fn preview_thread_settings_overrides( &self, overrides: CodexThreadSettingsOverrides, ) -> ConstraintResult<ThreadConfigSnapshot>

Preview persistent thread settings overrides without committing them.

pub async fn submit_with_id(&self, sub: Submission) -> CodexResult<()>

Use sparingly: this is intended to be removed soon.

pub async fn next_event(&self) -> CodexResult<Event>

pub async fn agent_status(&self) -> AgentStatus

pub async fn list_background_terminals(&self) -> Vec<BackgroundTerminalInfo>

pub async fn terminate_background_terminal(&self, process_id: i32) -> bool

pub async fn token_usage_info(&self) -> Option<TokenUsageInfo>

Returns the complete token usage snapshot currently cached for this thread.

This accessor is intentionally narrower than direct session access: it lets app-server lifecycle paths replay restored usage after resume or fork without exposing broader session mutation authority. A caller that only reads total_token_usage would drop last-turn usage and make the v2 thread/tokenUsage/updated payload incomplete.

pub async fn inject_response_items( &self, items: Vec<ResponseItem>, ) -> CodexResult<()>

Record raw Responses API items without starting a new turn.

pub fn rollout_path(&self) -> Option<PathBuf>

pub fn session_configured(&self) -> SessionConfiguredEvent

pub async fn guardian_trunk_rollout_path(&self) -> Option<PathBuf>

pub async fn load_history( &self, include_archived: bool, ) -> ThreadStoreResult<StoredThreadHistory>

pub async fn read_thread( &self, include_archived: bool, include_history: bool, ) -> ThreadStoreResult<StoredThread>

pub async fn update_thread_metadata( &self, patch: ThreadMetadataPatch, include_archived: bool, ) -> ThreadStoreResult<StoredThread>

pub async fn append_rollout_items( &self, items: &[RolloutItem], ) -> ThreadStoreResult<()>

Appends rollout items through the live thread so derived metadata stays in sync.

pub fn state_db(&self) -> Option<StateDbHandle>

pub async fn config_snapshot(&self) -> ThreadConfigSnapshot

pub async fn instruction_sources(&self) -> Vec<PathUri>

Returns the files that supplied the thread’s loaded model instructions.

pub async fn legacy_instruction_sources(&self) -> Vec<LegacyAppPathString>

Returns loaded instruction sources rendered as legacy app-server path strings.

pub async fn config(&self) -> Arc<Config>

pub async fn runtime_mcp_config(&self, config: &Config) -> McpConfig

Resolves the MCP runtime configuration using this thread’s extension data.

pub async fn current_mcp_runtime(&self) -> Arc<McpRuntimeSnapshot>

Returns the exact MCP config, environment bindings, and manager most recently published.

pub fn multi_agent_version(&self) -> Option<MultiAgentVersion>

pub async fn refresh_runtime_config(&self, next_config: Config)

Refresh the thread’s layer-backed user config state from a caller-supplied config snapshot. Thread-scoped layers and session-static settings remain unchanged.

pub async fn environment_selections(&self) -> Vec<TurnEnvironmentSelection>

pub fn inspect_selected_capability_roots(&self) -> SelectedCapabilityRootsStatus

Passively inspects the selected capability roots whose environments are ready now.

pub async fn read_mcp_resource(&self, server: &str, uri: &str) -> Result<Value>

pub async fn call_mcp_tool( &self, server: &str, tool: &str, arguments: Option<Value>, meta: Option<Value>, ) -> Result<CallToolResult>

pub fn enabled(&self, feature: Feature) -> bool

pub async fn increment_out_of_band_elicitation_count(&self) -> CodexResult<i64>

pub async fn decrement_out_of_band_elicitation_count(&self) -> CodexResult<i64>