[PAUSED] feat: run ACP agents on connected computers

[akazwz]

Warning

Status: Paused / 暂停开发

这个 Draft PR 暂时保留，作为已完成实验和实现参考，不准备按当前 Remote ACP 方案继续推进或合并。我们正在把核心抽象调整为 Connected/External Agent Runtime：Codex 直接使用 app-server，Claude 使用官方 Agent SDK sidecar，ACP 仅作为兼容 driver。待统一 runtime contract 和原生 driver 稳定后，再从本 PR 中提取可复用的连接、认证、进程执行与双向流基础设施。当前阶段无需继续 QA 或 review。

Important

这是一个 Draft PR，目前还不能合并。 核心传输和路由已经实现，并有自动化测试覆盖，但真实 Desktop/CLI 端到端测试和发布验证还没有完成。先提交 Draft 是为了尽早确认方案，再用真实连接电脑持续测试和优化。

这个 PR 做了什么

Remote ACP 允许 Memoh Server 在用户已连接的电脑上启动 Codex ACP 或 Claude Code ACP adapter，并通过该进程的 stdin/stdout 交换 ACP JSON-RPC 消息。

实现直接复用现有的 Remote Runtime 传输链路：

Memoh Server ACP client
  -> bridgepb.ContainerService.Exec（双向 gRPC stream）
  -> 现有的出站 WebSocket / HTTP2 连接
  -> @memohai/runtime
  -> 固定的本地 adapter launcher
  -> codex-acp / claude-agent-acp
  -> 用户自行安装的 Codex / Claude Code CLI

每个 ACP 进程都有自己独立的双向 Exec stream。多个 Session 可以复用同一条电脑连接，但 HTTP/2 会分别处理各个 stream 的流控、顺序、stdin、stdout、stderr、退出状态、取消信号和进程生命周期，彼此不会串流。stdin 帧在进程 spawn 窗口内统一排队，flush 后才切换直写，保证字节顺序在任何时序下都与到达顺序一致。这里不需要再增加一套 ACP 专用连接或网络协议。

范围边界与信任模型

这个 PR 只负责启动本地进程和转发 stdio。

• 不复制、暂存、修改、同步或删除本机 Codex/Claude 配置。
• 不注入模型供应商 API key，也不管理登录或 OAuth。
• 不决定本机 CLI 使用哪种认证方式。
• 不打包原生 Codex 或 Claude Code CLI。

Remote ACP 继承 Runtime 现有 exec 能力的信任模型：连接电脑即意味着允许 Server 以本机用户身份执行命令。固定 launcher 机制解决的是名字解析和路径卫生（alias 一定解析到打包的 adapter、本地 CLI 路径不出本机），不是执行范围的收窄。docs/design/remote-acp.md 的 Trust model 一节完整描述了这一边界，以及未来若要提供「仅 ACP、无通用 shell」授权所需要的 capability 级 Exec 白名单。

实现方式

Runtime 和 Desktop

• Runtime 只有在能够构造对应的固定 launcher 时，才会上报 acp_codex 或 acp_claude_code capability。
• 受信任的 launcher 路径只存在于 Desktop Main 和 Runtime 内部，不会暴露给 renderer，也不会发送到 Server。
• Desktop 用登录 shell（$SHELL -lc 'command -v …'）解析用户真实 PATH 来发现本机 codex/claude，覆盖 nvm、fnm、volta、pnpm、mise 等版本管理器；登录 shell 不可用时回退到确定性目录列表。找到的路径不做 realpath 解析，保留 symlink 分发语义（如 volta）。
• launcher 描述符以 provider 形式传给 Runtime，每次连接尝试都会重新发现，装完 CLI 后重连或重新配置即可生效，无需重启 App。
• Desktop 固定打包 JavaScript adapter：codex-acp 1.2.0 和 claude-agent-acp 0.66.0；版本号由 Web 连接命令测试与 Desktop manifest 交叉断言，第三方声明中的传递依赖版本由打包测试对照 lockfile 校验。
• Web 生成的连接命令会把 Runtime 和两个固定版本 adapter 安装到同一个临时 npm 执行环境，不要求用户再全局安装 adapter。
• Runtime 负责监管当前连接启动的子进程，并通过现有 Exec RPC 转发 stdin、stdout、stderr 和退出状态；单个 adapter 校验或物化失败只降级为告警，不影响整条电脑连接。

