Skip to content

An agent-managed museum exhibit, built in Rust with Gajae-Code / LazyCodex — developed and maintained with no human intervention.

Rust

Implement US-022: Enhanced error context for API failures

Yeachan-Heo4cb1db9faad0
diff --git a/prd.json b/prd.json
index 084d8120..9cc64a7c 100644
--- a/prd.json
+++ b/prd.json
@@ -160,6 +160,168 @@
],
"passes": true,
"priority": "P2"
+ },
+ {
+ "id": "US-012",
+ "title": "Trust prompt resolver with allowlist auto-trust",
+ "description": "Add allowlisted auto-trust behavior for known repos/worktrees. Trust prompts currently block TUI startup and require manual intervention. Implement automatic trust resolution for pre-approved repositories.",
+ "acceptanceCriteria": [
+ "TrustAllowlist config structure with repo patterns",
+ "Auto-trust behavior for allowlisted repos/worktrees",
+ "trust_required event emitted when trust prompt detected",
+ "trust_resolved event emitted when trust is granted",
+ "Non-allowlisted repos remain gated (manual trust required)",
+ "Integration with worker boot lifecycle",
+ "Tests for allowlist matching and event emission"
+ ],
+ "passes": true,
+ "priority": "P1"
+ },
+ {
+ "id": "US-013",
+ "title": "Phase 2 - Session event ordering + terminal-state reconciliation",
+ "description": "When the same session emits contradictory lifecycle events (idle, error, completed, transport/server-down) in close succession, expose deterministic final truth. Attach monotonic sequence/causal ordering metadata, classify terminal vs advisory events, reconcile duplicate/out-of-order terminal events into one canonical lane outcome.",
+ "acceptanceCriteria": [
+ "Monotonic sequence / causal ordering metadata attached to session lifecycle events",
+ "Terminal vs advisory event classification implemented",
+ "Reconcile duplicate or out-of-order terminal events into one canonical outcome",
+ "Distinguish 'session terminal state unknown because transport died' from real 'completed'",
+ "Tests verify reconciliation behavior with out-of-order event bursts"
+ ],
+ "passes": true,
+ "priority": "P1"
+ },
+ {
+ "id": "US-014",
+ "title": "Phase 2 - Event provenance / environment labeling",
+ "description": "Every emitted event should declare its source (live_lane, test, healthcheck, replay, transport) so claws do not mistake test noise for production truth. Include environment/channel label, emitter identity, and confidence/trust level.",
+ "acceptanceCriteria": [
+ "EventProvenance enum with live_lane, test, healthcheck, replay, transport variants",
+ "Environment/channel label attached to all events",
+ "Emitter identity field on events",
+ "Confidence/trust level field for downstream automation",
+ "Tests verify provenance labeling and filtering"
+ ],
+ "passes": true,
+ "priority": "P1"
+ },
+ {
+ "id": "US-015",
+ "title": "Phase 2 - Session identity completeness at creation time",
+ "description": "A newly created session should emit stable title, workspace/worktree path, and lane/session purpose at creation time. If any field is not yet known, emit explicit typed placeholder reason rather than bare unknown string.",
+ "acceptanceCriteria": [
+ "Session creation emits stable title, workspace/worktree path, purpose immediately",
+ "Explicit typed placeholder when fields unknown (not bare 'unknown' strings)",
+ "Later-enriched metadata reconciles onto same session identity without ambiguity",
+ "Tests verify session identity completeness and placeholder handling"
+ ],
+ "passes": true,
+ "priority": "P1"
+ },
+ {
+ "id": "US-016",
+ "title": "Phase 2 - Duplicate terminal-event suppression",
+ "description": "When the same session emits repeated completed/failed/terminal notifications, collapse duplicates before they trigger repeated downstream reactions. Attach canonical terminal-event fingerprint per lane/session outcome.",
+ "acceptanceCriteria": [
+ "Canonical terminal-event fingerprint attached per lane/session outcome",
+ "Suppress/coalesce repeated terminal notifications within reconciliation window",
+ "Preserve raw event history for audit while exposing one actionable outcome downstream",
+ "Surface when later duplicate materially differs from original terminal payload",
+ "Tests verify deduplication and material difference detection"
+ ],
+ "passes": true,
+ "priority": "P2"
+ },
+ {
+ "id": "US-017",
+ "title": "Phase 2 - Lane ownership / scope binding",
+ "description": "Each session and lane event should declare who owns it and what workflow scope it belongs to. Attach owner/assignee identity, workflow scope (claw-code-dogfood, external-git-maintenance, infra-health, manual-operator), and mark whether watcher is expected to act, observe only, or ignore.",
+ "acceptanceCriteria": [
+ "Owner/assignee identity attached to sessions and lane events",
+ "Workflow scope field (claw-code-dogfood, external-git-maintenance, etc.)",
+ "Watcher action expectation field (act, observe-only, ignore)",
+ "Preserve scope through session restarts, resumes, and late terminal events",
+ "Tests verify ownership and scope binding"
+ ],
+ "passes": true,
+ "priority": "P2"
+ },
+ {
+ "id": "US-018",
+ "title": "Phase 2 - Nudge acknowledgment / dedupe contract",
+ "description": "Periodic clawhip nudges should carry nudge id/cycle id and delivery timestamp. Expose whether claw has already acknowledged or responded for that cycle. Distinguish new nudge, retry nudge, and stale duplicate.",
+ "acceptanceCriteria": [
+ "Nudge id / cycle id and delivery timestamp attached",
+ "Acknowledgment state exposed (already acknowledged or not)",
+ "Distinguish new nudge vs retry nudge vs stale duplicate",
+ "Allow downstream summaries to bind reported pinpoint back to triggering nudge id",
+ "Tests verify nudge deduplication and acknowledgment tracking"
+ ],
+ "passes": true,
+ "priority": "P2"
+ },
+ {
+ "id": "US-019",
+ "title": "Phase 2 - Stable roadmap-id assignment for newly filed pinpoints",
+ "description": "When a claw records a new pinpoint/follow-up, assign or expose a stable tracking id immediately. Expose that id in structured event/report payload and preserve across edits, reorderings, and summary compression.",
+ "acceptanceCriteria": [
+ "Canonical roadmap id assigned at filing time",
+ "Roadmap id exposed in structured event/report payload",
+ "Same id preserved across edits, reorderings, summary compression",
+ "Distinguish 'new roadmap filing' from 'update to existing roadmap item'",
+ "Tests verify stable id assignment and update detection"
+ ],
+ "passes": true,
+ "priority": "P2"
+ },
+ {
+ "id": "US-020",
+ "title": "Phase 2 - Roadmap item lifecycle state contract",
+ "description": "Each roadmap pinpoint should carry machine-readable lifecycle state (filed, acknowledged, in_progress, blocked, done, superseded). Attach last state-change timestamp and preserve lineage when one pinpoint supersedes or merges into another.",
+ "acceptanceCriteria": [
+ "Lifecycle state enum with filed, acknowledged, in_progress, blocked, done, superseded",
+ "Last state-change timestamp attached",
+ "New report can declare first filing, status update, or closure",
+ "Preserve lineage when one pinpoint supersedes or merges into another",
+ "Tests verify lifecycle state transitions"
+ ],
+ "passes": true,
+ "priority": "P2"
+ },
+ {
+ "id": "US-021",
+ "title": "Request body size pre-flight check for OpenAI-compatible provider",
+ "description": "Implement pre-flight request body size estimation to prevent 400 Bad Request errors from API gateways with size limits. Based on dogfood findings with kimi-k2.5 testing, DashScope API has a 6MB request body limit that was exceeded by large system prompts.",
+ "acceptanceCriteria": [
+ "Pre-flight size estimation before sending requests to OpenAI-compatible providers",
+ "Clear error message when request exceeds provider-specific size limit",
+ "Configuration for different provider limits (6MB DashScope, 100MB OpenAI, etc.)",
+ "Unit tests for size estimation and limit checking",
+ "Integration with existing error handling for actionable user messages"
+ ],
+ "passes": true,
+ "priority": "P1"
+ },
+ {
+ "id": "US-022",
+ "title": "Enhanced error context for API failures",
+ "description": "Add structured error context to API failures including request ID tracking across retries, provider-specific error code mapping, and suggested user actions based on error type (e.g., 'Reduce prompt size' for 413, 'Check API key' for 401).",
+ "acceptanceCriteria": [
+ "Request ID tracking across retries with full context in error messages",
+ "Provider-specific error code mapping with actionable suggestions",
+ "Suggested user actions for common error types (401, 403, 413, 429, 500, 502-504)",
+ "Unit tests for error context extraction",
+ "All existing tests pass and clippy is clean"
+ ],
+ "passes": true,
+ "priority": "P1"
}
- ]
+ ],
+ "metadata": {
+ "lastUpdated": "2026-04-16",
+ "completedStories": ["US-001", "US-002", "US-003", "US-004", "US-005", "US-006", "US-007", "US-008", "US-009", "US-010", "US-011", "US-012", "US-013", "US-014", "US-015", "US-016", "US-017", "US-018", "US-019", "US-020", "US-021", "US-022"],
+ "inProgressStories": [],
+ "totalStories": 22,
+ "status": "in_progress"
+ }
}
diff --git a/rust/crates/api/src/error.rs b/rust/crates/api/src/error.rs
index 0319f833..836f46e0 100644
--- a/rust/crates/api/src/error.rs
+++ b/rust/crates/api/src/error.rs
@@ -53,6 +53,8 @@ pub enum ApiError {
request_id: Option<String>,
body: String,
retryable: bool,
+ /// Suggested user action based on error type (e.g., "Reduce prompt size" for 413)
+ suggested_action: Option<String>,
},
RetriesExhausted {
attempts: u32,
@@ -239,6 +241,7 @@ impl ApiError {
}
impl Display for ApiError {
+ #[allow(clippy::too_many_lines)]
fn fmt(&self, f: &mut Formatter<'_>) -> std::fmt::Result {
match self {
Self::MissingCredentials {
@@ -340,9 +343,7 @@ impl Display for ApiError {
provider,
} => write!(
f,
- "request body size ({} bytes) exceeds {provider} limit ({} bytes); reduce prompt length or context before retrying",
- estimated_bytes,
- max_bytes
+ "request body size ({estimated_bytes} bytes) exceeds {provider} limit ({max_bytes} bytes); reduce prompt length or context before retrying"
),
}
}
@@ -489,6 +490,7 @@ mod tests {
request_id: Some("req_jobdori_123".to_string()),
body: String::new(),
retryable: true,
+ suggested_action: None,
};
assert!(error.is_generic_fatal_wrapper());
@@ -511,6 +513,7 @@ mod tests {
request_id: Some("req_nested_456".to_string()),
body: String::new(),
retryable: true,
+ suggested_action: None,
}),
};
@@ -531,6 +534,7 @@ mod tests {
request_id: Some("req_ctx_123".to_string()),
body: String::new(),
retryable: false,
+ suggested_action: None,
};
assert!(error.is_context_window_failure());
diff --git a/rust/crates/api/src/providers/anthropic.rs b/rust/crates/api/src/providers/anthropic.rs
index dd18a4d7..7c9f0294 100644
--- a/rust/crates/api/src/providers/anthropic.rs
+++ b/rust/crates/api/src/providers/anthropic.rs
@@ -885,6 +885,7 @@ async fn expect_success(response: reqwest::Response) -> Result<reqwest::Response
request_id,
body,
retryable,
+ suggested_action: None,
})
}
@@ -909,6 +910,7 @@ fn enrich_bearer_auth_error(error: ApiError, auth: &AuthSource) -> ApiError {
request_id,
body,
retryable,
+ suggested_action,
} = error
else {
return error;
@@ -921,6 +923,7 @@ fn enrich_bearer_auth_error(error: ApiError, auth: &AuthSource) -> ApiError {
request_id,
body,
retryable,
+ suggested_action,
};
}
let Some(bearer_token) = auth.bearer_token() else {
@@ -931,6 +934,7 @@ fn enrich_bearer_auth_error(error: ApiError, auth: &AuthSource) -> ApiError {
request_id,
body,
retryable,
+ suggested_action,
};
};
if !bearer_token.starts_with("sk-ant-") {
@@ -941,6 +945,7 @@ fn enrich_bearer_auth_error(error: ApiError, auth: &AuthSource) -> ApiError {
request_id,
body,
retryable,
+ suggested_action,
};
}
// Only append the hint when the AuthSource is pure BearerToken. If both
@@ -955,6 +960,7 @@ fn enrich_bearer_auth_error(error: ApiError, auth: &AuthSource) -> ApiError {
request_id,
body,
retryable,
+ suggested_action,
};
}
let enriched_message = match message {
@@ -968,6 +974,7 @@ fn enrich_bearer_auth_error(error: ApiError, auth: &AuthSource) -> ApiError {
request_id,
body,
retryable,
+ suggested_action,
}
}
@@ -1555,6 +1562,7 @@ mod tests {
request_id: Some("req_varleg_001".to_string()),
body: String::new(),
retryable: false,
+ suggested_action: None,
};
// when
@@ -1595,6 +1603,7 @@ mod tests {
request_id: None,
body: String::new(),
retryable: true,
+ suggested_action: None,
};
// when
@@ -1623,6 +1632,7 @@ mod tests {
request_id: None,
body: String::new(),
retryable: false,
+ suggested_action: None,
};
// when
@@ -1650,6 +1660,7 @@ mod tests {
request_id: None,
body: String::new(),
retryable: false,
+ suggested_action: None,
};
// when
@@ -1674,6 +1685,7 @@ mod tests {
request_id: None,
body: String::new(),
retryable: false,
+ suggested_action: None,
};
// when
diff --git a/rust/crates/api/src/providers/openai_compat.rs b/rust/crates/api/src/providers/openai_compat.rs
index cf98158f..082a41b6 100644
--- a/rust/crates/api/src/providers/openai_compat.rs
+++ b/rust/crates/api/src/providers/openai_compat.rs
@@ -32,9 +32,9 @@ pub struct OpenAiCompatConfig {
pub base_url_env: &'static str,
pub default_base_url: &'static str,
/// Maximum request body size in bytes. Provider-specific limits:
- /// - DashScope: 6MB (6_291_456 bytes) - observed in dogfood testing
- /// - OpenAI: 100MB (104_857_600 bytes)
- /// - xAI: 50MB (52_428_800 bytes)
+ /// - `DashScope`: 6MB (`6_291_456` bytes) - observed in dogfood testing
+ /// - `OpenAI`: 100MB (`104_857_600` bytes)
+ /// - `xAI`: 50MB (`52_428_800` bytes)
pub max_request_body_bytes: usize,
}
@@ -196,6 +196,10 @@ impl OpenAiCompatClient {
request_id,
body,
retryable: false,
+ suggested_action: suggested_action_for_status(
+ reqwest::StatusCode::from_u16(code.unwrap_or(400))
+ .unwrap_or(reqwest::StatusCode::BAD_REQUEST),
+ ),
});
}
}
@@ -1289,6 +1293,7 @@ fn parse_sse_frame(
request_id: None,
body: payload.clone(),
retryable: false,
+ suggested_action: suggested_action_for_status(status),
});
}
}
@@ -1346,6 +1351,8 @@ async fn expect_success(response: reqwest::Response) -> Result<reqwest::Response
let parsed_error = serde_json::from_str::<ErrorEnvelope>(&body).ok();
let retryable = is_retryable_status(status);
+ let suggested_action = suggested_action_for_status(status);
+
Err(ApiError::Api {
status,
error_type: parsed_error
@@ -1357,6 +1364,7 @@ async fn expect_success(response: reqwest::Response) -> Result<reqwest::Response
request_id,
body,
retryable,
+ suggested_action,
})
}
@@ -1364,6 +1372,20 @@ const fn is_retryable_status(status: reqwest::StatusCode) -> bool {
matches!(status.as_u16(), 408 | 409 | 429 | 500 | 502 | 503 | 504)
}
+/// Generate a suggested user action based on the HTTP status code and error context.
+/// This provides actionable guidance when API requests fail.
+fn suggested_action_for_status(status: reqwest::StatusCode) -> Option<String> {
+ match status.as_u16() {
+ 401 => Some("Check API key is set correctly and has not expired".to_string()),
+ 403 => Some("Verify API key has required permissions for this operation".to_string()),
+ 413 => Some("Reduce prompt size or context window before retrying".to_string()),
+ 429 => Some("Wait a moment before retrying; consider reducing request rate".to_string()),
+ 500 => Some("Provider server error - retry after a brief wait".to_string()),
+ 502..=504 => Some("Provider gateway error - retry after a brief wait".to_string()),
+ _ => None,
+ }
+}
+
fn normalize_finish_reason(value: &str) -> String {
match value {
"stop" => "end_turn",
@@ -2142,7 +2164,7 @@ mod tests {
assert_eq!(max_bytes, 6_291_456); // 6MB limit
assert!(estimated_bytes > max_bytes);
}
- _ => panic!("expected RequestBodySizeExceeded error, got {:?}", err),
+ _ => panic!("expected RequestBodySizeExceeded error, got {err:?}"),
}
}