Agentswarm/docs/integration/runtime-contract.md

Manager ↔ Swarm Runtime Contract（Swarm 侧拥有）

状态：FROZEN v1（契约冻结） —— 回应 agent_swarm#14（来自 HM #28/#45 客户端「任务驾驶舱」查询面：stop 端点 + ID 映射 + 状态机）。对齐对象：Heicode Manager Runtime Team。

冻结结论（供 HM #45 接 stop 真实调用）：

• stop 端点：POST /api/agent/swarm/deployments/{id}/stop（§3），已实现，幂等键 X-Idempotency-Key。
• ID 映射：deployment_id ↔ swarm_id ↔ manager_deployment_id（§3.2），get_run_by_identifier 支持任一 id 查询。
• 状态机：运行时真实状态见 §4；与客户端 #28 期望（含 preparing/degraded/verifying）的映射表见 §4.1（运行时不新增臆造状态，规则 #9）。

依据：

• HM 侧裁定 heicode-mananger/docs/integration/heicode-swarm-deferred.md：HM 当前不实现 swarm runtime；多 Agent 蜂群归 agent_swarm / HeiCode-Swarm（本仓）。
• 既有运行时集成范式 heicode-mananger/docs/integration/heicode-am-contract.md（单 Agent 模板 Agent，经 AM 启动）。本契约沿用其鉴权、回调、env、路径覆盖等约定。
• 事件 envelope/类型见 event-schema.md（同批冻结，agent_swarm#15）。

1. 角色与边界

