Unified Exec Process Management

Relevant source files

• codex-rs/core/src/tools/events.rs
• codex-rs/core/src/tools/handlers/apply_patch.rs
• codex-rs/core/src/tools/handlers/apply_patch_tests.rs
• codex-rs/core/src/tools/handlers/shell.rs
• codex-rs/core/src/tools/handlers/shell/shell_command.rs
• codex-rs/core/src/tools/handlers/unified_exec.rs
• codex-rs/core/src/tools/handlers/unified_exec/exec_command.rs
• codex-rs/core/src/tools/handlers/unified_exec/write_stdin.rs
• codex-rs/core/src/tools/handlers/unified_exec_tests.rs
• codex-rs/core/src/unified_exec/async_watcher.rs
• codex-rs/core/src/unified_exec/async_watcher_tests.rs
• codex-rs/core/src/unified_exec/errors.rs
• codex-rs/core/src/unified_exec/mod.rs
• codex-rs/core/src/unified_exec/mod_tests.rs
• codex-rs/core/src/unified_exec/process.rs
• codex-rs/core/src/unified_exec/process_manager.rs
• codex-rs/core/src/unified_exec/process_manager_tests.rs
• codex-rs/core/src/unified_exec/process_tests.rs
• codex-rs/core/tests/suite/unified_exec.rs

Purpose and Scope

The Unified Exec system provides interactive PTY-based process execution orchestrated with approvals and sandboxing, enabling persistent shell sessions that can maintain state across multiple tool calls. It manages PTY-backed subprocesses, their lifecycle, output buffering with caps, and enforces centralized approval and sandboxing policies using a shared orchestrator.

This page details the implementation of the Unified Exec process management layer, core tools exec_command and write_stdin, the ProcessStore for tracking active processes, and the LRU pruning mechanism for resource control.

Sources: codex-rs/core/src/unified_exec/mod.rs1-23

---

Architecture Overview

The Unified Exec architecture connects high-level tool invocation with underlying PTY process management and asynchronous event streaming.

Title: Unified Exec Component Interaction

Key Components:

• UnifiedExecProcessManager: Central coordinator handling process creation, reuse, lifecycle, and pruning codex-rs/core/src/unified_exec/mod.rs146-150
• ProcessStore: Thread-safe store tracking active process entries and reserved IDs codex-rs/core/src/unified_exec/mod.rs134-137
• ProcessEntry: Metadata for each process including process handle, call ID, last used timestamp for LRU, and associated session info codex-rs/core/src/unified_exec/mod.rs167-178
• UnifiedExecProcess: The PTY-backed process handle implementing I/O and exit status tracking codex-rs/core/src/unified_exec/process.rs88-103
• HeadTailBuffer: Efficient output buffer that retains leading and trailing output with a fixed max size, dropping middle output as needed for memory control codex-rs/core/src/unified_exec/mod.rs48
• Async watchers: Background tasks that monitor UnifiedExecProcess for incremental output and process exit, emitting structured events to the Codex session/event stream codex-rs/core/src/unified_exec/async_watcher.rs43-47

Sources: codex-rs/core/src/unified_exec/mod.rs122-178 codex-rs/core/src/unified_exec/process_manager.rs1-60 codex-rs/core/src/unified_exec/process.rs88-103

---

UnifiedExecProcessManager and ProcessStore

UnifiedExecProcessManager

The UnifiedExecProcessManager is the high-level interface managing the lifecycle of Unified Exec processes. It encapsulates a ProcessStore protected by an asynchronous Mutex to coordinate concurrent access.

• max_write_stdin_yield_time_ms defines the clamp on max wait time for output after writing stdin input codex-rs/core/src/unified_exec/mod.rs148
• Provides methods to spawn new processes (for exec_command calls) or write input to existing ones (write_stdin).
• Implements LRU pruning logic to maintain a maximum number of active processes, currently capped at 64 codex-rs/core/src/unified_exec/mod.rs73

