khyari hamza
170 lines
5.0 KiB
Markdown
170 lines
5.0 KiB
Markdown
# 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
|
|
```
|