V17

codex-rs/codex-infty/README.md

@@ -0,0 +1,229 @@
+# Codex Infty
+
+Codex Infty is a small orchestration layer that coordinates multiple Codex roles (Solver, Director, Verifier(s)) to drive longer, multi‑step objectives with minimal human intervention. It provides:
+
+- A run orchestrator that routes messages between roles and advances the workflow.
+- A durable run store on disk with metadata and standard subfolders.
+- Default role prompts for Solver/Director/Verifier.
+- A lightweight progress reporting hook for UIs/CLIs.
+
+The crate is designed to be embedded (via the library API) and also powers the `codex infty` CLI commands.
+
+## High‑Level Flow
+
+```
+objective → Solver
+  Solver → direction_request → Director → directive → Solver
+  Solver → verification_request → Verifier(s) → aggregated summary → Solver
+  … (iterate) …
+  Solver → final_delivery → Orchestrator returns RunOutcome
+```
+
+- The Solver always speaks structured JSON. The orchestrator parses those messages and decides the next hop.
+- The Director provides crisp guidance (also JSON) that is forwarded back to the Solver.
+- One or more Verifiers assess claims and return verdicts; the orchestrator aggregates results and reports a summary to the Solver.
+- On final_delivery, the orchestrator resolves and validates the deliverable path and returns the `RunOutcome`.
+
+## Directory Layout (Run Store)
+
+When a run is created, a directory is initialized with this structure:
+
+```
+<runs_root>/<run_id>/
+  artifacts/      # long‑lived artifacts produced by the Solver
+  memory/         # durable notes, claims, context
+  index/          # indexes and caches
+  deliverable/    # final output(s) assembled by the Solver
+  run.json        # run metadata (id, timestamps, roles)
+```
+
+See: `codex-infty/src/run_store.rs`.
+
+- The orchestrator persists rollout paths and optional config paths for each role into `run.json`.
+- Metadata timestamps are updated on significant events (role spawns, handoffs, final delivery).
+- Final deliverables must remain within the run directory. Paths are canonicalized and validated.
+
+## Roles and Prompts
+
+Default base instructions are injected per role if the provided `Config` has none:
+
+- Solver: `codex-infty/src/prompts/solver.md`
+- Director: `codex-infty/src/prompts/director.md`
+- Verifier: `codex-infty/src/prompts/verifier.md`
+
+You can provide your own instructions by pre‑populating `Config.base_instructions`.
+
+## Solver Signal Contract
+
+The Solver communicates intent using JSON messages (possibly wrapped in a fenced block). The orchestrator accepts three shapes:
+
+- Direction request (sent to Director):
+
+```json
+{"type":"direction_request","prompt":"<question or decision>"}
+```
+
+- Verification request (sent to Verifier(s)):
+
+```json
+{"type":"verification_request","claim_path":"memory/claims/<file>.json","notes":null}
+```
+
+- Final delivery (completes the run):
+
+```json
+{"type":"final_delivery","deliverable_path":"deliverable/summary.txt","summary":"<short text>"}
+```
+
+JSON may be fenced as ```json … ```; the orchestrator will strip the fence.
+
+## Key Types and Modules
+
+- Orchestrator: `codex-infty/src/orchestrator.rs`
+  - `InftyOrchestrator`: spawns/resumes role sessions, drives the event loop, and routes signals.
+  - `execute_new_run` / `execute_existing_run`: one‑shot helpers that spawn/resume and then drive.
+  - `spawn_run` / `resume_run`: set up sessions and the run store.
+  - `call_role`, `relay_assistant_to_role`, `post_to_role`, `await_first_assistant`, `stream_events`: utilities when integrating custom flows.
+
+- Run store: `codex-infty/src/run_store.rs`
+  - `RunStore`, `RunMetadata`, `RoleMetadata`: metadata and persistence helpers.
+
+- Types: `codex-infty/src/types.rs`
+  - `RoleConfig`: wraps a `Config` and sets sensible defaults for autonomous flows (no approvals, full sandbox access). Also used to persist optional config paths.
+  - `RunParams`, `ResumeParams`: input to spawn/resume runs.
+  - `RunExecutionOptions`: per‑run options (objective, timeouts).
+  - `RunOutcome`: returned on successful final delivery.
+
+- Signals: `codex-infty/src/signals.rs`
+  - DTOs for director responses and verifier verdicts, and the aggregated summary type.
+
+- Progress: `codex-infty/src/progress.rs`
+  - `ProgressReporter` trait: hook for UIs/CLIs to observe solver/director/verifier activity.
+
+## Orchestrator Workflow (Details)
+
+1. Spawn or resume role sessions (Solver, Director, and zero or more Verifiers). Default prompts are applied if the role’s `Config` has no base instructions.
+2. Optionally post an `objective` to the Solver. The progress reporter is notified and the orchestrator waits for the first Solver signal.
+3. On `direction_request`:
+   - Post a structured request to the Director and await the first assistant message.
+   - Parse it into a `DirectiveResponse` and forward the normalized JSON to the Solver.
+4. On `verification_request`:
+   - Send structured requests to each Verifier and await each first assistant message.
+   - Aggregate verdicts into an `AggregatedVerifierVerdict` and post the summary back to the Solver.
+5. On `final_delivery`:
+   - Canonicalize and validate that `deliverable_path` stays within the run directory.
+   - Notify the progress reporter, touch the run store, and return `RunOutcome`.
+
+Note: The orchestrator does not re‑run verification after `final_delivery`. Verification is performed whenever the Solver issues a `verification_request` during the run.
+
+## Library Usage
+
+```rust
+use std::sync::Arc;
+use codex_core::{CodexAuth, config::Config};
+use codex_infty::{InftyOrchestrator, RoleConfig, RunParams, RunExecutionOptions};
+
+#[tokio::main]
+async fn main() -> anyhow::Result<()> {
+    // 1) Load or build a Config for each role
+    let solver_cfg: Config = load_config();
+    let mut director_cfg = solver_cfg.clone();
+    director_cfg.model = "o4-mini".into();
+
+    // 2) Build role configs
+    let solver = RoleConfig::new("solver", solver_cfg.clone());
+    let director = RoleConfig::new("director", director_cfg);
+    let verifiers = vec![RoleConfig::new("verifier-alpha", solver_cfg.clone())];
+
+    // 3) Create an orchestrator (using default runs root)
+    let auth = CodexAuth::from_api_key("sk-…");
+    let orchestrator = InftyOrchestrator::new(auth)?;
+
+    // 4) Execute a new run with an objective
+    let params = RunParams {
+        run_id: "my-run".into(),
+        run_root: None, // use default ~/.codex/infty/<run_id>
+        solver,
+        director,
+        verifiers,
+    };
+    let mut opts = RunExecutionOptions::default();
+    opts.objective = Some("Implement feature X".into());
+
+    let outcome = orchestrator.execute_new_run(params, opts).await?;
+    println!("deliverable: {}", outcome.deliverable_path.display());
+    Ok(())
+}
+# fn load_config() -> codex_core::config::Config { codex_core::config::Config::default() }
+```
+
+Resuming an existing run:
+
+```rust
+use codex_infty::{InftyOrchestrator, ResumeParams, RoleConfig};
+
+async fn resume_example(orchestrator: &InftyOrchestrator) -> anyhow::Result<()> {
+    let solver = RoleConfig::new("solver", load_config());
+    let director = RoleConfig::new("director", load_config());
+    let verifiers = vec![];
+
+    let resume = ResumeParams {
+        run_path: std::path::PathBuf::from("/path/to/run"),
+        solver,
+        director,
+        verifiers,
+    };
+    let outcome = orchestrator.execute_existing_run(resume, Default::default()).await?;
+    println!("{}", outcome.run_id);
+    Ok(())
+}
+# fn load_config() -> codex_core::config::Config { codex_core::config::Config::default() }
+```
+
+## CLI Quickstart
+
+The CLI (`codex`) exposes Infty helpers under the `infty` subcommand. Examples:
+
+```bash
+# Create a run and immediately drive toward completion
+codex infty create --run-id demo --objective "Build and test feature"
+
+# Inspect runs
+codex infty list
+codex infty show demo
+
+# Send a one-off message to a role in a running/resumable run
+codex infty drive demo solver "Summarize progress"
+```
+
+Flags allow customizing the Director’s model and reasoning effort; see `codex infty create --help`.
+
+## Progress Reporting
+
+Integrate your UI by implementing `ProgressReporter` and attaching it with `InftyOrchestrator::with_progress(...)`. You’ll receive callbacks on key milestones (objective posted, solver messages, director response, verification summaries, final delivery, etc.).
+
+## Safety and Guardrails
+
+- `RoleConfig::new` sets `SandboxPolicy::DangerFullAccess` and `AskForApproval::Never` to support autonomous flows. Adjust if your environment requires stricter policies.
+- Deliverable paths are validated to stay inside the run directory and are fully canonicalized.
+- JSON payloads are schema‑checked where applicable (e.g., solver signals and final delivery shape).
+
+## Tests
+
+Run the crate’s tests:
+
+```bash
+cargo test -p codex-infty
+```
+
+Many tests rely on mocked SSE streams and will auto‑skip in sandboxes where network is disabled.
+
+## When to Use This Crate
+
+Use `codex-infty` when you want a minimal, pragmatic multi‑role loop with:
+
+- Clear role separation and routing.
+- Durable, restart‑resilient state on disk.
+- Simple integration points (progress hooks and helper APIs).
+
+It’s intentionally small and focused so it can be embedded into larger tools or extended to meet your workflows.