From 27696c70f95061edf90d02e44285af583f638069 Mon Sep 17 00:00:00 2001
From: nav <nav@mgr.hangman-lab.top>
Date: Mon, 23 Mar 2026 22:38:02 +0000
Subject: [PATCH] feat: add Agent Exhausted state machine &
 ScheduledGatewayRestart SystemEvent to calendar design

---
 CALENDAR_DESIGN.md | 34 +++++++++++++++++++++++++++++++++-
 1 file changed, 33 insertions(+), 1 deletion(-)

diff --git a/CALENDAR_DESIGN.md b/CALENDAR_DESIGN.md
index 485db8a..c528636 100644
--- a/CALENDAR_DESIGN.md
+++ b/CALENDAR_DESIGN.md
@@ -49,10 +49,14 @@
 **SystemEvent:**
 ```json
 {
-  "event": "ScheduleToday|SummaryToday"
+  "event": "ScheduleToday|SummaryToday|ScheduledGatewayRestart"
 }
 ```
 
+- `ScheduleToday` — 每日日程规划
+- `SummaryToday` — 每日总结
+- `ScheduledGatewayRestart` — OpenClaw 网关计划重启前触发；插件收到后应持久化状态、发送最终心跳、暂停定时任务
+
 **Entertainment:**
 ```
 待设计
@@ -191,6 +195,34 @@ Plan 只存规则，不为每一天生成数据行。
 | 无待执行日程 | → Idle |
 | 被 TimeSlot 唤醒 | → Busy / OnCall |
 | 完成 TimeSlot | → Idle |
+| API rate-limit 或 billing 错误 | → Exhausted |
+| Exhausted 恢复计时器到期 | → Idle |
+
+### 6.5 Exhausted 状态详细规则
+
+**前提：** 所有 Agent 只使用一个主模型，没有 fallback 模型。
+
+**进入条件：**
+- Agent 调用 LLM API 时收到 rate-limit 错误（HTTP 429 等）
+- Agent 调用 LLM API 时收到 billing 相关错误（额度不足、配额耗尽等）
+
+**恢复逻辑：**
+- 解析错误信息，查找类似 `reset in X mins`、`retry after X`、`resets at <timestamp>` 的模式
+- 如果能解析出时间 → 设置 **X 分钟** 后恢复为 Idle
+- 如果无法解析 → 默认 **5 小时** 后恢复为 Idle
+
+**Exhausted 期间行为：**
+- Agent 视为不可用，不被心跳唤醒
+- 待执行的 slot 设为 Deferred
+- 前端/Monitor 显示 Exhausted 状态 + 预计恢复时间
+
+**Agent 表扩展字段：**
+
+| 字段 | 类型 | 说明 |
+|------|------|------|
+| exhausted_at | datetime, nullable | 进入 Exhausted 的时间 |
+| recovery_at | datetime, nullable | 预计恢复时间 |
+| exhaust_reason | Enum(RateLimit, Billing), nullable | 原因 |
 
 ---