LangBot/docs/agent-runner-pluginization/RUNTIME_CONTROL_PLANE_V2.md

Agent Runtime Control Plane V2

本文档记录后续 Agent Platform / runtime 管控面的设计方向。它是当前讨论中的 v2 文档，但这里的 v2 指 Host capability layer / runtime control plane，不是 AgentRunner Protocol v2，也不属于当前 AgentRunner Protocol v1 插件化主线的交付范围。

1. 结论

当前主线应继续收口 AgentRunner v1：

message/event -> binding -> runner.run(ctx) -> result stream

Runtime Control Plane v2 在 Host 侧新增 runtime control plane：

event -> task -> runtime selection -> daemon claim -> execute -> progress/audit/result

在 Runtime Control Plane v2 之上，可以构建独立的 agent 管控面插件。插件负责 UI、策略和编排体验；runtime、task、heartbeat、audit 的事实源必须属于 LangBot Host，而不是插件私有 storage。

2. 不影响 v1 主线

v2 不应改变 AgentRunner v1 的基本契约：

• 现有 local-agent、Dify、n8n、Coze 等 runner 仍可按 v1 直接执行。
• 当前 Claude Code / Codex MVP runner 可以继续作为本机 subprocess 开发路径。
• Host v1 已有的 event-first context、resource authorization、history / event / artifact / state / storage pull APIs 继续保留。
• Pipeline 仍只是当前入口 adapter，不参与 v2 runtime 管控面的设计中心。

v2 只是在 Host 上新增一层可选能力。需要管控面的 runner 或管理插件可以声明使用它；不需要的 runner 不受影响。

3. 当前 Host 能力与缺口

当前 Host 已经具备 v2 的基础设施底座：

• AgentEventEnvelope / AgentBinding
• run-scoped resource authorization
• EventLog / Transcript / ArtifactStore / PersistentStateStore
• History / Event / Artifact / State / Storage pull APIs
• AgentRunner result stream 和受控错误回流
• binding config 与 host-owned state

这些能力足够支持一次 runner.run(ctx) 内的安全执行，但不足以承担完整 runtime 管控面。

v2 还需要 Host 新增：

• runtime registry：runtime id、所属 workspace、所在机器、provider 能力、状态。
• capability discovery：claude / codex / 其它 CLI 是否存在、版本、登录状态、执行隔离能力。
• heartbeat / liveness：runtime 在线、忙闲、最后心跳、可用 slot。
• task queue：enqueue、claim、start、progress、complete、fail、cancel。
• workspace mapping：LangBot workspace / project 如何映射到 runtime 上的真实目录、仓库或挂载。
• secret / env projection：按授权向 runtime 投影 token、代理、MCP 配置、技能和环境变量。
• runtime audit：stdout、stderr、事件流、产物、失败原因、执行耗时、使用量。
• control API / UI：选择 runtime、测试 runtime、查看状态、下线、取消任务、重试任务。

4. 角色边界

4.1 LangBot Host

Host 是事实源和控制面内核：

• 保存 runtime / task / heartbeat / audit 状态。
• 做权限校验、资源裁剪、workspace 绑定和审计。
• 决定任务是否可被某 runtime claim。
• 将执行结果统一回写到 event / transcript / artifact / state。

Host 不应内置具体 agent CLI 的复杂业务逻辑，也不应把某个官方 runner 的特殊行为提升为通用协议。

4.2 Agent 管控面插件

管理插件是 v2 control plane 的产品化管理层：

• 展示 runtime、agent、task、进度、失败、审计。
• 提供策略配置，例如默认 runtime、provider 偏好、并发限制、重试策略。
• 触发 runtime 测试、任务取消、任务重试、手动分配。

管理插件不应把 runtime/task 的事实源放进自己的 plugin storage。它应该调用 Host v2 API。

4.3 Runtime daemon / worker

Runtime daemon 负责真实执行：

• 在所在机器上检测 CLI 和版本。
• 管理工作目录、仓库、挂载、临时文件和进程。
• 从 Host claim 任务，执行后上报 progress / complete / fail。
• 将 stdout / stderr / artifacts / session id 回流 Host。

Claude Code、Codex、OpenCode、Gemini CLI 等 provider 适配逻辑应主要落在 daemon / worker 或 provider adapter 中。

5. 部署形态

5.1 uv / local embedded

用户用 uv 或源码直接启动 LangBot 时，LangBot 进程所在机器就是 runtime host。

这种模式下可以直接检测用户主机上的 claude、codex 等 CLI，也可以直接 subprocess 执行。它适合个人开发和本地 smoke，但不应作为团队级管控面的唯一形态。

