diff --git a/docs/showcase/cli-tools/actor-management-workflow.md b/docs/showcase/cli-tools/actor-management-workflow.md index dbb9664db..b0294c769 100644 --- a/docs/showcase/cli-tools/actor-management-workflow.md +++ b/docs/showcase/cli-tools/actor-management-workflow.md @@ -23,6 +23,8 @@ actor, switching the default, and cleaning up — all from the command line. - How to update actor options without replacing the full config - How to safely remove a custom actor (with impact reporting) - The naming convention: built-ins use `/`, custom actors use `local/` +- How to handle actor removal when sessions, plans, or actions reference it +- When and how to use the `--unsafe` flag for forced removal --- @@ -493,6 +495,159 @@ entry is removed. This lets you re-add the actor later with the same config. --- +## Understanding Actor Removal Impact and the `--unsafe` Flag + +When you attempt to remove an actor, CleverAgents first computes the **impact** +of that removal — how many sessions, active plans, and configured actions +reference the actor. This safeguard prevents accidental data loss. + +### Impact Reporting + +The **Impact** panel shows three counts: + +- **Sessions affected**: How many active or paused sessions are using this actor +- **Active Plans affected**: How many lifecycle plans (currently running or scheduled) depend on this actor +- **Actions Referencing**: How many configured actions (e.g., in tools or workflows) reference this actor + +If all three counts are zero, the removal is safe and proceeds immediately. + +### Non-Zero Impact Scenarios + +If any impact count is **non-zero**, the removal is **blocked by default**. This +prevents breaking active workflows. For example: + +```bash +$ python -m cleveragents actor remove local/my-production-actor +``` + +**Actual Output (blocked):** +``` +╭─────────────────────────────── Actor Removal Blocked ────────────────────────╮ +│ Name: local/my-production-actor │ +│ Provider: Anthropic │ +│ Model: claude-3-5-sonnet-20241022 │ +╰──────────────────────────────────────────────────────────────────────────────╯ +╭─────────────────────────────────── Impact ───────────────────────────────────╮ +│ Sessions: 3 affected │ +│ Active Plans: 2 affected │ +│ Actions Referencing: 5 │ +╰──────────────────────────────────────────────────────────────────────────────╯ +⚠ BLOCKED: Cannot remove actor with non-zero impact. Use --unsafe to override. +``` + +**What's Happening:** +The removal is rejected because: +- 3 sessions are actively using this actor +- 2 lifecycle plans depend on it +- 5 configured actions reference it + +To proceed, you must explicitly acknowledge the risk using the `--unsafe` flag. + +### The `--unsafe` Flag + +The `--unsafe` flag explicitly overrides the impact safeguard and forces removal +even when impact counts are non-zero. Use it only when you understand the +consequences: + +```bash +$ python -m cleveragents actor remove local/my-production-actor --unsafe +``` + +**Actual Output (forced removal):** +``` +╭─────────────────────────────── Actor Removed ────────────────────────────────╮ +│ Name: local/my-production-actor │ +│ Provider: Anthropic │ +│ Model: claude-3-5-sonnet-20241022 │ +╰──────────────────────────────────────────────────────────────────────────────╯ +╭─────────────────────────────────── Impact ───────────────────────────────────╮ +│ Sessions: 3 affected │ +│ Active Plans: 2 affected │ +│ Actions Referencing: 5 │ +╰──────────────────────────────────────────────────────────────────────────────╯ +╭────────────────────────────────── Cleanup ───────────────────────────────────╮ +│ Config: kept on disk │ +│ Contexts: 0 orphaned │ +│ ⚠ WARNING: 3 sessions will lose actor reference │ +│ ⚠ WARNING: 2 active plans will fail on next execution │ +│ ⚠ WARNING: 5 actions will reference a non-existent actor │ +╰──────────────────────────────────────────────────────────────────────────────╯ +✓ OK Actor removed (with warnings) +``` + +### When to Use `--unsafe` + +Use the `--unsafe` flag only in these scenarios: + +1. **Decommissioning a deprecated actor**: You've migrated all sessions and + plans to a new actor, but some stale action configurations still reference + the old one. You're confident they won't be executed. + +2. **Emergency cleanup**: An actor is corrupted or misconfigured, and you need + to remove it immediately to prevent further damage. You'll manually fix + affected sessions and plans afterward. + +3. **Development/testing**: You're in a development environment and don't care + about breaking test sessions or plans. + +4. **Automated cleanup**: A script is removing actors as part of a larger + migration or cleanup process, and you've already handled the affected + sessions and plans programmatically. + +### Best Practices for Safe Removal + +To remove an actor **without** using `--unsafe`: + +1. **Identify affected sessions**: Use `session list --format json` and filter + for sessions using the actor you want to remove. + +2. **Migrate or terminate sessions**: For each affected session, either: + - Migrate it to a different actor using `session update --actor ` + - Terminate it using `session terminate ` + +3. **Update or cancel plans**: For each affected active plan, either: + - Update it to use a different actor + - Cancel it using `plan cancel ` + +4. **Update action configurations**: For each action referencing the actor, + update its configuration to use a different actor or remove the action. + +5. **Remove the actor**: Once all impact counts are zero, removal proceeds safely: + +```bash +$ python -m cleveragents actor remove local/my-production-actor +``` + +**Actual Output (safe removal):** +``` +╭─────────────────────────────── Actor Removed ────────────────────────────────╮ +│ Name: local/my-production-actor │ +│ Provider: Anthropic │ +│ Model: claude-3-5-sonnet-20241022 │ +╰──────────────────────────────────────────────────────────────────────────────╯ +╭─────────────────────────────────── Impact ───────────────────────────────────╮ +│ Sessions: 0 affected │ +│ Active Plans: 0 affected │ +│ Actions Referencing: 0 │ +╰──────────────────────────────────────────────────────────────────────────────╯ +╭────────────────────────────────── Cleanup ───────────────────────────────────╮ +│ Config: kept on disk │ +│ Contexts: 0 orphaned │ +╰──────────────────────────────────────────────────────────────────────────────╯ +✓ OK Actor removed +``` + +### Safety Rules Summary + +- **Built-in actors cannot be removed** — they are system-managed and essential +- **The default actor cannot be removed** — switch the default first +- **Non-zero impact blocks removal by default** — use `--unsafe` to override +- **YAML config files are preserved** — only the registry entry is deleted +- **Removal is irreversible** — once deleted, the actor must be re-added from + the YAML file if needed + +--- + ## Built-in Actors Reference The five built-in actors registered at startup: @@ -654,6 +809,8 @@ $ python -m cleveragents actor remove local/my-haiku-actor - **`actor remove`** shows an **Impact** panel before deletion — sessions, active plans, and actions referencing the actor are counted. The YAML file on disk is preserved. +- **Impact safeguards**: Non-zero impact blocks removal by default. Use `--unsafe` + to force removal when you understand the consequences. - **Safety rules**: built-in actors cannot be removed; the current default actor cannot be removed (switch the default first).