Server 和 Workspace 路由

• 触达 remote 电脑的权限收口在 target 解析之后按解析结果统一判定：显式选择电脑、Folder 绑定、以及 bot Primary 是 remote 时的 ambient 解析，全部要求 workspace_read。无 Folder 的 ACP Session 在 remote Primary 上冷启动同样被该门拦截。
• Session 持久化的 Folder 会固定 workspace target 和绝对 workdir；每轮执行都会重新解析同一个 target，不会静默回退到另一台 Primary 电脑。
• 预热 runtime 绑定新 Session 时按 Folder 的实际路径与 target 匹配，路径不一致时拒绝绑定并冷启动。
• Remote 进程启动路径会绕过 Server 管理的 ACP 环境变量和配置暂存逻辑。
• 仍被 Folder 引用的 remote target 不能删除（RESTRICT 同时匹配 PostgreSQL 18 的 23001 与旧版本的 23503）；删除未被引用的 target 时，会关闭固定在该 target 上的 ACP runtime。
• 创建 Session 或 Runtime 前会重新校验 remote workspace 的权限和所有权；读取 runtime 状态（含本机绝对路径的 project_path）与修改模型/推理走同一套 remote 门。
• Memoh MCP Tool 请求使用严格限定的 runtime-token 认证路径，不会把普通 Bot Tool 接口变成公开接口。

Web

• ACP Session 可以选择已连接电脑上的 Folder。
• 绑定 native Folder 的草稿会按 Folder 路径预热 runtime，模型与推理选择器在发送前即可用，创建 Session 时直接复用该 runtime；绑定 remote Folder（或 Folder 列表尚未确认）的草稿不预热，由创建后的首轮在目标电脑上冷启动。
• 加载 workdir 列表期间不会丢失已经持久化的 Folder。
• Computers 页面生成带固定版本并经过安全转义的连接命令。
• 页面文案只说明本地执行、系统限制和 adapter 缺失，不会暗示 Memoh 管理模型供应商凭证。

已完成的验证

• go test ./...、golangci-lint
• pnpm --filter @memohai/runtime test，包括同一条传输连接上的两个并发双向 Exec stream、spawn 窗口内的 stdin 顺序回归测试
• Runtime typecheck 和 build
• Desktop launcher/Runtime/打包测试（含登录 shell 探测与 lockfile 版本交叉断言）
• Web ACP、workdir、连接命令相关测试和 production build
• 已 rebase 到最新 main（含 feat(acp): preserve live interactions and expose agent commands #1002），迁移编号更新为 0135

Draft 阶段还要完成的工作

• 使用已经在本机配置好的 Codex 和 Claude Code，在真实 macOS/Linux Desktop 与 CLI 上跑通完整流程。
• 在托管环境测试断线重连、取消、并发 Session 和长时间 Prompt。
• 完成安装包、签名和第三方依赖许可证检查。
• 部署配套 Web 连接命令前，先发布包含这些能力的新版本 @memohai/runtime；registry 上现有版本还不包含 Remote ACP。
• ACP 原生 Session 在进程或 Server 重启后的 resume 不在本 PR 范围内；当前实现会冷启动新的原生 ACP Session。
• 第一版暂不在 Windows 上开放 Remote ACP。
• 后续跟进（不阻塞本 PR）：Runtime 进程被强杀后的孤儿 adapter 收割、stdin 背压、无 Folder Session 在 Primary 变更时的聊天内提示、MCP tools URL 为空时的运维告警。

目前还没有宣称完成人工端到端 QA。这个 PR 现阶段主要用于评审架构，并作为后续真实环境测试和迭代的基础。

⚠️ No human QA — this PR has not been verified by a human yet. Remove this line once a human confirms the happy path.