xinyin025/LangBot
1
0
Fork 0
mirror of https://github.com/langbot-app/LangBot.git synced 2026-06-26 15:34:26 +00:00
Code Issues Packages Projects Releases Wiki Activity

refactor(agent-runner): use sandbox file model

Browse Source
This commit is contained in:
huanghuoguoguo
2026-06-19 09:30:12 +08:00
parent 2c09af406e
commit 79a5fba06b
49 changed files with 203 additions and 3401 deletions
Download Patch File Download Diff File Expand all files Collapse all files
docs/agent-runner-pluginization/RUNTIME_CONTROL_PLANE_V2.md
+17 -19
View File
@@ -4,7 +4,7 @@
> 本文是当前决策版。协议数据结构仍以 [PROTOCOL_V1.md](./PROTOCOL_V1.md) 为准；测试执行入口见 [AGENT_RUNNER_QA_GUIDE.md](./AGENT_RUNNER_QA_GUIDE.md)；扩展边界见 [EXTENSION_SCOPE_MATRIX.md](./EXTENSION_SCOPE_MATRIX.md)。
>
> 实现状态说明：本文描述的是 Runtime Control Plane v2 的目标能力和分阶段落地建议。当前 AgentRunner 插件化主线已经具备 event-first context、run-scoped authorization、EventLog / Transcript / Artifact / State 等 Host capability，并已落地持久 `AgentRun` / `AgentRunEvent` ledger、run control actions、最小 runtime heartbeat/claim lease 和 admin reconcile 原语。完整 Agent Platform 产品形态、daemon supervisor、runtime wakeup channel 和分布式 runtime 管控仍未完成。当前实现状态以 [STATUS.md](./STATUS.md) 为准。
> 实现状态说明：本文描述的是 Runtime Control Plane v2 的目标能力和分阶段落地建议。当前 AgentRunner 插件化主线已经具备 event-first context、run-scoped authorization、EventLog / Transcript / State / sandbox 文件等 Host capability，并已落地持久 `AgentRun` / `AgentRunEvent` ledger、run control actions、最小 runtime heartbeat/claim lease 和 admin reconcile 原语。完整 Agent Platform 产品形态、daemon supervisor、runtime wakeup channel 和分布式 runtime 管控仍未完成。当前实现状态以 [STATUS.md](./STATUS.md) 为准。
## 1. 当前决策
@@ -13,7 +13,7 @@ LangBot 后续定位应更像 **Agent Host / infrastructure provider / transfer
结论：
- **Agent Platform 产品形态做成插件**。插件负责 agent 管理、策略、业务队列、UI、编排、多 agent 协作和产品体验。
- **Agent Platform 所需的基础事实源做进 Host**。当前 Host 已保存 event、artifact、state、transcript、active run 权限快照、持久 run/result ledger、审计关联和通用控制状态。
- **Agent Platform 所需的基础事实源做进 Host**。当前 Host 已保存 event、state、transcript、sandbox 文件边界、active run 权限快照、持久 run/result ledger、审计关联和通用控制状态。
- **最小 runtime registry / heartbeat / claim lease 已作为 Host 原语落地，但不等于完整 daemon worker 管控**。远程 harness / daemon 的进程托管、wakeup channel、provider 登录态诊断和分布式调度仍可以先由 AgentRunner 插件和 SDK remote layer 自己维护。
- **不把业务调度写进 Host**。Host 提供通用 run/result/control primitives，Platform 插件决定哪些事件触发哪些 agent、如何排队、如何分配、是否 fan-out。
@@ -21,7 +21,7 @@ LangBot 后续定位应更像 **Agent Host / infrastructure provider / transfer
```text
LangBot Host
Current base: EventLog / runtime AgentBinding / Artifact / State / Transcript / active run authorization
Current base: EventLog / runtime AgentBinding / State / Transcript / sandbox files / active run authorization
Current v2 foundation: Run / RunEvent / audit / result persistence / control primitives / minimal runtime heartbeat and claim lease
Planned: Agent / Binding persistence / daemon supervisor / wakeup channel / distributed runtime operations
@@ -30,7 +30,7 @@ Agent Platform plugin
Business queue / multi-agent orchestration / runtime selection policy
AgentRunner plugin / external harness runtime
Connects LiteLLM Agent Platform / remote agent / subprocess / HTTP API
Connects ACP / remote daemon / local subprocess / HTTP API
Executes and converts provider-native events to AgentRunResult
```
@@ -41,14 +41,14 @@ AgentRunner plugin / external harness runtime
- 抹平不同 AgentRunner。
- 从 IM / Pipeline 入口触发 runner。
- 有 event-first context 方向。
- 有 Host-owned EventLog / Transcript / Artifact / State。
- 有 Host-owned EventLog / Transcript / State 和 sandbox/workspace 文件边界。
- 有 runner config 下发和 active run-scoped authorization。
- 有 `run_id` 串联 event、transcript、artifact、state 和内存授权上下文。
- 有 `run_id` 串联 event、transcript、state、sandbox 文件和内存授权上下文。
这还不是完整 Agent Platform。完整 Platform 至少还需要：
- 可管理的 agent 资产：agent profile、binding、resource policy、runner config、可用状态。
- 可观察的执行生命周期：run status、result stream、失败原因、artifact、审计、回放。
- 可观察的执行生命周期：run status、result stream、失败原因、文件引用、审计、回放。
- 可运营的控制面：取消、重试、排队、并发、超时、恢复、诊断。
- 可产品化的调度体验：事件订阅、路由策略、任务板、多 agent 协作、项目/工作区视图。
@@ -66,7 +66,7 @@ Host 负责这些能力的通用事实源和安全边界；Platform 插件负责
- `EventLog` 保存输入事件和审计入口，并记录 `run_id` / `runner_id`。
- `Transcript` 保存对话历史投影，并用 `run_id` 关联 assistant 输出。
- `ArtifactStore` 保存输入和 runner 产物，并用 `run_id` 做访问边界的一部分。
- Sandbox/workspace 保存当前运行输入文件和 runner 产物，并用 `run_id` 做访问边界的一部分。
- `PersistentStateStore` 保存 runner state，但不等同于 run lifecycle。
- `AgentRunSessionRegistry` 保存 active run 的内存态授权快照，用于 proxy action 校验；进程结束或 run 结束后不作为可回放事实源。
- `AgentRun` 保存 run lifecycle、scope、authorization snapshot、queue/claim 状态、cancel intent、usage/cost 和 metadata。
@@ -120,14 +120,13 @@ message.delta
message.completed
tool.call.started
tool.call.completed
artifact.created
state.updated
action.requested
run.completed
run.failed
```
Host 应保存这些输出事件，按 `run_id + sequence` 可回放。Transcript、Artifact、State 可以由这些 result event 触发写入现有 store，并保留能回溯到 `AgentRunEvent` 的关联。
Host 应保存这些输出事件，按 `run_id + sequence` 可回放。Transcript、State 可以由这些 result event 触发写入现有 store，并保留能回溯到 `AgentRunEvent` 的关联。文件和工具大结果留在当前 run 的 sandbox/workspace 中，不作为 result event blob 回传。
### 3.4 Queue
@@ -211,7 +210,6 @@ data_json
usage_json
created_at
source
artifact_refs_json
metadata_json
```
@@ -220,7 +218,7 @@ metadata_json
- 同一 `run_id` 内 `sequence` 单调递增。
- append 必须幂等，支持远程 daemon / plugin 重试。
- 未知 result type 可保存但 Host 只对已知类型执行副作用。
- 大 payload 仍应转 artifact，不直接塞入 result event。
- 大 payload 仍应进入 sandbox/workspace，不直接塞入 result event。
- `usage_json` 保存 `AgentRunResult.usage` 原样结构；缺失表示 unknown，不等于 0。
### 4.3 Run Control API
@@ -240,7 +238,7 @@ run.finalize
语义：
- `run.create` 创建 Host-owned run 和授权快照。
- `run.append_result` 只允许受信 SDK/runtime 路径调用，必须绑定 run 创建时固化的授权快照，写入 `AgentRunEvent` 并触发 transcript/artifact/state/delivery 副作用。
- `run.append_result` 只允许受信 SDK/runtime 路径调用，必须绑定 run 创建时固化的授权快照，写入 `AgentRunEvent` 并触发 transcript/state/delivery 副作用。
- `run.finalize` 关闭 run，更新 terminal status。
- `run.cancel` 设置取消意图；同步 runner 通过 context/deadline 感知，远程 runner 通过插件/daemon 通道感知。
@@ -261,7 +259,7 @@ event -> binding -> context -> runner invocation -> result normalization
- `run.completed` / 正常 generator 结束时标记 completed。
- `run.failed` / exception / timeout 标记 failed 或 timeout。
- terminal result 携带 usage 时，写入 `AgentRunEvent.usage_json` 并汇总到 `AgentRun.usage_json`。
- `state.updated`、`artifact.created`、transcript 写入继续走现有 journal，但应与 `AgentRunEvent` 有可追踪关系。
- `state.updated`、transcript 写入继续走现有 journal，但应与 `AgentRunEvent` 有可追踪关系。
### 4.5 Usage / Cost Accounting
@@ -275,7 +273,7 @@ SDK 侧 `AgentRunResult` 已提供可选 `usage` 字段，用于把不同 runner
- Host 应把 event-level usage 原样写入 `AgentRunEvent.usage_json`，并在 terminal event 或 finalize 阶段汇总到 `AgentRun.usage_json`。
- cost 应由 Host 根据 usage、runner/model identity、发生时间和价格表计算，写入 `AgentRun.cost_json`；runner/provider 上报的 cost 只能作为非权威 telemetry 保留在 metadata 或 usage extra 中。
这层约束先解决协议位置和持久化位置；具体 ACP、LiteLLM、remote daemon、local subprocess runner 如何从 native event 中抽取 usage，可在各插件后续适配。
这层约束先解决协议位置和持久化位置；具体 ACP、remote daemon、local subprocess runner 如何从 native event 中抽取 usage，可在各插件后续适配。
### 4.6 Authorization Snapshot
@@ -289,7 +287,7 @@ SDK 侧 `AgentRunResult` 已提供可选 `usage` 字段，用于把不同 runner
- state scopes
- conversation/thread/workspace scope
后续 append result、state API、artifact API、history API 都以这个 snapshot 校验，不重新扩大权限。
后续 append result、state API、history API 和 sandbox/workspace 文件访问都以这个 snapshot 校验，不重新扩大权限。
## 5. SDK 侧应新增的最小能力
@@ -357,12 +355,12 @@ Agent Platform 插件可以负责：
- 维护业务 queue：优先级、重试策略、人工审批、分配规则。
- 选择 runner / runtime / daemon。
- 在 Run Control API 落地后，调用 Host run API 创建、取消、查询执行。
- 展示 run status、result stream、artifact、失败原因和审计。
- 展示 run status、result stream、文件引用、失败原因和审计。
Platform 插件不应负责：
- 在 Host Run Ledger 落地后，私有保存通用 run/result 事实源。
- 绕过 Host 直接写 transcript/artifact/state。
- 绕过 Host 直接写 transcript/state 或越权访问 sandbox/workspace 文件。
- 让外部 harness 直接访问 LangBot DB 或 Host 内部资源。
- 把某个业务队列语义强塞进 AgentRunner Protocol v1。
@@ -392,7 +390,7 @@ EventGateway
-> plugin displays / Host delivers
```
这两条路径最终应共享 Host run/result/artifact/state 事实源。当前阶段可共享的是 event/transcript/artifact/state 和同步执行链路；持久 run/result ledger 需要 Runtime Control Plane v2 Phase 1 补齐。区别在于是否有 Platform 插件参与产品化调度和业务队列。
这两条路径最终应共享 Host run/result/state 事实源和 sandbox/workspace 文件边界。当前阶段可共享的是 event/transcript/state、sandbox 文件和同步执行链路；持久 run/result ledger 需要 Runtime Control Plane v2 Phase 1 补齐。区别在于是否有 Platform 插件参与产品化调度和业务队列。
## 8. 与 AgentRunner Protocol v1 的关系