Agent Composition Boundary：Provider、Child Agent 还是 ACP Proxy？

[627150795]

这是 #314 Capability Shape and Harness Value 的运行时互操作专题。

OpenPI 如果以后要让一个 Agent 调用 Codex、Claude Code 或其他独立 Agent，需要先回答一个容易被忽略的问题：下游对象到底是什么？它是提供模型生成的 Provider、拥有独立上下文和生命周期的 Child Agent，还是只负责转发协议和事件的 Proxy？

如果把这三种对象都放在同一个 Provider 接口后面，父 Agent 就可能需要替下游 Agent 翻译 context、tool event、streaming、权限、steering、取消、重试和 Session 恢复。发生失败或迟到结果时，系统也很难判断那是一次模型 attempt、一个独立 child run，还是一次协议转发。

Goose #11384 讨论了类似问题。Goose 描述的 AcpProvider 会把外部 Agent 放在普通 model-provider 的位置，于是出现两个 Agent loop 嵌套运行的情况。维护者在回复中区分了 Provider wrapper 和真正的 Agent-to-Agent orchestration。讨论也显示，不同外部 Agent 往往有不同的 Skill、Connector、订阅方式和知识边界，扁平化成一个模型名称会丢掉重要信息。

ACP #690 提出了一个较小的 Subagent runtime surface。它把可用 Subagent 做成 Session-scoped catalog，用 capability gating 控制 delegation policy，在父 Session 的 tool call 中关联 childSessionId，并让 child 继续使用普通 Session 的恢复、取消和关闭语义。这个 RFD 仍然是设计信号，没有要求所有产品统一 manifest 文件、目录结构或 prompt syntax。

问题场景

至少要覆盖以下情况：

1. 父 Agent 调用一个只提供模型生成的 Provider；
2. 父 Agent 委派一个拥有独立 Session、权限和预算的 Child Agent；
3. Host 只转发下游 Agent 的协议、事件和结果，不接管下游语义；
4. child 失败、取消、重试、恢复或产生迟到结果；
5. 下游能力目录未知，或目录已知但为空。

先区分三种组合形态

model_provider

它只提供模型生成，使用当前 Agent loop 的 context 和 lifecycle，不拥有第二套 Agent Session。

child_agent

它拥有独立的 context、权限交集、预算、事件或 Session、取消边界和结构化结果。父子关系必须有稳定 identity，父 Agent 不能把 child 的真实执行成本压缩成一条普通模型调用。

agent_proxy

它负责把下游 Agent 的协议或事件暴露给调用方。Proxy 不应偷偷替下游做 prompt、permission 或 retry 决策，也不应把下游的独立 Session 伪装成当前 Agent loop 的内部状态。

建议的最小 Runtime contract

• dispatch 前声明组合模式，并通过 capability negotiation 确认对方支持的模式；
• child_agent 使用 Session-scoped catalog，明确区分 catalog unknown 和 empty catalog；
• delegation policy 至少能表达 auto、disable、prefer 和 require。require 不满足时应 typed-fail，不能静默 fallback；
• 父事件先关联 child identity，再允许 child 的事件流出，避免 observer 先看到没有归属的执行事件；
• child 的权限交集、预算、取消传播、恢复、retry 和 result receipt 都要有明确 owner；
• Proxy 必须声明谁拥有下游 Session、谁负责恢复、谁能看到 transcript，以及哪些事件只是转发事实。

最小可证伪实验

选一个能够通过 ACP 调用的外部编码 Agent，分别以 model_provider wrapper、child_agent Session 和 agent_proxy pass-through 接入。使用同一个任务、同一个模型和同一组工具，比较：

• 总 token、实际费用和上下文重复量；
• 取消、重试和迟到结果的处理；
• 父子 trace lineage 是否完整；
• 权限是否在 child boundary 被扩大；
• 用户是否能理解当前到底是谁在执行。

与现有工作的关系

#314 已经讨论 Child Session/Subagent 何时值得存在；其他相关工作已经覆盖委托身份与执行拓扑。这里新增的是：当下游本身是一个完整 Agent 时，Provider、Child Agent、Proxy 三种拓扑如何分类，以及最小互操作面应由谁拥有 lifecycle。