• HM（Heicode Manager）：控制面。负责用户输入、资源/权限/计费/审计、模型网关（/v1/*）。HM 不承载蜂群编排。
• Swarm Runtime（本仓）：执行面。接收 HM 下发的编排请求，分解→派发→执行→评审→汇总，并通过带签名回调回报生命周期事件。
• HM 不在对话/执行回路；Swarm 通过回调把状态推回 HM，HM 也可主动拉取（见 §4）。

2. 鉴权（沿用 AM 约定）

• HM → Swarm：Authorization: Bearer <service_token>。Swarm 侧校验 AGENT_RUNTIME_SERVICE_TOKEN（兼容 AGNET_RUNTIME_SERVICE_TOKEN）。未配置时为非安全开发模式（仅本地）。
• 统一响应信封：成功 { "success": true, "data": {...} }；失败 { "success": false, "error": { "code", "message", "request_id" } }。
• 常用请求头：X-Correlation-ID、X-Idempotency-Key、Authorization。

3. 生命周期接口（已实现 / 待对齐）

Swarm 暴露以下接口（三组别名等价，便于 HM 路径覆盖）： /api/swarms、/api/agent/swarm/deployments、/api/agnet/deployments。

动作	方法 + 路径	状态	说明
create	POST /api/agent/swarm/deployments	✅ 已实现	创建蜂群部署；幂等键 X-Idempotency-Key
status	GET …/{deployment_id}	✅ 已实现	返回部署概要与状态
task graph	GET …/{deployment_id}/tasks	✅ 已实现	任务 DAG
logs / events	GET …/{deployment_id}/logs、/events	✅ 已实现	事件流（分页 cursor/limit）
metrics / workflow / diagnostics	GET …/{deployment_id}/metrics、/workflow、/diagnostics	✅ 已实现	指标与编排视图
cancel	POST …/{deployment_id}/stop	✅ 已实现	停止并取消非终态任务，向 Agent 下发 cancel_task
approve	POST …/{deployment_id}/approvals/{approval_id}	✅ 已实现	接收 Manager 审批决定（approved/rejected）
resume	—	🟡 待对齐	当前仅「审批通过」隐式恢复（approvals）；无独立 resume 端点
retry	—	🟡 待对齐	任务级重试 / 评审重做为内部机制；无外部 retry 端点

3.1 create 请求（必填校验）

必填：orchestration_plan.objective、callback.url、metadata.manager_deployment_id。 约束：mode 必须为 swarm；billing_context.secret_ref（若有）必须 azkv:// 前缀；resource_grants/metadata/callback 不得含明文密钥。

create 响应 data：deployment_id、runtime_deployment_id、manager_deployment_id、swarm_id、mode、status、runtime_execution_status、created。

3.2 ID 语义（回应 HM 标记的 deployment_id ↔ swarm_id 缺口）

• deployment_id / runtime_deployment_id：Swarm 侧运行时部署 ID（runtime-dep-…）。
• swarm_id：工作流 ID（swarm-…），作为 workflow_id；事件按 swarm_id 持久化与查询。
• manager_deployment_id：HM 侧部署 ID（请求 metadata.manager_deployment_id 透传）。
• correlation_id：贯穿一次交付的追踪 ID（X-Correlation-ID），作为 trace_id。
• 三者映射在 Swarm 持久化中维护：deployment_id ↔ swarm_id ↔ manager_deployment_id，get_run_by_identifier 支持三者任一查询。

HM 侧 heicode-swarm-deferred.md 记录的「Swarm 仅暴露 /tasks、缺 deployment_id↔swarm_id」为旧状态；本仓 v5/v6 已实现上述映射与 /api/agent/swarm/* 接口，需 HM 复核更新该锚点。

3.3 蜂群专家 agent 拉起环境契约（agent launch env，回应 agent_swarm#16）

冻结状态：下表的 env 字段清单本身已稳定（agent/main.py 实读，无异议）；但**「拉起触发链」（谁调 AM、何时拉起、agent 池由谁提供）仍为提案，待 @azgy(AM) + @zsbgnw12(HM) 确认**（见 #16），未冻结。在触发链敲定前，本节按「env 契约已定、触发流程待定」对待。

关键拓扑事实：编排器（swarm runtime）不拉起 agent、无 AM 客户端、不持有模型 key。专家 agent 是外部进程主动出站连编排器 WS（/ws/{agent_id}，见 §5/security-boundary §6）。注意 §1「分解→派发→执行」里的「派发」= 把任务指派给已连入的 agent，不是编排器拉起 agent pod——§1 与本节不矛盾，但二者都未定义「谁拉起 pod」（即 #16 的缺口）。

拉起触发链（提案，待确认，见 #16）：去中心化模型下编排器只播种单一种子任务、agent 自选+自主分解，无「按 run 分解算出 agent 数/角色」这一步；故 agent 是按用户的常驻池（能力多样），由 HM 触发 AM 拉起（HM 持 per-user sk- + 已有 AM 客户端；若 AM 无批量接口则 HM 循环调模板 POST /agents）。模型 key 全程 HM→AM，不经编排器 create 请求体（满足 §3.1）。ORCHESTRATOR_URL 为部署期常量，由 HM 注入。

AM 拉起每个蜂群专家 agent 时，须注入以下进程环境变量（本仓 agent/main.py 实读，为接线清单——此部分无异议）：

env	含义	来源
OPENAI_API_KEY	模型调用凭据 = HM 为该用户现签的 per-user sk-（NewAPI token），扣发起用户 user.Quota	HM 现签
OPENAI_API_BASE	HM 模型网关 /v1（OpenAI 兼容）	HM
OPENAI_MODEL	所选模型 id	HM/计划
ORCHESTRATOR_URL	编排器 WS 基址（如 ws://<swarm-runtime>）；agent 据此回连、自选任务	部署
AGENT_ID	agent 实例 id（唯一）	AM
AGENT_CAPABILITIES	能力集合（逗号分隔）	计划/角色
HEICODE_USER_ID	发起用户；用于每用户并发 Agent 上限 MAX_AGENTS_PER_USER（注册时强制，见 security-boundary §6）	HM
WORKSPACE_DIR / GIT_REPO_URL	可选：工作区 / 代码仓	资源授权

约束：

• key 注入是 server→server env，不入 create 请求 / 回调 / 日志 / 事件（与模板 Agent 一致）；编排器 create 的 billing_context 仅为归因元数据（newapi_user_ref/quota_ref），不承载 key。见 usage-billing-schema.md §2。
• token 生命周期 = agent 部署生命周期（stop/delete 时由 HM 吊销），非 run 结束——专家 agent 长驻、跨 run 自选任务。
• 所有专家 agent 注入同一把该用户的 sk- + OPENAI_API_BASE=HM/v1，保证计费归一到发起用户；task_executor 随模型请求带 X-Agent-* 归因头供 HM/NewAPI 关联。
• 运行时事件前置：只有 (i) HM 真把 create 派发到编排器（SWARM_RUNTIME_ENABLED=true，非 manager-local 适配器）且 (ii) 专家 agent 已按上表拉起连入，编排器才会回推 task.*/swarm.* 等运行时事件（否则 events feed 仅有 HM 控制面的 deployment.status_changed）。

4. 状态机

部署状态：waiting_approval → running →（blocked ⇄ running）→ 终态 completed / failed / stopped。

状态	含义	进入方式
waiting_approval	高危/需审批，等待 Manager 审批	create 时命中审批条件
running	任务派发与执行中	审批通过 / 有在途任务
blocked	任务因移交/依赖阻塞	子任务 blocked_on_handoff
completed	所有任务终态且评审通过	全部完成（评审循环可选）
failed	存在失败且不可恢复	任务终态含 failed
stopped	Manager 主动停止	…/stop

