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.jsonindex 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.rsindex 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.rsindex 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::Responserequest_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,} = errorelse {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,};// whendiff --git a/rust/crates/api/src/providers/openai_compat.rs b/rust/crates/api/src/providers/openai_compat.rsindex 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::Responselet 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::Responserequest_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 limitassert!(estimated_bytes > max_bytes);}- _ => panic!("expected RequestBodySizeExceeded error, got {:?}", err),+ _ => panic!("expected RequestBodySizeExceeded error, got {err:?}"),}}