refactor(agent-runner): use sandbox file model

docs/agent-runner-pluginization/AGENT_CONTEXT_PROTOCOL.md

@@ -14,7 +14,7 @@
 - Claude Code SDK / Codex 类 runtime 有自己的 session、transcript、tool loop 和上下文压缩。
 - Pi Agent SDK 或外部 agent 平台可能只需要当前事件和一个外部 conversation key。
 
-因此 LangBot 不应强行决定最终传给模型的历史窗口。Host 只提供：当前事件的完整结构化信息、稳定身份和会话引用、可授权读取的 history / event / artifact / state API、可投影给外部 harness 的 scoped context / SDK-owned MCP bridge / resource handles、payload hard cap 和权限 guardrail。
+因此 LangBot 不应强行决定最终传给模型的历史窗口。Host 只提供：当前事件的完整结构化信息、稳定身份和会话引用、可授权读取的 history / event / state API、sandbox/workspace 文件能力、可投影给外部 harness 的 scoped context / SDK-owned MCP bridge / resource handles、payload hard cap 和权限 guardrail。
 
 ### 1.2 Host 不定义通用历史窗口
 
@@ -44,12 +44,12 @@ LangBot 不提供 host-side inline history window。简单 runner 如果需要
 - Host MUST NOT inline full history by default.
 - Host SHOULD inline only current event / input and context handles.
 - Runner owns working-context assembly.
-- Runner MAY use Host history / event / artifact / state / storage API when authorized.
+- Runner MAY use Host history / event / state / storage API and sandbox/workspace file tools when authorized.
 - Official runners MUST consume Host infrastructure through the same public API as third-party runners.
 
 ### 2.1 必须 inline 的内容
 
-当前 event 的类型/id/时间/source；当前输入文本和结构化内容；附件/文件/图片的 metadata 和 artifact ref；actor / subject / conversation / thread / bot / workspace；delivery 能力；已授权资源列表；context cursors 和可用 API 能力；Agent/runner config。这些是 agent 决定下一步所需的最低信息。
+当前 event 的类型/id/时间/source；当前输入文本和结构化内容；附件/文件/图片的 metadata、path 或 URL；actor / subject / conversation / thread / bot / workspace；delivery 能力；已授权资源列表；context cursors 和可用 API 能力；Agent/runner config。这些是 agent 决定下一步所需的最低信息。
 
 ### 2.2 默认不 inline 的内容
 
@@ -67,19 +67,19 @@ LangBot 不提供 host-side inline history window。简单 runner 如果需要
 
 所有 API 都走 `AgentRunAPIProxy`（PROTOCOL_V1 §8），由 host 用 `run_id` 校验。
 
-外部 harness 不能直接访问 LangBot 资源。无论是 history、event、artifact、state、model、tool、knowledge base，还是 LangBot skills，都必须通过 SDK runtime 转发到 Host API，并由 Host 按 active `run_id`、runner identity、binding resource policy 和 caller plugin identity 校验。harness 自己的 native tools 只属于 harness 执行环境，不能绕过 SDK runtime 访问 LangBot 内部资源。
+外部 harness 不能直接访问 LangBot 资源。无论是 history、event、state、model、tool、knowledge base，还是 LangBot skills，都必须通过 SDK runtime 转发到 Host API，并由 Host 按 active `run_id`、runner identity、binding resource policy 和 caller plugin identity 校验。当前运行文件进入授权 sandbox/workspace 后，再由 runner 用 read/write/exec 类工具按需访问。harness 自己的 native tools 只属于 harness 执行环境，不能绕过 SDK runtime 访问 LangBot 内部资源。
 
 ### 4.1 History
 
 ```python
 await api.history_page(conversation_id=ctx.context.conversation_id,
                        before_cursor=ctx.context.latest_cursor,
-                       limit=50, direction="backward", include_artifacts=False)
+                       limit=50, direction="backward", include_attachments=False)
 ```
 
 返回 `HistoryPage`（schema 见 PROTOCOL_V1 §8）。
 
-约束：`limit` 有 host hard cap；默认只能读当前 conversation / thread；跨会话读取需 binding policy / run authorization snapshot 授权；返回 artifact ref，不默认返回大文件内容。
+约束：`limit` 有 host hard cap；默认只能读当前 conversation / thread；跨会话读取需 binding policy / run authorization snapshot 授权；可返回 attachment ref，不默认返回大文件内容。
 
 ### 4.2 Search
 
