Agentswarm/docs/integration/event-schema.md

Swarm 运行时事件 Schema（回调 / 事件流）

状态：FROZEN v1（契约冻结） —— 回应 agent_swarm#15（来自 HM #28/#45/#46 客户端「任务驾驶舱」消费需求）。本文是 Swarm → HM 回调与 GET …/{id}/events 事件流的统一 schema，已对齐 HM 实现（heicode-mananger/heicode/controller/agent_callback.go，handler POST /api/agent/callbacks/runtime-events）。

冻结要点（实现见 orchestrator/swarm_runtime.py，契约测试 scripts/test-contract-freeze.py）：

1. envelope 带 per-swarm 严格递增 sequence（从 1、无空洞，供客户端 events?after= 去重/续传，§2）。
2. 客户端事件集（§4 标 ⭐）冻结为 FROZEN_CLIENT_EVENT_TYPES（swarm_runtime.py）：#28 的 13 类核心 + #34 新增 4 类评审/返工（review.started/review.decision_made/rework.requested/rework.completed，脱敏投影，见 §4）= 17。
3. artifact 扁平字段 {uri, checksum, task_id, size_bytes?, created_at}（§3）。
4. 凭据红线：secret_ref/credential_ref/signing_secret_ref 为 azkv:// 引用（非明文），Swarm 侧 _redact_sensitive 透传引用、剔除明文 *_token/_secret/_key/password；客户端可见视图由 HM 再做递归脱敏。

配套：生命周期与签名见 runtime-contract.md。

1. 传输与鉴权

• Swarm → HM：POST {callback.url}（create 时下发）。
• 鉴权二选一：服务令牌 X-Agent-Service-Token（或 Authorization: Bearer），或 HMAC 签名。
• HMAC 签名（机制已实现，规范与 HM 对齐；待主链路端到端联调验收）：
  • 头：X-Agent-Timestamp（Unix 毫秒）、X-Agent-Signature、X-Agent-Event-Id、X-Correlation-ID（均含 X-Agnet- 兼容别名）。
  • 规范串：canonical = f"{timestamp}.{event_id}.{raw_body}"。
  • 签名：X-Agent-Signature = "sha256=" + hex(HMAC_SHA256(secret, canonical))。
  • secret：AGENT_CALLBACK_SIGNING_SECRET（兼容 AGNET_…，支持 …_REF 的 azkv:// 解析）。
  • 时间容差：HM 默认 300s（AGENT_CALLBACK_SIGNATURE_TOLERANCE_SECONDS）。
• 幂等去重：HM 依次按 X-Agent-Event-Id 头 → body event_id → idempotency_key。重复返回 {inserted:false, idempotent:true, deduplicated:true}。

2. 事件 Envelope

{
  "event_id": "evt-...",            // 必填；去重主键
  "idempotency_key": "...",          // 可选；缺省回退 event_id
  "sequence": 12,                    // 必填；per-swarm 严格递增（从 1、无空洞）；客户端按此去重/升序/续传
  "event_type": "task.completed",    // 必填；取值见 §4
  "deployment_id": "runtime-dep-...",// 运行时部署 ID
  "swarm_id": "swarm-...",           // 工作流 ID（事件按此持久化）
  "agent_instance_id": "...",        // Agent 实例/角色实例 ID（可选）
  "task_id": "...",                  // 任务相关事件填
  "occurred_at": "2026-06-08T...Z",  // 事件时间
  "correlation_id": "corr-...",      // 追踪 ID（X-Correlation-ID）
  "source": "heicode-swarm-runtime", // 事件来源标识
  "metadata": { },                   // 自定义元数据（不得含明文密钥）
  "payload": { },                    // 事件专属字段（见 §4）
  "artifact": { }                    // 可选；见 §3
}

3. Artifact 子对象（artifact.created 及完成事件可带）

{
  "artifact_id": "art_...",
  "artifact_type": "code_patch | document | deployment_manifest",
  "title": "...",
  "summary": "...",
  "uri": "git://repo#branch | runtime://...",   // 仅 uri，绝不含 secret_ref/凭据
  "checksum": "<commit_sha>",
  "task_id": "...",                              // 缺省回填 envelope.task_id（#15.4）
  "size_bytes": 1234,                            // 可选；未知则省略（不伪造，规则 #9）
  "created_at": "2026-06-08T...Z",               // 缺省回填 envelope.occurred_at
  "metadata": { "redacted": true, "agent_role": "...", "files_modified": [] }
}

客户端 artifact 视图（HM #28）取扁平 {uri, checksum, task_id, size_bytes?, created_at}；HM 由 artifact.created envelope 的上述字段直接产出，无 secret_ref/密钥。

4. 事件类型注册表（与 HM 一致）

⭐ = 冻结的客户端事件（FROZEN_CLIENT_EVENT_TYPES，17 类 = #28 的 13 核心 + #34 的 4 评审/返工，驾驶舱据此渲染；HM agent_callback.go 据此对齐注册表）。review.*/rework.* 为脱敏客户端投影（仅 reviewer id/verdict/failed_criteria/affected_tasks/recommended_rework/root_cause + 安全标量；不含 evidence/summary/rework_reason 自由文本）。其余为 Swarm 也发的辅助/运行时事件（HM 仍消费，但非客户端必需）。

