Solve

When moving from a high-level roadmap to production-grade code, real project files in a deterministic runtime like codex-rs aren't just empty wrappers—they contain specific data structures, state machines, isolation logic, and fallback handlers.
Here is a breakdown of what real, production-ready files inside each core directory actually look like.

1. Root Level Configurations & Directives

codex/
├── Cargo.toml # Workspace configuration, async runtimes, sandbox bindings
├── AGENTS.md # System-level operational constraints & repo rules
├── config.default.toml # Execution limits (timeouts, token budgets, sandboxing defaults)
└── .env.example # API keys, telemetry toggles, isolated path settings

• Cargo.toml (Workspace Manifest): Defines dependencies like tokio (async engine), serde/serde_json (serialization), git2 (Git operations), bollard (Docker container API), tracing (structured logging), and anyhow/thiserror (error handling).
• AGENTS.md: Non-negotiable instructions loaded at runtime. Defines formatting rules, forbidden dependencies, and safety guardrails.

1. Core Subsystem Files (codex-rs/)

agent/ — Prompt Resolution & Execution Loop
Handles hierarchy merging and orchestrates LLM interactions.
agent/
├── src/
│ ├── lib.rs
│ ├── instruction.rs # Layered prompt resolver & precedence logic
│ ├── context.rs # Token budget manager & sliding window cache
│ └── loop.rs # Main agent step loop (think -> tool -> evaluate)

• instruction.rs contains:
• enum PrecedenceTier { System, Repo, Subdir, User, Runtime }
• struct InstructionResolver to parse AGENTS.md files recursively up the directory tree and deduplicate redundant rules using SHA-256 content hashes.
• loop.rs contains:
• async fn run_step(state: &mut AgentState) -> Result<AgentDecision>
• Error handlers that catch model output drift before invoking tools.

session/ — State Snapshotting & Interruption Recovery
Guarantees that interrupted tasks can resume seamlessly.
session/
├── src/
│ ├── store.rs # SQLite or JSON-lines state persistence on disk
│ ├── snapshot.rs # Memory & file diff snapshot data structures
│ └── events.rs # Append-only event log (Replay Log)

• snapshot.rs contains:
• struct SessionSnapshot: Stores message history, active plan step ID, pending tool calls, and git commit HEAD hash at the moment of snapshot.
• fn restore_checkpoint(session_id: Uuid) -> Result<AgentState> to re-hydrate state after system crashes or API timeouts.
• events.rs contains:
• An append-only log (Event::ToolExecuted, Event::FileModified, Event::PlanUpdated) used to replay history deterministically during debugging.

sandbox/ — Process & Filesystem Isolation
Prevents agents from breaking the host system or leaving dirty state behind.
sandbox/
├── src/
│ ├── docker.rs # Ephemeral container worker implementation
│ ├── process.rs # Local OS child process wrapper with cgroups/resource limits
│ ├── fs_overlay.rs # Read-only root with OverlayFS writable scratchpad
│ └── limits.rs # CPU, memory, and wall-clock execution limits

• docker.rs / process.rs contain:
• struct SandboxRunner: Manages container lifecycles, mounting host directories as read-only, and exposing ephemeral writable scratch spaces.
• async fn exec_command(cmd: &str, timeout: Duration) -> Result<ExecOutput> with stdout/stderr streaming and hard SIGKILL enforcement on timeout.

executor/ & tools/ — Safe Edits & Fault-Tolerant Tooling
Performs multi-file editing, Git transaction management, and robust API retries.
tools/
├── src/
│ ├── git.rs # Safe Git wrappers (branching, stash, diff generation)
│ ├── patch.rs # AST-aware diff parsing & conflict detection
│ ├── bash.rs # Shell execution tool handler
│ └── retry.rs # Exponential backoff & circuit breaker logic

• patch.rs contains:
• struct PatchApplier: Validates unified diffs before writing to disk.
• fn verify_and_apply_patch(patch: &str) -> Result<PatchResult>: Checks for overlapping edits, syntax validity, and automatically performs git checkout rollbacks if a patch corrupts a file.
• retry.rs contains:
• struct FaultTolerantTool: Wraps external tool calls with automatic retries for rate limits (429), network drops, and malformed JSON responses before failing up to the agent.

planner/ — Multi-Step DAG Execution
Tracks long-running, multi-step engineering tasks.
planner/
├── src/
│ ├── dag.rs # Directed Acyclic Graph for task steps
│ ├── step.rs # Step execution state (Pending, Running, Verified, Failed)
│ └── evaluator.rs # Milestone verification logic

• dag.rs contains:
• struct Plan { steps: Vec<PlanStep>, active_index: usize }
• Methods to re-plan or prune steps dynamically if intermediate tool outputs fail expectations.

1. Test Suites & Fixtures (tests/)

Production agent repos require extensive integration test fixtures:
tests/
├── integration/
│ ├── test_session_resume.rs # Kills process mid-task and verifies state restore
│ ├── test_instruction_merge.rs # Tests priority conflicts across AGENTS.md files
│ └── test_patch_rollback.rs # Simulates broken syntax patch and asserts zero disk pollution
└── fixtures/
├── sample_repo/ # A mini 10-file Rust/JS repo with intentional bugs
└── mock_responses/ # Saved LLM API JSON payloads for offline testing