knowledge-interaction-surfaces-acp-host-integration

name	knowledge-interaction-surfaces-acp-host-integration
description	覆盖 Blade 的 ACP stdio Agent、Session load/list/fork/close、宿主能力协商、远程 文件系统与终端、权限模式、流式 update、历史回放和资源回收。进入时机：接入 Zed 或 其他 ACP 宿主、修改协议能力、调试远程文件/终端、Session 替换、输出背压或宿主工具 展示。 不包含：普通 Web API（见 ../hono-server-api-and-streaming/）、本地 TUI 交互（见 ../terminal-ui/）。关键词：BladeAgent, AcpSession, AcpServiceContext, AgentSideConnection, sessionUpdate, session/load, unstable_forkSession, requestPermission。

Module Structure

ACP 层把每个宿主 Session 映射为独占的 Agent、SessionRuntime、文件系统/终端服务和 有界更新队列，通过 stdio NDJSON 与 IDE 通信。

Directory Layout

• packages/cli/src/acp/index.ts — stdio Web Streams 与 ACP connection 生命周期
• packages/cli/src/acp/BladeAgent.ts — 协议方法、Session residency 和配置能力
• packages/cli/src/acp/Session.ts — prompt、历史、权限、LoopEvent 与 update 投影
• packages/cli/src/acp/AcpServiceContext.ts — 按 Session 隔离的 FS/Terminal 后端
• packages/cli/src/acp/AcpFileSystemService.ts — ACP 文本文件能力适配
• packages/cli/src/services/FileSystemService.ts — 本地/远程文件系统公共接口
• packages/cli/src/tools/display/ToolResultProjector.ts — ACP 工具详情裁剪

Key Entry Points

• runAcpIntegration() in packages/cli/src/acp/index.ts — 建立 AgentSideConnection 并绑定关闭清理
• BladeAgent.initialize() in packages/cli/src/acp/BladeAgent.ts — 协商协议和 Agent 能力
• BladeAgent.newSession() and BladeAgent.loadSession() — 创建或原子替换宿主 Session
• AcpSession.initialize() in packages/cli/src/acp/Session.ts — 创建服务上下文、恢复交互和 Runtime
• AcpSession.prompt() in packages/cli/src/acp/Session.ts — 处理 prompt 并串行投影事件

Gotchas

• session/load 必须在返回响应前按协议回放所有用户可见历史；system、tool 和内部消息留在模型上下文但不发送给宿主 (packages/cli/src/acp/BladeAgent.ts, packages/cli/src/acp/Session.ts, git:6d712a03)
• 同一个 Session 的并发 load/close 通过 sessionLoadQueues 串行，旧 owner 完全销毁后才能提交新 owner；否则两个 Runtime 会同时消费同一 durable inbox (packages/cli/src/acp/BladeAgent.ts, git:804a5c64)
• ACP Runtime residency 的 allowEviction 为 false；容量满时新 Session 直接返回结构化 internal error，不能静默逐出宿主仍持有的 Session (packages/cli/src/acp/BladeAgent.ts)
• 宿主声明 fs.readTextFile/writeTextFile 后，远端调用失败必须 fail closed，不能读取或写入 Agent 主机上的同名路径；只有未声明能力时才选择本地 FS (packages/cli/src/acp/AcpFileSystemService.ts)
• Terminal 后端在 Session 初始化时按 capability 选择：声明 terminal 后远端创建失败不自动本地执行，未声明 terminal 才使用绑定 Session cwd 的本地后端 (packages/cli/src/acp/AcpServiceContext.ts, docs/testing/acp-terminal-capability-routing-evidence.md, git:4991291e)
• ACP terminal 的 currentOutput() 是累计快照而非增量；轮询必须按已观察长度切 delta，输出回退或 truncated 时重建 capture 并标记 accounting incomplete (packages/cli/src/acp/AcpServiceContext.ts)
• terminal timeout/abort 的完成顺序是 kill → 停止轮询 → 最终读取 → release；提前返回会丢尾部输出并泄漏宿主 terminal (packages/cli/src/acp/AcpServiceContext.ts)
• 所有 sessionUpdate() 共用一个 BoundedSerialEgress；任何 overflow、超时或 connection abort 会中止当前 prompt、user shell 和 side conversation，而不是继续生成未送达内容 (packages/cli/src/acp/Session.ts, git:1af43232)
• closeSession 会以 discardPendingInput: true 销毁，连接级 shutdown 默认保留 durable inbox 供下次恢复；这两个关闭语义不能合并 (packages/cli/src/acp/BladeAgent.ts, packages/cli/src/acp/Session.ts, git:e260f4bc)
• available_commands_update 必须延迟到 session/new 或 session/load 响应之后；立即发送会命中尚未准备好的宿主 (packages/cli/src/acp/Session.ts)
• ACP 的 auto-edit 与 Blade 内部 autoEdit 名称不同，模式变更必须先持久化 Session 权限，再发送 current_mode_update (packages/cli/src/acp/BladeAgent.ts, packages/cli/src/acp/Session.ts)
• 模型、reasoning、tier、verbosity 和 communication style 在 prompt 活动期间不可切换；持久化 metadata 失败时模型切换会回滚 Runtime ()

