Agentswarm/docs/integration/event-schema.md

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

状态：已对齐 HM 实现（依据 heicode-mananger/heicode/controller/agent_callback.go，handler POST /api/agent/callbacks/runtime-events）。本文是 Swarm → HM 回调与 GET …/{id}/events 事件流的统一 schema。

配套：生命周期与签名见 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
  "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://...",
  "checksum": "<commit_sha>",
  "metadata": { "redacted": true, "agent_role": "...", "files_modified": [] }
}

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

event_type	payload 必填字段（HM 校验）	分类	Swarm 是否发出
deployment.status_changed	status	deployment	✅
phase.changed	stage 或 checkpoint	ordinary_sub	❌（暂未用）
agent.started	agent_role	ordinary_sub	❌
agent.completed	agent_role	ordinary_sub	❌
agent.crashed	agent_role, reason	ordinary_sub	❌
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.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	⚠️ 未发出（见 §6）
task.failed	task_id, reason	swarm_task_flow	✅
task.completed	task_id	swarm_task_flow	✅
handoff.requested	task_id, from_role, to_role	swarm_task_flow	✅
handoff.completed	task_id, from_role, to_role	swarm_task_flow	⚠️ 缺 from_role/to_role（见 §6）
approval.requested	approval_id, operation, risk_level	approval	✅
artifact.created	artifact_id	artifact	✅
timeline.updated	title	timeline	⚠️ 发出 summary，缺 title（见 §6）
sk_tool.called	tool_name, tool_invocation_id	sk	❌（无 SK 工具）
sk_tool.completed	tool_name, tool_invocation_id	sk	❌
sk_tool.failed	tool_name, tool_invocation_id, reason	sk	❌
budget.alert	threshold_pct	budget	⚠️ 发出 threshold，缺 threshold_pct（见 §6）

说明：评审/重做循环复用 task.retried + timeline.updated（Review cycle N）表达，无单独 review 事件类型；如 HM 前端需要独立 review 事件，列为待对齐项。

5. HM 响应

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

6. 已知对齐缺口（需在 Swarm 代码修正）

下列为本仓 orchestrator/ 当前发出字段与 HM 校验的差异，应在对应 emit 处修正后再宣称完全对齐：

1. timeline.updated：HM 要求 title；当前发 summary。修正：payload 增加 title（可复用 summary）。
2. budget.alert：HM 要求 threshold_pct；当前发 threshold（如 0.8）。修正：增加 threshold_pct（百分比，如 80）。
3. handoff.completed：HM 要求 from_role/to_role；当前缺。修正：在 finalize_parent_after_child / handoff 完成处补 from_role/to_role。
4. task.released：HM 注册表含此事件；task_queue.release_task 当前静默。修正：释放任务时发 task.released（task_id, agent_role）。

这些是确定性的小修，建议配 contract test（按 HM 必填字段断言每类事件 payload）。