Sources: codex-rs/core/src/unified_exec/mod.rs146-165 codex-rs/core/src/unified_exec/process_manager.rs38-47

ProcessStore

The ProcessStore holds the active processes keyed by their integer process IDs and maintains a reservation set for allocated IDs.

• Provides safe removal of processes via remove codex-rs/core/src/unified_exec/mod.rs139-144
• Prunes the least recently used processes when capacity is exceeded using timestamps stored in ProcessEntry codex-rs/core/src/unified_exec/mod.rs177

Sources: codex-rs/core/src/unified_exec/mod.rs134-144

ProcessEntry

Each stored process includes metadata necessary for management, LRU tracking, and context association:

• References the actual process handle (UnifiedExecProcess) codex-rs/core/src/unified_exec/mod.rs168
• Includes session linkage via a weak reference to prevent reference cycles codex-rs/core/src/unified_exec/mod.rs176
• Tracks last_used instant for LRU pruning codex-rs/core/src/unified_exec/mod.rs177
• Holds optional DeferredNetworkApproval for network access tracking codex-rs/core/src/unified_exec/mod.rs175

Sources: codex-rs/core/src/unified_exec/mod.rs167-178

---

Tools: exec_command and write_stdin

exec_command Tool

The exec_command tool starts a new process or reuses an existing one by spawning a PTY-backed process.

• Handled by ExecCommandHandler codex-rs/core/src/tools/handlers/unified_exec/exec_command.rs57-59
• Parses arguments like cmd, workdir, shell, and options such as tty, login, and max_output_tokens codex-rs/core/src/tools/handlers/unified_exec.rs28-48
• Resolves the effective shell command invocation considering session shell and shell modes (Direct or ZshFork) codex-rs/core/src/tools/handlers/unified_exec.rs97-142
• Intercepts apply_patch calls if the command matches patch patterns codex-rs/core/src/tools/handlers/unified_exec/exec_command.rs11
• Delegates protocol-level approval and sandboxing orchestration to ToolOrchestrator codex-rs/core/src/tools/handlers/shell.rs175-190

Title: exec_command tool execution flow

Sources: codex-rs/core/src/tools/handlers/unified_exec/exec_command.rs106-180 codex-rs/core/src/tools/handlers/unified_exec.rs97-142 codex-rs/core/src/tools/handlers/shell.rs175-190

write_stdin Tool

The write_stdin tool sends input to an existing process via its process_id.

• Managed by WriteStdinHandler codex-rs/core/src/tools/handlers/unified_exec/write_stdin.rs25
• Looks up the process entry in the ProcessStore with the requested ID.
• Uses a yield time to pause for output generation, clamping defaults to 250ms minimum codex-rs/core/src/unified_exec/mod.rs64 and 5s minimum if input is empty codex-rs/core/src/unified_exec/mod.rs67

Sources: codex-rs/core/src/unified_exec/mod.rs113-120 codex-rs/core/src/unified_exec/process_manager.rs48-49

---

Output Buffering and Streaming

HeadTailBuffer

Output from processes is buffered in a HeadTailBuffer, which stores the leading and trailing output segments, dropping intermediate content if the output grows beyond a configured limit codex-rs/core/src/unified_exec/mod.rs48

Async Output Streaming

Upon spawning a process, start_streaming_output is called:

• Runs asynchronously, reading output chunks from the UnifiedExecProcess codex-rs/core/src/unified_exec/async_watcher.rs43-47
• Emits output delta events incrementally to the session event stream via process_chunk codex-rs/core/src/unified_exec/async_watcher.rs111-119
• Respects maximum output token limits (default 10,000 tokens) codex-rs/core/src/unified_exec/mod.rs70 and total byte cap (1 MiB) codex-rs/core/src/unified_exec/mod.rs71

An exit watcher spawned by spawn_exit_watcher waits for the process termination and emits a final ExecCommandEnd event codex-rs/core/src/unified_exec/async_watcher.rs158-170

