feat(ops): add cleanup commands

2026-02-19 13:37:43 +00:00
parent bd38a00cf0
commit bab4560dde
11 changed files with 2193 additions and 22 deletions
@@ -0,0 +1,169 @@
+# Cleanup / Garbage Collection
+
+The `agents cleanup` command group provides garbage collection for stale
+platform resources: sandboxes, checkpoints, sessions, logs, and backups.
+All operations respect configurable retention policies and protect active
+resources from accidental deletion.
+
+---
+
+## Subcommands
+
+### `agents cleanup scan`
+
+Dry-run scan that identifies stale resources without deleting anything.
+Prints a per-resource summary table and lists every item that would be
+cleaned.
+
+```
+agents cleanup scan
+```
+
+### `agents cleanup purge`
+
+Remove stale resources based on retention policies.
+
+```
+agents cleanup purge [--dry-run] [--all] [--yes|-y]
+```
+
+| Flag | Default | Description |
+|------|---------|-------------|
+| `--dry-run` | `false` | Report what would be removed without deleting. |
+| `--all` | `false` | Purge all resource types (sandboxes, checkpoints, sessions, logs, backups). Without this flag, only sandboxes and checkpoints are purged. |
+| `--yes`, `-y` | `false` | Skip the interactive confirmation prompt. |
+
+### `agents cleanup status`
+
+Display current retention policy settings.
+
+```
+agents cleanup status
+```
+
+---
+
+## Resource Types
+
+### Sandboxes
+
+Sandbox directories live in the system temp directory with prefixes
+`ca-sandbox-` and `ca-cow-sandbox-`.  A sandbox is considered stale when
+its modification time exceeds `cleanup_sandbox_max_age_hours`.  Sandboxes
+linked to a currently-running plan are skipped and logged.
+
+### Checkpoints
+
+LangGraph checkpoint files (`checkpoint_*.json`) reside under
+`<data_dir>/checkpoints/<plan_id>/`.  When a plan accumulates more
+checkpoints than `cleanup_checkpoint_max_per_plan`, the oldest files are
+pruned while always keeping the first and most recent checkpoint.
+
+### Sessions
+
+Sessions in the SQLite database that have not been updated for longer than
+`cleanup_session_inactivity_days` are eligible for removal.  Session
+cleanup is only performed when `--all` is passed to `purge`.
+
+### Logs
+
+Log files (`*.log`) under `<log_dir>` older than
+`cleanup_log_retention_days` are removed during an `--all` purge.
+
+### Backups
+
+Backup files under `<data_dir>/backups/` older than
+`cleanup_backup_retention_days` are removed during an `--all` purge.
+
+---
+
+## Configuration
+
+All retention policies are configurable via environment variables or the
+Settings model.
+
+| Setting | Env Variable | Default | Description |
+|---------|-------------|---------|-------------|
+| `cleanup_sandbox_max_age_hours` | `CLEVERAGENTS_CLEANUP_SANDBOX_MAX_AGE_HOURS` | `48` | Max sandbox age in hours before eligibility. |
+| `cleanup_checkpoint_max_per_plan` | `CLEVERAGENTS_CHECKPOINT_MAX` | `50` | Max checkpoints retained per plan. |
+| `cleanup_session_inactivity_days` | `CLEVERAGENTS_CLEANUP_SESSION_INACTIVITY_DAYS` | `30` | Days of inactivity before session is stale. |
+| `cleanup_log_retention_days` | `CLEVERAGENTS_LOG_RETENTION_DAYS` | `30` | Days to retain log files. |
+| `cleanup_backup_retention_days` | `CLEVERAGENTS_BACKUP_RETENTION_DAYS` | `7` | Days to retain backup snapshots. |
+| `cleanup_schedule` | `CLEVERAGENTS_CLEANUP_SCHEDULE` | `manual` | `manual` (user-initiated) or `auto` (stub). |
+
+These correspond to the specification config keys:
+
+- `sandbox.cleanup` → `manual` (MVP)
+- `sandbox.checkpoint.max-per-plan` → 50
+- `core.log.retention-days` → 30
+- `core.backup.retention-days` → 7
+
+---
+
+## Safety
+
+- **Active plan protection**: Sandboxes linked to a running plan ID are
+  never deleted.  The skipped items and reasons appear in the report.
+- **Confirmation prompt**: `purge` requires interactive confirmation
+  unless `--yes` is passed.
+- **Dry-run**: Both `scan` and `purge --dry-run` preview cleanup without
+  side effects.
+- **Checkpoint preservation**: The first and most recent checkpoint for
+  each plan are always retained, even when pruning excess files.
+
+---
+
+## Examples
+
+Scan for stale resources:
+
+```
+$ agents cleanup scan
+Cleanup Scan Results (dry-run)
+
+  Mode: Dry-run
+  Sandboxes        scanned=4  to remove=2  skipped=1
+  Checkpoints      scanned=120  to remove=15  skipped=0
+  Sessions         scanned=0  to remove=0  skipped=0
+  Logs             scanned=8  to remove=3  skipped=0
+  Backups          scanned=5  to remove=2  skipped=0
+
+Stale items found:
+  [sandbox] /tmp/ca-sandbox-plan123-abcd (3 days old)
+  [checkpoint] .cleveragents/checkpoints/plan456/checkpoint_003.json (excess)
+  ...
+```
+
+Purge only sandboxes and checkpoints (default):
+
+```
+$ agents cleanup purge --yes
+Cleanup Complete
+
+  Mode: Purge
+  Sandboxes        scanned=4  removed=2  skipped=1
+  Checkpoints      scanned=120  removed=15  skipped=0
+  Sessions         scanned=0  removed=0  skipped=0
+  Logs             scanned=0  removed=0  skipped=0
+  Backups          scanned=0  removed=0  skipped=0
+```
+
+Purge all resource types with dry-run preview:
+
+```
+$ agents cleanup purge --all --dry-run
+```
+
+View current retention settings:
+
+```
+$ agents cleanup status
+Cleanup Retention Policies
+
+  Sandbox max age:        48 hours
+  Checkpoint max/plan:    50
+  Session inactivity:     30 days
+  Log retention:          30 days
+  Backup retention:       7 days
+  Schedule:               manual
+```