# JavaScript 会话状态与 idle 事件

## 目标

为 `@ccweb/session` 增加会话状态查询、直接子对话 ID 查询，以及指定会话从活动状态转为 `idle` 时的事件监听与注销能力；脚本不需要自行编写轮询。

## 已确认语义

- `getConversationStatus(conversationId)` 返回 `Promise<'running' | 'waiting_for_children' | 'idle'>`，优先级为 `running` > `waiting_for_children` > `idle`。
- `getChildConversationIds(conversationId)` 返回该对话通过 MCP 创建的直接持久子对话 ID，不递归返回孙对话。
- `onConversationEvent(conversationId, 'idle', listener)` 监听 `running/waiting_for_children → idle` 边沿，不因注册时已是 `idle` 而立即触发。
- `onConversationEvent` 返回注销函数；注销后不再产生新回调。
- 第一版只公开 `idle` 事件，但协议应便于后续扩展。
- 回调错误不应破坏底层监听；由脚本自己的未捕获异常规则处理。

## 阶段

1. [complete] 梳理现有会话状态与脚本包调用链
2. [complete] 确定状态查询、idle 等待、取消注销和 manifest 的协议语义
3. [complete] 补充失败测试覆盖状态查询和 idle 监听
4. [complete] 实现服务端状态查询与事件等待能力
5. [complete] 实现 @ccweb/session 监听、注销和状态 API
6. [complete] 更新 manifest 并运行单元与回归测试
7. [complete] 检查运行对话后重启并验证 idle 后未完成则继续发送的闭环
8. [complete] 清理临时计划并交付使用示例

## 风险

- 长时间监听必须能让脚本进程保持运行，又不能在注销后遗留服务端等待器。
- idle 必须是活动状态到 idle 的边沿事件，不能把“注册时已经 idle”误判为新完成。
- 当前来源对话允许 steer；事件监听必须与现有状态判定保持一致。
- 重启前必须确认除当前对话外不存在其他 `running` 会话；否则不重启并记录阻塞。

## 协议验收清单

- 状态查询：按 conversationId 返回 `running`、`waiting_for_children` 或 `idle`。
- 子对话查询：按 conversationId 返回直接子对话 ID 数组，不递归。
- 事件等待：只支持 `idle`，且只响应 `running/waiting_for_children → idle`。
- 注销取消：注销后停止包内监听，不再回调，也不遗留活动资源。
- manifest：三个新函数的参数、返回值、状态值、触发/注销语义和错误码与实现一致，总计 8 个函数。
- 场景闭环：idle 回调中判断任务未完成后调用 `sendMessage` 继续，随后再次进入 idle。

## 错误记录

| 错误 | 尝试 | 处理 |
|---|---:|---|
| 运行时单测 `5 !== 8` | 1 | 预期的红灯，证明新增 manifest/API 测试在旧实现上失败；进入实现阶段。 |