hermeticormus /agent-triage — Smart Failure Triage
Failed tasks fall into a small number of buckets. Classify, then act.
Prerequisites
| Var | Purpose |
|---|---|
AGENT_API_URL |
Base URL of the agent's HTTP API |
AGENT_API_TOKEN |
Bearer token |
Endpoints used:
GET /api/tasks?status=failed&since=<window>— list failed tasksGET /api/tasks/:id/log— full log for one taskPOST /api/tasks/:id/requeue— requeuePOST /api/tasks/:id/dead-letter— dead-letter
Workflow
Phase 1: Pull failures
curl -s -H "Authorization: Bearer $AGENT_API_TOKEN" \
"$AGENT_API_URL/api/tasks?status=failed&since=24h"
Phase 2: Classify each failure
For each failed task, fetch its log/last error and assign one classification:
| Class | Pattern | Recommended action |
|---|---|---|
infra |
API rate limit, credit exhausted, network timeout, 5xx from upstream | requeue — not the task's fault |
auth |
401/403 from upstream, expired token, missing credential | fix-and-retry — operator must rotate or refresh |
code |
Compile error, test failure, lint failure that the agent could fix | requeue with prompt amendment, or dead-letter if 3+ retries already |
prompt |
Agent looped, hit max iterations without converging, hallucinated nonexistent file | fix-and-retry — operator amends the prompt |
env |
Missing dep, wrong Node version, path doesn't exist on worker | fix-and-retry — operator fixes the env |
wontfix |
Task is no longer needed, superseded by another, or scope was wrong | dead-letter |
unknown |
Doesn't match any pattern above | inspect — drill in with /agent-inspect <task-id> |
Phase 3: Present grouped summary
TRIAGE — <N failures> in last 24h
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
INFRA <count> → bulk requeue
• <task-id> <slug> — <one-line cause>
• <task-id> <slug> — <one-line cause>
AUTH <count> → fix credentials, then requeue
• <task-id> <slug> — <missing/expired creds>
CODE <count> → requeue with amendment OR dead-letter
• <task-id> <slug> — <error type> — <attempt N/3>
PROMPT <count> → operator amends prompt
• <task-id> <slug> — <pattern: looped / hallucinated / max-iter>
ENV <count> → fix worker env, then requeue
• <task-id> <slug> — <missing dep / wrong version>
WONTFIX <count> → dead-letter
• <task-id> <slug> — <reason>
UNKNOWN <count> → /agent-inspect each
• <task-id> <slug>
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
PROPOSED ACTIONS
Bulk requeue: <N> tasks (infra)
Bulk dead-letter: <N> tasks (wontfix)
Operator action: <N> tasks (auth/prompt/env)
Inspect deeper: <N> tasks (unknown)
Phase 4: Bulk action
After presenting, offer bulk operations. Do NOT execute without explicit user approval.
# Bulk requeue infra failures (after user confirms)
for tid in $INFRA_TASK_IDS; do
curl -s -X POST -H "Authorization: Bearer $AGENT_API_TOKEN" \
"$AGENT_API_URL/api/tasks/$tid/requeue"
done
Heuristics for log → classification
Common patterns to grep in logs:
| Pattern | Class |
|---|---|
rate.limit|429|credit.balance.exhausted|insufficient.credits |
infra |
401|403|invalid.api.key|expired.token|unauthor |
auth |
Module not found|Cannot find package|node_modules |
env |
iteration.limit|max.iterations|loop.detected|too many turns |
prompt |
ENOENT|file.not.found|path.does.not.exist |
env (probably) |
tsc.*error|test.*failed|lint |
code |
superseded|cancelled.by.user|scope.changed |
wontfix |
When in doubt, classify as unknown and recommend /agent-inspect.
Notes
- Default window is 24h. For longer windows (
/agent-triage 7d), sweep is heavier — paginate accordingly. - Don't auto-classify based on task slug or project name — read the actual error.
- A single task may match multiple patterns. Pick the most specific (auth beats code, env beats prompt).
- Never bulk-act without showing the user the count + class breakdown first. A misclassification that bulk-requeues 50 prompt failures will create 50 more failures.