Agentswarm/docs/integration/frontend-event-api.md

前端事件 API（Frontend Event API）

状态：DRAFT / 待对齐 Frontend & Product Team。

依据：heicode-mananger/docs/integration/heicode-desktop-client-api.md、docs/integration/manager-side-contract-patches.md §6。配套：event-schema.md、runtime-contract.md。

1. 现状（重要）

• 当前桌面端是单 Agent 模型：用户部署「模板 Agent」，客户端从 HM 拿 subdomain+access_token 后直连 Agent走 A2A：POST {subdomain}/message/stream（SSE）/ message/send、GET /.well-known/agent.json、/health。HM 不在回路。
• HM 尚未定义「蜂群图 / agent 拓扑 / review loop / retry 时间线」的前端事件 API。蜂群前端契约归 Swarm + Frontend/Product Team 共同定义，目前不存在。
• 因此本文档区分：①HM 既有的任务卡片事件通道；②Swarm 现已提供、前端可消费的 REST；③待定义的蜂群前端事件 API。

2. HM 既有前端事件通道（任务卡片，非蜂群图）

来自 manager-side-contract-patches.md §6：

• GET /api/user/tasks/{id}/events（SSE）；HM 当前以轮询兜底（active 3s、其它状态 15s）。
• 建议 SSE 事件名与载荷：
  • status_changed → 新状态
  • followup_added → followup 载荷
  • card_updated → 完整 HeicodeTaskCard（{goal, scope, generated_artifacts, manager_actions:[{label, deeplink}]}）
• 这是任务卡片视角，不是蜂群 DAG/拓扑视角。

3. Swarm 现已提供的可消费 REST（已实现）

前端（经 HM 或直连受控读接口）可消费：

接口	用途	关键字段
GET …/{deployment_id}/workflow	工作流/阶段视图	status、summary、agent_count、tokens、tools、elapsed_seconds、phases[]、artifacts[]
GET …/{deployment_id}/tasks	任务 DAG	每任务 task_id、agent_role、status、depends_on、parent_task_id、root_task_id、attempt、blocked_reason
GET …/{deployment_id}/logs（/events）	事件流	事件 envelope（见 event-schema），分页 cursor/limit
GET …/{deployment_id}/metrics	指标	tasks_by_status、agents_connected、average_task_duration_seconds、budget
GET …/{deployment_id}/diagnostics	诊断	失败任务、回调尝试、审批

phases[] 形如：{phase_id, name, status, agents[]}，name ∈ {Plan, Dispatch, Execute, Handoff, Review, Deliver}；agents[] 形如 {agent_id, name, role, status, tokens, tools, elapsed_seconds, artifact_ids}。

注意：当前仅 REST 拉取，Swarm 未向前端推送 SSE/WS。前端可轮询 /workflow + /logs（用 cursor 增量）。

4. 目标：蜂群前端事件 API（待定义）

为支撑工单要求的 swarm graph / agent topology / task DAG / review loop / retry timeline / token-cost monitor / collaboration timeline，建议（待 Frontend/Product Team 冻结）：

UI 视图	数据来源（现有）	缺口
Task DAG / topology	/tasks（depends_on）+ /workflow.phases	稳定 graph schema、增量更新事件
Review loop / retry timeline	task.retried + timeline.updated（Review cycle N）	独立 review/retry 事件类型与时间线 schema
Collaboration timeline	handoff.requested/completed + peer 路由	peer 消息事件未对前端暴露
Token / cost monitor	/metrics + budget.alert（usage）	统一 usage 推送（见 usage-billing §7）
实时推送	/logs 轮询	统一 SSE/WS event stream（事件名、断线重连、刷新可恢复）

建议事件流形态（草案）：SSE GET …/{deployment_id}/stream，事件名复用 event-schema 的 event_type，载荷为对应 envelope；前端按 swarm_id 渲染、按 event_id 去重、断线后用 /logs?cursor= 回补。

5. 缺口与待对齐

• 🔴 Swarm 未提供前端 SSE/WS 推送（仅 REST 轮询）。
• 🔴 蜂群 graph/timeline/cost 的统一前端 schema 未定义。
• 🟡 review/retry/collaboration 缺独立事件类型（当前借 task.retried/timeline.updated）。
• 待对齐：Frontend / Product Team 确认蜂群三视图（graph / timeline / cost）入口与事件流形态；与 HM 的 /api/user/tasks/{id}/events 通道如何衔接。

6. Swarm 侧冻结口径（#18：run/task/event API + Agent Registry/调度）

回应 #18 两项 DoD，明确本仓已满足的范围与外部/后续项（按规则 #9 据实标注，不夸大）：

• 「前端可渲染 run/task/event 稳定 API」——本仓已冻结：前端（经 HM 或受控读接口）用 §3 的 REST 即可稳定渲染：GET …/{id}（run 状态）、/tasks（task DAG）、/events?after=<sequence>（事件流，per-swarm 严格递增 sequence 去重/续传）、/workflow、/metrics、/diagnostics、/audit。事件类型与 envelope 见 event-schema.md（FROZEN v1，客户端事件集 + sequence）。即 run/task/event 的数据契约已稳定冻结。
• 「Agent Registry / 调度入口统一」——蜂群内已统一（单实现）：Agent 经 WS /ws/{agent_id} 注册能力（agent_registry）；调度由 swarm_dispatch 自选（能力 + 信息素 τ + 负载 + 预算，见 agent-capability-schema.md、orchestrator/dispatch_score.py、orchestrator/decision_engine.py）。蜂群内单一调度入口，无双实现。
• 外部 / 后续（非本仓范围）：
  • ① 统一 SSE/WS 推送传输：HM Phase2（见 #46 / runtime-contract §8）；当前为 REST 轮询 + events?after= 续传，前端不丢步。
  • ② 跨平台统一 agent registry / capability center / quota / region·GPU / provider routing：Infra/Scheduling Team（#2 对齐对象），非本仓编排器。
  • ③ cockpit 三视图（graph / timeline / cost）渲染：客户端仓子工单。

结论：#18 在本仓范围内已满足（run/task/event 稳定 API + 蜂群调度入口统一）；SSE 传输与跨平台 registry 为外部/Phase2。建议 owner 据此关闭本仓部分，或保留 #18 跟踪上述外部项（同 #19 口径）。