Adding a bit of docs

This commit is contained in:
jif-oai
2025-10-16 12:56:02 +01:00
parent 802082f748
commit aeb82f79c0
2 changed files with 61 additions and 0 deletions
+29
View File
@@ -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;
+32
View File
@@ -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;