From 060fb7c67546aff8d24c0d23307fea7fc2943859 Mon Sep 17 00:00:00 2001
From: "google-labs-jules[bot]"
 <161369871+google-labs-jules[bot]@users.noreply.github.com>
Date: Tue, 17 Mar 2026 20:57:52 +0000
Subject: [PATCH] feat: implement error categorization for agent loop
 observability

This commit introduces error categorization for the agent loop to distinguish between infrastructure, model, and logic failures, fulfilling Phase 5 of the AGENT_LOOP_IMPROVEMENTS.md roadmap.

Changes include:
- `pkg/agent/loop_execute_llm.go`: Classifies LLM errors using `providers.ClassifyError`. Errors related to formatting or context length are categorized as `model_failure`, while others (e.g., timeout, rate limits, auth) default to `infrastructure_failure`.
- `pkg/agent/loop_llm.go`: Checks `r.result.IsError` during tool execution processing. If true, logs the failure with the `error_category` set to `logic_failure`.
- `AGENT_LOOP_IMPROVEMENTS.md`: Marks the Error Categorization task as complete.

Co-authored-by: hobbyistlabs-coder <267281733+hobbyistlabs-coder@users.noreply.github.com>
---
 AGENT_LOOP_IMPROVEMENTS.md    |  2 +-
 pkg/agent/loop_execute_llm.go | 14 +++++++++++---
 pkg/agent/loop_llm.go         |  9 +++++++++
 3 files changed, 21 insertions(+), 4 deletions(-)

diff --git a/AGENT_LOOP_IMPROVEMENTS.md b/AGENT_LOOP_IMPROVEMENTS.md
index 6ad9241c3..338f5bde7 100644
--- a/AGENT_LOOP_IMPROVEMENTS.md
+++ b/AGENT_LOOP_IMPROVEMENTS.md
@@ -33,7 +33,7 @@ This document outlines a series of tasks to improve the main loop of the agentic
 ## Phase 5: Observability & Logging Dashboard
 
 * [ ] **Session Replay:** Capture the full "Chain of Thought" (CoT), including tool-call inputs/outputs, and state transitions to facilitate deep-dive session reviews.
-* [ ] **Error Categorization:** Distinguish between Model Failures (hallucinations/refusals), Infrastructure Failures (API timeouts), and Logic Failures (code execution errors).
+* [x] **Error Categorization:** Distinguish between Model Failures (hallucinations/refusals), Infrastructure Failures (API timeouts), and Logic Failures (code execution errors).
 * [ ] **Real-time Visuals:** Implement a lightweight UI/Dashboard using a Go-compatible framework like a custom Bubble Tea TUI to monitor the agent's health.
 
 ---
diff --git a/pkg/agent/loop_execute_llm.go b/pkg/agent/loop_execute_llm.go
index fd4ec75f4..fb8023896 100644
--- a/pkg/agent/loop_execute_llm.go
+++ b/pkg/agent/loop_execute_llm.go
@@ -142,11 +142,19 @@ func (al *AgentLoop) executeLLMWithRetry(
 	}
 
 	if err != nil {
+		errorCategory := "infrastructure_failure"
+		if failErr := providers.ClassifyError(err, agent.ID, activeModel); failErr != nil {
+			if failErr.Reason == providers.FailoverFormat || failErr.Reason == providers.FailoverContextLength {
+				errorCategory = "model_failure"
+			}
+		}
+
 		logger.ErrorCF("agent", "LLM call failed",
 			map[string]any{
-				"agent_id":  agent.ID,
-				"iteration": iteration,
-				"error":     err.Error(),
+				"agent_id":       agent.ID,
+				"iteration":      iteration,
+				"error":          err.Error(),
+				"error_category": errorCategory,
 			})
 		return nil, fmt.Errorf("LLM call failed after retries: %w", err)
 	}
diff --git a/pkg/agent/loop_llm.go b/pkg/agent/loop_llm.go
index b41a00a36..6cb6c2fd9 100644
--- a/pkg/agent/loop_llm.go
+++ b/pkg/agent/loop_llm.go
@@ -361,6 +361,15 @@ func (al *AgentLoop) runLLMIteration(
 				contentForLLM = r.result.Err.Error()
 			}
 
+			if r.result.IsError {
+				logger.ErrorCF("agent", "Tool execution failed",
+					map[string]any{
+						"tool":           r.tc.Name,
+						"error":          contentForLLM,
+						"error_category": "logic_failure",
+					})
+			}
+
 			toolResultMsg := providers.Message{
 				Role:       "tool",
 				Content:    contentForLLM,