From 69936f457f732b9ccc124a087d02461f32be10c6 Mon Sep 17 00:00:00 2001 From: dave Date: Sun, 22 Mar 2026 19:28:48 +0000 Subject: [PATCH] storkit: done 365_story_surface_api_rate_limit_warnings_in_chat --- ...surface_api_rate_limit_warnings_in_chat.md | 64 +++++++++++++++++++ 1 file changed, 64 insertions(+) create mode 100644 .storkit/work/5_done/365_story_surface_api_rate_limit_warnings_in_chat.md diff --git a/.storkit/work/5_done/365_story_surface_api_rate_limit_warnings_in_chat.md b/.storkit/work/5_done/365_story_surface_api_rate_limit_warnings_in_chat.md new file mode 100644 index 0000000..d117419 --- /dev/null +++ b/.storkit/work/5_done/365_story_surface_api_rate_limit_warnings_in_chat.md @@ -0,0 +1,64 @@ +--- +name: "Surface API rate limit warnings in chat" +--- + +# Story 365: Surface API rate limit warnings in chat + +## User Story + +As a project owner watching the chat, I want to see rate limit warnings surfaced directly in the conversation when they appear in the agent's PTY output, so that I know immediately when an agent is being throttled without having to watch server logs. + +## Acceptance Criteria + +- [x] Server detects rate limit warnings in pty-debug output lines +- [x] When a rate limit warning is detected, a notification is sent to the active chat (Matrix/Slack/WhatsApp) +- [x] The notification includes which agent/story triggered the rate limit +- [x] Rate limit notifications are debounced to avoid spamming the chat with repeated warnings + +## Technical Context + +Claude Code emits `rate_limit_event` JSON in its streaming output: + +```json +{ + "type": "rate_limit_event", + "rate_limit_info": { + "status": "allowed_warning", + "resetsAt": 1774443600, + "rateLimitType": "seven_day", + "utilization": 0.82, + "isUsingOverage": false, + "surpassedThreshold": 0.75 + } +} +``` + +Key fields: +- `status`: `"allowed_warning"` when approaching limit, likely `"blocked"` or similar when hard-limited +- `rateLimitType`: e.g. `"seven_day"` rolling window +- `utilization`: 0.0–1.0 fraction of limit consumed +- `resetsAt`: Unix timestamp when the window resets +- `surpassedThreshold`: the threshold that triggered the warning (e.g. 0.75 = 75%) + +These events are already logged as `[pty-debug] raw line:` in the server logs. The PTY reader in `server/src/llm/providers/claude_code.rs` (line ~234) sees them but doesn't currently parse or act on them. + +## Out of Scope + +- TBD + +## Test Results + + + +### Unit Tests (6 passed, 0 failed) + +- ✅ rate_limit_event_json_sends_watcher_warning — PTY reader detects rate_limit_event JSON and emits RateLimitWarning watcher event +- ✅ rate_limit_warning_sends_notification_with_agent_and_story — Notification listener sends chat message with agent and story info +- ✅ rate_limit_warning_is_debounced — Second warning within 60s window is suppressed +- ✅ rate_limit_warnings_for_different_agents_both_notify — Different agents are debounced independently +- ✅ format_rate_limit_notification_includes_agent_and_story — Notification text includes story number, name, and agent name +- ✅ format_rate_limit_notification_falls_back_to_item_id — Falls back to item_id when story name is unavailable + +### Integration Tests (0 passed, 0 failed) + +*No integration tests recorded.*