HAL9000
7f47ec85da
CI / build (pull_request) Successful in 1m7s
CI / lint (pull_request) Successful in 1m13s
CI / quality (pull_request) Successful in 1m13s
CI / helm (pull_request) Successful in 43s
CI / typecheck (pull_request) Successful in 1m22s
CI / security (pull_request) Successful in 1m25s
CI / push-validation (pull_request) Successful in 31s
CI / unit_tests (pull_request) Successful in 5m11s
CI / integration_tests (pull_request) Successful in 8m22s
CI / docker (pull_request) Successful in 2m22s
CI / coverage (pull_request) Successful in 10m39s
CI / status-check (pull_request) Successful in 4s
Refactor Milestones documentation to address PR #9957 reviewer feedback: - Split v3.0.0.md (506 lines) into 3 sub-pages under milestones/v3.0.0/: - index.md — Overview, goals, feature table, architecture notes (87 lines) - cli-reference.md — Full CLI command reference (142 lines) - deep-dive.md — Sandbox, persistence, domain model internals (95 lines) - Split v3.1.0.md (682 lines) into 5 sub-pages under milestones/v3.1.0/: - index.md — Overview, goals, feature table, architecture notes (69 lines) - actor-yaml.md — Actor YAML format + Compiler/LangGraph integration (131 lines) - integration.md — MCP Adapter + Tool Router provider normalization (91 lines) - skills.md — Skill Registry + Validation Runner gates (127 lines) - quickstart.md — Common workflows and reference guide (66 lines) - Update mkdocs.yml navigation to reflect the new sub-page structure - Total: from 2 files at 506/682 lines to 9 files all under 150 lines ISSUES CLOSED: #9957
3.4 KiB
3.4 KiB
v3.0.0 — Deep Dive: Sandbox, Persistence & Domain Model
Internal architecture details for CleverAgents v3.0.0.
Git Worktree Sandbox
The git worktree sandbox isolates LLM-generated changes in a dedicated branch
and worktree until the user approves them via agents plan apply.
See the full Git Worktree Sandbox module docs.
How It Works
- Plan execute creates branch
cleveragents/plan-<id>from current HEAD. - A temporary git worktree is created in a system temp directory.
- The LLM writes changes only inside the worktree (not the real repo).
plan diffshows proposed changes as unified diff.plan applymerges sandbox into original viagit merge, then cleans up.plan canceldiscards the worktree — no real repo changes.
Non-git resources (e.g. fs-directory) fall back to shutil.copy2.
Apply Summary Output
╭─ Apply Summary ────────────────────────────────────────╮
│ Plan ID: plan-01HZ... │
│ Artifacts: 3 files changed │
│ Insertions: +142 │
│ Deletions: -17 │
╰───────────────────────────────────────────────────────╯
╭─ Sandbox Cleanup ──────────────────────────────────────╮
│ [x] Worktree removed │
│ [x] Branch deleted │
╰───────────────────────────────────────────────────────╯
SQLite Persistence with Alembic
All entities persist in ~/.cleveragents/cleveragents.db.
Managed Tables
| Table | Description |
|---|---|
actions |
Action templates |
action_arguments, action_invariants |
Per-action metadata |
resources |
Resource instances |
projects, project_resource_links |
Projects and links |
plans, plan_project_links |
Plans and project bindings |
decisions |
Decision tree nodes per plan |
Migration Commands
alembic upgrade head # apply pending migrations
alembic current # show current revision
alembic history # migration history
Domain Model (Pydantic v2)
All domain entities use Pydantic v2 with frozen=True for immutability.
from cleveragents.domain.models import Action, Resource, Project, Plan
action = Action(
name="local/code-coverage",
description="Increase code coverage",
strategy_actor="openai/gpt-4",
execution_actor="openai/gpt-4",
definition_of_done="Coverage reaches target.",
)
# action.name = "other" # raises ValidationError (frozen)
ULIDs (Universally Unique Lexicographically Sortable Identifiers) are the primary keys.
See ADR-019 for storage details.
See Also
- CLI Reference — All command documentation
- Git Worktree Sandbox
- ADR-006: Plan Lifecycle
- ADR-019: Storage & Persistence