From aeb82f79c09b3b242f88ffaa61d5199f7d5a4357 Mon Sep 17 00:00:00 2001 From: jif-oai Date: Thu, 16 Oct 2025 12:56:02 +0100 Subject: [PATCH] Adding a bit of docs --- codex-rs/core/src/executor/mod.rs | 29 ++++++++++++++++++++++++ codex-rs/core/src/unified_exec/mod.rs | 32 +++++++++++++++++++++++++++ 2 files changed, 61 insertions(+) diff --git a/codex-rs/core/src/executor/mod.rs b/codex-rs/core/src/executor/mod.rs index d438de314b..026d28ec84 100644 --- a/codex-rs/core/src/executor/mod.rs +++ b/codex-rs/core/src/executor/mod.rs @@ -1,3 +1,32 @@ +//! Executor: centralized sandbox policy, approvals, and execution planning. +//! +//! Purpose and responsibilities +//! - Normalizes per‑mode parameters via backends (`backends.rs`). +//! - Selects sandbox placement and handles approvals (`sandbox.rs`). +//! - Produces an `ExecutionPlan` (single source of truth for policy) that +//! callers can either execute directly via `Executor::run` (non‑PTY, piped), +//! or consume piecemeal (e.g., Unified Exec) to launch with a PTY while +//! retaining consistent policy decisions. +//! +//! Key types +//! - `ExecutionMode`: `Shell`, `InteractiveShell`, `ApplyPatch`. +//! - `ExecutionRequest`: inputs + mode + stdout streaming preference. +//! - `ExecutionPlan`: immutable snapshot of the policy decision and helpers to +//! build a `SandboxLaunch` and retry without a sandbox when approved. +//! - `SandboxLaunch`: concrete program/args/env to execute under the chosen +//! sandbox. +//! +//! Typical flows +//! - Non‑PTY (piped): `Executor::run(request, …)` handles plan → launch → +//! execution and post‑processing, including converting sandbox failures into +//! user‑facing messages. +//! - PTY (Unified Exec): build the plan with `prepare_execution_plan` and then +//! use `ExecutionPlan::attempt_with_retry_if` to drive the spawn with +//! `SandboxLaunch`; PTY I/O and buffering remain the caller’s responsibility. +//! +//! This separation keeps sandbox logic and user interaction consistent while +//! allowing different transports (piped vs PTY) to manage their own lifecycles. + mod backends; mod cache; mod runner; diff --git a/codex-rs/core/src/unified_exec/mod.rs b/codex-rs/core/src/unified_exec/mod.rs index 222384b1cf..700cf90cf4 100644 --- a/codex-rs/core/src/unified_exec/mod.rs +++ b/codex-rs/core/src/unified_exec/mod.rs @@ -1,3 +1,35 @@ +//! Unified Exec: interactive PTY execution with session management. +//! +//! Purpose and responsibilities +//! - Manages interactive PTY sessions (create, reuse, buffer output with caps). +//! - Delegates sandbox selection, approvals, and policy decisions to the +//! executor (single source of truth) via `prepare_execution_plan`. +//! - Spawns the PTY using the `SandboxLaunch` produced by the plan and reuses +//! `ExecutionPlan::attempt_with_retry_if` to optionally retry without a +//! sandbox when policy allows and the user approves. +//! - After process exit, classifies sandbox denials using the shared +//! `is_likely_sandbox_denied` heuristic so denial messages stay consistent. +//! +//! Why not call `executor.run`? +//! `executor.run` drives a non‑PTY (piped) execution flow end‑to‑end. Unified +//! Exec needs an interactive PTY that persists across requests and supports +//! streaming I/O. To keep policy logic centralized while still owning the PTY +//! lifecycle, Unified Exec builds an `ExecutionRequest` with +//! `ExecutionMode::InteractiveShell`, asks the executor for an +//! `ExecutionPlan`, then performs the PTY spawn itself with the plan’s +//! sandboxed command and environment. +//! +//! Handoff at a glance +//! 1) Build `ExecutionRequest` (interactive shell). +//! 2) `executor.update_environment(turn.sandbox_policy, turn.cwd)`. +//! 3) `plan = executor.prepare_execution_plan(request, …)`. +//! 4) `plan.attempt_with_retry_if(|launch| spawn_pty_process(launch), retry_on_denied)`. +//! 5) Buffer+stream output, apply timeouts, and return `UnifiedExecResult`. +//! +//! This structure ensures Unified Exec benefits from the same approval, +//! sandbox selection, and escalation rules as regular exec, while keeping the +//! PTY/session concerns isolated here. + use std::collections::HashMap; use std::collections::VecDeque; use std::sync::Arc;