tools / tool_failure.py
Failure classification taxonomy. Decides whether a failed tool should retry, replan, or self-correct.
Classes
| Class | Patterns (regex) | Agent action |
|---|---|---|
| RETRYABLE | timeout · rate-limit · connection reset · 502/503/504 | Retry with exponential backoff up to MAX_RETRIES = 3. |
| FATAL | permission denied · access denied · tool not found · MANDATORY · invalid param · auth error · 401/403 | Mark FAILED; trigger replan; do not retry. |
| DIAGNOSTIC | AssertionError · RuntimeError · SyntaxError · Traceback · FileNotFoundError · ImportError · EXIT CODE: [1-9] | Inject the full error into context for LLM self-correction. |
| UNKNOWN | none of the above | Inject a short error notice. |
Retry delay
delay = min(base · 2^attempt, 30s)
delay += 0.25 · delay · random() # jitterPer-tool hints
_FALLBACK_HINTS attaches a tool-specific suggestion when a known signature fires:
execute+ModuleNotFoundError→ "pip install X first".file_system+ "not found" → "run list_files first".web_search+ CAPTCHA → "DuckDuckGo rate-limiting; shorter query".postgres_admin+ timeout → "add LIMIT or push filters into WHERE".