人机协作（HITL）

wesgine 的 HITL（Human-in-the-Loop）系统允许 Agent 在运行过程中请求用户介入。

HITL 不是治理

重要区分：HITL 不由治理链（Governance Pipeline）触发。治理链的三步管道（Hardline / Sandbox / Zone）独立于 HITL。

HITL 的触发来源：

来源	说明
`ask_user` 工具	Agent 主动请求用户输入
`browser_wait_for_user`	浏览器操作等待用户干预（AlwaysOn）
CycleDetector	检测到真循环，自愈失败后
ErrorStreak	连续错误累积超阈值

工作流程

触发源 → 发起 HITL 请求
            ↓
       Agent Loop 阻塞
            ↓
       SSE 事件推送到前端
            ↓
       用户在同一会话内响应
            ↓
       Loop 继续执行

API

查看待处理请求

GET /cells/{id}/hitl/pending?run_id=

返回当前 Cell 内待处理的 HITL 请求列表。

响应请求

POST /cells/{id}/hitl/{reqID}/respond

Body 包含用户的决定和理由。

超时

HITL 请求有超时机制：

CycleDetector 触发：60s 超时 → 自动终止 Run
ErrorStreak 触发：HITL 超时 → Run 终止（error_streak）
ask_user：由 CellSpec.HITL.Timeout 配置

Actor 边界

HITL 遵循 Actor 边界：

请求绑定到发起 Run 的 Actor
只有该 Actor 能响应
无主请求不算任何人的
admin 可以查看全部待处理请求

`browser_wait_for_user`

浏览器安全阀，AlwaysOn：

Cell boot 时无条件注册
当浏览器操作需要用户手动干预（如登录、验证码）
Agent 暂停等待用户完成操作
用户完成后通知 Agent 继续

CycleDetector 与 HITL

CycleDetector 使用两阶段终止协议：

首次 CycleTerm → 自愈（注入纠正消息 + 重置计数）
                   ↓ 自愈失败
第二次 CycleTerm → HITL（问用户怎么办）
                   ↓ 用户不响应
                 超时 60s → 终止 Run + 保存进度

与消费方的集成

产品	HITL 实现
wesclaw 桌面	对话内审批（SSE → 前端弹框）
wescode	对话内审批
teleclaw	对话内审批 + Actor 校验（Java handler）