事件与定时器
关于具体配置与验证步骤，请参阅连接外部事件或调度 Agent 工作。本页记录这些工作流背后的权威契约。
回调端点（Callback endpoints）
| 方法与路由 | 交付模式 |
|---|---|
POST /api/callbacks/wake/:callback_token | wake_hint：唤醒 Agent 检查外部状态 |
POST /api/callbacks/enqueue/:callback_token | enqueue_message：将外部回调内容作为消息入队 |
POST /api/control/agents/:agent_id/reset-callback | 认证控制操作：吊销当前默认凭据并颁发新凭据 |
每个回调对应一种交付模式和一个 trigger_url。回调 Token 是解析到有效触发器与目标 Agent 的能力凭据（Capability secret）。无效的 Token、未处于活跃状态的身份以及不匹配的交付模式均会被系统拒绝。回调被成功接收并不能证明底层业务已顺利完成。
回调端点支持可选的请求体。对于唤醒模式（wake hint），空的 POST 请求即可完成触发；对于入队通知模式（enqueue message），JSON 请求体可包含 text 字段：
{ "text": "登记的 CI 构建状态发生变更，请核实当前状态。" }
回调载荷始终属于外部证据。持有回调 URL 的发送方并不会因此获得操作者指令权威。回调端点的请求体限制为 256 KB；请传递稳定的来源标识，避免发送庞大的日志全文。
重置接口返回 ok、agent_id、external_trigger_id、trigger_url、delivery_mode 和 status。应将返回的 URL 视同机密并直接使用。切勿将其打印至对话记录、粘贴到 Issue 或提交到版本控制中。
默认接入凭据与吊销
Agent 的运行时上下文会自动注入其默认接入凭据。对于常规集成，直接复用该凭据即可，无需频繁创建多个触发器。CreateExternalTrigger 仅用于受支持的兼容模式或备用模式场景，并非绕过调用方权限的手段。
CancelExternalTrigger 接收 external_trigger_id 并吊销该能力。重置操作会使旧的默认 URL 立即失效并生成新凭据。停止 Agent 会自动吊销其所有外部触发器；当 Agent 重新启动时，不要假定外部发送方保存的历史密钥依然有效。
定时器操作
| 操作 | 操作者 CLI | Agent 工具 |
|---|---|---|
| 创建 | holon timer create --after-ms N [--every-ms N] [--summary TEXT] [--agent ID] | CreateTimer(duration_ms, interval_ms?, summary?) |
| 列表 | holon timer list [--limit N] [--agent ID] | ListTimers(limit?) |
| 详情 | 见下方 HTTP 路由 | GetTimer(timer_id) |
| 取消 | holon timer cancel TIMER_ID [--agent ID] | CancelTimer(timer_id) |
系统依然支持旧版的 holon timer --after-ms N 创建语法。Agent 工具仅对当前 Agent 生效，不接受指定目标 Agent ID。延迟与周期参数均为正毫秒数。创建定时器不会暂停当前轮次。取消已处于取消状态的定时器是幂等的；已触发完成的单次定时器无法再被取消。
| HTTP 路由 | 契约说明 |
|---|---|
POST /api/control/agents/:id/timers | 创建定时器，接收 duration_ms，可选 interval_ms、summary 以及控制层 authority_class 元数据 |
GET /api/agents/:id/timers | 列出近期的定时器记录 |
GET /api/agents/:id/timers/:timer_id | 读取归属于该 Agent 的定时器详情，不存在时返回 404 |
POST /api/control/agents/:id/timers/:timer_id/cancel | 取消定时器；支持可选的控制层 authority_class 元数据 |
控制层元数据不会越权提升调用方本身的权限。认证与准入规则请参阅 HTTP 控制平面参考。
定时器记录字段
| 字段 | 含义 |
|---|---|
id、agent_id | 定时器唯一标识与所属 Agent |
created_at | 创建时间戳 |
duration_ms | 首次触发延迟（毫秒） |
interval_ms | 可选的重复周期（毫秒） |
repeat | 是否周期性重复触发 |
status | active、completed 或 cancelled；旧版 scheduled 会被反序列化为 active |
summary | 可选的提醒说明文本 |
next_fire_at、last_fired_at | 下次预计触发时间戳与最近一次已触发时间戳 |
fire_count | 已记录的触发次数 |
WaitFor 契约
WaitFor 用于登记调度等待条件；它既不创建定时器，也不配置 Webhook。其字段定义如下：
| 字段 | 契约要求 |
|---|---|
wake | operator_input、task_result、external、timer 或 system |
resource | 任务结果对应任务 ID；定时器对应实际的定时器 ID；外部等待对应可选的稳定外部对象标识 |
reason | 清晰阐明阻碍当前继续推进的具体原因 |
delivery | 必填项：final（需要面向操作者的报告）或 silent（静默） |
work_item_id | 可选项：当无绑定的执行项时，显式指定归属的已开启工作项 |
recheck_after_ms | 可选项：回退重新核对的超时延迟，并非周期性调度 |
wake=timer 要求定时器归属于当前 Agent 且具备可用的唤醒信号。无效、归属于他人、已取消或已被消费的定时器资源会返回可恢复的工具错误。对于 wake=task_result，任务可以属于该 Agent 的任意工作项；等待操作绝不会迁移任务的归属。
若存在绑定的执行工作项，则该工作项具有等待所属权，即使传入了冲突的参数也会被忽略并如实记录。若无绑定，解析顺序依次为：显式指定的所属已开启工作项、轮次绑定的工作项、当前焦点，或回退至 Agent 生命周期级。
后续流转与交付模式
| 返回的延续状态 | Agent 应对动作 |
|---|---|
continue_turn | 立即在当前轮次继续执行有效工作；无需发布等待报告 |
yield_and_wait | 让出执行权，挂起直至注册的唤醒信号到达 |
yield_and_reenter | 让出执行权，等待排队的确切结果重新进入模型 |
若选择 delivery=final 并返回了 awaiting_final_report，代表等待尚未最终提交。此时必须输出一段非空的操作者答复；在该报告后续轮次中，仅允许调用只读核验工具，严禁递归调用生命周期工具。若选择 delivery=silent，挂起时无需输出面向操作者的等待报告。
等待注册与最终报告提交是强原子绑定的。陈旧的执行上下文、工作项版本冲突、唤醒状态变更或并发插话均会导致预备的等待失效。即便工作项存在独立的业务阻塞，匹配成功的唤醒信号依然能够恢复后续执行，但这绝不代表满足或清除了该业务阻塞。停止、完成、替换、取消以及结果消费屏障依然能够防止过时或重复的延续执行。