runtime-contract §3.3：蜂群专家 agent 拉起环境契约（Refs #16）

回应 agent_swarm#16 的接线问题：钉死「per-user sk- 怎么进 agent」。编排器不拉 agent / 无 AM 客户端 / 不持 key，agent 由 AM 拉起（HM 触发，同模板 mintAgentModelToken→env）。新增 §3.3 列出 AM 拉起蜂群专家 agent 必须注入的 env（OPENAI_API_KEY=per-user sk-、OPENAI_API_BASE=HM /v1、OPENAI_MODEL、ORCHESTRATOR_URL、AGENT_ID、AGENT_CAPABILITIES、HEICODE_USER_ID、可选 WORKSPACE_DIR/GIT_REPO_URL），均为 agent/main.py 实读；key 走 HM→AM server→server、不经 create 体；token 绑 agent 生命周期；并注明运行时事件前置（SWARM_RUNTIME_ENABLED 真派发 + agent 连入）。

仅文档；无代码/契约逻辑改动。Refs #16

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

docs/integration/runtime-contract.md

@@ -56,6 +56,29 @@ create 响应 `data`：`deployment_id`、`runtime_deployment_id`、`manager_depl
 
 > 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）
+
+**关键拓扑事实**：编排器（swarm runtime）**不拉起 agent、无 AM 客户端、不持有模型 key**。专家 agent 是**外部进程主动出站**连编排器 WS（`/ws/{agent_id}`，见 §5/security-boundary §6）。因此 agent pod 由 **Agent 平台（AM）拉起**（由 HM 触发，与模板 Agent 同构：HM `mintAgentModelToken` → 经 AM 注入 env），模型 key 全程 **HM→AM**，**不经编排器 create 请求体**（满足 §3.1「请求体不得含明文密钥」）。
+
+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](./usage-billing-schema.md)。
+- 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`。