非目标

• 现在就统一所有 Agent 的 manifest 或目录格式；
• 为 Agent-to-Agent 调用建立一套与 Session 平行的完整 RPC 家族；
• 预设所有 child 都必须递归创建更多 child；
• 让 Provider adapter 代替 Runtime 拥有权限、预算和生命周期。

希望讨论的问题

1. 什么条件下，一个拥有独立 context 和 lifecycle 的下游对象必须被建模为 Child Agent，而不能继续放在 Model Provider 接口后面？
2. Subagent catalog、prefer/require、foreground/background 和 parent-child identity 是否足以构成第一版最小互操作面？
3. Child 的权限、预算、取消、恢复和成本由父 Agent、Host 还是 Runtime 拥有？
4. Proxy 应保留哪些下游事实，哪些转换会改变语义并必须被显式记录？

希望讨论最终回答：

当 OpenPI 调用一个可独立运行的 Agent 时，最小的角色分类、权限边界、生命周期归属和可验证 receipt 合同应该是什么？

[tt-a1i]

补两种真实 Pi 社区实现，作为本讨论 Provider / Agent / Proxy 边界的源码样本；本次只读检查，没有安装或运行。

1. svkozak/pi-acp@d1cffc0 接近协议适配。 它启动现有 pi --mode rpc --no-themes，将 Pi 的 confirm/select 转成 ACP permission 请求，无法支持的 input/editor 请求取消。Pi 仍拥有实际工具执行和 Session 文件。进程入口、UI 映射与取消。它是 MVP，client filesystem/terminal delegation 和 MCP 接线仍有缺口，不能由“支持ACP”推导 OpenPI Setup/审批/后台完成都兼容。
2. tintinweb/vscode-pi-model-chat-provider@95d8de3 把完整 Pi agent 放进 VS Code Language Model Provider。 底层 Pi 已执行工具，所以输出工具文本，刻意不发会让VS Code再执行的 LanguageModelToolCallPart。执行与投影区别。但它通过用户消息+模型hash推测会话归属，再拼接用户消息给 --no-session Pi；这无法作为OpenPI canonical Session identity/branch/replay 合同。session pool、hash。

这给最小互操作实验增加两项验收：调用方拿到的是纯生成还是可执行本地工具的Agent；已执行工具事件跨协议后是否仅作证据投影，绝不触发二次执行。Session/child身份必须显式传递，不能从消息相似度或内容hash推断。

另一个更小的边界样本是 pi-nvim-context@b3d5bc9：prefill请求把显式选择的编辑器上下文追加到现有 Pi 草稿，并只返回prefilled；用户检查后普通提交。它甚至不需要成为Agent/Provider。其直接模型补全功能是另一条生命周期，应单独评估。

以上项目均有 MIT 声明；版本约束/实际宿主身份不同，不能据源码观察宣布当前OpenPI互通验收完成。

研究记录：Pi 社区能力研究与候选清单（2026-09-08）。源码证据、运行验证与采用决策分别记录。

[tt-a1i]

再补一个不是 Provider、也不是 ACP 的编辑器样本；本次只读浅克隆，没有安装或运行。

carderne/pi-nvim@3efbe67 / pi-nvim 0.2.5 在现有交互 Pi Session 上开 socket，把选区/文件经 pi.sendUserMessage(..., { deliverAs: "followUp" }) 注入。Pi 仍拥有 Session。这是 editor inject，不是把 Neovim 或外部 Agent 扁平化成 model provider。它会进主对话 follow-up，因此也不能冒充 #477 的 /btw 旁路。

同日复检：svkozak/pi-acp 仍是 d1cffc0；tintinweb/vscode-pi-model-chat-provider 仍是 95d8de3（--no-session + 用户消息 hash 猜会话）。Zetaphor/pi-vscode-extension@526df5e（2026-05-07）把旧 @mariozechner/pi-coding-agent 嵌进 VS Code 侧栏，是过期的 first-class UI，不是 ACP。

不要把 Codex / Claude Code 收成 Provider。ACP 保持 agent_proxy，Pi 继续是 Session / 工具 / 取消的 source of truth。