event_type	payload 必填字段（HM 校验）	分类	Swarm 是否发出
⭐ task.created	task_id, title	swarm_task_flow	✅
⭐ task.claimed	task_id, agent_role	swarm_task_flow	✅
⭐ task.running	task_id, agent_role	swarm_task_flow	✅
⭐ task.completed	task_id	swarm_task_flow	✅
⭐ task.failed	task_id, reason	swarm_task_flow	✅
⭐ handoff.created	task_id, from_role, to_role	swarm_task_flow	✅（child 任务建立时，与 handoff.requested 并发）
⭐ approval.requested	approval_id, operation, risk_level	approval	✅
⭐ approval.approved	approval_id	approval	✅（审批决定落地时）
⭐ approval.rejected	approval_id	approval	✅（审批决定落地时）
⭐ artifact.created	artifact_id, uri, checksum	artifact	✅（带 §3 扁平字段）
⭐ swarm.completed	status（+ summary/deliverable 可选）	swarm_terminal	✅（终态；携带用户面结果 = 综述 + deliverable 摘要，客户端可直接取；完整见 GET …/{id}/result，#40）
⭐ swarm.failed	status	swarm_terminal	✅（终态）
⭐ swarm.stopped	status	swarm_terminal	✅（stop_run）
⭐ review.started	cycle, reviewer_count	review	✅（#34，脱敏投影；交叉评审一轮开始）
⭐ review.decision_made	accepted, rework_targets	review	✅（#34，脱敏投影；仲裁结论 + 逐评审者 verdict/criteria，无 evidence/summary）
⭐ rework.requested	task_id, root_cause	review	✅（#34，脱敏投影；无 rework_reason/evidence）
⭐ rework.completed	task_id, root_cause	review	✅（#34，脱敏投影；返工被重新接受）
deployment.status_changed	status	deployment	✅（HM 用于 AgentDeployment.Status；客户端用 swarm.* 终态）
task.heartbeat	task_id, agent_role	swarm_task_flow	✅
task.blocked	task_id, reason	swarm_task_flow	✅
task.retried	task_id, attempt	swarm_task_flow	✅
task.released	task_id, agent_role	swarm_task_flow	✅
handoff.requested	task_id, from_role, to_role	swarm_task_flow	✅
timeline.updated	title	timeline	✅（emit 时回填 title=summary）
budget.alert	threshold_pct	budget	✅（emit 时回填 threshold_pct）
swarm.pool_terminated	user_id, secret_ref	lifecycle	✅（HM #60 模型 key 吊销握手；非客户端事件，见下）
phase.changed / agent.* / sk_tool.*	—	ordinary_sub / sk	❌（本运行时不产生）

说明：评审/重做循环复用 task.retried + timeline.updated（Review cycle N）表达，无单独 review 事件类型；蜂群内部遥测（提案/竞价/交叉评审/收敛/health）不经回调外发（见各协议文档「事件不进 Manager 流」），故不在本表。swarm.completed/failed/stopped 与 approval.approved/rejected、handoff.created 为本次冻结新增，HM 注册表需据此登记（agent_swarm#15.2）。

swarm.pool_terminated（HM #60 模型 key 吊销握手）：HM 控制面生命周期事件，非客户端 cockpit 事件、不入 FROZEN_CLIENT_EVENT_TYPES、不渲染到驾驶舱。当某用户所有 swarm run 均被 stop（completed/failed 可经 …/input 重开故仍保 key）时，运行时发恰好一次，载 user_id + secret_ref（azkv:// 引用，非明文 key）。HM 需在 subscribed_events + agent_callback 登记，收到即吊销该用户 per-user sk- + 清 KV。口径见 runtime-contract §3.3.1。

5. HM 响应

{ "success": true, "event_id": "evt-...", "inserted": true, "idempotent": false, "deduplicated": false, "deployment_id": "dep_..." }

6. 对齐状态（冻结时已修正 / 剩余小项）

冻结时 orchestrator/swarm_runtime.emit_event 已统一处理下列历史缺口：

1. ✅ timeline.updated：emit 时若缺 title 自动回填（复用 summary）。
2. ✅ budget.alert：emit 时若缺 threshold_pct 由 threshold 自动换算（≤1 视为比例 ×100）。
3. ✅ sequence：每事件带 per-swarm 严格递增序号（INCR 计数键 swarm_event_seq:{swarm_id}）。
4. ✅ artifact 扁平字段：created_at/task_id 自动回填，size_bytes 透传（未知则省略，不伪造）。

剩余小项（不影响客户端 13 类冻结）：

• handoff.completed 的 from_role/to_role：辅助事件，客户端 13 类用 handoff.created（已带 from/to）；如 HM 仍消费 handoff.completed，在 handoff 完成处补两字段为后续小修。

契约由 scripts/test-contract-freeze.py 守护（断言 sequence 单调、13 类 round-trip、artifact 形状、审批/停止真实发出、明文凭据脱敏）；scripts/test-workflow-e2e.py 在全流程 e2e 中额外断言 swarm.completed + sequence 无空洞。