每次状态变更通过回调 deployment.status_changed 推送（见 §5）；终态另发 swarm.completed/swarm.failed/swarm.stopped（客户端驾驶舱据此切终态横幅，见 event-schema §4）。

4.1 与客户端期望状态的映射（#14.3 决议：映射，不新增运行时状态）

客户端 #28 期望 created/preparing/running/waiting_approval/degraded/verifying/completed/failed/stopped。本运行时不臆造 preparing/degraded/verifying 等中间态（规则 #9：无真实信号不造态），由 HM/客户端按下表映射现有真实状态：

客户端期望态	运行时真实来源	映射口径
created	create 成功、尚无在途任务	初始 running 前的瞬态；HM 可在落 runtime_swarm_id 后、首个 task.* 前显示
preparing	同上（播种中）	映射到 running（种子已注入、Agent 尚未自选）；无独立状态
running	running	直通
waiting_approval	waiting_approval	直通
degraded	blocked	blocked（移交/依赖/审批驳回阻塞）映射为 degraded；P-guard run.metadata["health"] 不健康亦可佐证
verifying	running + 交叉评审进行中	评审期仍是 running；如需细分，由 timeline.updated(Review cycle N) / run.metadata["cross_review"] 提示
completed/failed/stopped	同名终态	直通；并有 swarm.{completed,failed,stopped} 终态事件

即：运行时真实状态集 = waiting_approval/running/blocked/completed/failed/stopped（§4 表）；created/preparing/degraded/verifying 是展示层别名，不改变运行时语义，也不进入回调 status 字段。如客户端坚持要真实细分态，需另立工单评估状态机扩展（非本次冻结范围）。

5. 回调（已与 HM 处理器对齐）

Swarm → HM：POST {callback.url}（create 时下发，默认 HM 的 /api/agent/callbacks/runtime-events）。

鉴权与签名（与 HM agent_callback.go 一致，已实现）：

• 头：X-Agent-Service-Token（或 Authorization: Bearer）、X-Agent-Timestamp（Unix 毫秒）、X-Agent-Signature、X-Agent-Event-Id、X-Correlation-ID（均含 X-Agnet- 兼容别名）。
• 签名：signature = "sha256=" + hex(HMAC_SHA256(secret, f"{timestamp}.{event_id}.{raw_body}"))。
• secret：AGENT_CALLBACK_SIGNING_SECRET（兼容 AGNET_…）；HM 侧容差默认 300s。
• 幂等：HM 按 X-Agent-Event-Id → body event_id → idempotency_key 去重。

事件 envelope 字段与 event_type 取值见 event-schema.md（与 HM 注册表一致）。

6. 路径与超时覆盖（沿用 AM 约定）

HM 侧可用 env 覆盖：AGENT_RUNTIME_BASE_URL、AGENT_RUNTIME_SERVICE_TOKEN、AGENT_RUNTIME_AGENT_START_PATH、AGENT_RUNTIME_AGENT_PATH、AGENT_RUNTIME_AGENT_STOP_PATH、AGENT_RUNTIME_START_TIMEOUT_SECONDS、AGENT_RUNTIME_CALLBACK_URL。

7. 安全

• env/请求体不得含明文密钥；凭据经 secret_ref（azkv://）注入。详见 security-boundary.md。
• Swarm 启动接口必须 HTTPS / 私网；回调走 HTTPS。

8. 冻结状态与剩余对齐项

本次冻结（agent_swarm#14）已定稿：stop 端点（§3）、ID 映射（§3.2）、状态机 + 客户端映射表（§4/§4.1）、终态 swarm.* 事件。HM #45 可据此接 stop 真实调用。

剩余非阻塞项（不影响 #45 Phase1 接入）：

• resume / retry 是否需要独立外部端点，还是沿用 approvals + 内部重做（当前：无独立端点）。
• HM 是否以 AM 同款 /agents 生命周期（而非 /api/agent/swarm/*）调用 Swarm；若是，需路径映射。
• HM 注册表（agent_callback.go）登记本次新增的 swarm.completed/failed/stopped、approval.approved/rejected、handoff.created（见 event-schema §4 ⭐）。
• 更新 HM 侧 heicode-swarm-deferred.md 锚点，登记本契约。
• #46 Phase2（SSE 长连 + 追加输入写语义）：待本契约 + event-schema 冻结后由 HM 把轮询升级 SSE（见 frontend-event-api.md §4）。