diff --git a/docs/prds/0039-smolmachines-capability-remediation.md b/docs/prds/0039-smolmachines-capability-remediation.md new file mode 100644 index 0000000..e7715d9 --- /dev/null +++ b/docs/prds/0039-smolmachines-capability-remediation.md @@ -0,0 +1,87 @@ +# PRD 0039: smolmachines Capability-Block Remediation + +- **Status:** Draft +- **Author:** didericis-codex +- **Created:** 2026-06-02 +- **Issue:** #136 + +## Summary + +Make capability-block remediation backend-aware. Today the dashboard approval +path calls Docker-only teardown and apply code regardless of which backend +created the bottle. Either implement smolmachines remediation or add a clean +disable/unsupported path so operators never get a partial Docker teardown +against a smolmachines slug. + +## Problem + +`bot_bottle/cli/dashboard.py` dispatches every capability-block approval to +`bot_bottle/backend/docker/capability_apply.py`. That code snapshots with +`docker cp`, pushes via `docker exec`, rewrites a Dockerfile override, and +removes Docker containers and networks. It does not stop or delete a smolvm +machine. + +smolmachines bottles still receive the capability-block supervise tool through +`backend/smolmachines/provision/supervise.py`, so agents can queue a +remediation the host cannot correctly apply. A partial Docker teardown against +a smolmachines slug corrupts neither backend cleanly. + +## Goals / Success Criteria + +- Capability-block approval is routed to backend-specific code. +- For the smolmachines backend, either: + a. A real remediation implementation that stops the VM, applies the + capability change, and restarts correctly; or + b. A clean unsupported response that tells the operator the action cannot + be taken and leaves the bottle in a consistent state. +- If option (b): smolmachines agents do not receive the capability-block tool, + so the operator is never prompted for an action that will fail. +- Unit tests cover the dispatch logic and the smolmachines path. + +## Non-goals + +- No changes to the Docker capability-apply path. +- No changes to other supervise tools (cred-block, pipelock-block). +- No changes to manifest or egress configuration. + +## Scope + +In scope: + +- `bot_bottle/cli/dashboard.py` approval dispatch. +- `bot_bottle/backend/smolmachines/provision/supervise.py` tool registration. +- New or updated backend-specific capability apply/disable module for + smolmachines. +- Unit tests for dispatch routing and smolmachines path. + +Out of scope: + +- Changes to `backend/docker/capability_apply.py` internals. +- Integration tests that exercise a live smolmachines VM remediation. + +## Design + +Introduce a backend-aware dispatch at the approval call site. Each backend +exposes a capability remediation entry point; the dashboard calls the one that +matches the bottle's backend. If the backend does not support remediation, +the entry point returns a structured error that the dashboard surfaces as an +operator message without attempting any teardown. + +If option (b) is chosen initially, suppress capability-block registration in +`smolmachines/provision/supervise.py` so agents never see the tool. + +## Testing Strategy + +- Unit test that approval dispatch selects the smolmachines path for a + smolmachines bottle and the Docker path for a Docker bottle. +- Unit test for the smolmachines path (unsupported response or real apply). +- Regression test that Docker approval still calls `capability_apply.py`. + +Run: + +- `python3 -m unittest discover -s tests/unit` + +## Open Questions + +- Is a real smolmachines capability-apply implementation in scope for this PRD, + or should it be deferred to a follow-on after PRD 0040 lands?