Architecture

• BladeAgent 是连接级 owner，管理多个 AcpSession 与 residency；每个 AcpSession 再独占 Agent、SessionRuntime、服务上下文和 update queue (packages/cli/src/acp/BladeAgent.ts, packages/cli/src/acp/Session.ts)
• AcpServiceContext 按 session ID 保存 connection、capabilities、cwd、FS 和 Terminal，避免并发 Session 共享“当前”远程服务；无 session 参数的兼容 API 只用于旧调用 (packages/cli/src/acp/AcpServiceContext.ts)
• prompt 事件映射为 agent_message_chunk、agent_thought_chunk、tool_call(_update)、plan 与 session_info_update，所有 update 在 Agent generator 继续前可被 flush 形成背压 (packages/cli/src/acp/Session.ts)
• Session setup 同时暴露权限 modes 和模型相关 configOptions；可选项来自该 Session 冻结的 model configuration，不从宿主请求临时拼装 (packages/cli/src/acp/BladeAgent.ts, packages/cli/src/acp/Session.ts)
• fork 先由 SessionService 复制 durable history 与 metadata，再创建独立 AcpSession；父子共享来源 workspace 但拥有不同 Session ID、Runtime 和终端上下文 (packages/cli/src/acp/BladeAgent.ts)
• Slash commands 复用核心命令注册表，但 model、permissions、theme、config、exit、ide 等由 ACP 原生 UI/协议接管的命令不会重复暴露 (packages/cli/src/acp/Session.ts)

Decisions

• ACP 能力协商是后端选择，而不是失败回退：未声明能力允许本地实现，已声明能力则认定资源归宿主所有并 fail closed (packages/cli/src/acp/AcpServiceContext.ts, packages/cli/src/acp/AcpFileSystemService.ts)
• 工具结果优先投影为 ACP 原生 diff content；没有结构化 edit/patch metadata 时才退化为经统一预算裁剪的文本内容 (packages/cli/src/acp/Session.ts, packages/cli/src/tools/display/ToolResultProjector.ts)
• Session 配置是 durable 状态，setSessionMode 和 config option 不只是 UI 通知；宿主看到成功前必须已更新 Runtime 与 Session metadata (packages/cli/src/acp/Session.ts)
• 用户问题和 MCP Elicitation 被线性化为 ACP permission 选择流程，以适配宿主交互能力；取消或协议错误统一 fail closed (packages/cli/src/acp/Session.ts)

Patterns

• 创建、fork、load 都先预留 residency，完成 Session 初始化后才 commit；任一步失败都会 cancel reservation 并销毁半初始化 Session (packages/cli/src/acp/BladeAgent.ts)
• 所有异步宿主更新先检查 Session 未 destroyed、connection 未 aborted、egress 未 closed；迟到 timer、Bus 回调和 completion 都不得重新激活已释放 Session (packages/cli/src/acp/Session.ts)
• 后台子代理完成和 team message 先进入 durable inbox，再在 Session idle 时通过空 prompt 自动续跑；连接关闭时保留该 inbox (packages/cli/src/acp/Session.ts)
• durable inbox 自动续跑失败时只重试结构化标记为 retryable、且尚未产生部分输出或任何 tool_start/tool_progress/tool_result 的回合；重试采用单飞、有界指数退避、稳定抖动和硬总时限，cancel、egress 失败与 destroy 会使排队及执行中的旧代际失效，Goal/preflight 失败也不能吞掉随后到达的新输入；blade/pendingResume metadata 投影恢复状态 (packages/cli/src/acp/Session.ts)
• destroy() 是 single-flight，先关闭 update egress 与订阅，再 cancel 活动工作并等待 completion，最后销毁 Agent、Runtime 和服务上下文，同时保留首个错误 (packages/cli/src/acp/Session.ts)
• 图片 prompt 在协议入口同时限制数量、base64 总字节和文本字符/字节；通过校验后才转换成 Blade UserMessageContent (packages/cli/src/acp/Session.ts)

Dependencies

• ACP 协议、NDJSON stream、Session capabilities 和 terminal/file RPC 来自 @agentclientprotocol/sdk；本地 fallback 仍使用 Blade 的 FileSystemService 与受控进程树 (packages/cli/src/acp/index.ts, packages/cli/src/acp/AcpServiceContext.ts)