Sources: codex-rs/core/src/unified_exec/async_watcher.rs43-170 codex-rs/core/src/unified_exec/mod.rs68-73

---

Process ID and Yield Time Controls

Process ID Generation

Process IDs are generated using a random range in production, but can be forced to deterministic values for testing via set_deterministic_process_ids_for_tests codex-rs/core/src/unified_exec/mod.rs53-55

Sources: codex-rs/core/src/unified_exec/mod.rs197-202 codex-rs/core/src/unified_exec/process_manager.rs92-108

Yield Time Clamping

Output wait times after commands or input writes are clamped by clamp_yield_time codex-rs/core/src/unified_exec/mod.rs180-187:

Constant	Value (ms)	Description
MIN_YIELD_TIME_MS	250	Min normal yield time for output codex-rs/core/src/unified_exec/mod.rs64
MIN_EMPTY_YIELD_TIME_MS	5,000	Min wait time if input is empty codex-rs/core/src/unified_exec/mod.rs67
MAX_YIELD_TIME_MS	30,000	Max allowed yield time codex-rs/core/src/unified_exec/mod.rs68
WINDOWS_INITIAL_EXEC_YIELD_TIME_FLOOR_MS	2,000	Min yield time on Windows codex-rs/core/src/unified_exec/mod.rs65

Sources: codex-rs/core/src/unified_exec/mod.rs64-68 codex-rs/core/src/unified_exec/mod.rs180-187

---

LRU Pruning and Resource Limits

The UnifiedExecProcessManager enforces an upper bound on concurrently active processes:

Constant	Value	Description
MAX_UNIFIED_EXEC_PROCESSES	64	Maximum concurrent PTY processes allowed codex-rs/core/src/unified_exec/mod.rs73

When spawning a new process while capacity is reached, the manager prunes the least recently used (LRU) process by sorting entries by their last_used timestamp in the ProcessStore codex-rs/core/src/unified_exec/mod.rs177

Sources: codex-rs/core/src/unified_exec/mod.rs73 codex-rs/core/src/unified_exec/process_manager.rs39

---

Summary Table: Responsibilities of Core Entities

Component/Entity	Responsibility / Role	File and Location
UnifiedExecProcessManager	Guard process lifecycle: spawn, reuse, prune; manage IDs	codex-rs/core/src/unified_exec/mod.rs146-158
ProcessStore	Storage and bookkeeping of active processes	codex-rs/core/src/unified_exec/mod.rs134-137
ProcessEntry	Metadata per active process: call_id, timestamps, session refs	codex-rs/core/src/unified_exec/mod.rs167-178
UnifiedExecProcess	Low-level PTY and OS process handle	codex-rs/core/src/unified_exec/process.rs88-103
ExecCommandHandler	Tool handler entrypoint for exec_command	codex-rs/core/src/tools/handlers/unified_exec/exec_command.rs57-59
WriteStdinHandler	Tool handler entrypoint for write_stdin	codex-rs/core/src/tools/handlers/unified_exec/write_stdin.rs25
ToolOrchestrator	Central approval and sandbox orchestration	codex-rs/core/src/tools/orchestrator.rs31
ToolEmitter	Factory for emitting tool lifecycle events (Shell/UnifiedExec)	codex-rs/core/src/tools/events.rs130-151

---

Diagrams Bridging Natural Language to Code Entities

Diagram 1: From user prompt through exec_command tool to managed process lifecycle

Title: User Intent to Managed Process

Diagram 2: Writing to process stdin and output streaming chain

Title: write_stdin tool and output event chain

Sources: codex-rs/core/src/unified_exec/mod.rs1-202 codex-rs/core/src/unified_exec/process_manager.rs1-183 codex-rs/core/src/tools/handlers/unified_exec.rs1-142 codex-rs/core/src/tools/events.rs130-198