@@ -91,15 +91,14 @@ await api.history_search(query="用户之前提到的数据库连接信息",
 
 Search 可先用数据库全文索引，后续接 embedding recall。它是 host 检索能力，不等于 agent 的长期记忆策略。
 
-### 4.3 Event / Artifact / State
+### 4.3 Event / State
 
 - Event API（`events.get` / `events.page`）用于读取非消息事件、工具事件、系统事件。Agent 不应把所有事件都当成 user/assistant message。
-- Artifact API（`artifact_metadata` / `artifact_read` / `artifact_read_range`）必须校验 artifact 所属 conversation / run / binding，校验 MIME / 大小 / 过期 / 权限，大文件按 range/file-key 读取，工具大结果也应 artifact 化。
 - State API（`state.get` / `set`）是可选寄宿能力。自管 runtime 可以完全不用；依附 LangBot 的官方 runner 可以使用，例如 `external.session_id`、`summary.checkpoint`。
 
 ### 4.4 大文件与工具协作
 
-大文件、多模态输入和工具产物不要内联进 prompt 或 tool result：message/content 里只放小文本和必要摘要；大文件、图片、音频、长工具输出返回 artifact ref（`artifact_id`、`mime_type`、`size`、`digest`、`summary`、`expires_at`、`permissions`）。工具之间传递大结果时传 artifact ref，不传完整 blob。Host 校验 artifact 是否属于当前 run / scope，默认不允许插件直接读任意本地路径；临时文件应有 TTL 和清理机制。
+大文件、多模态输入和工具产物不要内联进 prompt 或 tool result：message/content 里只放小文本和必要摘要；当前事件附件由 Host staged 到授权 sandbox/workspace，并在 input attachment 中给出轻量 metadata/path。工具之间传递大结果时传 sandbox path 或 attachment ref，不传完整 blob。Host 只保证当前 run 授权范围，默认不允许插件直接读任意本地路径；临时文件由 sandbox 生命周期和清理机制管理。
 
 ### 4.5 External harness context projection
 
@@ -114,24 +113,24 @@ Claude Code、Codex、Kimi Code 这类 runtime 通常已有自己的 session、
 - `MCP config`：只投影 per-run、scoped 的 SDK-owned bridge 或外部 MCP 连接配置；LangBot 资源访问必须回到 SDK runtime / Host API，不允许 harness 通过自带 MCP/native tool 直接读 Host 内部资源。
 - `state pointers`：外部 session id、working directory、checkpoint 等小型 JSON 状态通过 Host state API 保存。
 
-当前官方外部 harness 路径由 LiteLLM Agent Platform runner 承担（现状见 OFFICIAL_RUNNER_PLUGINS §7）。这类 projection 是"把 LangBot 事实源和授权资源句柄交给 harness"，不是"把 LangBot 资源本体或内部权限交给 harness"，也不是"由 LangBot 决定最终模型上下文"。
+当前官方外部 harness 路径由 ACP / Claude Code / Codex 等 runner 插件承担（现状见 OFFICIAL_RUNNER_PLUGINS §7）。这类 projection 是"把 LangBot 事实源和授权资源句柄交给 harness"，不是"把 LangBot 资源本体或内部权限交给 harness"，也不是"由 LangBot 决定最终模型上下文"。
 
 ## 5. Runner 上下文边界
 
-Host 只给当前事件、当前输入和 context handles。Runner 是否能拉取历史、事件、artifact、state 或 storage，以运行时 `ctx.context.available_apis` 为准；runner 自己决定是否拉取历史、是否搜索、何时摘要、如何构造最终 prompt。
+Host 只给当前事件、当前输入和 context handles。Runner 是否能拉取历史、事件、state 或 storage、是否能访问 sandbox/workspace 文件，以运行时 `ctx.context.available_apis` 和工具授权为准；runner 自己决定是否拉取历史、是否搜索、何时摘要、如何构造最终 prompt。
 
 ## 6. KV cache 友好的上下文管理
 
 支持 Claude Code SDK、Codex、Pi Agent SDK 等 runtime 时，必须避免每轮由 LangBot 重组大块 prompt：
 
 - 稳定 session key：`workspace/bot/binding/runner/conversation/thread`。
-- 每轮只传 delta：当前 event、artifact refs、少量 runtime metadata。
+- 每轮只传 delta：当前 event、attachment refs/path、少量 runtime metadata。
 - 历史 append-only：不要每轮改写同一段 history 文本。
 - Summary checkpoint 稳定：只有压缩发生时产生新 checkpoint。
-- 大文件和工具结果 artifact 化。
+- 大文件和工具结果写入 sandbox/workspace。
 - Tool/context API schema 稳定，数据通过 API 拉取而非塞入 prompt。
 - 对自管 runtime，优先让它复用自身 session/cache，而不是强制 LangBot 每轮重放 transcript。
-- LiteLLM 接入后，模型窗口元信息应作为 resource/runtime metadata 暴露给 runner，由 runner 决定预算和压缩策略。
+- 模型窗口元信息应作为 resource/runtime metadata 暴露给 runner，由 runner 决定预算和压缩策略。
 
 稳定 session key 的用途是隔离外部 runtime 的 resume/cache/state，不是改变 PROTOCOL_V1 §13 定义的 Agent 复用和 dispatch 边界。只有当某个外部 harness 的同一 native session 不支持并发 turn 时，runner 或 future runtime control plane 才应按 external session key 做 turn-level 串行化。
 
@@ -139,7 +138,7 @@ Host 只给当前事件、当前输入和 context handles。Runner 是否能拉
 
 ## 7. Host guardrail
 
-Agent 自管 context 不代表无限制访问。LangBot 仍必须控制：每次 run 的 active `run_id`、runner identity、当前 binding 的 resource policy、conversation / actor / subject scope、page size / artifact read size / API rate limit、跨会话读取权限、数据脱敏和敏感变量过滤、审计日志。Host 不负责"最佳上下文策略"，但负责"不越权、不爆内存、不不可审计"。
+Agent 自管 context 不代表无限制访问。LangBot 仍必须控制：每次 run 的 active `run_id`、runner identity、当前 binding 的 resource policy、conversation / actor / subject scope、page size / sandbox file read size / API rate limit、跨会话读取权限、数据脱敏和敏感变量过滤、审计日志。Host 不负责"最佳上下文策略"，但负责"不越权、不爆内存、不不可审计"。
 
 外部 harness 的 native tools、shell、MCP 或 skill 机制不构成 LangBot 资源授权边界。只要访问的是 LangBot 持有的资源，就必须经 SDK runtime 转发并接受 Host 校验；完整边界见 HOST_SDK §4.8。
 
@@ -147,4 +146,4 @@ Agent 自管 context 不代表无限制访问。LangBot 仍必须控制：每次
 
 官方 runner 插件可以把状态寄宿在 LangBot，但必须和第三方 runner 一样通过公开 Host API 消费。LangBot core 不内置官方 agent 的业务流程（prompt 组装、tool loop、RAG 编排、summary/compaction、"local-agent 专用"状态字段）。
 
-官方 local-agent 应作为"依附 LangBot 基础设施的复杂 runner 参考实现"：transcript/history 通过 `api.history_page()` / `api.history_search()` 读取，summary/checkpoint/外部 session id/用户偏好通过 `api.state_get()` / `api.state_set()` 或 storage 方法保存，图片/文件/工具大结果通过 `api.artifact_metadata()` / `api.artifact_read_range()` 读取，模型/工具/知识库通过 `api.invoke_llm()` / `api.call_tool()` / `api.retrieve_knowledge()` 调用。这样 LangBot 保持为通用 agent host，不变成内置 agent 框架。具体迁移要求见 [OFFICIAL_RUNNER_PLUGINS.md](./OFFICIAL_RUNNER_PLUGINS.md)。
+官方 local-agent 应作为"依附 LangBot 基础设施的复杂 runner 参考实现"：transcript/history 通过 `api.history_page()` / `api.history_search()` 读取，summary/checkpoint/外部 session id/用户偏好通过 `api.state_get()` / `api.state_set()` 或 storage 方法保存，图片/文件/工具大结果通过 sandbox/workspace read/write 工具访问，模型/工具/知识库通过 `api.invoke_llm()` / `api.call_tool()` / `api.retrieve_knowledge()` 调用。这样 LangBot 保持为通用 agent host，不变成内置 agent 框架。具体迁移要求见 [OFFICIAL_RUNNER_PLUGINS.md](./OFFICIAL_RUNNER_PLUGINS.md)。

docs/agent-runner-pluginization/AGENT_RUNNER_QA_GUIDE.md

@@ -16,8 +16,8 @@ event -> binding -> runner.run(ctx) -> result stream
 
 - Host 能通过当前 Query entry adapter 进入 event-first `run(event, binding)` 主链路。
 - Runner 来自插件 registry，而不是旧内置 runner 分支。
-- `local-agent` 能消费 Host 模型、工具、知识库、history、state、artifact 等基础设施。
-- 外部 harness runner（当前为 LiteLLM Agent Platform 统一入口）能消费 event-first context，并把外部 session 指针写回 host-owned state。
+- `local-agent` 能消费 Host 模型、工具、知识库、history、state、sandbox 文件等基础设施。
+- 外部 harness runner（ACP / Claude Code / Codex 等直接 runner 插件）能消费 event-first context，并把外部 session 指针写回 host-owned state。
 - 错误、权限裁剪、无输出、timeout 等路径不会破坏主聊天流程。
 
 本指南不验证：
@@ -49,7 +49,7 @@ event -> binding -> runner.run(ctx) -> result stream
 1. Host / SDK / runner 单测。
 2. WebUI 登录与 Pipeline Debug Chat 基础 smoke。
 3. `local-agent` 高价值场景。
-4. LiteLLM Agent Platform 外部 harness smoke。
+4. 外部 code-agent harness smoke。
 5. 权限和错误路径补充检查。
 6. 汇总 PASS / FAIL / BLOCKED，并给出下一步建议。
 
@@ -149,29 +149,29 @@ bin/lbs case list
 
 Rerank、remove-think、文件输入等场景只在本次改动直接涉及时补测，不作为每轮必跑项。
 
-## 7. LiteLLM Agent Platform Harness Smoke
+## 7. Code-agent Harness Smoke
 
-这些测试用于验证 Claude Code / Codex 这类自管 runtime 经 LiteLLM Agent Platform 能走同一条 Host 协议路径。若 LiteLLM Agent Platform 服务不可用、目标 harness 没有 CLI/登录态/代理配置，标记 BLOCKED，不要伪造 PASS。
+这些测试用于验证 ACP、Claude Code、Codex 这类自管 runtime 能走同一条 Host 协议路径。若目标 harness 没有 CLI/daemon、登录态、代理配置或远端 workspace，标记 BLOCKED，不要伪造 PASS。
 
-Smoke 前应优先保留一层轻量单测或 fixture 测试：LiteLLM Agent Platform HTTP session、消息发送、结果解析、`run_id` 提示词注入和 LangBot MCP gateway 必须有稳定测试覆盖。WebUI smoke 证明真实链路可用，但不能替代转换层和错误映射测试。
+Smoke 前应优先保留一层轻量单测或 fixture 测试：session 创建/复用、消息发送、结果解析、`run_id` 注入和 LangBot MCP gateway 必须有稳定测试覆盖。WebUI smoke 证明真实链路可用，但不能替代转换层和错误映射测试。
 
-### 7.1 LiteLLM Agent Platform runner
+### 7.1 外部 harness runner
 
 步骤：
 
-1. 确认 LiteLLM Agent Platform 服务可访问，目标 harness（例如 Claude Code 或 Codex）在该服务所在机器上可执行且已登录。
-2. 绑定 `plugin:langbot/litellm-agent-platform-agent/default`。
-3. 配置 `base-url`、`api-mode`、`agent-id` 或 `harness` 等必要字段。
+1. 确认目标 harness（例如 ACP daemon、Claude Code 或 Codex）在对应机器上可执行且已登录。
+2. 绑定目标 runner，例如 `plugin:langbot/acp-agent-runner/default`、`plugin:langbot/claude-code-agent/default` 或 `plugin:langbot/codex-agent/default`。
+3. 配置 runner 必要字段，例如 remote target、workspace、provider、startup timeout、reuse session 等。
 4. 在 Debug Chat 执行一次确定性真实 smoke。
 5. 检查 LangBot MCP gateway、`run_id` 回填和 host-owned state。
 
 通过条件：
 
 - WebUI 可见回复包含预期 sentinel。
-- 发送给 LiteLLM 的消息包含当前 LangBot `run_id` 和可访问资源摘要。
+- 发送给 harness 的消息包含当前 LangBot `run_id` 和可访问资源摘要。
 - Harness 通过 gateway 调用 `langbot_history_page`、`langbot_retrieve_knowledge` 或 `langbot_call_tool` 时必须携带正确 `run_id`；错误 run id 被拒绝。
 - `external.session_id` 写入 host-owned state。
-- LiteLLM 服务错误、timeout、empty output 都转成受控 `run.failed`。
+- 外部 harness 错误、timeout、empty output 都转成受控 `run.failed`。
 - resume 到同一 external session 时，全局锁边界符合 PROTOCOL_V1 §13。
 
 ### 7.2 API 型外部 runner

docs/agent-runner-pluginization/EVENT_BASED_AGENT.md

@@ -83,7 +83,7 @@ Delivery 方面，event 不一定回复到当前聊天窗口：消息事件通
 
 ## 7. 与 Context 协议的关系
 
-EBA 事件进入 AgentRunner 时仍遵循 [AGENT_CONTEXT_PROTOCOL.md](./AGENT_CONTEXT_PROTOCOL.md)：inline 当前事件、大 payload 用 raw/artifact ref、不默认 inline 完整 history、agent 按需通过 API 拉取、Host 保留 EventLog 和权限 guardrail。非消息事件可以被投影进 Transcript，但不能强制伪装为 user message；AgentRunner 根据 event type 自己决定是否纳入模型上下文。
+EBA 事件进入 AgentRunner 时仍遵循 [AGENT_CONTEXT_PROTOCOL.md](./AGENT_CONTEXT_PROTOCOL.md)：inline 当前事件、大 payload 用 raw/staged file ref、不默认 inline 完整 history、agent 按需通过 API 拉取、Host 保留 EventLog 和权限 guardrail。非消息事件可以被投影进 Transcript，但不能强制伪装为 user message；AgentRunner 根据 event type 自己决定是否纳入模型上下文。
 
 ## 8. EBA 分支联调内容
 

docs/agent-runner-pluginization/EXTENSION_SCOPE_MATRIX.md

@@ -11,7 +11,7 @@
 | 范围 | 本分支职责 | 不在本分支做 |
 | --- | --- | --- |
 | AgentRunner Protocol v1 | 定义 Host 调用 runner 的稳定合同：discovery、`AgentRunContext`、result stream、Host pull API、错误和权限边界。 | 不定义 Agent Platform 的产品数据库模型；不定义 runtime task queue。 |
-| Host runner 外化底座 | 提供 `AgentEventEnvelope`、`AgentBinding` 运行投影、`run(event, binding)`、resource authorization、run-scoped session、EventLog / Transcript / Artifact / State。 | 不实现 EventGateway、scheduler、integration provider、Agent 管控面 UI。 |
+| Host runner 外化底座 | 提供 `AgentEventEnvelope`、`AgentBinding` 运行投影、`run(event, binding)`、resource authorization、run-scoped session、EventLog / Transcript / State / sandbox 文件边界。 | 不实现 EventGateway、scheduler、integration provider、Agent 管控面 UI。 |
 | 当前 Pipeline 入口 | 通过 `QueryEntryAdapter` 把旧 Query / Pipeline config 投影成 event + binding，作为迁移期入口。 | 不继续把 Pipeline 当作长期 agent 配置中心。 |
 | 官方 runner 插件 | 作为协议消费者验证 local-agent / 外部 harness runner 能接入 Host 基础设施。 | 不让官方 runner 的内部实现反向决定 Host / SDK 协议形态。 |
 
@@ -22,16 +22,16 @@
 | Product `Agent` | 已有运行期 `AgentConfig` / `AgentBinding` 投影；还没有正式持久化产品对象。 | Agent Platform / binding persistence UI。 | 持久 Agent 保存 runner id、runner config、resource/state/delivery policy；运行前投影为 `AgentBinding`。 | 不把持久 Agent schema 加进 SDK 协议；插件实例边界见 PROTOCOL_V1 §13。 |
 | Bot / channel 绑定 Agent | 已有单次运行前的 `AgentBinding` 解析投影；目标调度语义见 PROTOCOL_V1 §13。 | EBA / Agent Platform。 | EventRouter 根据 bot、channel、workspace、conversation、event type 解析有效 `AgentBinding`。 | 不在本矩阵重定义 fan-out / observer 语义；需要时按 §3 新增设计。 |
 | Agent session / run | 当前只有 `run_id` 和 active `AgentRunSessionRegistry`，用于权限校验和生命周期。 | Agent Platform / Runtime Control Plane。 | 如需要可新增持久 `AgentRun` / `AgentSession` / task 表，但执行仍回到 `run(event, binding)` 或 runtime-managed 等价入口。 | 不把持久 session 字段塞进 `AgentRunContext` 顶层；不要求所有 runner 长期持有 LangBot session。 |
-| EventLog / Transcript / Artifact | 已完成 Host-owned store 和 pull API；runner 不直接写 DB。 | 本分支持续维护底座；Agent Platform 可复用。 | 外部 EBA、scheduler、integration、runtime task 都写同一套 EventLog / Transcript / Artifact。 | 不让 runner / sandbox 直接访问 Host DB；不把大 payload 内联进 prompt。 |
-| Host-owned state / storage | 已有 state snapshot、`state.updated` 处理和 State API；storage 作为授权能力保留。 | 本分支持续维护底座；Runtime / Platform 可复用。 | 外部 session id、working directory、checkpoint 等小 JSON 用 state；大对象用 storage / artifact。 | 不把跨轮次状态存在插件实例内；不绕过 run-scoped authorization。 |
+| EventLog / Transcript / Sandbox files | 已完成 Host-owned store、history pull API 和 sandbox 文件边界；runner 不直接写 DB。 | 本分支持续维护底座；Agent Platform 可复用。 | 外部 EBA、scheduler、integration、runtime task 都写同一套 EventLog / Transcript；当前 run 文件通过 sandbox/workspace staging 共享。 | 不让 runner / sandbox 直接访问 Host DB；不把大 payload 内联进 prompt。 |
+| Host-owned state / storage | 已有 state snapshot、`state.updated` 处理和 State API；storage 作为授权能力保留。 | 本分支持续维护底座；Runtime / Platform 可复用。 | 外部 session id、working directory、checkpoint 等小 JSON 用 state；当前 run 大对象用 sandbox/workspace 文件。 | 不把跨轮次状态存在插件实例内；不绕过 run-scoped authorization。 |
 | EventGateway / EventRouter | 本分支只提供 event-first envelope 和 `run(event, binding)` 入口。 | EBA 分支（联调中）。 | EventGateway 规范化平台/WebUI/API/scheduler 事件；EventRouter 解析一个 binding；调用现有 orchestrator。 | 不为 EBA 新增另一套 runner 调用协议；不把非消息事件伪装成 user message。 |
 | Scheduler / Automation | 不实现。文档中只把 `scheduler` 作为 future event source。 | EBA / Agent Platform。 | 定时任务触发 `schedule.triggered` host event，复用 EventGateway -> EventRouter -> `run(event, binding)`。 | 不直接调用某个 runner 插件；不绕过 EventLog / authorization。 |
 | Integration provider | 不实现。IM platform adapter 仍是当前平台接入系统。 | EBA / Agent Platform。 | OAuth/webhook/outbound provider 应先转成 canonical host event 或 platform action，再交给 AgentRunner。 | 不把 Linear/Slack/GitHub 等 provider 私有 payload 扩散到 runner 协议顶层。 |
 | Platform action / delivery | `action.requested` 已预留但当前仅 telemetry，不执行。`DeliveryContext` 只作为上下文/策略投影。 | EBA / platform action executor。 | 后续 executor 校验 runner capability、binding policy、actor/bot/workspace 权限和审批后执行。 | 不让 runner 直接调用平台 adapter 私有 API；不把平台动作伪装成文本回复副作用。 |
-| Runtime registry / worker / task queue | 不实现。当前官方外部 harness 通过 LiteLLM Agent Platform runner 调用外部平台，不在本分支维护本机 subprocess worker。 | Runtime Control Plane v2。 | 第一阶段先补 Host-owned `AgentRun` / `AgentRunEvent` / run control primitives；完整 runtime registry、heartbeat、task queue、daemon claim、progress/audit 是后续可选阶段。 | 不把 heartbeat/task/warm pool 放进 Protocol v1；不让管理插件拥有 runtime/task 事实源。 |
+| Runtime registry / worker / task queue | 不实现。当前官方外部 harness 通过 ACP、远端 daemon、本机 subprocess 或外部 HTTP API runner 调用目标运行环境，不在本分支维护通用 worker。 | Runtime Control Plane v2。 | 第一阶段先补 Host-owned `AgentRun` / `AgentRunEvent` / run control primitives；完整 runtime registry、heartbeat、task queue、daemon claim、progress/audit 是后续可选阶段。 | 不把 heartbeat/task/warm pool 放进 Protocol v1；不让管理插件拥有 runtime/task 事实源。 |
 | Warm pool / reconcile / diagnose | 不实现。 | Runtime Control Plane v2 / deployment layer。 | 作为 task/runtime 的运维能力，围绕 Host-owned runtime/task/audit 表实现。 | 不把 runtime 运维语义写进普通 runner 协议；不把 pod/task 细节泄漏给普通 runner。 |
-| Agent memory | 不实现通用长期记忆产品层；提供 history/state/storage/artifact 基础能力。 | Agent Platform 或具体 runner/plugin。 | 平台 memory 可通过 Host storage/state 或独立产品表实现，runner 通过授权 API 拉取。 | 不在 Host core 内置通用 agentic memory 策略；不默认把 memory 全量 inline 到 context。 |
-| External harness native session | LiteLLM Agent Platform runner 支持 external session id state handoff 和 LangBot resource projection。 | 官方 runner 后续增强；Runtime Control Plane v2 可接管执行。 | 外部平台调用继续走 `runner.run(ctx)`；如后续引入长连接/daemon 模式，按 external session key 串行 turn，reader 独占 native stream。 | 不把具体 provider native wire 变成 LangBot 协议；全局锁边界见 PROTOCOL_V1 §13。 |
+| Agent memory | 不实现通用长期记忆产品层；提供 history/state/storage 和 sandbox 文件基础能力。 | Agent Platform 或具体 runner/plugin。 | 平台 memory 可通过 Host storage/state 或独立产品表实现，runner 通过授权 API 拉取。 | 不在 Host core 内置通用 agentic memory 策略；不默认把 memory 全量 inline 到 context。 |
+| External harness native session | ACP / Claude Code / Codex 等 runner 支持 external session id state handoff 和 LangBot resource projection。 | 官方 runner 后续增强；Runtime Control Plane v2 可接管执行。 | 外部 harness 调用继续走 `runner.run(ctx)`；如后续引入长连接/daemon 模式，按 external session key 串行 turn，reader 独占 native stream。 | 不把具体 provider native wire 变成 LangBot 协议；全局锁边界见 PROTOCOL_V1 §13。 |
 
 ## 3. 后续分支接入规则
 
@@ -39,13 +39,13 @@
 
 - 新入口只生产或解析 Host 内部模型：`AgentEventEnvelope`、持久 Agent 投影出的 `AgentBinding`、以及必要的 delivery/resource/state policy。
 - runner 调用仍走 `AgentRunOrchestrator.run(event, binding)`，除非 Runtime Control Plane 明确引入 runtime-managed 执行模式；即便如此，runner 可见合同仍应保持 Protocol v1。
-- Host-owned facts 继续写入 EventLog / Transcript / Artifact / State；产品层可以新增更高阶视图，但不能替代这些事实源。
+- Host-owned facts 继续写入 EventLog / Transcript / State，当前 run 文件继续走 sandbox/workspace；产品层可以新增更高阶视图，但不能替代这些事实源。
 - 新能力如果需要持久化，优先加 Host-owned 表或 service；不要把事实源藏在插件 storage 或 runner subprocess 内。
 - 新 result type 可以按 Protocol v1 的演进规则增加；不能用入口 adapter 私有字段绕过 schema。
 - 任何 fan-out、observer agent、parallel arbitration、platform action execution 都必须单独定义 delivery、state conflict、approval 和 audit 语义。
 
-## 4. 与 LiteLLM Agent Platform 的关系
+## 4. 与 Agent Platform 产品层的关系
 
-这里的 LiteLLM Agent Platform 指面向 agent 产品层的实体拆分：`Agent` 描述可配置 agent，`Session` / `SessionMessage` 描述会话事实，`Automation` 描述自动触发，`IntegrationBinding` 描述外部集成连接，`Memory` 描述长期记忆，`WarmTask` 描述预热/后台任务。这些拆分对 LangBot 后续产品层有参考价值，但不能直接搬进本分支。
+这里的 Agent Platform 指面向 agent 产品层的实体拆分：`Agent` 描述可配置 agent，`Session` / `SessionMessage` 描述会话事实，`Automation` 描述自动触发，`IntegrationBinding` 描述外部集成连接，`Memory` 描述长期记忆，`WarmTask` 描述预热/后台任务。这些拆分对 LangBot 后续产品层有参考价值，但不能直接搬进本分支。
 
 LangBot 当前分支的对应目标是更底层的：把 IM/WebUI/API 等入口统一投影到 Host event，把 Agent / binding 配置统一投影到 runner binding，把 runner 能力统一收束到 Protocol v1。完整 Agent Platform 可以在这个底座之上构建，而不应反过来污染本分支的 runner 外化边界。

docs/agent-runner-pluginization/HOST_SDK_INFRASTRUCTURE.md

@@ -42,7 +42,8 @@ AgentRunOrchestrator
         |-- AgentResourceBuilder
         |-- AgentContextBuilder
         |-- AgentRunSessionRegistry
-        |-- PersistentStateStore / EventLogStore / TranscriptStore / ArtifactStore
+        |-- PersistentStateStore / EventLogStore / TranscriptStore
+        |-- Sandbox / workspace file tools
         v
 Plugin Runtime / AgentRunner
         |
@@ -81,7 +82,7 @@ class AgentEventEnvelope(BaseModel):
     metadata: dict[str, Any] = {}
 ```
 
-`AgentEventEnvelope` 是 Host 内部入口模型；投影给 runner 的是 `ctx.event`（PROTOCOL_V1 §5.4）。原始平台 payload 存为 raw event 或 artifact ref，不扩散到 runner 协议顶层。
+`AgentEventEnvelope` 是 Host 内部入口模型；投影给 runner 的是 `ctx.event`（PROTOCOL_V1 §5.4）。原始平台 payload 存为 raw event 或 staged file reference，不扩散到 runner 协议顶层。
 
 **当前 adapter source**：`QueryEntryAdapter.query_to_event(query)` 从 Query 生成 `AgentEventEnvelope`。
 
@@ -188,7 +189,8 @@ QueryEntryAdapter / EventRouter
           -> Host API / Store
        <- AgentRunResult stream
   -> apply state.updated to PersistentStateStore
-  -> write message.completed / artifact.created to Transcript / ArtifactStore
+  -> write message.completed to Transcript
+  -> keep current-run files and large tool outputs in sandbox/workspace
   -> render delivery or raise RunnerExecutionError
   -> AgentRunSessionRegistry.unregister(run_id)
 ```
@@ -222,19 +224,19 @@ SDK 侧本地校验只用于开发体验，host 侧 run authorization snapshot
 
 LangBot 可提供 host-owned state 让 runner 寄宿状态（conversation / actor / subject / runner / binding / workspace state），但**不是强制**。Host 只需提供：授权开关、scope key、get/set/list/delete API（见 PROTOCOL_V1 §8）、持久化 backend、审计和清理策略。外部 agent runtime 可维护自己的 session 和 memory。进程内 state store 只能作为过渡实现，不能作为正式生产语义。
 
-### 4.7 EventLog / Transcript / Artifact（事实源）
+### 4.7 EventLog / Transcript / Sandbox Files（事实源）
 
 - `EventLog`: durable append-only，保存原始事件、系统事件、工具调用、投递结果、错误。
 - `Transcript`: 从 EventLog 投影出的对话视图，用于 UI、审计和按需历史读取。
-- `ArtifactStore`: 保存大文件、多模态输入、工具大结果、平台附件。
+- `Sandbox / workspace files`: 当前 run 的上传文件、平台附件、工具大结果和临时产物。Host 负责 staging 与授权边界，runner 通过 read/write/exec 类工具按需访问。
 
 三类数据与 working context 的边界、读取约束见 [AGENT_CONTEXT_PROTOCOL.md](./AGENT_CONTEXT_PROTOCOL.md)。AgentRunner 可读取这些能力，但不被迫使用 LangBot 作为唯一记忆系统。
 
 ### 4.8 External harness resource projection
 
-Claude Code、Codex、Kimi Code 等外部 harness runner 可能不直接调用 LangBot 的 model/tool loop，而是把 LangBot 事件和授权资源句柄投影到自己的 harness 执行。Host 侧仍保持统一边界：Host 负责构造 event-first context、资源授权、state/storage、EventLog/Transcript/ArtifactStore 和审计；Host 或 binding policy 决定哪些 MCP bridge、skill-backed tool、artifact、history/state 句柄可投影给 runner；runner plugin 把 scoped projection 转成目标 harness 可消费形式；所有 LangBot 资源访问必须经 SDK runtime / `AgentRunAPIProxy` / SDK-owned MCP bridge 转发并接受 Host 校验；外部 harness 负责自己的 native session、tool loop、压缩、权限模式和 resume，但不能用 native tools 绕过 Host 授权。
+Claude Code、Codex、Kimi Code 等外部 harness runner 可能不直接调用 LangBot 的 model/tool loop，而是把 LangBot 事件和授权资源句柄投影到自己的 harness 执行。Host 侧仍保持统一边界：Host 负责构造 event-first context、资源授权、state/storage、EventLog/Transcript、sandbox/workspace 文件边界和审计；Host 或 binding policy 决定哪些 MCP bridge、skill-backed tool、sandbox path、history/state 句柄可投影给 runner；runner plugin 把 scoped projection 转成目标 harness 可消费形式；所有 LangBot 资源访问必须经 SDK runtime / `AgentRunAPIProxy` / SDK-owned MCP bridge 转发并接受 Host 校验；外部 harness 负责自己的 native session、tool loop、压缩、权限模式和 resume，但不能用 native tools 绕过 Host 授权。
 
-投影的具体形态（context 文件、resource handles、LangBot MCP gateway、state pointers）见 AGENT_CONTEXT_PROTOCOL §4.5；当前 LiteLLM Agent Platform runner 形态见 OFFICIAL_RUNNER_PLUGINS §7。发布级隔离要求见 SECURITY_HARDENING。
+投影的具体形态（context 文件、resource handles、LangBot MCP gateway、state pointers）见 AGENT_CONTEXT_PROTOCOL §4.5；当前 code-agent harness runner 形态见 OFFICIAL_RUNNER_PLUGINS §7。发布级隔离要求见 SECURITY_HARDENING。
 
 ## 5. SDK 侧协议
 

docs/agent-runner-pluginization/OFFICIAL_RUNNER_PLUGINS.md

@@ -16,7 +16,7 @@ langbot-app/
     manifest.yaml
     components/agent_runner/default.{yaml,py}
   langbot-agent-runner/               # 外部服务 runner 仓库
-    litellm-agent-platform-agent/  dify-agent/  n8n-agent/  ...
+    acp-agent-runner/  claude-code-agent/  codex-agent/  dify-agent/  n8n-agent/  ...
 ```
 
 后续可聚合进 monorepo，也可继续独立发布——这个选择不影响协议设计。重复逻辑优先沉淀到 SDK 或明确的共享 helper 包，不要把宿主私有结构泄漏给插件。旧 `src/langbot/pkg/provider/runners/*` 只作为历史行为对齐基准；当前未发布分支不提供旧内置 runner 的运行时 fallback。
@@ -29,7 +29,9 @@ langbot-app/
 | `dify-service-api` | `langbot/dify-agent` | `plugin:langbot/dify-agent/default` |
 | `n8n-service-api` | `langbot/n8n-agent` | `plugin:langbot/n8n-agent/default` |
 | `coze-api` | `langbot/coze-agent` | `plugin:langbot/coze-agent/default` |
-| - | `langbot/litellm-agent-platform-agent` | `plugin:langbot/litellm-agent-platform-agent/default` |
+| - | `langbot/acp-agent-runner` | `plugin:langbot/acp-agent-runner/default` |
+| - | `langbot/claude-code-agent` | `plugin:langbot/claude-code-agent/default` |
+| - | `langbot/codex-agent` | `plugin:langbot/codex-agent/default` |
 | `dashscope-app-api` | `langbot/dashscope-agent` | `plugin:langbot/dashscope-agent/default` |
 | `deerflow-api` | `langbot/deerflow-agent` | `plugin:langbot/deerflow-agent/default` |
 | `langflow-api` | `langbot/langflow-agent` | `plugin:langbot/langflow-agent/default` |
@@ -40,7 +42,7 @@ langbot-app/
 
 ## 3. 迁移批次
 
-- **Batch 1（打通协议）**：`local-agent`（能力最完整基准）、`litellm-agent-platform-agent`（外部 code-agent harness 统一入口）、`dify-agent`（传统 service API runner）。
+- **Batch 1（打通协议）**：`local-agent`（能力最完整基准）、`acp-agent-runner` / `claude-code-agent` / `codex-agent`（外部 code-agent harness 路径）、`dify-agent`（传统 service API runner）。
 - **Batch 2（外部 workflow）**：`n8n-agent`、`langflow-agent`（webhook/workflow 输入输出、timeout、外部 conversation id）。
 - **Batch 3（平台 Agent API）**：`coze-agent`、`dashscope-agent`、`tbox-agent`、`deerflow-agent`、`weknora-agent`（平台特有响应格式、引用资料、文件/图片输入、外部 thread/session 状态）。
 
@@ -67,7 +69,7 @@ execution:
 
 ## 5. local-agent 插件方向
 
-`local-agent` 是官方插件中能力最完整的消费者，但不是宿主协议的设计中心。它需要证明：一个主要依附 LangBot host 能力的 agent runner 可以通过公开协议完成模型、工具、知识库、状态、history、artifact、上下文压缩和消息投递。
+`local-agent` 是官方插件中能力最完整的消费者，但不是宿主协议的设计中心。它需要证明：一个主要依附 LangBot host 能力的 agent runner 可以通过公开协议完成模型、工具、知识库、状态、history、sandbox 文件访问、上下文压缩和消息投递。
 
 迁移或重写需覆盖旧内置 runner 的用户可见能力：model primary/fallback 选择、prompt、knowledge-bases、rerank-model、rerank-top-k、function calling、streaming、multimodal input、conversation history、monitoring metadata。
 
@@ -93,13 +95,13 @@ Claude Code、Codex、Kimi Code 这类 runner 不一定通过 LangBot 的模型/
 
 本文件只补充官方 runner 的实现要求：输入来自 `ctx.event` / `ctx.input`，不依赖 Pipeline 私有 `Query`；外部 session id / workspace / checkpoint 写入 Host state 或 plugin storage；插件实例边界见 PROTOCOL_V1 §13；CLI / subprocess runner 必须处理 timeout、取消、空输出、非零退出和 stderr 映射。
 
-实现结构应把 provider-native output 解析与 LangBot result stream 组装分开：Claude stream-json、Codex JSONL、Kimi / OpenCode 事件等只在 runner adapter 内解析，输出统一归一为 `AgentRunResult`（`message.completed` / `message.delta`、`state.updated`、`artifact.created`、`run.completed` / `run.failed`）。未知 native event 不应导致 run 崩溃；应记录诊断 metadata 或 warning。新增 harness 时优先补 native fixture -> `AgentRunResult` 的转换测试，再接 WebUI smoke。
+实现结构应把 provider-native output 解析与 LangBot result stream 组装分开：Claude stream-json、Codex JSONL、Kimi / OpenCode 事件等只在 runner adapter 内解析，输出统一归一为 `AgentRunResult`（`message.completed` / `message.delta`、`state.updated`、`run.completed` / `run.failed`）。文件和工具大结果留在当前 run 的 sandbox/workspace，通过消息 metadata、attachment ref 或 path 指向。未知 native event 不应导致 run 崩溃；应记录诊断 metadata 或 warning。新增 harness 时优先补 native fixture -> `AgentRunResult` 的转换测试，再接 WebUI smoke。
 
 并发约束应按外部 session 粒度表达，而不是按 Agent / runner id / 插件实例表达；Agent 复用和全局锁边界见 PROTOCOL_V1 §13。若 runner 使用 `external.session_id` / `thread_id` resume 到同一 native session，且该 harness 不支持并发 turn，runner 应按稳定 external session key 串行写入；一次性 subprocess runner 可以只在单次 `run(ctx)` 内处理，长连接/daemon runner 则应采用 reader 独占 native stream、turn writer 串行写入的结构。
 
 ### 6.2 LangBot MCP gateway
 
-外部 harness 不能直接持有进程内的 `plugin_runtime_handler`，也不能用自己的 native tools 直接访问 LangBot 资源。当前 LiteLLM Agent Platform runner 通过稳定 HTTP MCP gateway 把 harness 的工具请求转回 SDK runtime / Host API：
+外部 harness 不能直接持有进程内的 `plugin_runtime_handler`，也不能用自己的 native tools 直接访问 LangBot 资源。外部 harness runner 应通过稳定 HTTP MCP gateway 或 SDK-owned bridge 把 harness 的工具请求转回 SDK runtime / Host API：
 
 - Gateway 由 runner 插件启动，暴露稳定的 `langbot_history_page`、`langbot_retrieve_knowledge`、`langbot_call_tool` 等最小工具面。
 - Harness 每次调用必须携带当前 LangBot `run_id`；Host 仍按 run session、caller identity 和授权快照校验。
@@ -107,20 +109,20 @@ Claude Code、Codex、Kimi Code 这类 runner 不一定通过 LangBot 的模型/
 
 第一批工具保持很小：history page、knowledge retrieve、authorized tool call。新增工具必须先有 Host action 权限与 run-scoped authorization，再由 gateway 投影。
 
-## 7. LiteLLM Agent Platform runner 当前形态
+## 7. Code-agent harness runner 当前形态
 
-`litellm-agent-platform-agent` 是当前外部 harness runner 的统一入口，用来把 Claude Code、Codex 等具体执行器交给 LiteLLM Agent Platform / lite-harness 管理，而不是在 LangBot 官方 runner 仓库中维护每个 CLI provider 的独立适配器。本地 smoke 验收入口与记录见 [AGENT_RUNNER_QA_GUIDE.md](./AGENT_RUNNER_QA_GUIDE.md)。
+外部 code-agent harness 由直接 runner 插件承接，例如 `acp-agent-runner`、`claude-code-agent`、`codex-agent`，每个 runner 负责把目标 harness 的 native session、workspace、MCP bridge 和输出事件转换为统一 `AgentRunResult`。本地 smoke 验收入口与记录见 [AGENT_RUNNER_QA_GUIDE.md](./AGENT_RUNNER_QA_GUIDE.md)。
 
 当前形态：
 
-- Runner ID：`plugin:langbot/litellm-agent-platform-agent/default`。
-- Runner 通过 HTTP 调用 LiteLLM Agent Platform，外部 harness 的安装、登录态、workspace 和 provider-native 权限由该平台所在运行环境负责。
+- Runner ID 示例：`plugin:langbot/acp-agent-runner/default`、`plugin:langbot/claude-code-agent/default`、`plugin:langbot/codex-agent/default`。
+- Runner 可通过 ACP、远端 daemon、本机 subprocess 或外部 HTTP API 调用 harness；harness 的安装、登录态、workspace 和 provider-native 权限由该运行环境负责。
 - Runner 会把当前 LangBot `run_id`、可访问资源摘要和 gateway 使用规则注入本次消息；harness 通过 gateway 回填 `run_id` 后访问 LangBot 资产。
-- 外部 session id 写回 Host state，后续轮次可复用目标平台会话。
+- 外部 session id / workspace / checkpoint 写回 Host state 或 plugin storage，后续轮次可复用目标 harness 会话。
 
 ### 7.1 当前限制
 
-这不是发布级安全边界实现；LangBot 只约束 LangBot 持有资产的访问，外部 harness 的文件、进程、workspace、provider-native MCP 和模型凭据由 LiteLLM Agent Platform 部署侧承担。当前 `run_id` 由系统提示词传递给 harness 并由 gateway 校验，后续若 LiteLLM 原生支持 run-scoped MCP session，可切换为平台级传递。runtime 管控面方向见 [RUNTIME_CONTROL_PLANE_V2.md](./RUNTIME_CONTROL_PLANE_V2.md)。
+这不是发布级安全边界实现；LangBot 只约束 LangBot 持有资产的访问，外部 harness 的文件、进程、workspace、provider-native MCP 和模型凭据由对应 runner 的运行环境承担。当前 `run_id` 可由系统提示词、ACP metadata 或 runner 自有 session metadata 传递给 harness 并由 gateway 校验。runtime 管控面方向见 [RUNTIME_CONTROL_PLANE_V2.md](./RUNTIME_CONTROL_PLANE_V2.md)。
 
 ## 8. 发布和安装策略
 
@@ -132,5 +134,5 @@ Claude Code、Codex、Kimi Code 这类 runner 不一定通过 LangBot 的模型/
 - LangBot 主聊天路径不再通过 `RequestRunner` 执行业务 runner。
 - 官方插件测试覆盖非流式、流式、错误、timeout、配置缺失。
 - `local-agent` 能完成模型 fallback、tool calling、知识库检索、多模态输入、静态绑定 prompt 消费、history API 拉取、rerank。
-- `litellm-agent-platform-agent` 或同类 code-agent harness runner 能消费 event-first context、投影 scoped resources、保存 external session state，并通过 WebUI Debug Chat smoke。
+- 外部 code-agent harness runner 能消费 event-first context、投影 scoped resources、保存 external session state，并通过 WebUI Debug Chat smoke。
 - `local-agent` 覆盖旧内置 runner 的用户可见核心能力；代码结构和运行路径不需要相同。

docs/agent-runner-pluginization/PROTOCOL_V1.md

@@ -39,7 +39,7 @@ Protocol v1 **不定义**：
 `ctx.config`、`ctx.resources`、`ctx.context` 和 `ctx.delivery`。SDK 不需要知道
 Agent / binding 的持久化形态。
 
-外部 harness runner（Claude Code、Codex、Kimi Code 等）也是 `AgentRunner`：它们消费 event-first `AgentRunContext`、返回 `AgentRunResult`，并通过 Host 授权的 state/storage/artifact API 保存跨轮次指针。它们内部可以继续使用自己的 session、tool loop、MCP、上下文压缩和权限模型。
+外部 harness runner（Claude Code、Codex、Kimi Code 等）也是 `AgentRunner`：它们消费 event-first `AgentRunContext`、返回 `AgentRunResult`，并通过 Host 授权的 state/storage API 保存跨轮次指针；当前运行文件和工具大结果进入 sandbox/workspace。它们内部可以继续使用自己的 session、tool loop、MCP、上下文压缩和权限模型。
 
 ## 3. 协议演进
 
@@ -64,17 +64,11 @@ class AgentRunnerDiscovery(BaseModel):
     plugin_author: str
     plugin_name: str
     runner_name: str
-    runner_description: I18nObject | None = None
     manifest: AgentRunnerManifest
-    capabilities: AgentRunnerCapabilities  # compatibility alias of manifest.capabilities
-    permissions: AgentRunnerPermissions    # compatibility alias of manifest.permissions
-    config: list[DynamicFormItemSchema] = []
 ```
 
 `manifest` 是 SDK typed `AgentRunnerManifest`，由 Runtime 从插件组件 manifest 解析并校验后返回。`plugin_author` / `plugin_name` / `runner_name` 保留为 transport 寻址字段；Host 以它们生成稳定 runner id，并把 `manifest.id` 校验为 `plugin:author/name/runner`。单个 runner manifest 解析失败时 Runtime/Host 记录 warning 并跳过该 runner，不影响同一插件或其它插件的 runner discovery。
 
-`capabilities` / `permissions` 顶层字段是兼容旧 discovery 消费方的冗余别名；新代码必须以 `manifest.capabilities` / `manifest.permissions` 为准。
-
 ### 4.2 AgentRunnerManifest
 
 这里的 manifest 指 Runtime 返回给 Host 的 typed runner manifest：
@@ -116,7 +110,7 @@ class AgentRunnerCapabilities(BaseModel):
 - `streaming`: runner 可以返回 `message.delta`。
 - `tool_calling`: runner 可能调用 Host tool API。
 - `knowledge_retrieval`: runner 可能调用 Host knowledge API。
-- `multimodal_input`: runner 可以处理非纯文本 input / artifact。
+- `multimodal_input`: runner 可以处理非纯文本 input / attachment。
 - `skill_authoring`: runner 需要 Host 提供 skill facts 以及 skill authoring tools，例如 `activate` / `register_skill`。
 - `interrupt`: runner 支持取消或中断。
 - `steering`: runner 支持在 turn 边界通过 Host pull API 消费同 conversation 在途追加消息。
@@ -132,7 +126,6 @@ class AgentRunnerPermissions(BaseModel):
     knowledge_bases: list[Literal["list", "retrieve"]] = []
     history: list[Literal["page", "search"]] = []
     events: list[Literal["get", "page"]] = []
-    artifacts: list[Literal["metadata", "read"]] = []
     storage: list[Literal["plugin", "workspace"]] = []
     files: list[Literal["config", "knowledge"]] = []
 
@@ -161,7 +154,7 @@ effective_access = manifest.permissions ∩ binding.resource_policy ∩ current
 - Host 不得默认 inline 全量历史。
 - Host 只 inline 当前 event / input 和 context handles。
 - Runner 拥有 working context assembly。
-- Runner 可在授权后通过 Host history / event / artifact / state API 拉取更多上下文。
+- Runner 可在授权后通过 Host history / event / state API 拉取更多上下文，并通过授权 sandbox/workspace 工具访问当前运行文件。
 - 历史窗口策略不属于 Protocol v1 字段，也不属于 Host 通用语义。
 
 context 边界的设计理由见 [AGENT_CONTEXT_PROTOCOL.md](./AGENT_CONTEXT_PROTOCOL.md)。
@@ -242,7 +235,7 @@ class AgentEventContext(BaseModel):
 
 - `event_type` 使用 LangBot 稳定协议名，例如 `message.received`。稳定事件名清单见 [EVENT_BASED_AGENT.md](./EVENT_BASED_AGENT.md)。
 - 平台原始事件名放入 `source_event_type`。
-- 大型原始 payload 必须放入 `raw_ref` 或 artifact，不应直接塞入 `data`。
+- 大型原始 payload 必须放入 `raw_ref` 或 staged file，不应直接塞入 `data`。
 
 ### 5.5 Conversation / Actor / Subject
 
@@ -281,11 +274,11 @@ class SubjectContext(BaseModel):
 class AgentInput(BaseModel):
     text: str | None = None
     contents: list[ContentElement] = []
-    attachments: list[ArtifactRef] = []
+    attachments: list[InputAttachment] = []
 ```
 
 - 文本、多模态、附件都属于当前 event input。
-- 大文件、图片、音频、工具大结果应以 artifact ref 传递。
+- 大文件、图片、音频、工具大结果应进入授权 sandbox/workspace，input attachment 只携带轻量 metadata/path/url/content。
 - 平台原始消息链不属于 SDK `AgentInput`；需要诊断时放在 Host 内部 envelope 或 `ctx.adapter.extra` 的一次性兼容字段中，不作为长期 runner 合同。
 
 ### 5.7 DeliveryContext
@@ -329,8 +322,6 @@ class ContextAPICapabilities(BaseModel):
     history_search: bool = False
     event_get: bool = False
     event_page: bool = False
-    artifact_metadata: bool = False
-    artifact_read: bool = False
     state: bool = False
     storage: bool = False
     steering_pull: bool = False
@@ -373,14 +364,13 @@ class AgentResources(BaseModel):
     tools: list[ToolResource] = []
     knowledge_bases: list[KnowledgeBaseResource] = []
     skills: list[SkillResource] = []
-    files: list[FileResource] = []
     storage: StorageResource = StorageResource()
     platform_capabilities: dict[str, Any] = {}
 ```
 
 `skills` 只包含本次 run 中 pipeline-visible 的 skill facts，例如 `skill_name`、`display_name` 和 `description`。Host 不把这些 facts 追加到 system prompt，也不把它们编排进工具描述；runner 可以自行决定是否放入 model prompt、转换成 MCP surface，或只在自己的策略层使用。
 
-资源列表是本次 run 的授权结果。History / Event / Artifact 访问通过 `ctx.context.available_apis` 和 Host 侧 run session 校验控制，不作为可枚举 resource list 暴露。Runner 只能通过 `AgentRunAPIProxy` 访问这些能力。
+资源列表是本次 run 的授权结果。History / Event / State / Storage 访问通过 `ctx.context.available_apis` 和 Host 侧 run session 校验控制，不作为可枚举 resource list 暴露。Runner 只能通过 `AgentRunAPIProxy` 访问这些能力。当前事件的文件和工具大结果优先进入授权 sandbox/workspace，由 runner 通过 read/write/exec 类工具按需读取。
 
 ## 7. Result Stream
 
@@ -394,7 +384,6 @@ ResultType = Literal[
     "message.completed",
     "tool.call.started",
     "tool.call.completed",
-    "artifact.created",
     "state.updated",
     "action.requested",
     "run.completed",
@@ -432,7 +421,7 @@ class LLMTokenUsage(BaseModel):
 
 Host 边界分级校验：
 
-- `message.delta`、`message.completed`、`artifact.created`、`state.updated`、`action.requested`、`run.completed`、`run.failed` 属于会影响投递或 Host 副作用的严格 payload；校验失败时丢弃该 result 并记录 warning。
+- `message.delta`、`message.completed`、`state.updated`、`action.requested`、`run.completed`、`run.failed` 属于会影响投递或 Host 副作用的严格 payload；校验失败时丢弃该 result 并记录 warning。
 - `tool.call.started`、`tool.call.completed` 当前只作为 telemetry，payload 宽松兼容。
 - 未知 `type` 忽略并记录 warning。
 
@@ -444,13 +433,12 @@ Host 边界分级校验：
 | `message.completed` | `{ "message": Message }` |
 | `tool.call.started` | `{ "tool_call_id": str, "tool_name": str, "parameters": dict }` |
 | `tool.call.completed` | `{ "tool_call_id": str, "tool_name": str, "result": dict \| None, "error": str \| None }` |
-| `artifact.created` | `{ "artifact_type": str, "artifact_id"?: str, "mime_type"?: str, "name"?: str, "size_bytes"?: int, "sha256"?: str, "metadata"?: dict, "content_base64"?: str }` |
 | `state.updated` | `{ "scope": "conversation" \| "actor" \| "subject" \| "runner", "key": str, "value": JSONValue }` |
 | `action.requested` | `{ "action": str, "target": dict \| None, "payload": dict \| None }` |
 | `run.completed` | `{ "finish_reason": str, "message"?: Message }` |
 | `run.failed` | `{ "code": str, "error": str, "retryable": bool }` |
 
-`artifact.created.content_base64` 是小 artifact 的 inline 通道；Host 解码后写入 ArtifactStore，当前 hard cap 是 1 MiB。大 artifact 应使用外部存储 / file key / 后续上传通道，不应塞入 result event。
+Runner 生成的大文件、工具输出和临时产物不通过 result event 回传；应写入当前 run 的授权 sandbox/workspace，再用消息文本、metadata 或 attachment reference 指向它们。
 
 ### 7.3 稳定 result types
 
@@ -460,7 +448,6 @@ Host 边界分级校验：
 | `message.completed` | 完整消息。 | ✅ |
 | `tool.call.started` | 工具调用开始的可观测事件。 | telemetry |
 | `tool.call.completed` | 工具调用完成的可观测事件。 | telemetry |
-| `artifact.created` | runner 生成 artifact。 | ✅ |
 | `state.updated` | runner 请求更新 host-owned state。 | ✅ |
 | `action.requested` | runner 请求 Host 执行平台动作。 | **reserved / 仅 telemetry，不执行** |
 | `run.completed` | run 正常结束。 | ✅ |
@@ -511,7 +498,7 @@ await api.retrieve_knowledge(kb_id, query_text, top_k=5, filters=None)
 # History（返回 Transcript projection，不返回原始平台 payload）
 await api.get_prompt()
 await api.history_page(conversation_id=None, before_cursor=None, after_cursor=None,
-                       limit=50, direction="backward", include_artifacts=False)
+                       limit=50, direction="backward", include_attachments=False)
 await api.history_search(query, filters=None, top_k=10)
 
 # Event（返回稳定 event envelope 或受限 raw ref，不默认返回大 payload）
@@ -519,11 +506,6 @@ await api.event_get(event_id)
 await api.event_page(conversation_id=None, event_types=None, before_cursor=None, limit=50)
 await api.steering_pull(mode="all", limit=None)
 
-# Artifact（必须支持大小限制、MIME 校验、过期时间和授权范围）
-await api.artifact_metadata(artifact_id)
-await api.artifact_read(artifact_id, offset=0, limit=None)
-await api.artifact_read_range(artifact_id, offset=0, length=65536)
-
 # State / Storage
 await api.state_get(scope, key);   await api.state_set(scope, key, value);   await api.state_delete(scope, key)
 await api.state_list(scope, prefix=None, limit=100)
@@ -532,8 +514,7 @@ await api.get_plugin_storage_keys()
 await api.get_workspace_storage(key); await api.set_workspace_storage(key, value); await api.delete_workspace_storage(key)
 await api.get_workspace_storage_keys()
 
-# Files / Host info
-await api.get_file(file_key)
+# Host info
 await api.get_langbot_version()
 ```
 
@@ -593,7 +574,7 @@ class TranscriptItem(BaseModel):
     item_type: str = "message"
     content: str | None = None
     content_json: dict[str, Any] | None = None
-    artifact_refs: list[dict[str, Any]] = []
+    attachment_refs: list[dict[str, Any]] = []
     seq: int | None = None
     cursor: str | None = None
     created_at: int | None = None
@@ -653,31 +634,6 @@ class SteeringInputItem(BaseModel):
 
 class SteeringPullResult(BaseModel):
     items: list[SteeringInputItem] = []
-
-class ArtifactMetadata(BaseModel):
-    artifact_id: str
-    artifact_type: str
-    mime_type: str | None = None
-    name: str | None = None
-    size_bytes: int | None = None
-    sha256: str | None = None
-    source: str
-    conversation_id: str | None = None
-    run_id: str | None = None
-    runner_id: str | None = None
-    created_at: int | None = None
-    expires_at: int | None = None
-    metadata: dict[str, Any] = {}
-
-class ArtifactReadResult(BaseModel):
-    artifact_id: str
-    mime_type: str | None = None
-    size_bytes: int | None = None
-    offset: int = 0
-    length: int | None = None
-    content_base64: str | None = None
-    file_key: str | None = None
-    has_more: bool = False
 ```
 
 ## 9. 错误模型
@@ -720,11 +676,11 @@ Runner 失败使用 `run.failed`：
 
 Protocol v1 的安全边界在 Host：
 
-- Runner 不能直接访问未授权 model/tool/kb/history/artifact/storage。
+- Runner 不能直接访问未授权 model/tool/kb/history/storage/sandbox。
 - SDK 本地校验只提升开发体验，不能替代 Host 校验。
 - 所有 resource id 对 runner 来说都是 opaque。
 - 默认只能访问当前 conversation / thread 的 history；跨会话、workspace 级访问必须额外授权。
-- 大 payload 必须 artifact 化；`artifact.created.content_base64` 只用于小 artifact，当前 Host hard cap 是 1 MiB。
+- 大 payload 不应塞进 result event；当前 run 的文件和工具大结果应进入授权 sandbox/workspace，由 read/write/exec 类工具按需访问。
 - Host 必须记录 run_id、runner_id、action、resource、scope、result。
 
 Host 不负责业务编排：不拼接全量历史、不替 runner 做 prompt assembly、不内置 agent memory / tool loop / 上下文压缩策略。这些由官方或第三方 AgentRunner 插件实现。
@@ -764,7 +720,6 @@ entry adapter 只是迁移桥。它负责：
 ## 14. 开放问题
 
 - `AgentBinding` 是否需要进入 SDK 文档作为只读诊断信息，还是完全 Host 内部。
-- ArtifactStore 是否复用现有 BinaryStorage backend，还是引入独立实体。
 - State 与 Storage 的边界是否需要更强类型。
 - platform action 的审批模型如何表达。
 - Host 侧 scoped MCP / skill / workspace projection 是否需要从 runner config 上移为一等 resource projection API。

docs/agent-runner-pluginization/README.md

@@ -24,8 +24,9 @@
 - Host-side `AgentEventEnvelope` / `AgentBinding` 模型
 - `run(event, binding)` event-first 入口
 - `QueryEntryAdapter`：Query → AgentEventEnvelope + AgentBinding
-- EventLog / Transcript / ArtifactStore / PersistentStateStore
-- History / Event / Artifact / State pull APIs
+- EventLog / Transcript / PersistentStateStore
+- History / Event / State pull APIs
+- Sandbox/workspace read/write/exec 文件能力，用于当前 run 的上传文件、工具大结果和临时产物
 - SDK runtime forwarding pull APIs + `caller_plugin_identity` 验证路径
 
 ## 本分支不实现
@@ -52,7 +53,7 @@ EventGateway / EventRouter 在本文档中描述为 **external EBA branch integr
 
 **当前 Pipeline 是入口 adapter，不再是 agent runner 设计核心。**
 
-主入口仍可由 Pipeline 触发，但内部已转换成 event-first path：`run_from_query()` 经 `QueryEntryAdapter` 把 `Query` 转换为 `AgentEventEnvelope` + `AgentBinding`，再委托到统一的 `run(event, binding, ...)`。Pipeline path 因此获得了 event-first host capabilities（EventLog / Transcript / ArtifactStore / PersistentStateStore 写入，History / Event / Artifact / State pull API 可用）。
+主入口仍可由 Pipeline 触发，但内部已转换成 event-first path：`run_from_query()` 经 `QueryEntryAdapter` 把 `Query` 转换为 `AgentEventEnvelope` + `AgentBinding`，再委托到统一的 `run(event, binding, ...)`。Pipeline path 因此获得了 event-first host capabilities（EventLog / Transcript / PersistentStateStore 写入，History / Event / State pull API 和 sandbox/workspace 文件读写能力可用）。
 
 下一轮测试路径、状态定义和 smoke 记录见 [AGENT_RUNNER_QA_GUIDE.md](./AGENT_RUNNER_QA_GUIDE.md)。
 
@@ -67,7 +68,7 @@ EventGateway / EventRouter 在本文档中描述为 **external EBA branch integr
 | envelope | Host 内部事件封装，即 `AgentEventEnvelope`；runner 看到的是由它投影出的 `ctx.event`。 |
 | descriptor / manifest | runner discovery 的能力和配置描述；manifest 来自插件，descriptor 是 Host 校验后的注册表视图。 |
 | EBA | Event Based Agent，把消息、撤回、入群、定时任务等都统一成 host event 的接入方向；完整网关和路由在外部 EBA 分支联调。 |
-| harness runner | LiteLLM Agent Platform、Claude Code、Codex 等已有自身 session / tool loop / MCP / 压缩机制的外部 runtime adapter。 |
+| harness runner | ACP、Claude Code、Codex 等已有自身 session / tool loop / MCP / 压缩机制的外部 runtime adapter。 |
 | projection | Host 把内部事实源、授权资源或配置裁剪成 runner / harness 可消费视图的过程。 |
 | Runtime Control Plane | v2 Host 能力层，当前已落地 Host-owned run/result ledger、run control primitives、最小 runtime heartbeat/claim lease；完整 daemon worker 管控、task wakeup 和 Agent Platform 产品形态不是 Protocol v1 主线。 |
 
@@ -77,7 +78,7 @@ EventGateway / EventRouter 在本文档中描述为 **external EBA branch integr
 | --- | --- |
 | [PROTOCOL_V1.md](./PROTOCOL_V1.md) | **🔒 唯一 schema 事实源**。LangBot Host 与 SDK / Runtime / AgentRunner 的协议合同：版本协商、discovery、run context、result stream、proxy actions、错误和 adapter 边界。 |
 | [HOST_SDK_INFRASTRUCTURE.md](./HOST_SDK_INFRASTRUCTURE.md) | LangBot 宿主能力与分层架构、Host 内部模型（`AgentEventEnvelope` / `AgentBinding` / Descriptor / 各 Store）、runner 发现、绑定、资源授权、状态、存储、生命周期和调用链。 |
-| [AGENT_CONTEXT_PROTOCOL.md](./AGENT_CONTEXT_PROTOCOL.md) | Agent-owned context 方向：事件到来时 LangBot 传什么，agent 如何按需拉取更多历史 / artifact / state，以及如何支持 KV cache 友好的上下文管理。 |
+| [AGENT_CONTEXT_PROTOCOL.md](./AGENT_CONTEXT_PROTOCOL.md) | Agent-owned context 方向：事件到来时 LangBot 传什么，agent 如何按需拉取更多历史 / state、如何访问 sandbox/workspace 文件，以及如何支持 KV cache 友好的上下文管理。 |
 | [EXTENSION_SCOPE_MATRIX.md](./EXTENSION_SCOPE_MATRIX.md) | AgentRunner 外化与外部 EBA / Agent Platform / Runtime Control Plane 的扩展边界矩阵，说明哪些是本分支底座、哪些由外部分支接入。 |
 | [EVENT_BASED_AGENT.md](./EVENT_BASED_AGENT.md) | EBA 接入边界：事件模型、事件来源、触发绑定、非消息事件如何复用 AgentRunner 调度；完整 EventGateway / EventRouter 由外部 EBA 分支联调。 |
 | [RUNTIME_CONTROL_PLANE_V2.md](./RUNTIME_CONTROL_PLANE_V2.md) | Agent Platform v2 / runtime 管控面决策：`AgentRun` / `AgentRunEvent` / run control 已作为 Host 事实源落地，最小 runtime heartbeat/claim lease 已落地；完整 runtime registry / daemon 管控仍是后续可选阶段。 |
@@ -98,7 +99,8 @@ EventGateway / EventRouter 在本文档中描述为 **external EBA branch integr
 - Agent / binding 配置解析
 - run orchestration 和生命周期管理
 - resource authorization 与 `run_id` 级权限校验
-- host-owned state / storage / event log / transcript / artifact 能力
+- host-owned state / storage / event log / transcript 能力
+- sandbox/workspace 文件 staging 与 read/write/exec 能力
 - SDK `AgentRunner`、`AgentRunContext`、`AgentRunResult`、`AgentRunAPIProxy`
 
 协议合同详见 [PROTOCOL_V1.md](./PROTOCOL_V1.md)。

docs/agent-runner-pluginization/RUNTIME_CONTROL_PLANE_V2.md

@@ -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 的关系
 

docs/agent-runner-pluginization/SECURITY_HARDENING.md

@@ -8,7 +8,7 @@
 
 LangBot 的目标不是托管一个强隔离、不可信 code runner 平台。AgentRunner 插件，尤其是 ACP / Claude Code / Codex / OpenCode / Kimi Code 这类外部 harness，默认视为 **operator-owned execution**：用户或部署者显式配置并承担其文件系统、进程、网络、workspace、provider 登录态和 native tool 风险。
 
-LangBot 需要负责的是保护 **LangBot 自己持有的资源**，包括模型、知识库、LangBot tools、history、event、artifact、state、plugin/workspace storage 等。只要这些资源访问是 run-scoped、permission-scoped、可校验、可诊断的，当前阶段即可接受。
+LangBot 需要负责的是保护 **LangBot 自己持有的资源**，包括模型、知识库、LangBot tools、history、event、state、plugin/workspace storage、sandbox/workspace 文件访问等。只要这些资源访问是 run-scoped、permission-scoped、可校验、可诊断的，当前阶段即可接受。
 
 这意味着：
 
@@ -24,11 +24,11 @@ LangBot 需要负责的是保护 **LangBot 自己持有的资源**，包括模
 
 - **资源授权**：根据 runner manifest permissions、binding resource policy、run scope 生成本次 run 可访问的资源快照。
 - **运行期校验**：所有带 `run_id` 的 SDK / Host action 必须校验 active run session、caller plugin identity、resource id 和 operation。
-- **Scoped projection**：只把授权后的资源摘要、MCP server config、context、artifact ref、state snapshot 投影给 runner。
-- **LangBot artifact 路径约束**：LangBot 自己登记和读取的 file artifact 必须限制在声明 root 内，防止 path escape。
+- **Scoped projection**：只把授权后的资源摘要、MCP server config、context、attachment/path ref、state snapshot 投影给 runner。
+- **LangBot 文件路径约束**：LangBot 自己 staged 和读取的文件必须限制在声明 root 内，防止 path escape。
 - **基础 secret 策略**：不要主动把 LangBot 持有的 API key / token / secret 投影给 runner；日志和错误里做常见 secret 字段脱敏。
 - **基础运行约束**：提供 timeout、取消传播、输出大小限制或错误映射的基础能力。
-- **audit-lite**：记录 event、run id、runner id、binding、资源授权摘要、关键失败、state/artifact/transcript 事实。
+- **audit-lite**：记录 event、run id、runner id、binding、资源授权摘要、关键失败、state/file/transcript 事实。
 
 ### Runner Plugin 负责
 
@@ -72,7 +72,7 @@ Claude Code、Codex、OpenCode、Kimi Code、Gemini CLI 等外部工具继续使
 - runtime action 按 `run_id` + `caller_plugin_identity` + resource id + operation 校验。
 - manifest permissions 只约束 LangBot 持有资源，不约束 external harness native tools。
 
-当前实现方向是正确的：`AgentRunSessionRegistry` 保存 run-scoped snapshot，`plugin/handler.py` 对模型、工具、知识库、history、artifact、state、storage 等 action 做运行期校验。
+当前实现方向是正确的：`AgentRunSessionRegistry` 保存 run-scoped snapshot，`plugin/handler.py` 对模型、工具、知识库、history、state、storage 等 action 做运行期校验，sandbox/workspace 文件访问由 scoped tool 边界控制。
 
 ### MCP / Asset Gateway Boundary
 
@@ -93,9 +93,9 @@ LangBot MCP / asset gateway 只暴露当前 run 授权的工具面：
 
 LangBot 只需要约束自己管理的路径：
 
-- Host 生成或登记的 file artifact 必须校验 `realpath` 和 root containment。
-- Artifact metadata 不应暴露 Host-only storage key / host path。
-- Context 文件、artifact 文件如由 LangBot 创建，应放在可清理的位置。
+- Host staged 文件必须校验 `realpath` 和 root containment。
+- Attachment/file metadata 不应暴露 Host-only storage key / host path。
+- Context 文件、sandbox/workspace 文件如由 LangBot 创建，应放在可清理的位置。
 
 用户配置给 ACP runner 的 workspace 不属于 LangBot 的强监管范围。Docker/K8s 下依赖 volume 挂载边界；普通进程部署下依赖 OS 用户权限和用户自担风险。
 
@@ -107,7 +107,7 @@ LangBot 只需要约束自己管理的路径：
 
 - LangBot 不主动把自己持有的 secret 投影给 runner，除非这是 runner config 明确需要的外部服务凭据。
 - run token 是短期、run-scoped 的，不应长期保存。
-- 日志、错误、transcript、artifact metadata 尽量避免打印常见 secret 字段。
+- 日志、错误、transcript、attachment/file metadata 尽量避免打印常见 secret 字段。
 - 配置 UI / API 返回时继续沿用现有 secret masking 规则。
 
 不要求当前阶段实现完整 DLP、全链路敏感数据追踪、secret lineage 或自动轮换体系。
@@ -119,7 +119,7 @@ LangBot 需要提供基本可控性：
 - Host run deadline / runner timeout。
 - runner 侧请求 timeout。
 - generator close / cancel 传播。
-- 输出和 artifact inline size 上限。
+- 输出和 inline payload size 上限。
 - 错误映射为受控 runner failure。
 
 不要求 LangBot 为外部 harness 实现 CPU、内存、磁盘、网络、进程树强隔离。需要这些能力时由 Docker/K8s、systemd、容器平台或用户机器策略提供。
@@ -144,7 +144,7 @@ LangBot 需要提供基本可控性：
 
 - run id、runner id、binding、event。
 - 授权资源摘要。
-- state update、artifact created、transcript message。
+- state update、file write/read event、transcript message。
 - MCP / pull API 拒绝时的 warning。
 - steering queued / injected / dropped。
 
@@ -154,7 +154,7 @@ LangBot 需要提供基本可控性：
 
 | 项目 | 当前要求 | 状态判断 |
 | --- | --- | --- |
-| Path isolation | 只约束 LangBot 管理的 artifact/context 路径；runner workspace 归用户/部署环境。 | Minimal required |
+| Path isolation | 只约束 LangBot 管理的 context/sandbox 文件路径；runner workspace 归用户/部署环境。 | Minimal required |
 | Permission boundary | 必须保护 LangBot 资源；不约束外部 CLI native 能力。 | Required |
 | Secret handling | 基础不投影、基础 masking、run token 短期化。 | Basic required |
 | MCP policy | run-scoped token + scoped tool surface；无复杂审批。 | Required |
@@ -163,7 +163,7 @@ LangBot 需要提供基本可控性：
 | State lifecycle | scope 隔离、JSON size limit、基础 cleanup primitive。 | Basic required |
 | Audit | 记录运行事实和拒绝原因。 | Audit-lite |
 | UI / Admin control | 权限摘要可展示；不要求审批流。 | Optional |
-| Test matrix | 覆盖 run auth、MCP token、permission deny、timeout、artifact path、state size。 | Focused tests |
+| Test matrix | 覆盖 run auth、MCP token、permission deny、timeout、sandbox path、state size。 | Focused tests |
 
 ## 当前实现快照
 
@@ -172,8 +172,8 @@ LangBot 需要提供基本可控性：
 - SDK typed AgentRunner manifest、capabilities、permissions。
 - Host resource builder 按 manifest permissions 和 binding policy 生成 `ctx.resources`。
 - Active run session snapshot 和 `caller_plugin_identity` 校验。
-- History / event / artifact / state / tool / knowledge runtime action 的 run-scoped 校验。
-- Artifact file path `realpath` + root containment。
+- History / event / state / tool / knowledge runtime action 的 run-scoped 校验。
+- Sandbox file path `realpath` + root containment。
 - Persistent state scope 隔离和 JSON size limit。
 - SDK-owned MCP bridge 和 long-lived asset gateway。
 - Dify / ACP runner 对 LangBot asset gateway 的接入。
@@ -183,7 +183,7 @@ LangBot 需要提供基本可控性：
 
 - 前端展示 runner LangBot 资源权限摘要。
 - 常见 secret 字段 redaction 收敛成统一 helper。
-- Artifact/context TTL cleanup 调度。
+- Context/sandbox file TTL cleanup 调度。
 - 更完整的 MCP 调用 audit。
 - 更好的文档提示：ACP runner 是 operator-owned execution。
 

docs/agent-runner-pluginization/STATUS.md

@@ -14,7 +14,7 @@
 | Run authorization snapshot | Done | active run session 冻结 run-scoped resources 与 available APIs；runtime handler 按 snapshot 校验 pull API。 |
 | Result payload validation | Done | Wire 保持 `{type, data}`；Host 对投递/副作用类 payload 严格校验，tool-call telemetry 宽松，未知 type 忽略并 warning。 |
 | Old built-in runners | Done | 旧 `src/langbot/pkg/provider/runners/*` 与 `RequestRunner` 路径已从本分支删除。 |
-| Official runner manifests | Done | `local-agent`、LiteLLM Agent Platform、外部服务 runner 已重新声明真实生效的 LangBot resource permissions。 |
+| Official runner manifests | Done | `local-agent`、ACP / Claude Code / Codex 外部 harness runner、外部服务 runner 已重新声明真实生效的 LangBot resource permissions。 |
 | Runtime Control Plane v2 foundation | Partial | Host-owned `AgentRun` / `AgentRunEvent` ledger、orchestrator 自动建账、result event persistence、run get/list/event page/cancel/append/finalize actions 已落地；`agent_run:admin` / `runtime:admin` 控制权限、最小 runtime register/heartbeat/list/reconcile 和 run claim/renew/release 原语已落地。完整 Agent Platform 产品形态、daemon supervisor、任务唤醒/长轮询/WebSocket、分布式 runtime 管控仍未完成。 |
 | Security boundary | Done | 当前口径降级为轻量边界：LangBot 保护自身持有资源；external harness 的 OS / process / network / workspace 风险由用户或部署环境承担；managed sandbox 不是当前承诺。 |
 | Steering control path | Done | claim 异常不再逃逸 consumer loop；queue 有上限；未 pull 的 claimed 输入在 run 结束时写 `steering.dropped` 审计终态。 |
@@ -25,7 +25,7 @@
 - `action.requested` 仍只作为 telemetry / reserved surface；platform action executor 不在本分支执行。
 - EventGateway / EventRouter 完整实现由外部 EBA 分支联调；本分支只提供 event-first host envelope / binding / run 入口。
 - State 与 storage 的长期类型边界仍可继续收窄；当前合同只要求 JSON-safe state 与受控 storage API。
-- Artifact 读取路径已检查 `expires_at`，EventLog / Transcript / Artifact 已提供显式 cleanup primitive；长期 retention 默认值、TTL 调度接入和大 payload 去重仍是运维收尾项，应在 Runtime Control Plane 产品化前补齐。
+- EventLog / Transcript 已提供显式 cleanup primitive；长期 retention 默认值、TTL 调度接入和 sandbox/workspace 文件清理仍是运维收尾项，应在 Runtime Control Plane 产品化前补齐。
 - External harness 的 native shell / filesystem / CLI / MCP 权限不受 manifest permissions 约束；manifest permissions 只约束 LangBot 持有的资源访问。
 - LangBot 当前不承诺 managed sandbox；external harness 的 OS/process/network quota、workspace GC、provider-native tool 权限由用户或部署环境承担。
 - Runtime Control Plane v2 当前只落地 Host 事实源和控制原语；还没有内置 Agent Platform UI、业务队列、daemon 进程托管、runtime wakeup channel、跨 Host 分布式锁或 provider 登录态诊断。
@@ -35,7 +35,7 @@
 | Runner | 状态 | 最近证据 |
 | --- | --- | --- |
 | `plugin:langbot/local-agent/default` | Unit-pass; UI smoke pending | 2026-06-10 本地 pytest / ruff 通过；WebUI smoke 由人工统一执行。 |
-| `plugin:langbot/litellm-agent-platform-agent/default` | Unit-pass; E2E pending | 通过 runner 仓库单测覆盖 HTTP session、run_id prompt 注入和 LangBot MCP gateway；真实 harness E2E 取决于 LiteLLM Agent Platform 部署和 provider 登录态。 |
+| `plugin:langbot/acp-agent-runner/default` / `plugin:langbot/claude-code-agent/default` / `plugin:langbot/codex-agent/default` | Unit-pass; E2E pending | 通过 runner 仓库单测覆盖 session、run_id 注入和 LangBot MCP gateway；真实 harness E2E 取决于对应运行环境、CLI/daemon 可用性和 provider 登录态。 |
 | Dify / n8n / Coze / DashScope / Langflow / Tbox / DeerFlow / WeKnora | Unit-pass; credential smoke optional | 2026-06-13 plugin layout / parser tests 通过；真实服务凭据 smoke 非每轮必跑。 |
 
 ## Host / SDK 验收状态
@@ -52,6 +52,6 @@
 截至 2026-05-29，已有本地 smoke 证明：
 
 - `local-agent` 可以通过 Pipeline Debug Chat 走插件化 `AgentRunOrchestrator` 主链路。
-- 外部 harness runner 可以通过同一条 `run(event, binding)` 路径执行；当前官方实现已收敛到 LiteLLM Agent Platform runner，具体 Claude Code / Codex CLI provider 不再由本仓库直接维护。
+- 外部 harness runner 可以通过同一条 `run(event, binding)` 路径执行；当前官方实现已收敛到 ACP / Claude Code / Codex 等直接 runner 插件。
 
 这些记录只证明本地协议闭环可用，不代表 LangBot 提供 managed sandbox 或 external harness OS 级隔离。