5.2 Docker embedded

用户用 Docker 启动 LangBot 时，runtime host 是容器，不是宿主机。

因此：

• 只能检测容器内的 claude、codex。
• 只能使用容器内的 HOME、PATH、凭据和挂载目录。
• 如果镜像未安装 CLI，或未挂载认证文件 / workspace，CLI runner 会不可用。

Docker embedded 可以作为高级部署选项，但需要用户显式安装 CLI、挂载工作区和凭据。Host 不应假设 Docker 容器能自动访问宿主机 CLI。

5.3 Sidecar daemon

推荐的 v2 形态是 sidecar daemon：

LangBot Host (Docker or server)
  <-> Runtime daemon on user host / worker host
        -> claude / codex / other CLI

这种模式下，LangBot 可以跑在 Docker 内，runtime daemon 跑在宿主机或独立 worker 机器上。daemon 负责检测本机 CLI、持有本机凭据和工作区访问能力。

5.4 Remote runtime

团队场景可以使用远端 runtime：

• 开发机、构建机、云主机或专用 worker。
• 多个 workspace 可绑定不同 runtime。
• Host 只通过 registry / task queue / heartbeat / audit 进行管理。

5.5 API-only agent

Dify、n8n、Coze、DashScope 等 API 型 runner 不依赖本地 CLI。它们可以继续按 v1 直接执行，也可以在未来按需要接入 v2 task/audit。

6. 与 Claude Code / Codex MVP runner 的关系

当前 Claude Code / Codex runner 是 v1 runner：

runner.run(ctx) -> subprocess("claude" / "codex")

它们适合验证 Host context 投影、state resume、result stream 和基础 CLI 调用，但有明确限制：

• 命令只在 LangBot runtime host 上执行。
• Docker 环境只能看到容器内 CLI。
• 没有 runtime registry、heartbeat、task queue、cancel、workspace lifecycle。
• 不提供发布级执行隔离、secret projection、团队级 audit。

v2 不需要删除这些 runner。它们可以继续作为 dev / MVP 路径存在。未来若接入管控面，可以增加 runtime-managed 执行模式：

runner binding -> Host task -> runtime daemon -> provider CLI -> Host result

7. 最小 v2 API 草案

以下仅记录能力边界，不代表最终 API 命名。

Runtime：

• runtime.register
• runtime.heartbeat
• runtime.list
• runtime.get
• runtime.disable
• runtime.capabilities.report
• runtime.capabilities.probe

Task：

• task.enqueue
• task.claim
• task.start
• task.progress
• task.complete
• task.fail
• task.cancel
• task.retry

Workspace：

• runtime.workspace.bind
• runtime.workspace.unbind
• runtime.workspace.resolve

Audit / artifacts：

• task.log.append
• task.artifact.create
• task.events.page

这些 API 应由 Host 提供，并受 workspace、runtime、binding、actor 和 plugin identity 约束。

8. 管控面插件可以构建的能力

基于 v2 Host 能力，可以实现一个类似 Multica 的 agent 管控面插件：

• runtime 列表、在线状态、CLI 能力、版本、认证状态。
• agent profile 与 runtime/provider 绑定。
• 任务看板、任务详情、进度流、失败原因、重试和取消。
• workspace 到 runtime 目录 / 仓库的映射管理。
• provider capability 测试，例如 Claude Code / Codex 是否可执行。
• 审计视图：输入、输出、工具、artifact、stdout/stderr、session id。
• 策略配置：并发、队列、默认 runtime、fallback runtime、权限模式。

该插件应该是 Host v2 的消费者，而不是 Host v2 的替代品。

9. 设计原则

• v1 先稳定，v2 可选叠加。
• Host 保存事实源，插件提供管理体验。
• Runtime daemon 执行具体 CLI 和本机资源访问。
• Docker 不假设拥有宿主机 CLI；需要 sidecar 或显式挂载。
• Pipeline 不进入 v2 控制面中心。
• 直接 subprocess runner 可保留，但只作为 local/dev/MVP 路径。
• 发布级能力必须经过 Host 权限、审计和资源边界。

10. 待定问题

• runtime daemon 与 Host 的认证模型：workspace token、device token、还是 scoped PAT。
• task 与 AgentRunner binding 的映射关系：由 binding 直接 enqueue，还是由独立 task policy 决定。
• runtime capability schema 的稳定字段：provider、version、login status、execution isolation、workspace access、slot。
• secret projection 的边界：Host 存储、用户本机存储、或外部 secret manager。
• Docker compose 是否提供官方 sidecar daemon 示例。
• v2 UI 是核心前端的一部分，还是完全由管理插件提供。