Diagnostics & Recovery
Generic AI troubleshooting usually boils down to "try rewriting your prompt." For an enterprise tool executing native code, that is useless. This is your operations manual for when a session loops, crashes, or loses the plot.
1. The Hard Stops (UI Controls)
If an agent is going down a destructive rabbit hole, you don't need to politely ask it to stop in the chat. Cut the engine.
The Stop Button
Located in the active session UI. This gracefully interrupts the current agent loop, allowing you to inject a corrective prompt before it takes its next step.
The Kill Button
Located on the session's Info tab. This is the worst-case scenario fallback. It forcibly terminates the session's worker process immediately.
2. Built-in Loop Protections
LLMs are notoriously prone to infinite loops. Buffaly has architectural circuit breakers built in to prevent this:
- The 3-Identical-Call InterruptIf Buffaly detects the agent making three perfectly identical tool calls in a row, it automatically interrupts the loop and throws an error back to the agent to force a pivot.
- Max Tool Results Per LoopA hard cap on how much execution data an agent can digest in a single reasoning cycle, preventing the context window from exploding or hanging the worker.
3. Self-Diagnostics & Logs
Stop guessing why a tool failed or a C# service crashed. Look at the logs. Or better yet, make Buffaly look at its own logs.
Have the Agent Read the Logs
Because Buffaly has file system access, it can read its own execution history. If a native tool or ProtoScript action is failing silently, use this exact prompt:
4. Swapping Models & Providers
Different models are better at different things. If an agent is consistently failing to understand its Plan, or if a provider is experiencing high latency/timeouts, swap the brain. Change the active model or switch providers entirely for that session to unstick the logic.
5. The "Halt and Catch Fire" Prompts
When the agent is thrashing, don't ask it to "try again." Force it into a strict diagnostic state using these recovery prompts:
| The Goal | The Exact Prompt to Use |
|---|---|
| Stop blind execution | "Stop. I need you to Plan before acting. Write out exactly what you intend to do in Scratch.md before calling any more tools." |
| Stop guessing fixes | "Stop guessing. Diagnose before you fix. Identify the root cause of the error and wait for my approval." |
| Demand operational evidence | "Give me proof, not theories. Run a scoped git status, check the absolute target path, and report the actual state." |
| Context collapse recovery | "You lost the thread. Re-read Plan.md, Scratch.md, and task-01.md to regain your context, then tell me the next step." |
Where to go next
Now that you know how to survive day-to-day operations and pull the emergency brakes, it's time to learn how to actually build your own tools.