| 1 | # stop.py DOX |
| 2 | |
| 3 | ## Purpose |
| 4 | |
| 5 | - Own the authenticated WebUI endpoint that stops an active agent run without deleting or resetting its chat context. |
| 6 | |
| 7 | ## Ownership |
| 8 | |
| 9 | - `stop.py` resolves the requested in-memory context and exposes the shared `stop_context()` operation used by the endpoint and slash command. |
| 10 | |
| 11 | ## Runtime Contracts |
| 12 | |
| 13 | - `Stop` derives from `ApiHandler`, retaining the default authentication and CSRF protections. |
| 14 | - Input uses the selected chat ID in `context`; the endpoint never creates a missing context. |
| 15 | - Stopping cancels the context task through `AgentContext.kill_process()`, clears pause state, preserves chat history and queued messages, and does not start another run. |
| 16 | - The endpoint clears active progress and logs a terminal `Agent process stopped.` info step so the WebUI closes the interrupted process group. |
| 17 | - The response contains `message`, `context`, and a `stopped` boolean indicating whether the context was running when requested. |
| 18 | - Other authenticated entry points should call `stop_context()` so cancellation, progress cleanup, and terminal logging remain identical to the Stop button. |
| 19 | |
| 20 | ## Work Guidance |
| 21 | |
| 22 | - Keep this endpoint aligned with the composer stop-button state and the existing `AgentContext` task lifecycle. |
| 23 | |
| 24 | ## Verification |
| 25 | |
| 26 | - Run `pytest tests/test_stop_agent.py` and smoke-test stopping during model streaming and tool execution. |
| 27 | |
| 28 | ## Child DOX Index |
| 29 | |
| 30 | No child DOX files. |