From a99b90cc02c40c8c99b5a025cf30329488a9e8d4 Mon Sep 17 00:00:00 2001 From: mesalogo Date: Sat, 29 Aug 2026 17:20:25 +0800 Subject: [PATCH] fix: make Host environment updates fast and recoverable MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Published Host updates could fail while the desktop reverified Runtime against its bundled lock and repeatedly traversed remote payloads. Host preparation now verifies and extracts once, adopts Agent and Runtime on one pinned connection, and uses registered metadata for normal health, capability, and prompt paths. Interrupted commits and adoption retain bounded recovery and rollback state. Desktop and Agent versions are 0.11.8. Remote Projects remain a technical preview; the Agent targets Linux x64 and arm64, with no LoongArch preview. Release note: 修复正式环境 Host 更新失败并移除重复远端包体扫描；中断恢复与清理失败不再破坏已健康环境。 --- AGENTS.md | 11 + BUILD.md | 11 +- FEATURES.md | 4 +- agent-runtime-lock.json | 2 +- .../remote-host-and-goodbuddy-agent-design.md | 33 +- ...te-host-environment-provisioning-design.md | 63 +- ...istant-workbar-and-execution-spaces-prd.md | 13 +- package-lock.json | 4 +- package.json | 2 +- resources/release-notes.json | 34 + src/agent-daemon/cli.test.ts | 44 +- src/agent-daemon/cli.ts | 223 ++- .../installation-registry.test.ts | 3 +- src/agent-daemon/installation-registry.ts | 3 +- src/agent-daemon/installed-bundle-verifier.ts | 11 +- src/agent-daemon/runtime-acp-backend.test.ts | 2 +- src/agent-daemon/runtime-acp-backend.ts | 4 +- src/agent-daemon/runtime-bundle-registry.ts | 118 +- .../runtime-bundle-verifier.test.ts | 14 +- src/agent-daemon/runtime-bundle-verifier.ts | 2 + src/agent-daemon/runtime-composition.test.ts | 9 +- src/agent-daemon/runtime-composition.ts | 119 +- src/main/index.ts | 5 - .../agent-installation-manager.test.ts | 1345 +++----------- .../agent-installation-manager.ts | 1363 ++------------ src/main/remote-agent/bounded-diagnostic.ts | 21 + .../control-plane-package-installer.ts | 1076 ++++++----- .../host-activation-coordinator.ts | 255 +++ .../managed-remote-execution-services.ts | 31 +- ...remote-environment-operation-store.test.ts | 35 +- .../remote-environment-operation-store.ts | 156 +- .../remote-environment-preparer.test.ts | 297 +++- .../remote-environment-preparer.ts | 338 +++- .../remote-environment-progress.ts | 35 - ...emote-runtime-installation-manager.test.ts | 1229 +++---------- .../remote-runtime-installation-manager.ts | 1572 +++-------------- src/main/ssh/ssh-agent-command.ts | 7 +- .../ssh/ssh-remote-package-bootstrap.test.ts | 7 +- src/main/ssh/ssh-remote-package-bootstrap.ts | 63 +- src/shared/node/runtime-bundle-verifier.ts | 124 ++ .../remote-environment-registry-contracts.ts | 24 +- tests/agent-package.test.ts | 139 +- 42 files changed, 3292 insertions(+), 5559 deletions(-) create mode 100644 src/main/remote-agent/bounded-diagnostic.ts create mode 100644 src/main/remote-agent/host-activation-coordinator.ts delete mode 100644 src/main/remote-agent/remote-environment-progress.ts diff --git a/AGENTS.md b/AGENTS.md index f1c87c85..5087e5b3 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -182,6 +182,17 @@ Release note: 修复左上角项目设置与消息通道项目设置不一致的 ## Release Packaging +- Unless the user explicitly requests a local Windows package, never run local + Windows packaging or launch probes as part of release preparation. In + particular, do not run `npm run portable`, Windows + `npm run release:package`, direct `electron-builder` packaging, or launch a + locally packaged Windows app before publishing a release. Source validation + and the native GitHub Actions jobs are the release authorities. +- After a release is published, confirm only that the expected Windows assets + exist in the public release metadata. Do not locally rebuild or launch the + Windows package, download or hash published installers, attach browser + automation to a packaged app, or perform exhaustive per-asset network probes + unless the user explicitly asks for that additional validation. - `.github/workflows/packages.yml` is the canonical cross-platform packaging workflow. It validates and builds `out` once, then packages on six native runners: Windows, macOS, and Linux, each for x64 and arm64. diff --git a/BUILD.md b/BUILD.md index ce3b01e4..b30c45b3 100644 --- a/BUILD.md +++ b/BUILD.md @@ -173,9 +173,12 @@ JSON。签名目录、包描述符、manifest、签名和 payload 的原始字 两种 acquisition 都把同一签名 compound `.gbagent` 交付到固定 operation staging，随后 共用 control-plane `prepare → commit → Agent activate/health → Runtime activate → finalize → cleanup`。commit 终态持久化，通道丢失时只用 `commit-status` 读取恢复而不 -重放 commit。prepare 完成后、commit 前快照 Agent/Runtime 五个 metadata 文件；任一 adoption 失败恢复 +重新下载或准备包；若终态文件不完整，`commit-status` 会从已认证准备状态幂等完成剩余 +rename/metadata 发布。prepare 完成后、commit 前快照 Agent/Runtime 五个 metadata 文件；任一 adoption 失败恢复 原字节或原缺失状态，已发布 side-by-side payload 不成为 current，确认 adoption 后显式 -cleanup。 +cleanup。Host 在 prepare 解包时完成一次完整 payload 校验；commit 只复核签名 metadata +并原子发布，Agent/Runtime 注册后的 health、capabilities 和 prompt 启动不再遍历或哈希 +完整 payload。cleanup 失败保留为维护重试，不回滚已健康环境。 进入“主机与远程执行”设置页只读取本地 Host 列表，不逐台连接。用户点击某台 Host 的 “刷新版本”后才执行远端版本和直连准备能力探测。项目切换只更新本地选择，不建立 SSH @@ -217,8 +220,8 @@ Agent、固定 Node 和当前桌面源码维护并适配的签名 OpenCode Runti 独立的用户版本流。远程直连所需的有界 one-shot installer 由桌面控制面打包并通过固定 SSH prepare channel 发送，不是 `.gbagent` 的必需条目。Host 按签名目录校验完整归档 大小和 SHA-256 后，包内固定 Node 解码并运行 installer。两种 acquisition 都在固定 -operation staging 中执行同一 prepare/commit；commit 终态持久化并可通过只读 -`commit-status` 恢复。Agent/Runtime adoption 使用 commit 前五个 metadata 文件的原字节 +operation staging 中执行同一 prepare/commit；commit 终态持久化，`commit-status` +可读取终态或从已认证准备状态幂等完成中断的发布。Agent/Runtime adoption 使用 commit 前五个 metadata 文件的原字节 或原缺失状态回滚，已发布 side-by-side payload 不会因此成为 current。生产构建命令为： ```bash diff --git a/FEATURES.md b/FEATURES.md index ab67d551..cf8d5fe7 100644 --- a/FEATURES.md +++ b/FEATURES.md @@ -23,8 +23,8 @@ - [x] **直连模型 Runtime**：支持问答、知识总结、受控工具执行和图像生成。 - [x] **OpenCode 与 Continue**：使用隔离子进程、环境变量白名单、统一配置、取消、总执行时限、有界流式输出和活动记录；共享进程回收逻辑保留 Windows 完整进程树终止，并对采用独立进程组的 POSIX 子进程执行组回收。交互提问只由前台对话回答，定时任务、远程通道和委派等后台执行遇到提问时会立即失败并提示改为前台运行，避免无限等待。 -- [x] **托管 SSH OpenCode 闭环（技术预览）**：该能力由“设置 > 平台功能”中的独立“远程项目（技术预览）”页签控制并默认关闭；关闭时不影响任何本地项目、普通桌面功能或桌面发布。启用后可管理固定 Host Key 的 SSH Host、浏览有界远端目录并创建 Ask/Execute 项目；Ask 在 Runtime 边界通过 bubblewrap 保持 Workspace 只读，Execute 使用所选 SSH 账号的完整权限。Main 通过签名 Agent、私有 Unix socket、ACP v3、持久恢复 cursor 和 Main-only 模型桥维持长任务、重连与会话恢复，模型凭据不进入远端。远端组件不嵌入桌面包，项目切换只更新本地选择且不会连接或下载；设置页只读取小型签名目录并按 Linux x64/arm64 显示本地版本、在线最新兼容版本和“有更新/已是最新”，用户点击后才下载签名 `.gbagent`，也可导入/导出离线包。每个复合包包含 Agent、固定 Node 与由桌面源码统一维护适配的 OpenCode Runtime；在线来源跟随“关于与更新”的 GitHub/北京 OSS 选择，签名累计目录绑定最低桌面版本、Agent 协议、架构、大小、SHA-256 和固定 URL。公钥 registry 接受等价 JSON 空白和换行，但仍严格校验 schema、Ed25519 key、环境与撤销；目录、包、manifest、payload 签名和流式 SHA-256 不变。缺少某架构包只使该架构托管 SSH 不可用。项目只保存 Host、远端路径、Runtime 选择和模式；首次实际使用 Workspace/Runtime 时读取 Host current identity，同一进程内其他项目复用已确认 identity 和 Agent 连接。托管 SSH 会话只显示支持的 OpenCode 选择。同一 Host 可并行运行多个项目和对话；活动请求沿精确 resume/replay 恢复，controller 换代遗留的空闲 binding 只在 takeover 已证明且没有活动请求时换新 channel epoch 并恢复原 ACP session。Windows 到 Linux x64 的安装、provider-free 模型桥、断线重放、Session 续接和零残留清理已完成真实 Host 验证；签名 Agent 0.11.2-e2e.12 与 OpenCode Runtime 1.18.9 已完成一次只提交一遍、只调用一个 Ask 原生 read、无标题轮次且精确返回证据内容的有界真实模型验收，当前源码 lock 已更新为待发布 Agent 0.11.7。 -- [x] **SSH Host 手动环境准备源码链路**：Host Key、认证和系统探针成功后先保存 Host，并只读探测共享 Agent/Runtime；保存 Host、打开项目都不自动安装。Host 卡片只有一个按版本事实显示“安装远程环境”“更新远程环境”或“重新安装”的主按钮，次级 SegmentedControl 选择默认且不持久化的“自动”、Host 下载或 GoodBuddy 传输；“版本匹配”badge 不等同环境健康。自动模式只在 operation/prepare 前探测并择一，显式选择保持有效，任何 prepare、commit 或 adoption 失败都不跨 acquisition 自动 fallback。两种方式把同一签名 compound `.gbagent` 交付到固定 staging 后，共用 control-plane prepare、持久化 commit、Agent activate/health、Runtime activate、finalize 与显式 cleanup。GoodBuddy 路径可在同一次操作下载并验证缺失候选、缓存并取得 lease，再有界流式 SFTP 上传一个归档和其中已验证的 bootstrap Node，不把约 294 MiB 整包读入 Main `Buffer`；Host 再次校验。通道丢失通过只读 `commit-status` 恢复而不重放 commit；组件 adoption 失败恢复 Agent/Runtime 五个 metadata 文件的原字节或原缺失状态，已发布 side-by-side payload 不成为 current。已有项目在实际使用 Workspace/Runtime 时按需解析 Host current identity 并执行固定 `attach-or-bootstrap`，不安装或扫描 payload。详见 [设计说明](./docs/architecture/remote-host-environment-provisioning-design.md)。 +- [x] **托管 SSH OpenCode 闭环（技术预览）**：该能力由“设置 > 平台功能”中的独立“远程项目（技术预览）”页签控制并默认关闭；关闭时不影响任何本地项目、普通桌面功能或桌面发布。启用后可管理固定 Host Key 的 SSH Host、浏览有界远端目录并创建 Ask/Execute 项目；Ask 在 Runtime 边界通过 bubblewrap 保持 Workspace 只读，Execute 使用所选 SSH 账号的完整权限。Main 通过签名 Agent、私有 Unix socket、ACP v3、持久恢复 cursor 和 Main-only 模型桥维持长任务、重连与会话恢复，模型凭据不进入远端。远端组件不嵌入桌面包，项目切换只更新本地选择且不会连接或下载；设置页只读取小型签名目录并按 Linux x64/arm64 显示本地版本、在线最新兼容版本和“有更新/已是最新”，用户点击后才下载签名 `.gbagent`，也可导入/导出离线包。每个复合包包含 Agent、固定 Node 与由桌面源码统一维护适配的 OpenCode Runtime；在线来源跟随“关于与更新”的 GitHub/北京 OSS 选择，签名累计目录绑定最低桌面版本、Agent 协议、架构、大小、SHA-256 和固定 URL。公钥 registry 接受等价 JSON 空白和换行，但仍严格校验 schema、Ed25519 key、环境与撤销；目录、包、manifest、payload 签名和流式 SHA-256 不变。缺少某架构包只使该架构托管 SSH 不可用。项目只保存 Host、远端路径、Runtime 选择和模式；首次实际使用 Workspace/Runtime 时读取 Host current identity，同一进程内其他项目复用已确认 identity 和 Agent 连接。托管 SSH 会话只显示支持的 OpenCode 选择。同一 Host 可并行运行多个项目和对话；活动请求沿精确 resume/replay 恢复，controller 换代遗留的空闲 binding 只在 takeover 已证明且没有活动请求时换新 channel epoch 并恢复原 ACP session。Windows 到 Linux x64 的安装、provider-free 模型桥、断线重放、Session 续接和零残留清理已完成真实 Host 验证；签名 Agent 0.11.2-e2e.12 与 OpenCode Runtime 1.18.9 已完成一次只提交一遍、只调用一个 Ask 原生 read、无标题轮次且精确返回证据内容的有界真实模型验收，当前源码 lock 已更新为 Agent 0.11.8。 +- [x] **SSH Host 手动环境准备源码链路**：Host Key、认证和系统探针成功后先保存 Host，并只读探测共享 Agent/Runtime；保存 Host、打开项目都不自动安装。Host 卡片只有一个按版本事实显示“安装远程环境”“更新远程环境”或“重新安装”的主按钮，次级 SegmentedControl 选择默认且不持久化的“自动”、Host 下载或 GoodBuddy 传输；“版本匹配”badge 不等同环境健康。自动模式只在 operation/prepare 前探测并择一，显式选择保持有效，任何 prepare、commit 或 adoption 失败都不跨 acquisition 自动 fallback。两种方式把同一签名 compound `.gbagent` 交付到固定 staging 后，共用 control-plane prepare、持久化 commit、Agent activate/health、Runtime activate、finalize 与显式 cleanup。GoodBuddy 路径可在同一次操作下载并验证缺失候选、缓存并取得 lease，再有界流式 SFTP 上传一个归档和其中已验证的 bootstrap Node，不把约 294 MiB 整包读入 Main `Buffer`；Host 在解包时完成一次完整 payload 校验。通道丢失时 `commit-status` 读取终态或从已认证准备状态幂等完成中断发布；组件 adoption 失败恢复 Agent/Runtime 五个 metadata 文件的原字节或原缺失状态，已健康环境的 cleanup 失败不触发回滚。已有项目在实际使用 Workspace/Runtime 时按需解析 Host current identity 并执行固定 `attach-or-bootstrap`，注册后的 health、capabilities 和 prompt 启动不扫描完整 payload。详见 [设计说明](./docs/architecture/remote-host-environment-provisioning-design.md)。 - [ ] **SSH Host 环境准备真实 Host 验收**：源码已可使用当前 format v1 包；仍需完成 GitHub、北京镜像、Linux x64/arm64、取消和离线 GoodBuddy 传输的真实 Host 验收。当前状态不表示已发布或已完成真实 Host 测试。 - [x] **DeepSeek Harness（预览）**：使用 GoodBuddy 固定 Host 和 OpenAI 兼容模型连接；Ask 只允许调用 Host 中真实注册的 `read`、`skill` 以及 Main 管理的 Web Search/Fetch 代理，拒绝插件同名冒充，Execute 放行全部已启用内置及插件工具，并以当前用户权限运行。图像输入跟随所选模型连接的能力声明，文本模型在 Host 或模型调用前拒绝图片，图片模型通过有界内联内容和临时 Attachment Store 接收 JPEG/PNG。 - [x] **DSH npm 插件市场**：市场默认关闭，由用户显式开启后搜索公共 npm 的 `dsh-plugin` 包，使用捆绑 npm 执行精确版本安装和普通 lifecycle scripts，并支持启停、JSON 配置、移除、失败启动自动停用和离线管理已安装插件；关闭市场只隐藏目录与管理界面，不改变已有插件的启停状态，第三方代码不受 Ask 初始化隔离。 diff --git a/agent-runtime-lock.json b/agent-runtime-lock.json index 9ed961a7..db0591e4 100644 --- a/agent-runtime-lock.json +++ b/agent-runtime-lock.json @@ -1,6 +1,6 @@ { "formatVersion": 1, - "agentVersion": "0.11.7", + "agentVersion": "0.11.8", "protocol": { "major": 2, "minor": 0 diff --git a/docs/architecture/remote-host-and-goodbuddy-agent-design.md b/docs/architecture/remote-host-and-goodbuddy-agent-design.md index 38a6f531..95e135e0 100644 --- a/docs/architecture/remote-host-and-goodbuddy-agent-design.md +++ b/docs/architecture/remote-host-and-goodbuddy-agent-design.md @@ -2,7 +2,7 @@ ## 状态 -本文记录截至 2026-08-28 的当前代码实现，不定义额外的信任框架。“新增 Host 只探测、Host 卡片手动准备 +本文记录截至 2026-08-29 的当前代码实现，不定义额外的信任框架。“新增 Host 只探测、Host 卡片手动准备 Agent/Runtime、Host 直接从 GitHub/北京镜像下载、项目始终使用 Host current 环境”已经完成源码接线， 详细事务与验收边界见 [SSH Host 远程环境准备与直连下载设计](./remote-host-environment-provisioning-design.md)； @@ -13,10 +13,9 @@ Windows 到 Linux x64 的既有安装、 Main-only 模型桥、断线恢复、输出重放、同一 OpenCode Session 续接与终态清理已经在真实 Host 上完成 provider-free 验证。上一轮 Linux x64 验收使用 Agent `0.11.2-e2e.12` 与 OpenCode Runtime `1.18.9` 完成了一次有界真实模型工具调用；加入每 helper 随机 loopback -路径 capability 后，当前源码 lock 已更新为待发布 Agent `0.11.7`。失败的 `agent-v0.11.3` -保持不可变且未发布。远程 OpenCode 功能仍处于发布前验证阶段；公开签名 key registry -已供应，当前发布门槛是通过独立 Agent workflow 正式发布并公开验证 Linux x64/arm64 -复合包和签名累计目录。 +路径 capability 后，Agent `0.11.7` 已通过独立 workflow 发布 Linux x64/arm64 复合包和 +签名累计目录；当前源码准备 `0.11.8`，修复 Host 更新并消除重复 payload 验证。失败的 +`agent-v0.11.3` 保持不可变且未发布。 ## 产品语义 @@ -66,17 +65,16 @@ Detached GoodBuddy Agent - Agent bundle 通过 manifest、Ed25519 签名、payload digest、平台和架构校验。 - 安装使用当前 SSH 用户目录中的 GoodBuddy-owned 路径和 side-by-side digest 目录。 -- Agent 代码与固定 Node Runtime 是独立 payload。升级时如果当前 Host Agent 的签名 - manifest、registry identity、owner/mode/size 和 Node digest 都可验证，且候选 - manifest 声明完全相同的 Node，安装器直接在新的 side-by-side 目录中复用该 Node； - 否则正常上传候选 Node。Agent 不匹配不会阻止升级，也不会覆盖旧安装。 +- Agent 代码与固定 Node Runtime 一起位于签名 compound payload。显式安装或重装从本次 + 已完整校验的准备目录原子发布整个 Agent，不扫描旧安装、不创建跨版本 Node 硬链接； + Agent 不匹配不会阻止升级，也不会覆盖 GoodBuddy-owned 路径以外的内容。 - 桌面包只携带版本 lock 与 production 公钥，不携带远端 payload。Host 卡片只有一个按 版本事实显示“安装远程环境”“更新远程环境”或“重新安装”的主按钮；次级 SegmentedControl 选择“自动”“Host 下载”或“GoodBuddy 传输”，默认“自动”且不持久化。 每个复合包绑定 Agent、固定 Node 与桌面维护的 OpenCode Runtime 精确工件。添加或重新 验证 Host 只保存并探测，不自动传输完整包。 - Host 管理独占 Agent/Runtime 的包准备、更新和完整 payload 验证。已有项目的打开和切换 - 只更新本地项目选择。Workspace 和执行路径按需通过安装管理器解析 Host current identity， + 只更新本地项目选择。Workspace 和执行路径按需读取 Host current registry， 执行固定 `attach-or-bootstrap` 并复用当前 Agent 连接；同一进程内复用已确认 identity。 它们不取得安装包、不发布组件，也不通过 SFTP 重读或哈希 payload。 - Agent 的固定 attach/按需启动命令只读取 Host 管理已提交的 installation registry 和 @@ -110,11 +108,13 @@ Detached GoodBuddy Agent bootstrap Node；约 294 MiB 完整包不会一次读入 Main `Buffer`，Host 仍再次校验完整包。 - 两种 acquisition 交付到固定 operation staging 后，完全共用 control-plane `prepare → commit → Agent activate/health → Runtime activate → finalize → cleanup`。 - commit 终态持久化；通道丢失只用 `commit-status` 只读恢复，不重放 commit。prepare + commit 终态持久化；通道丢失时 `commit-status` 读取终态，或从已认证准备状态幂等完成 + 中断的目录/metadata 发布，不重新下载或准备包。prepare 完成后、commit 前快照 Agent/Runtime 五个 metadata 文件，任一组件 adoption 失败都恢复其原字节或原缺失 状态；已经发布的 side-by-side payload 可以保留但不能成为 current。确认 adoption 后 - 才显式 cleanup。首次 bootstrap 不依赖既有 Agent daemon，也不要求 format v1 归档携带 - `agent/lib/package-installer.cjs`。 + 才显式 cleanup；cleanup 失败只保留维护重试，不回滚健康环境。Host 在 prepare 解包时 + 完成一次完整 payload 校验，commit 和后续注册检查不再遍历包体。首次 bootstrap 不依赖 + 既有 Agent daemon，也不要求 format v1 归档携带 `agent/lib/package-installer.cjs`。 - 即使版本号均为当前版本，Host 卡片仍提供同版本“重新安装”，用于修复 registry、签名 或安装 identity 异常。GoodBuddy-owned 同 digest 目录损坏时先隔离后替换，并在发布或 激活失败时恢复；不要求删除 Host、凭据或引用项目。 @@ -187,8 +187,8 @@ Execute 不经过 Ask 的 bubblewrap profile： - 直接启动已签名 Runtime entrypoint； - 使用 Main-only 模型桥时，签名 Agent launcher 会 `exec` 候选 manifest 锁定的 - Node Runtime；完全相同且已验证的 Node 可在 Agent 版本间复用。进程 owner 校验 - 最终 Node executable，而不是已经被替换的 shell launcher 路径； + Node Runtime；进程 owner 校验最终 Node executable，而不是已经被替换的 shell + launcher 路径； - `cwd` 为项目 Workspace； - 继承 SSH 账号的正常环境、文件系统、进程和网络能力； - 不进行 T2/T3、confinement attestation、approval bridge 或逐工具批准。 @@ -245,7 +245,8 @@ Execute 不经过 Ask 的 bubblewrap profile： - 2026-08 的本地 fixture 完整验证 Linux x64 Agent `0.11.2-e2e.12`、Node `24.19.0` 和 Agent protocol `2.0`；当时没有 arm64 fixture，因此该记录不能作为当前独立发布 - 的双架构验收。当前源码 lock 是待发布版本 `0.11.7`，需要由新的复合包发布流程另行验证。 + 的双架构验收。Agent `0.11.7` 后续已由原生 workflow 发布并公开验证双架构工件； + 当前源码 lock 是修复候选 `0.11.8`。 - 正常 Host 更新路径把 Linux x64 Host 的 Agent 更新为 `0.11.2-e2e.12`，并确认 OpenCode Runtime 已安装版本与所需版本均为 `1.18.9`。 - 一条新的 Ask 用户操作只提交一次。OpenCode 先在 build 模型轮次请求一个原生 diff --git a/docs/architecture/remote-host-environment-provisioning-design.md b/docs/architecture/remote-host-environment-provisioning-design.md index cac865b5..0cd42d8d 100644 --- a/docs/architecture/remote-host-environment-provisioning-design.md +++ b/docs/architecture/remote-host-environment-provisioning-design.md @@ -150,17 +150,21 @@ daemon 参与。两种 acquisition 的差别只在于如何把同一个签名 co 1. Main 创建带 operation ID、总时限、输出上限和取消信号的准备操作，并通过固定 `prepare` channel 发送有界 one-shot installer 与结构化输入。 -2. Host 校验归档大小、SHA-256、外层及内层签名、平台、架构、协议和 payload digest， - 只把候选准备到 side-by-side 目录，不改变 current。 +2. Host 在解包写入准备目录的同一遍处理中校验归档大小、SHA-256、外层及内层签名、 + 平台、架构、协议和每个 payload digest；不再先完整扫描 payload、再重复解包和哈希。 3. `prepare` 完成后、`commit` 前按原字节记录 Agent 与 Runtime 的五个 current/registry metadata 文件， 同时记录原本缺失的状态。 -4. `commit` 终态先持久化到 operation staging。控制通道丢失时，Main 只用同一 operation - 的 `commit-status` 恢复结果，绝不重放 `commit`。 -5. commit 后依次完成 Agent activate/health、Runtime activate 和 finalize。任一组件 - adoption 失败都停止候选，并把五个 metadata 文件恢复为原字节或原缺失状态；已经发布的 - side-by-side payload 可以保留，但不能成为 current。 -6. Main 确认 adoption 后才显式执行 cleanup，释放 staging、缓存 lease 和操作资源。 +4. `commit` 只复核有界的签名 manifest、准备回执和入口 metadata，再以目录 rename 发布 + 已准备内容及包内认证的公钥 registry/Runtime lock；不会重读归档或遍历 payload。 + 终态先持久化到 operation staging；控制通道丢失时，同一 operation 的 + `commit-status` 读取终态，或从已认证准备状态幂等完成中断的 rename/metadata 发布。 +5. commit 后在同一条已固定身份的 SSH lease 上执行 Agent bootstrap/readiness 和 Runtime + activate。新 Agent 最多完整验证一次，新 Runtime 最多完整验证一次；注册成功后的 + health、capabilities 和 prompt 启动只读取 registry、签名 manifest 与入口 metadata。 + adoption 失败时停止候选，并把五个 metadata 文件恢复为原字节或原缺失状态。 +6. Main 确认 adoption 后显式执行 cleanup。cleanup 失败只保留待重试的有界 operation， + 不回滚已经健康的 Agent/Runtime。 这不是两个并行安装管理器，也不存在把 Agent 与 Runtime payload 逐文件走 SFTP 安装的 第二条路径。两种 acquisition 共享相同的 prepare、commit、adoption、finalize 与 cleanup。 @@ -182,16 +186,16 @@ Host 下载返回明确失败；本次操作不自动切换 acquisition，用户 后也走同一缓存 lease、上传和 Host 校验流程。 - 本地项目和普通桌面打包不依赖任何远端 Agent 工件。 -## 完整包与复用 +## 完整包与发布 第一阶段继续发布和下载完整复合 `.gbagent`，不同时引入组件化增量发布： - 远程直连和 GoodBuddy 本机下载都会传输完整包，其中包含 Agent、固定 Node 和 OpenCode Runtime。 -- 新 Agent 安装时，如果旧 manifest、registry identity、owner/mode/size 和 Node digest - 全部可验证，并且候选声明同一 Node，则使用硬链接复用，不重新写入 Node 数据。 -- 相同 Runtime bundle digest 已存在且完整时只验证并激活，不重复上传或解包。 -- Agent 其他文件或变化后的 Runtime 仍按完整候选安装。 +- 每次显式安装或重装都从本次已经校验并解包的准备目录原子替换对应 Agent 与 Runtime + digest 目录，不为节省本机磁盘写入而重新遍历旧目录，也不使用跨安装硬链接。 +- 操作响应丢失后的同 operation 重试只检查签名 manifest、registry identity 和三份小型 + trust metadata，不重新读取归档或 payload；正常 cleanup 随后删除准备目录。 只有真实包体和发布频率证明网络成本仍不可接受时，才另行设计 Agent、Node 和 Runtime 独立签名组件目录；本功能不提前引入第二套发布协议。 @@ -216,10 +220,13 @@ Host 下载返回明确失败；本次操作不自动切换 acquisition，用户 同一 Host identity 同时只允许一个由用户启动、Main-owned 的准备操作。重复观察者加入 已有操作，不启动第二次发布；窗口关闭、显式取消、Host identity 改变或 Main 退出时执行 -有界取消。Main 在 commit 前为该 Host 持久化一个不含凭据的 pending operation 记录； +有界取消。Main 在 commit 前为该 Host 持久化一个不含凭据的 pending operation 记录， +其中包含五份有界 metadata 的原字节/原缺失快照； commit 指令开始后若 SSH 通道、输出或终态丢失，当前操作保留该记录和远端 staging。 -下一次重试或应用重启后的首次操作先对同一 Host identity 执行只读 `commit-status` 和 -cleanup，不重放未知 commit，也不开始第二条 acquisition；确认清理后删除 pending 记录。 +下一次重试或应用重启后的首次操作先对同一 Host identity 执行 `commit-status` 并 +恢复 adoption；恢复中的 Agent/Runtime adoption 失败仍使用该持久化快照回滚。它不会 +重新下载或准备包，也不开始第二条 acquisition。环境健康后再重试 +cleanup，确认清理后删除 pending 记录。 取消在最终原子切换完成后不再伪装成回滚成功。 ## 项目创建与切换 @@ -264,9 +271,10 @@ cleanup，不重放未知 commit，也不开始第二条 acquisition；确认清 - 扩展当前 Host 系统探针和远程环境 inspector，返回瞬时下载准备能力。 - 让当前 `RemoteEnvironmentUpdateService` 演进为 Host 环境准备编排器，统一用户手动 启动的首次安装和后续更新、自动 acquisition 选择、进度、取消和最终失效。 -- Host 管理使用安装管理器完成准备、更新和完整验证。项目切换不调用安装管理器； - Workspace 和执行路径按需解析 current identity，并在当前进程内复用已确认 identity 和 - Agent 连接；Host 编辑或环境更新定向清空这些缓存。这些路径不会取得安装包或发布组件。 +- Host 环境准备编排器直接完成一次 package prepare/commit 及 Agent/Runtime adoption。 + Workspace 和执行路径只读取 current registry 并调用 Host 侧轻量 identity/health 检查， + 在当前进程内复用已确认 identity 和 Agent 连接；Host 编辑或环境更新定向清空这些缓存。 + 这些路径不会取得安装包、发布组件或通过 SFTP 扫描 payload。 - Host 卡片即使显示相同版本也保留显式重装操作，用于修复 registry、签名或 payload identity 异常；若同一 digest 的 GoodBuddy-owned 目录校验失败，重装会先隔离旧目录， 完整发布并验证新目录，失败时恢复旧目录。重装不要求删除 Host、凭据或项目，也不会处理 @@ -275,8 +283,8 @@ cleanup，不重放未知 commit，也不开始第二条 acquisition；确认清 发送脚本及结构化输入，避免 SSH command 长度限制；既有 package format v1 归档内固定 Node 负责解码和运行它。 - Preload 只暴露明确的 Host 探测、准备、取消和进度方法，不暴露 URL 或任意 SSH 命令。 -- 现有 Agent/Runtime side-by-side、Node 硬链接复用、Host identity 二次核对、Host 端 - 发布后复验、连接失效和项目稳定配置事务继续作为唯一实现。 +- 现有 Agent/Runtime side-by-side、固定 SSH lease、Host 端一次完整验证、注册后轻量检查、 + 连接失效和项目稳定配置事务继续作为唯一实现。 ## 迁移 @@ -288,6 +296,9 @@ cleanup，不重放未知 commit，也不开始第二条 acquisition；确认清 - 如果 Host 未就绪或版本不兼容，项目仍可在本地选择，但实际远程操作失败；不再走旧的 隐式安装。 - 已下载或导入的本地 `.gbagent` 保持可用，不能因加入远程直连而迁移或删除。 +- `0.11.7` 遗留的 version-1 pending operation 没有持久化 metadata 快照，也没有新格式的 + 已解包准备状态；`0.11.8` 只清理其暂存并重新执行一次认证 prepare，不尝试用新 installer + 续写旧 commit。 - 远程直连继续使用现有 package format version 1，不要求归档携带 installer，也不要求 目录声明额外的 bootstrap 能力元数据。 @@ -303,7 +314,9 @@ cleanup，不重放未知 commit，也不开始第二条 acquisition；确认清 4. 直接下载严格匹配签名目录中的 URL、大小和 SHA-256；GoodBuddy 传输可在同一次操作中 下载并验证缺失候选，以有界流式 SFTP 上传完整归档和已验证 bootstrap Node。Host 对 两者完成相同的外层与内层签名、路径、架构、协议和 payload 校验。 -5. 相同 Node 在可验证且支持硬链接时不重复传输或写入；相同 Runtime digest 不重复安装。 +5. Host 对本次候选只完成一次完整 payload 校验；commit、adoption、health、capabilities + 和 prompt 启动不得再次遍历或哈希完整 Agent/Runtime，显式重装仍能用本次准备内容修复 + 同 digest 的损坏目录。 6. 创建、打开和切换项目不会产生 `.gbagent` 下载、Agent payload SFTP 上传或安装目录发布。 7. 未就绪 Host 不能创建远程项目；已有项目仍可本地选择，但远程操作失败并引导到 Host 设置。 8. Host 编辑或更新后，引用项目使用 Host 管理的当前连接和 current registry，不读取项目 @@ -317,5 +330,7 @@ cleanup，不重放未知 commit，也不开始第二条 acquisition；确认清 仍待完成。 12. Host 不可达或远端目录不存在时，用户仍可从项目浮动管理入口删除本地项目；删除 Host 会列出并本地清理全部关联项目，但不会连接 Host 或删除任何远端目录和内容。 -13. commit 终态可在通道丢失后用 `commit-status` 只读恢复且不重放；Agent 或 Runtime - adoption 失败恢复五个 metadata 文件的原字节/原缺失状态，确认 adoption 后显式 cleanup。 +13. commit 终态可在通道丢失后用 `commit-status` 读取，或从已认证准备状态幂等完成； + Agent 或 Runtime + adoption 失败恢复五个 metadata 文件的原字节/原缺失状态；已健康环境的 cleanup + 失败保留为维护重试，不触发环境回滚。 diff --git a/docs/prd/assistant-experience/assistant-workbar-and-execution-spaces-prd.md b/docs/prd/assistant-experience/assistant-workbar-and-execution-spaces-prd.md index c69e536a..8bc0282c 100644 --- a/docs/prd/assistant-experience/assistant-workbar-and-execution-spaces-prd.md +++ b/docs/prd/assistant-experience/assistant-workbar-and-execution-spaces-prd.md @@ -586,12 +586,15 @@ attach 并读取 current registry，不存在项目中的旧 Host revision 或 prepare channel 发送有界 one-shot installer；Host 先验证目录绑定的归档大小和 SHA-256， 再由 format v1 归档内固定 Node 解码并运行 installer。归档无需包含 `agent/lib/package-installer.cjs`，目录不提供或检查额外的 bootstrap 能力元数据。 -- Agent 与 Runtime 各自维护版本，签名摘要标识精确工件；使用 side-by-side 安装、自检和 - 健康切换，失败时不改变当前项目绑定。相同且可验证的 Node 使用硬链接复用，相同 Runtime - digest 不重复安装。 -- commit 终态持久化，控制通道丢失时只用 `commit-status` 恢复而不重放。prepare 完成后、commit 前快照 +- Agent 与 Runtime 各自维护版本，签名摘要标识精确工件。Host 在解包到准备目录的同一遍 + 处理中完成完整 payload 校验，commit 只复核签名 metadata 并原子替换 side-by-side + 目录，不重新读取归档、扫描旧目录或使用跨安装硬链接。 +- commit 终态持久化；控制通道丢失时，`commit-status` 读取终态，或从已认证准备状态 + 幂等完成中断的目录/metadata 发布，不重新下载或准备包。prepare 完成后、commit 前快照 Agent/Runtime 五个 metadata 文件；任一组件 adoption 失败恢复原字节或原缺失状态， - 已发布 payload 不得成为 current，确认 adoption 后显式 cleanup。 + 已发布 payload 不得成为 current。新 Agent/Runtime 各自最多完整验证一次；注册后的 + health、capabilities 和 prompt 启动只检查 registry、签名 manifest 与入口 metadata。 + 确认 adoption 后显式 cleanup，cleanup 失败不回滚健康环境。 - 握手报告 installation、Daemon boot identity、协议、系统、架构、用户监督器和能力。 - 在远程执行路径规范化、Git、文件、PTY、进程组和 Runtime 管理。 - 持久化有界 Agent 到 Main 输出；SSH 断开后 Agent 继续运行，同一 Agent 重连时只恢复 diff --git a/package-lock.json b/package-lock.json index e37b04c3..cf7ef0e9 100644 --- a/package-lock.json +++ b/package-lock.json @@ -1,12 +1,12 @@ { "name": "goodbuddy", - "version": "0.11.7", + "version": "0.11.8", "lockfileVersion": 3, "requires": true, "packages": { "": { "name": "goodbuddy", - "version": "0.11.7", + "version": "0.11.8", "license": "0BSD", "dependencies": { "@agentclientprotocol/sdk": "0.25.1", diff --git a/package.json b/package.json index 0ea3890b..61bca97b 100644 --- a/package.json +++ b/package.json @@ -1,6 +1,6 @@ { "name": "goodbuddy", - "version": "0.11.7", + "version": "0.11.8", "private": true, "description": "Secure desktop AI workspace with controlled Agent Runtimes", "desktopName": "GoodBuddy", diff --git a/resources/release-notes.json b/resources/release-notes.json index 9dcf1012..21aec26f 100644 --- a/resources/release-notes.json +++ b/resources/release-notes.json @@ -1,6 +1,40 @@ { "formatVersion": 1, "releases": [ + { + "version": "0.11.8", + "releasedAt": "2026-08-29", + "notes": { + "zh-CN": { + "highlights": [ + "GoodBuddy 0.11.8 修复正式环境中的 Host 更新失败，并显著缩短 Agent 与 OpenCode Runtime 的安装、恢复和日常启动校验。" + ], + "features": [], + "fixes": [ + "**Host 更新恢复可用。** 修复已发布 OpenCode Runtime 在采用阶段被桌面内置锁重复校验而失败的问题。Host 现在信任签名复合包中的版本锁和身份，并在同一条固定 SSH 连接上完成 Agent 启动、健康检查与 Runtime 激活。", + "**不再重复扫描远端包体。** Host 在解包时完成完整 SHA-256 与签名校验；commit 只检查签名元数据。Main 不再通过 SFTP 逐文件读取 Agent/Runtime，后续健康检查、能力发现和每次提问只使用已登记 identity、manifest 与入口元数据。仍保留 SHA-256，提速来自消除重复读取。", + "**中断与清理更可靠。** 中断的 commit 可从已认证准备状态继续，待恢复操作会保留五份元数据快照并在采用失败时回滚。环境已健康后，暂存清理失败只留待重试，不再错误回滚；安装错误会显示具体的有界原因。" + ], + "notices": [ + "**技术预览与版本要求。** 远程项目仍默认关闭且为技术预览。Host 需要安装单独发布的 Agent `0.11.8`，提供 Linux x64 和 arm64；桌面包不内置 Agent 或远程 Runtime，本次不构建 LoongArch 预览。" + ] + }, + "en-US": { + "highlights": [ + "GoodBuddy 0.11.8 fixes Host updates in production and substantially reduces Agent and OpenCode Runtime verification during installation, recovery, and normal startup." + ], + "features": [], + "fixes": [ + "**Host updates work again.** Fixed published OpenCode Runtime adoption failing because it was redundantly checked against the desktop-bundled lock. The Host now uses the signed compound package's lock and identity, then starts and health-checks the Agent and activates Runtime on one pinned SSH connection.", + "**No repeated remote payload scans.** The Host completes full SHA-256 and signature verification while extracting, and commit checks only signed metadata. Main no longer reads Agent or Runtime file trees over SFTP. Later health, capability, and prompt paths use registered identities, manifests, and entrypoint metadata. SHA-256 remains; the speedup comes from eliminating rereads.", + "**Reliable interruption and cleanup recovery.** Interrupted commits resume from authenticated prepared state. Pending recovery keeps snapshots of all five metadata files and restores them if adoption fails. Once the environment is healthy, staging cleanup failures are retried instead of rolling it back, and bounded installer errors retain their concrete cause." + ], + "notices": [ + "**Technical preview and version requirement.** Remote Projects remain disabled by default and in technical preview. Hosts require the separately published Agent `0.11.8` for Linux x64 or arm64. Desktop packages do not embed the Agent or remote Runtime, and this release does not build a LoongArch preview." + ] + } + } + }, { "version": "0.11.7", "releasedAt": "2026-08-29", diff --git a/src/agent-daemon/cli.test.ts b/src/agent-daemon/cli.test.ts index 94a91efc..56767f92 100644 --- a/src/agent-daemon/cli.test.ts +++ b/src/agent-daemon/cli.test.ts @@ -192,11 +192,13 @@ describe('Agent CLI fixed command contract', () => { state: 'ready' as const, installationId })) + const verifyInstallation = vi.fn(async () => verified) const dependencies: AgentCliDependencies = { installationPaths: () => installationPaths, releaseKeyRegistry, installationRegistry, - verifyInstallation: async () => verified, + verifyInstallation, + loadRegisteredInstallation: async () => verified, createLifecycle: (() => ({ status, bootstrap @@ -227,6 +229,21 @@ describe('Agent CLI fixed command contract', () => { ).toBe(0) expect(status).toHaveBeenCalledOnce() expect(bootstrap).toHaveBeenCalledOnce() + expect( + installationRegistry.snapshot().current?.installationId + ).toBe(installationId) + + expect( + await runAgentCli( + buildFixedAgentCliArgv(installationId, { + kind: 'lifecycle', + action: 'adopt' + }), + { ...dependencies, io: cliIo() } + ) + ).toBe(0) + expect(verifyInstallation).toHaveBeenCalledOnce() + expect(bootstrap).toHaveBeenCalledTimes(2) }) it('dispatches generated attach argv using only derived managed paths', async () => { @@ -469,6 +486,31 @@ describe('Agent CLI fixed command contract', () => { architecture: 'x64', runtimeVersion: '1.18.9' }) + + expect( + await runAgentCli( + buildFixedAgentCliArgv( + verifyAgentInstallationId('install-1'), + { + kind: 'runtime-activate', + runtimeId: 'opencode', + bundleDigest, + architecture: 'x64', + forceVerification: true + } + ), + { + runtimePaths: () => paths, + runtimeReleaseKeyRegistry: releaseKeyRegistry, + runtimeLock: {} as RemoteRuntimeLock, + runtimeRegistry: registry, + verifyRuntime, + currentArchitecture: () => 'x64', + io: cliIo() + } + ) + ).toBe(0) + expect(verifyRuntime).toHaveBeenCalledTimes(2) }) it('derives Runtime paths and rejects activation argv injection', async () => { diff --git a/src/agent-daemon/cli.ts b/src/agent-daemon/cli.ts index 1d115fea..5271e018 100644 --- a/src/agent-daemon/cli.ts +++ b/src/agent-daemon/cli.ts @@ -39,6 +39,7 @@ import { RuntimeBundleRegistry } from './runtime-bundle-registry' import { + loadRegisteredRuntimeBundle, readRemoteRuntimeLock, verifyRuntimeBundle, type VerifiedRuntimeBundle @@ -111,6 +112,7 @@ export type ManagedRuntimePaths = { } const LIFECYCLE_ACTIONS = new Set([ + 'adopt', 'bootstrap', 'status', 'health', @@ -225,7 +227,8 @@ async function runRuntime( 'installation-id', 'runtime-id', 'bundle-digest', - 'architecture' + 'architecture', + 'force-verification' ]) requireOptions(options, [ 'installation-id', @@ -243,6 +246,16 @@ async function runRuntime( const architecture = validateRuntimeArchitecture( options.architecture! ) + const forceVerification = + options['force-verification'] === 'true' + if ( + options['force-verification'] !== undefined && + !forceVerification + ) { + throw new Error( + 'Invalid Runtime force-verification option' + ) + } const hostArchitecture = dependencies.currentArchitecture?.() ?? currentAgentArchitecture() @@ -271,15 +284,30 @@ async function runRuntime( runtimeRoot: paths.runtimeRoot, storagePath: paths.registryPath }) - const verified = await ( - dependencies.verifyRuntime ?? verifyRuntimeBundle - )(paths.bundleDirectory, { + const verificationOptions = { architecture, releaseKeyRegistry, runtimeLock, verificationEnvironment: dependencies.runtimeVerificationEnvironment ?? 'production' - }) + } as const + const registered = registry.find( + runtimeId, + bundleDigest, + architecture + ) + const verified = + registered === undefined || forceVerification + ? await ( + dependencies.verifyRuntime ?? verifyRuntimeBundle + )(paths.bundleDirectory, verificationOptions) + : await loadRegisteredRuntimeBundle( + registered.bundleDirectory, + { + ...verificationOptions, + registered: registered.entry + } + ) assertActivatedRuntimeIdentity( verified, runtimeId, @@ -352,7 +380,8 @@ async function runDaemon( installationId, paths, dependencies, - 'registered' + 'registered', + verified ).recordCurrentDaemonReady(daemon.status().daemonBootId) await (dependencies.waitForShutdown?.() ?? waitForShutdownSignal()) } finally { @@ -374,7 +403,7 @@ async function runAttach( installationId, dependencies ) - await loadManagedInstallation( + const { verified } = await loadManagedInstallation( installationId, paths, dependencies @@ -399,7 +428,8 @@ async function runAttach( installationId, paths, dependencies, - 'registered' + 'registered', + verified ).bootstrap() } }) @@ -451,10 +481,17 @@ async function runDoctor( options['installation-id']! ) const paths = resolveInstallationPaths(installationId, dependencies) - const status = await createDetachedLifecycle( + const { verified } = await loadManagedInstallation( installationId, paths, dependencies + ) + const status = await createDetachedLifecycle( + installationId, + paths, + dependencies, + 'registered', + verified ).status() io.output.write(`${JSON.stringify({ platform: process.platform, @@ -479,48 +516,150 @@ async function runLifecycle( options['installation-id']! ) const paths = resolveInstallationPaths(installationId, dependencies) - const { verified, registry } = await verifyManagedInstallation( - installationId, - paths, - dependencies - ) - const lifecycle = createDetachedLifecycle( - installationId, - paths, - dependencies - ) switch (action) { - case 'bootstrap': { - registry.stageCandidate(verified) - prepareManagedSocketDirectory(paths) - const status = await lifecycle.bootstrap() - io.output.write(`${JSON.stringify(status)}\n`) - break - } - case 'status': { - registry.assertVerifiedRole(verified, ['current', 'candidate']) - io.output.write(`${JSON.stringify(await lifecycle.status())}\n`) - break - } - case 'health': { - registry.assertVerifiedRole(verified, ['current', 'candidate']) - const status = await lifecycle.health() - if ( - registry.snapshot().candidate?.installationId === + case 'adopt': { + const { verified, registry } = + await verifyManagedInstallation( + installationId, + paths, + dependencies + ) + const alreadyCurrent = + registry.snapshot().current?.installationId === installationId - ) { + if (!alreadyCurrent) { + registry.stageCandidate(verified) + } + prepareManagedSocketDirectory(paths) + const status = await createDetachedLifecycle( + installationId, + paths, + dependencies, + 'verified', + verified + ).bootstrap() + if (!alreadyCurrent) { registry.promoteCandidate(installationId) } io.output.write(`${JSON.stringify(status)}\n`) break } + case 'bootstrap': { + const agentRoot = dirname( + dirname(dirname(paths.executablePath)) + ) + const registry = + dependencies.installationRegistry ?? + new InstallationRegistry({ + storagePath: resolve(agentRoot, 'registry.json') + }) + const snapshot = registry.snapshot() + const current = snapshot.current?.installationId === + installationId + ? snapshot.current + : undefined + const candidate = snapshot.candidate?.installationId === + installationId + ? snapshot.candidate + : undefined + const registered = current ?? candidate + const isNewInstallation = registered === undefined + const verified = isNewInstallation + ? ( + await verifyManagedInstallation( + installationId, + paths, + dependencies + ) + ).verified + : await ( + dependencies.loadRegisteredInstallation ?? + loadRegisteredAgentBundle + )(dirname(paths.executablePath), { + installationId, + architecture: currentAgentArchitecture(), + registered + }) + if (isNewInstallation) { + registry.stageCandidate(verified) + } + prepareManagedSocketDirectory(paths) + const lifecycle = createDetachedLifecycle( + installationId, + paths, + dependencies, + 'verified', + verified + ) + const status = await lifecycle.bootstrap() + if (current === undefined) { + registry.promoteCandidate(installationId) + } + io.output.write(`${JSON.stringify(status)}\n`) + break + } + case 'status': { + const { verified } = await loadManagedInstallation( + installationId, + paths, + dependencies + ) + const lifecycle = createDetachedLifecycle( + installationId, + paths, + dependencies, + 'registered', + verified + ) + io.output.write(`${JSON.stringify(await lifecycle.status())}\n`) + break + } + case 'health': { + const { verified } = await loadManagedInstallation( + installationId, + paths, + dependencies + ) + const lifecycle = createDetachedLifecycle( + installationId, + paths, + dependencies, + 'registered', + verified + ) + const status = await lifecycle.health() + io.output.write(`${JSON.stringify(status)}\n`) + break + } case 'stop': { - registry.assertVerifiedRole(verified, ['current', 'candidate']) + const { verified } = await loadManagedInstallation( + installationId, + paths, + dependencies + ) + const lifecycle = createDetachedLifecycle( + installationId, + paths, + dependencies, + 'registered', + verified + ) io.output.write(`${JSON.stringify(await lifecycle.stop())}\n`) break } case 'retire': { - registry.assertVerifiedRole(verified, ['current', 'candidate']) + const { verified } = await loadManagedInstallation( + installationId, + paths, + dependencies + ) + const lifecycle = createDetachedLifecycle( + installationId, + paths, + dependencies, + 'registered', + verified + ) io.output.write(`${JSON.stringify(await lifecycle.retire())}\n`) break } @@ -531,7 +670,8 @@ function createDetachedLifecycle( installationId: string, paths: ManagedInstallationPaths, dependencies: AgentCliDependencies, - identitySource: 'verified' | 'registered' = 'verified' + identitySource: 'verified' | 'registered' = 'verified', + verifiedInstallation?: VerifiedInstalledAgentBundle ): DetachedAgentLifecycle { const options: DetachedAgentLifecycleOptions = { installationId, @@ -539,6 +679,9 @@ function createDetachedLifecycle( stateDirectory: paths.stateDirectory, socketPath: paths.socketPath, verifyInstallation: async () => { + if (verifiedInstallation !== undefined) { + return verifiedInstallation + } if (identitySource === 'registered') { return ( await loadManagedInstallation( diff --git a/src/agent-daemon/installation-registry.test.ts b/src/agent-daemon/installation-registry.test.ts index 5e3105d4..9727a193 100644 --- a/src/agent-daemon/installation-registry.test.ts +++ b/src/agent-daemon/installation-registry.test.ts @@ -116,7 +116,8 @@ describe('Agent installation registry', () => { installationId: 'install-a', agentVersion: '0.11.0', manifestSha256: 'a'.repeat(64), - arch: 'x64' + arch: 'x64', + protocol: { major: 1, minor: 0 } } }) expect(readFileSync(storagePath, 'utf8')).toBe(legacyBytes) diff --git a/src/agent-daemon/installation-registry.ts b/src/agent-daemon/installation-registry.ts index 9d4288f2..06217aa4 100644 --- a/src/agent-daemon/installation-registry.ts +++ b/src/agent-daemon/installation-registry.ts @@ -221,7 +221,8 @@ function entryFromVerified( installationId: verified.installationId, agentVersion: verified.manifest.agentVersion, manifestSha256: verified.manifestSha256, - arch: verified.manifest.arch + arch: verified.manifest.arch, + protocol: verified.manifest.protocol }) } diff --git a/src/agent-daemon/installed-bundle-verifier.ts b/src/agent-daemon/installed-bundle-verifier.ts index 6f6402a8..0830f380 100644 --- a/src/agent-daemon/installed-bundle-verifier.ts +++ b/src/agent-daemon/installed-bundle-verifier.ts @@ -310,7 +310,16 @@ async function loadRegisteredAgentBundleUnchecked( manifestBytes ) || manifest.agentVersion !== registered.agentVersion || - manifest.arch !== registered.arch + manifest.arch !== registered.arch || + ( + registered.protocol !== undefined && + ( + manifest.protocol.major !== + registered.protocol.major || + manifest.protocol.minor !== + registered.protocol.minor + ) + ) ) { throw new Error( 'Agent manifest does not match the Host-managed registry' diff --git a/src/agent-daemon/runtime-acp-backend.test.ts b/src/agent-daemon/runtime-acp-backend.test.ts index bcb20491..cc4cbb46 100644 --- a/src/agent-daemon/runtime-acp-backend.test.ts +++ b/src/agent-daemon/runtime-acp-backend.test.ts @@ -268,7 +268,7 @@ function harness(input: { const backend = new RuntimeAcpBackend({ journal, resolveRuntimeBundle: vi.fn(async () => resolved), - reverifyRuntimeBundle: vi.fn(async () => verifiedBundle()), + loadRegisteredRuntimeBundle: vi.fn(async () => verifiedBundle()), resolveWorkspace: vi.fn(async (preparation) => ({ workspaceIdentity: preparation.workspaceIdentity, workspaceDirectory: '/workspace', diff --git a/src/agent-daemon/runtime-acp-backend.ts b/src/agent-daemon/runtime-acp-backend.ts index 1cdfe2f6..0793ffdf 100644 --- a/src/agent-daemon/runtime-acp-backend.ts +++ b/src/agent-daemon/runtime-acp-backend.ts @@ -227,7 +227,7 @@ export type RuntimeAcpBackendOptions = { runtimeId: string, runtimeBundleDigest: string ): RuntimeAcpResolvedBundle | Promise - reverifyRuntimeBundle( + loadRegisteredRuntimeBundle( resolved: RuntimeAcpResolvedBundle, preparation: RemotePromptOperationPreparation ): RuntimeAcpVerifiedBundle | Promise @@ -947,7 +947,7 @@ export class RuntimeAcpBackend { let verified: RuntimeAcpVerifiedBundle try { - verified = await this.#options.reverifyRuntimeBundle( + verified = await this.#options.loadRegisteredRuntimeBundle( binding.resolvedBundle, preparation ) diff --git a/src/agent-daemon/runtime-bundle-registry.ts b/src/agent-daemon/runtime-bundle-registry.ts index 0798bff0..dec16012 100644 --- a/src/agent-daemon/runtime-bundle-registry.ts +++ b/src/agent-daemon/runtime-bundle-registry.ts @@ -25,7 +25,7 @@ import { } from './managed-paths' import type { InstalledBundleVerificationEnvironment } from './installed-bundle-verifier' import { - verifyRuntimeBundle, + loadRegisteredRuntimeBundle, type VerifiedRuntimeBundle } from './runtime-bundle-verifier' @@ -120,6 +120,27 @@ export class RuntimeBundleRegistry { entry: RuntimeRegistryEntry bundleDirectory: string } { + const resolved = this.find( + runtimeIdInput, + bundleDigestInput, + architecture + ) + if (resolved === undefined) { + throw new Error( + 'Runtime bundle is not the verified current bundle' + ) + } + return resolved + } + + find( + runtimeIdInput: string, + bundleDigestInput: string, + architecture: AgentArchitecture + ): { + entry: RuntimeRegistryEntry + bundleDirectory: string + } | undefined { const runtimeId = agentIdentifierSchema.parse(runtimeIdInput) const bundleDigest = sha256DigestSchema.parse(bundleDigestInput) this.#state = this.#load({ createIfMissing: false }) @@ -130,9 +151,7 @@ export class RuntimeBundleRegistry { candidate.architecture === architecture ) if (entry === undefined) { - throw new Error( - 'Runtime bundle is not the verified current bundle' - ) + return undefined } return { entry: { ...entry }, @@ -231,7 +250,7 @@ export class RuntimeBundleRegistry { } } -export function createVerifiedRuntimeCapabilitySource(options: { +type VerifiedRuntimeCapabilitySourceOptions = { registry: RuntimeBundleRegistry architecture: AgentArchitecture releaseKeyRegistry: AgentReleaseKeyRegistry @@ -241,53 +260,65 @@ export function createVerifiedRuntimeCapabilitySource(options: { filesystemPlatform?: NodeJS.Platform uid?: number reportError?: (message: string, error: unknown) => void -}): () => Promise { + loadRegistered?: ( + entry: RuntimeRegistryEntry, + bundleDirectory: string + ) => Promise +} + +export function createVerifiedRuntimeCapabilitySource( + options: VerifiedRuntimeCapabilitySourceOptions +): () => Promise { return async () => await loadVerifiedRuntimeCapabilities(options) } -async function loadVerifiedRuntimeCapabilities(options: { - registry: RuntimeBundleRegistry - architecture: AgentArchitecture - releaseKeyRegistry: AgentReleaseKeyRegistry - runtimeLock: RemoteRuntimeLock - verificationEnvironment?: InstalledBundleVerificationEnvironment - enforceFilesystemMode?: boolean - filesystemPlatform?: NodeJS.Platform - uid?: number - reportError?: (message: string, error: unknown) => void -}): Promise { +async function loadVerifiedRuntimeCapabilities( + options: VerifiedRuntimeCapabilitySourceOptions +): Promise { const capabilities: DaemonCapabilities['runtimes'] = [] for (const entry of options.registry.current(options.architecture)) { try { - const verified = await verifyRuntimeBundle( + const bundleDirectory = options.registry.bundleDirectory( entry.runtimeId, entry.bundleDigest - ), - { - architecture: options.architecture, - releaseKeyRegistry: options.releaseKeyRegistry, - runtimeLock: options.runtimeLock, - ...(options.verificationEnvironment === undefined - ? {} - : { - verificationEnvironment: - options.verificationEnvironment - }), - ...(options.enforceFilesystemMode === undefined - ? {} - : { - enforceFilesystemMode: - options.enforceFilesystemMode - }), - ...(options.filesystemPlatform === undefined - ? {} - : { - filesystemPlatform: options.filesystemPlatform - }), - ...(options.uid === undefined ? {} : { uid: options.uid }) - } - ) + ) + const verified = options.loadRegistered === undefined + ? await loadRegisteredRuntimeBundle( + bundleDirectory, + { + registered: entry, + architecture: options.architecture, + releaseKeyRegistry: + options.releaseKeyRegistry, + runtimeLock: options.runtimeLock, + ...(options.verificationEnvironment === undefined + ? {} + : { + verificationEnvironment: + options.verificationEnvironment + }), + ...(options.enforceFilesystemMode === undefined + ? {} + : { + enforceFilesystemMode: + options.enforceFilesystemMode + }), + ...(options.filesystemPlatform === undefined + ? {} + : { + filesystemPlatform: + options.filesystemPlatform + }), + ...(options.uid === undefined + ? {} + : { uid: options.uid }) + } + ) + : await options.loadRegistered( + entry, + bundleDirectory + ) if ( verified.manifest.runtimeVersion !== entry.runtimeVersion || verified.manifestDigest !== entry.manifestDigest || @@ -326,6 +357,7 @@ function entryFromVerified( architecture: verified.manifest.architecture, bundleDigest: verified.manifest.bundleDigest, manifestDigest: verified.manifestDigest, + runtimeAdapterDigest: verified.manifest.adapterDigest, acpCapabilitiesDigest: verified.manifest.acpCapabilitiesDigest }) diff --git a/src/agent-daemon/runtime-bundle-verifier.test.ts b/src/agent-daemon/runtime-bundle-verifier.test.ts index 337c1470..adcaa510 100644 --- a/src/agent-daemon/runtime-bundle-verifier.test.ts +++ b/src/agent-daemon/runtime-bundle-verifier.test.ts @@ -155,7 +155,7 @@ describe('Remote Runtime bundle verifier', () => { ).rejects.toThrow(/managed directory/iu) }) - it('advertises only a bundle that still verifies against its registry', async () => { + it('uses registered metadata without rereading Runtime payload files', async () => { const fixture = await createBundle() const runtimeRoot = dirname(dirname(fixture.bundleDirectory)) const registry = new RuntimeBundleRegistry({ @@ -198,6 +198,18 @@ describe('Remote Runtime bundle verifier', () => { join(fixture.bundleDirectory, 'licenses', 'opencode.txt'), 'mutated' ) + await expect(capabilities()).resolves.toHaveLength(1) + expect(reportError).not.toHaveBeenCalled() + + writeFileSync( + join(fixture.bundleDirectory, 'bin', 'opencode'), + Buffer.concat([ + readFileSync( + join(fixture.bundleDirectory, 'bin', 'opencode') + ), + Buffer.from('changed') + ]) + ) await expect(capabilities()).resolves.toEqual([]) expect(reportError).toHaveBeenCalledWith( 'Verified Runtime unavailable: opencode', diff --git a/src/agent-daemon/runtime-bundle-verifier.ts b/src/agent-daemon/runtime-bundle-verifier.ts index 4d7456df..732d418c 100644 --- a/src/agent-daemon/runtime-bundle-verifier.ts +++ b/src/agent-daemon/runtime-bundle-verifier.ts @@ -1,5 +1,6 @@ export { canonicalRuntimeManifestBytes, + loadRegisteredRuntimeBundle, readRemoteRuntimeLock, runtimeManifestSignaturePayload, verifyRuntimeBundle, @@ -8,5 +9,6 @@ export { export type { VerifiedRuntimeBundle, + LoadRegisteredRuntimeBundleOptions, VerifyRuntimeBundleOptions } from '../shared/node/runtime-bundle-verifier' diff --git a/src/agent-daemon/runtime-composition.test.ts b/src/agent-daemon/runtime-composition.test.ts index 5c82a506..b4472a0b 100644 --- a/src/agent-daemon/runtime-composition.test.ts +++ b/src/agent-daemon/runtime-composition.test.ts @@ -37,7 +37,7 @@ afterEach(() => { }) describe('production Runtime composition', () => { - it('keeps ACP live and reloads managed metadata installed after daemon startup', async () => { + it('loads metadata installed after startup and caches the registered Runtime identity', async () => { const fixture = await createRuntimeBundleTestFixture() const root = fixture.root temporaryPaths.push(root) @@ -121,11 +121,8 @@ describe('production Runtime composition', () => { }, null, 2)}\n`, { mode: 0o600 } ) - await expect(protocol.runtimes()).resolves.toEqual([]) - expect(reportError).toHaveBeenCalledWith( - 'Verified Runtime unavailable: opencode', - expect.any(Error) - ) + await expect(protocol.runtimes()).resolves.toHaveLength(1) + expect(reportError).not.toHaveBeenCalled() await expect(protocol.dispose()).resolves.toBeUndefined() events.close() diff --git a/src/agent-daemon/runtime-composition.ts b/src/agent-daemon/runtime-composition.ts index f89b1570..db67be32 100644 --- a/src/agent-daemon/runtime-composition.ts +++ b/src/agent-daemon/runtime-composition.ts @@ -7,6 +7,9 @@ import type { AgentReleaseKeyRegistry } from '../shared/agent-installation-contracts' import type { AgentFrame } from '../shared/agent-protocol' +import type { + RuntimeRegistryEntry +} from '../shared/remote-environment-registry-contracts' import type { RemoteRuntimeLock } from '../shared/remote-runtime-launch-contracts' import type { EventJournal } from './event-journal' import { @@ -22,7 +25,8 @@ import { } from './runtime-bundle-registry' import { readRemoteRuntimeLock, - verifyRuntimeBundle + loadRegisteredRuntimeBundle, + type VerifiedRuntimeBundle } from './runtime-bundle-verifier' import { RuntimeAcpBackend } from './runtime-acp-backend' import type { ProtocolMethodContext } from './protocol-server' @@ -111,37 +115,90 @@ export async function createProductionRuntimeProtocol( } return registry } - const currentVerificationOptions = async () => { - const metadataOptions = - options.filesystemPlatform === undefined - ? {} - : { filesystemPlatform: options.filesystemPlatform } - const [releaseKeyRegistry, runtimeLock] = await Promise.all([ - options.releaseKeyRegistry ?? - readManagedAgentReleaseKeyRegistry( - join(runtimeRoot, 'release-keys.json'), - metadataOptions - ), - options.runtimeLock ?? - readRemoteRuntimeLock( - join(runtimeRoot, 'remote-runtime-lock.json'), - metadataOptions - ) - ]) - return { - architecture: options.architecture, - releaseKeyRegistry, - runtimeLock, - verificationEnvironment, - ...(options.filesystemPlatform === undefined - ? {} - : { filesystemPlatform: options.filesystemPlatform }) - } as const + let verificationOptionsPromise: + | Promise<{ + architecture: AgentArchitecture + releaseKeyRegistry: AgentReleaseKeyRegistry + runtimeLock: RemoteRuntimeLock + verificationEnvironment: 'production' | 'test' + filesystemPlatform?: NodeJS.Platform + }> + | undefined + const currentVerificationOptions = () => { + verificationOptionsPromise ??= (async () => { + const metadataOptions = + options.filesystemPlatform === undefined + ? {} + : { + filesystemPlatform: + options.filesystemPlatform + } + const [releaseKeyRegistry, runtimeLock] = + await Promise.all([ + options.releaseKeyRegistry ?? + readManagedAgentReleaseKeyRegistry( + join(runtimeRoot, 'release-keys.json'), + metadataOptions + ), + options.runtimeLock ?? + readRemoteRuntimeLock( + join( + runtimeRoot, + 'remote-runtime-lock.json' + ), + metadataOptions + ) + ]) + return { + architecture: options.architecture, + releaseKeyRegistry, + runtimeLock, + verificationEnvironment, + ...(options.filesystemPlatform === undefined + ? {} + : { + filesystemPlatform: + options.filesystemPlatform + }) + } + })() + void verificationOptionsPromise.catch(() => { + verificationOptionsPromise = undefined + }) + return verificationOptionsPromise + } + const verifiedRuntimeCache = + new Map>() + const loadRegistered = ( + entry: RuntimeRegistryEntry, + bundleDirectory: string + ): Promise => { + const key = `${bundleDirectory}\0${JSON.stringify(entry)}` + const cached = verifiedRuntimeCache.get(key) + if (cached !== undefined) { + return cached + } + const loading = (async () => + await loadRegisteredRuntimeBundle( + bundleDirectory, + { + ...(await currentVerificationOptions()), + registered: entry + } + ))() + verifiedRuntimeCache.set(key, loading) + void loading.catch(() => { + if (verifiedRuntimeCache.get(key) === loading) { + verifiedRuntimeCache.delete(key) + } + }) + return loading } const verifiedCapabilities = async () => { const source = createVerifiedRuntimeCapabilitySource({ registry: currentRegistry(), ...(await currentVerificationOptions()), + loadRegistered, reportError: options.reportError }) return await source() @@ -182,10 +239,10 @@ export async function createProductionRuntimeProtocol( bundleDigest, options.architecture ), - reverifyRuntimeBundle: async (resolved) => { - const verified = await verifyRuntimeBundle( - resolved.bundleDirectory, - await currentVerificationOptions() + loadRegisteredRuntimeBundle: async (resolved) => { + const verified = await loadRegistered( + resolved.entry, + resolved.bundleDirectory ) if ( verified.manifestDigest !== resolved.entry.manifestDigest || diff --git a/src/main/index.ts b/src/main/index.ts index 9cb6c89b..c180d2b2 100644 --- a/src/main/index.ts +++ b/src/main/index.ts @@ -1260,11 +1260,6 @@ if (hasSingleInstanceLock) { resolver: startupRemoteAgentServices.targetResolver, sshPool: startupRemoteAgentServices.sshPool, agentPackageManager, - agentInstallationManager: - startupRemoteAgentServices.installationManager, - runtimeInstallationManager: - startupManagedRemoteExecutionServices - .runtimeInstallationManager, operationStore: new RemoteEnvironmentOperationStore( app.getPath('userData') diff --git a/src/main/remote-agent/agent-installation-manager.test.ts b/src/main/remote-agent/agent-installation-manager.test.ts index e4850ff4..0b433ec3 100644 --- a/src/main/remote-agent/agent-installation-manager.test.ts +++ b/src/main/remote-agent/agent-installation-manager.test.ts @@ -1,1216 +1,337 @@ -import { - createHash, - generateKeyPairSync, - sign -} from 'node:crypto' -import { - mkdtemp, - mkdir, - readFile, - writeFile -} from 'node:fs/promises' -import { join } from 'node:path' -import { tmpdir } from 'node:os' +import { readFileSync } from 'node:fs' +import { resolve } from 'node:path' import { describe, expect, it, vi } from 'vitest' import type { - AgentBundleManifest, - AgentReleaseKeyRegistry -} from '../../shared/agent-installation-contracts' -import type { - SftpEntryMetadata, - StagedSftp -} from '../ssh/bounded-sftp' -import type { - SshConnectionLease, + AgentDiagnosticResult, SshConnectionPoolTarget } from '../ssh/ssh-connection-pool' import { - agentManifestSignaturePayload, - type VerifiedAgentBundle -} from './agent-bundle-verifier' -import { + AgentInstallationError, AgentInstallationManager } from './agent-installation-manager' -type RemoteEntry = { - type: 'file' | 'directory' | 'symbolic-link' - mode: number - uid: number - contents?: Buffer +const HOST_ID = 'host-1' +const MANIFEST_SHA256 = 'a'.repeat(64) +const INSTALLATION_ID = `agent-${MANIFEST_SHA256}` +const runtimeLock = JSON.parse( + readFileSync( + resolve('agent-runtime-lock.json'), + 'utf8' + ) +) as { + agentVersion: string + protocol: { major: number; minor: number } } -const home = '/home/tester' -const uid = 1000 - -function sha256(contents: Uint8Array): string { - return createHash('sha256').update(contents).digest('hex') -} - -function missing(): Error & { code: number } { - return Object.assign(new Error('missing'), { code: 2 }) -} - -class MemorySftp implements StagedSftp { - readonly stagingDirectory = home - readonly operations: string[] = [] - readonly entries = new Map([ - [home, { type: 'directory', mode: 0o700, uid }] - ]) - corruptReadPath?: string - abortWritePath?: string - abortController?: AbortController - closed = false - - private absolute(path: string): string { - return `${home}/${path}` - } - - private metadata(entry: RemoteEntry): SftpEntryMetadata { - return { - type: entry.type, - size: entry.contents?.byteLength ?? 0, - mode: entry.mode, - uid: entry.uid, - gid: entry.uid, - atime: 1, - mtime: 1 - } - } - - async uploadFile(): Promise { - throw new Error('uploadFile is unused in this fixture') - } - - async mkdir(path: string): Promise { - const absolute = this.absolute(path) - this.operations.push(`mkdir:${path}`) - if (this.entries.has(absolute)) { - throw Object.assign(new Error('exists'), { code: 4 }) - } - this.entries.set(absolute, { - type: 'directory', - mode: 0o700, - uid - }) - } - - async writeFile(path: string, contents: Buffer): Promise { - const absolute = this.absolute(path) - this.operations.push(`write:${path}`) - if (this.entries.has(absolute)) { - throw Object.assign(new Error('exists'), { code: 4 }) - } - this.entries.set(absolute, { - type: 'file', - mode: 0o600, - uid, - contents: Buffer.from(contents) - }) - if (this.abortWritePath === path) { - this.abortController?.abort() - throw this.abortController?.signal.reason - } - } - - async readFile(path: string): Promise { - this.operations.push(`read:${path}`) - const contents = this.entry(path).contents ?? Buffer.alloc(0) - return path === this.corruptReadPath - ? Buffer.from('corrupt') - : Buffer.from(contents) - } - - async lstat(path: string): Promise { - return this.metadata(this.entry(path)) - } - - async stat(path: string): Promise { - const entry = this.entry(path) - if (entry.type === 'symbolic-link') { - throw new Error('symbolic link') - } - return this.metadata(entry) - } - - async chmod(path: string, mode: 0o600 | 0o644 | 0o700 | 0o755): Promise { - this.operations.push(`chmod:${path}:${mode.toString(8)}`) - this.entry(path).mode = mode - } - - async setExecutable(path: string): Promise { - await this.chmod(path, 0o700) - } - - async rename(source: string, destination: string): Promise { - this.operations.push(`rename:${source}:${destination}`) - if (this.entries.has(this.absolute(destination))) { - throw new Error('destination exists') - } - this.moveTree(source, destination) - } - - async replaceFile(source: string, destination: string): Promise { - this.operations.push(`replace:${source}:${destination}`) - const sourceEntry = this.entry(source) - const destinationEntry = this.entries.get(this.absolute(destination)) - if ( - sourceEntry.type !== 'file' || - (destinationEntry && destinationEntry.type !== 'file') - ) { - throw new Error('unsafe replacement') - } - this.entries.delete(this.absolute(destination)) - this.entries.delete(this.absolute(source)) - this.entries.set(this.absolute(destination), sourceEntry) - } - - async hardLink(source: string, destination: string): Promise { - this.operations.push(`link:${source}:${destination}`) - const sourceEntry = this.entry(source) - if (sourceEntry.type !== 'file') { - throw new Error('not file') - } - if (this.entries.has(this.absolute(destination))) { - throw new Error('destination exists') - } - this.entries.set(this.absolute(destination), sourceEntry) - } - - async unlink(path: string): Promise { - this.operations.push(`unlink:${path}`) - const entry = this.entry(path) - if (entry.type !== 'file') { - throw new Error('not file') - } - this.entries.delete(this.absolute(path)) - } - - async rmdir(path: string): Promise { - this.operations.push(`rmdir:${path}`) - const absolute = this.absolute(path) - const entry = this.entry(path) - if (entry.type !== 'directory') { - throw new Error('not directory') - } - if ( - [...this.entries.keys()].some( - (candidate) => candidate.startsWith(`${absolute}/`) - ) - ) { - throw new Error('not empty') - } - this.entries.delete(absolute) - } - - close(): void { - this.closed = true - } - - add(path: string, entry: RemoteEntry): void { - this.entries.set(this.absolute(path), entry) - } - - private entry(path: string): RemoteEntry { - const entry = this.entries.get(this.absolute(path)) - if (!entry) { - throw missing() - } - return entry - } - - private moveTree(source: string, destination: string): void { - const sourceAbsolute = this.absolute(source) - const destinationAbsolute = this.absolute(destination) - const matches = [...this.entries.entries()].filter( - ([path]) => - path === sourceAbsolute || - path.startsWith(`${sourceAbsolute}/`) - ) - if (matches.length === 0) { - throw missing() - } - for (const [path] of matches) { - this.entries.delete(path) - } - for (const [path, entry] of matches) { - this.entries.set( - `${destinationAbsolute}${path.slice(sourceAbsolute.length)}`, - entry - ) - } - } -} - -function target(revision = 1): SshConnectionPoolTarget { +function target(): SshConnectionPoolTarget { return { host: { - id: 'host-1', - name: 'Host', - hostname: 'host.example', + id: HOST_ID, + name: 'Builder', + hostname: 'builder.example', port: 22, - username: 'tester', + username: 'goodbuddy', authentication: 'password', password: 'secret', hostKey: { algorithm: 'ssh-ed25519', - publicKeyBase64: 'AAAA', - fingerprintSha256: `SHA256:${'a'.repeat(43)}`, - generation: revision + publicKeyBase64: 'a2V5', + fingerprintSha256: `SHA256:${'b'.repeat(43)}`, + generation: 2 } }, - hostRevision: revision, - hostKeyGeneration: revision + hostRevision: 3, + hostKeyGeneration: 2 } } -async function bundleFixture(): Promise { - const directory = await mkdtemp(join(tmpdir(), 'agent-manager-')) - const files = [ - { path: 'node', contents: Buffer.from('node'), mode: '0755' as const }, - { - path: 'goodbuddy-agent', - contents: Buffer.from('agent'), - mode: '0755' as const - }, - { - path: 'lib/agent.cjs', - contents: Buffer.from('script'), - mode: '0644' as const - }, - { - path: 'licenses/LICENSE.txt', - contents: Buffer.from('license'), - mode: '0644' as const - } - ] - const manifest: AgentBundleManifest = { - formatVersion: 1, - product: 'GoodBuddy', - agentVersion: '1.0.0', - platform: 'linux', - arch: 'x64', - protocol: { major: 1, minor: 0 }, - signingKeyId: 'test-key', - entrypoint: { - path: 'goodbuddy-agent', - runtimePath: 'node', - scriptPath: 'lib/agent.cjs' - }, - files: files.map((file) => ({ - path: file.path, - size: file.contents.byteLength, - sha256: sha256(file.contents), - mode: file.mode - })), - licenses: [{ - package: 'fixture', - version: '1.0.0', - spdx: 'MIT', - path: 'licenses/LICENSE.txt' - }] - } - for (const file of files) { - const destination = join(directory, ...file.path.split('/')) - await mkdir(join(destination, '..'), { recursive: true }) - await writeFile(destination, file.contents) - } - const manifestBytes = Buffer.from( - `${JSON.stringify(manifest, null, 2)}\n` - ) - await writeFile(join(directory, 'manifest.json'), manifestBytes) - await writeFile(join(directory, 'manifest.sig'), 'fixture-signature\n') - return { - bundleDirectory: directory, - manifest, - manifestSha256: sha256(manifestBytes) - } +function diagnostic( + exitCode = 0, + stderr = '' +): AgentDiagnosticResult { + return { exitCode, stdout: '', stderr } } -function stageEmulatedCandidate( - sftp: MemorySftp, - bundle: VerifiedAgentBundle, - installationId: string -): void { - const path = '.goodbuddy/agent/registry.json' - const persisted = JSON.parse( - sftp.entries.get(`${home}/${path}`)?.contents?.toString('utf8') ?? - '{"formatVersion":1}' - ) as { - current?: Record - } - const current = persisted.current - sftp.add(path, { - type: 'file', - mode: 0o600, - uid, - contents: Buffer.from(`${JSON.stringify({ - formatVersion: 1, - ...(current === undefined - ? {} - : { - current: { - installationId: current.installationId, - agentVersion: current.agentVersion, - manifestSha256: current.manifestSha256, - arch: current.arch - } - }), - candidate: registryEntry(bundle, installationId) - }, null, 2)}\n`) - }) -} - -function promoteEmulatedCandidate( - sftp: MemorySftp, - bundle: VerifiedAgentBundle, - installationId: string -): void { - sftp.add('.goodbuddy/agent/registry.json', { - type: 'file', - mode: 0o600, - uid, - contents: Buffer.from(`${JSON.stringify({ - formatVersion: 1, - current: registryEntry(bundle, installationId) - }, null, 2)}\n`) - }) -} - -function registryEntry( - bundle: VerifiedAgentBundle, - installationId: string -): Record { - return { - installationId, - agentVersion: bundle.manifest.agentVersion, - manifestSha256: bundle.manifestSha256, - arch: bundle.manifest.arch - } -} - -function legacyRegistryBytes(): Buffer { - return Buffer.from(`{ - "formatVersion": 1, - "minimumTrustedReleaseSequence": 7, - "current": { - "installationId": "old-current", - "productVersion": "0.9.0", - "agentVersion": "0.9.0", - "releaseSequence": 7, - "manifestSha256": "${'d'.repeat(64)}", - "binaryDigest": "sha256:${'d'.repeat(64)}", - "arch": "x64", - "protocol": { "major": 1, "minor": 0 }, - "signingKeyId": "old-key", - "previouslyVerified": true - }, - "draining": [] -} -`) -} - -async function waitForGate( - gate: Promise, - signal?: AbortSignal -): Promise { - if (!signal) { - await gate - return - } - signal.throwIfAborted() - await new Promise((resolve, reject) => { - const abort = (): void => { - reject( - signal.reason ?? - new DOMException('The operation was aborted', 'AbortError') - ) - } - signal.addEventListener('abort', abort, { once: true }) - gate.then( - () => { - signal.removeEventListener('abort', abort) - resolve() - }, - (error: unknown) => { - signal.removeEventListener('abort', abort) - reject(error) - } - ) - }) -} - -async function metadataOnlyHarness(options: { - remoteRegistryBytes?: Buffer - remoteReleaseKeyBytes?: Buffer - hostRegistrySubset?: boolean - corruptPath?: string - resolverTargets?: SshConnectionPoolTarget[] - currentAgentVersion?: string - currentNodeContents?: Buffer - trustCurrentSignature?: boolean - agentStopped?: boolean - bootstrapGate?: Promise - publishedLifecycleFailure?: 'bootstrap' | 'health' - emulatePublishedRegistry?: boolean - remoteRegistryAbsent?: boolean - remoteReleaseKeysAbsent?: boolean +function fixture(options: { + registry?: unknown + lifecycle?: ( + action: string, + signal?: AbortSignal + ) => Promise + readRegistry?: () => Promise } = {}) { - const bundle = await bundleFixture() - const keyPair = generateKeyPairSync('ed25519') - const unrelatedKeyPair = generateKeyPairSync('ed25519') - const signedRegistry: AgentReleaseKeyRegistry = { + const calls: string[] = [] + const registry = options.registry ?? { formatVersion: 1, - keys: [ - { - keyId: 'test-key', - publicKeySpkiBase64: keyPair.publicKey.export({ - format: 'der', - type: 'spki' - }).toString('base64'), - environment: 'test' - }, - { - keyId: 'unrelated-new-key', - publicKeySpkiBase64: unrelatedKeyPair.publicKey.export({ - format: 'der', - type: 'spki' - }).toString('base64'), - environment: 'test' - } - ], - revocations: [] + current: { + installationId: INSTALLATION_ID, + agentVersion: runtimeLock.agentVersion, + manifestSha256: MANIFEST_SHA256, + arch: 'x64' + } } - const manifestBytes = await readFile( - join(bundle.bundleDirectory, 'manifest.json') - ) - const candidateSignatureBytes = Buffer.from( - `${sign( - null, - agentManifestSignaturePayload(manifestBytes), - keyPair.privateKey - ).toString('base64')}\n` - ) - await writeFile( - join(bundle.bundleDirectory, 'manifest.sig'), - candidateSignatureBytes - ) - const resourceRoot = await mkdtemp( - join(tmpdir(), 'agent-metadata-only-') - ) - const registryBytes = Buffer.from( - `${JSON.stringify(signedRegistry, null, 2)}\n` - ) - const rootLock = JSON.parse( - await readFile( - join(process.cwd(), 'agent-runtime-lock.json'), - 'utf8' - ) - ) as Record - const runtimeLock = { - ...rootLock, - agentVersion: bundle.manifest.agentVersion, - protocol: bundle.manifest.protocol - } - const runtimeLockBytes = Buffer.from( - `${JSON.stringify(runtimeLock, null, 2)}\n` - ) - const keyRegistryPath = join( - resourceRoot, - 'agent-release-keys.json' - ) - const runtimeLockPath = join( - resourceRoot, - 'agent-runtime-lock.json' - ) - await Promise.all([ - writeFile(keyRegistryPath, registryBytes), - writeFile(runtimeLockPath, runtimeLockBytes) - ]) - - const sftp = new MemorySftp() - const currentManifest: AgentBundleManifest = { - ...bundle.manifest, - agentVersion: - options.currentAgentVersion ?? - bundle.manifest.agentVersion, - files: bundle.manifest.files.map((file) => - file.path === bundle.manifest.entrypoint.runtimePath && - options.currentNodeContents !== undefined - ? { - ...file, - size: options.currentNodeContents.byteLength, - sha256: sha256(options.currentNodeContents) - } - : { ...file } - ) - } - const currentManifestBytes = Buffer.from( - `${JSON.stringify(currentManifest, null, 2)}\n` - ) - const currentManifestSha256 = sha256(currentManifestBytes) - const currentInstallationId = - `agent-${currentManifestSha256}` - const currentSigningKey = options.trustCurrentSignature === false - ? generateKeyPairSync('ed25519').privateKey - : keyPair.privateKey - const currentSignatureBytes = Buffer.from( - `${sign( - null, - agentManifestSignaturePayload(currentManifestBytes), - currentSigningKey - ).toString('base64')}\n` - ) - const installationId = `agent-${bundle.manifestSha256}` - const installationRoot = - `.goodbuddy/agent/installations/${currentInstallationId}` - for (const path of [ - '.goodbuddy', - '.goodbuddy/agent', - '.goodbuddy/agent/installations', - installationRoot, - `${installationRoot}/lib`, - `${installationRoot}/licenses` - ]) { - sftp.add(path, { - type: 'directory', - mode: 0o700, - uid + const readRegistry = + options.readRegistry ?? + vi.fn(async () => Buffer.from(JSON.stringify(registry))) + const lifecycle = + options.lifecycle ?? + vi.fn(async (action: string) => { + calls.push(action) + return diagnostic() }) - } - const persistedRegistry = - options.remoteRegistryBytes ?? - Buffer.from(`${JSON.stringify({ - formatVersion: 1, - current: { - installationId: currentInstallationId, - agentVersion: currentManifest.agentVersion, - manifestSha256: currentManifestSha256, - arch: currentManifest.arch - } - }, null, 2)}\n`) - if (!options.remoteRegistryAbsent) { - sftp.add('.goodbuddy/agent/registry.json', { - type: 'file', - mode: 0o600, - uid, - contents: persistedRegistry - }) - } - if (!options.remoteReleaseKeysAbsent) { - sftp.add('.goodbuddy/agent/release-keys.json', { - type: 'file', - mode: 0o600, - uid, - contents: - options.remoteReleaseKeyBytes ?? - ( - options.hostRegistrySubset - ? Buffer.from(`${JSON.stringify({ - ...signedRegistry, - keys: [signedRegistry.keys[0]] - }, null, 2)}\n`) - : registryBytes - ) - }) - } - for (const file of bundle.manifest.files) { - const contents = await readFile( - join(bundle.bundleDirectory, ...file.path.split('/')) - ) - sftp.add(`${installationRoot}/${file.path}`, { - type: 'file', - mode: file.mode === '0755' ? 0o755 : 0o644, - uid, - contents: - options.corruptPath === file.path - ? Buffer.alloc(contents.byteLength, 0x78) - : file.path === bundle.manifest.entrypoint.runtimePath && - options.currentNodeContents !== undefined - ? options.currentNodeContents - : contents - }) - } - sftp.add(`${installationRoot}/manifest.json`, { - type: 'file', - mode: 0o644, - uid, - contents: currentManifestBytes - }) - sftp.add(`${installationRoot}/manifest.sig`, { - type: 'file', - mode: 0o644, - uid, - contents: - options.corruptPath === 'manifest.sig' - ? Buffer.from(`${'A'.repeat(86)}==\n`) - : currentSignatureBytes - }) - - const lifecycleActions: string[] = [] - let healthCalls = 0 - const release = vi.fn() + const close = vi.fn(() => calls.push('close-sftp')) + const release = vi.fn(() => calls.push('release')) const lease = { identity: { - hostId: 'host-1', - hostRevision: 1, - hostKeyGeneration: 1, - authenticationIdentity: 'b'.repeat(64) + hostId: HOST_ID, + hostRevision: 3, + hostKeyGeneration: 2, + authenticationIdentity: 'c'.repeat(64) }, - isUsable: () => true, - runAgentBootstrapProbe: vi.fn(async (signal?: AbortSignal) => { - if (options.bootstrapGate) { - await waitForGate(options.bootstrapGate, signal) - } - return { + runAgentBootstrapProbe: vi.fn(async () => ({ ready: true, platform: 'linux', architecture: 'x64', - canonicalHomeDirectory: home, - uid, - shell: '/bin/bash', + canonicalHomeDirectory: '/home/goodbuddy', + uid: 1000, + shell: '/bin/sh', procfs: 'ready' - } as const - }), - openStagedSftp: vi.fn(async () => sftp), + })), + openStagedSftp: vi.fn(async () => ({ + lstat: vi.fn(async () => ({ + type: 'file', + size: 256, + mode: 0o600, + uid: 1000, + gid: 1000, + atime: 0, + mtime: 0 + })), + readFile: readRegistry, + close + })), runAgentLifecycleAction: vi.fn( - async (_installationId, action: string) => { - lifecycleActions.push(action) - if ( - options.emulatePublishedRegistry && - action === 'bootstrap' - ) { - stageEmulatedCandidate( - sftp, - { - ...bundle, - manifest: currentManifest, - manifestSha256: currentManifestSha256 - }, - currentInstallationId - ) - } - if (action === 'health') { - healthCalls += 1 - } - const publishedFailure = - options.publishedLifecycleFailure === action - if ( - options.emulatePublishedRegistry && - action === 'health' && - !publishedFailure - ) { - promoteEmulatedCandidate( - sftp, - { - ...bundle, - manifest: currentManifest, - manifestSha256: currentManifestSha256 - }, - currentInstallationId - ) - } - return { - exitCode: - publishedFailure || - ( - action === 'health' && - ( - ( - options.corruptPath === 'node' - ) || - (options.agentStopped === true && healthCalls === 1) - ) - ) - ? 1 - : 0, - stdout: '', - stderr: '' - } - } + async ( + _installationId: string, + action: string, + signal?: AbortSignal + ) => lifecycle(action, signal) ), - release - } as unknown as SshConnectionLease - let resolveCount = 0 - const targets = options.resolverTargets ?? [target()] - const resolver = { - resolve: vi.fn(async () => - targets[Math.min(resolveCount++, targets.length - 1)]! - ) + release, + isUsable: vi.fn(() => true) } + const resolver = { + resolve: vi.fn(async () => target()) + } + const acquire = vi.fn(async () => lease as never) const manager = new AgentInstallationManager({ resolver, - sshPool: { acquire: vi.fn(async () => lease) }, + sshPool: { acquire }, resourcePaths: { - keyRegistryPath, - runtimeLockPath, + runtimeLockPath: resolve('agent-runtime-lock.json'), + keyRegistryPath: resolve( + 'resources', + 'agent-release-keys.json' + ), bundleDirectories: { - x64: join(resourceRoot, 'missing-x64'), - arm64: join(resourceRoot, 'missing-arm64') + x64: resolve('.agent-resources', 'linux-x64'), + arm64: resolve('.agent-resources', 'linux-arm64') } - }, - verificationEnvironment: 'test' + } }) return { manager, - bundle, - installationId, - currentInstallationId, - publishedIdentity: { - installationId: currentInstallationId, - agentVersion: currentManifest.agentVersion, - manifestSha256: currentManifestSha256, - binaryDigest: `sha256:${currentManifestSha256}`, - platform: 'linux' as const, - architecture: currentManifest.arch, - protocol: { ...currentManifest.protocol }, - supervisor: 'detached-on-demand' as const - }, - lifecycleActions, + calls, resolver, - sftp, + acquire, + lease, + lifecycle, + readRegistry, + close, release } } describe('AgentInstallationManager', () => { - it('cryptographically reuses an exact current Host Agent when bundle resources are absent', async () => { - const fixture = await metadataOnlyHarness() + it('activates the registered Agent with one metadata read and one health command', async () => { + const value = fixture() + const progress: string[] = [] - await expect( - fixture.manager.activateInstalled('host-1') - ).resolves.toMatchObject({ - installationId: fixture.installationId, - agentVersion: fixture.bundle.manifest.agentVersion, + await expect(value.manager.activateInstalled( + HOST_ID, + { onProgress: (phase) => progress.push(phase) } + )).resolves.toMatchObject({ + installationId: INSTALLATION_ID, + binaryDigest: `sha256:${MANIFEST_SHA256}`, + agentVersion: runtimeLock.agentVersion, + protocol: runtimeLock.protocol, architecture: 'x64' }) - expect(fixture.lifecycleActions).toEqual(['health']) - expect( - fixture.sftp.operations.some((operation) => - operation.startsWith('write:') + expect(value.readRegistry).toHaveBeenCalledOnce() + expect(value.lease.runAgentLifecycleAction) + .toHaveBeenCalledWith( + INSTALLATION_ID, + 'health', + expect.any(AbortSignal) ) - ).toBe(false) - expect(fixture.release).toHaveBeenCalledOnce() - }) - - it('reuses the current Agent identity until the Host is invalidated', async () => { - const fixture = await metadataOnlyHarness() - - const first = await fixture.manager.activateInstalled('host-1') - await expect( - fixture.manager.activateInstalled('host-1') - ).resolves.toEqual(first) - expect(fixture.lifecycleActions).toEqual(['health']) - expect(fixture.release).toHaveBeenCalledOnce() - - fixture.manager.invalidateHost('host-1') - await expect( - fixture.manager.activateInstalled('host-1') - ).resolves.toEqual(first) - expect(fixture.lifecycleActions).toEqual(['health', 'health']) - expect(fixture.release).toHaveBeenCalledTimes(2) - }) - - it('activates an exact installed Agent without loading or publishing installable payloads', async () => { - const fixture = await metadataOnlyHarness({}) - - await expect( - fixture.manager.activateInstalled('host-1') - ).resolves.toMatchObject({ - installationId: fixture.currentInstallationId, - architecture: 'x64' - }) - - expect(fixture.lifecycleActions).toEqual(['health']) - expect( - fixture.sftp.operations.filter((operation) => - /^(?:mkdir|write|chmod|rename|replace|link|unlink|rmdir):/u - .test(operation) - ) - ).toEqual([]) - }) - - it('bootstraps a stopped installed Agent without SFTP mutation', async () => { - const fixture = await metadataOnlyHarness({ - agentStopped: true - }) - - await expect( - fixture.manager.activateInstalled('host-1') - ).resolves.toMatchObject({ - installationId: fixture.currentInstallationId - }) - - expect(fixture.lifecycleActions).toEqual([ + expect(value.calls).toEqual([ + 'close-sftp', 'health', - 'bootstrap', - 'health' + 'release' + ]) + expect(progress).toEqual([ + 'inspecting-host', + 'verifying-bundle', + 'checking-health', + 'complete' ]) - expect( - fixture.sftp.operations.filter((operation) => - /^(?:mkdir|write|chmod|rename|replace|link|unlink|rmdir):/u - .test(operation) - ) - ).toEqual([]) }) - it('adopts the exact package-published Agent without loading or mutating payloads', async () => { - const fixture = await metadataOnlyHarness({}) - - await expect( - fixture.manager.activatePublished( - 'host-1', - fixture.publishedIdentity - ) - ).resolves.toMatchObject({ - installationId: fixture.currentInstallationId, - agentVersion: fixture.bundle.manifest.agentVersion, - architecture: 'x64' - }) - - expect(fixture.lifecycleActions).toEqual([ - 'bootstrap', - 'health' - ]) - expect( - fixture.sftp.operations.filter((operation) => - /^(?:mkdir|write|chmod|rename|replace|link|unlink|rmdir):/u - .test(operation) - ) - ).toEqual([]) - }) - - it('adopts a package-published Agent when all global Agent metadata is absent', async () => { - const fixture = await metadataOnlyHarness({ - remoteRegistryAbsent: true, - remoteReleaseKeysAbsent: true - }) - - await expect( - fixture.manager.activatePublished( - 'host-1', - fixture.publishedIdentity - ) - ).resolves.toMatchObject({ - installationId: fixture.currentInstallationId, - architecture: 'x64' - }) - - expect(fixture.lifecycleActions).toEqual([ - 'bootstrap', - 'health' - ]) - expect( - fixture.sftp.entries.get( - `${home}/.goodbuddy/agent/release-keys.json` - )?.contents - ).toBeDefined() - expect( - fixture.sftp.entries.has( - `${home}/.goodbuddy/agent/registry.json` - ) - ).toBe(false) - }) - - it('verifies a published Agent with packaged trust instead of stale Host keys', async () => { - const fixture = await metadataOnlyHarness({ - remoteReleaseKeyBytes: Buffer.from( - '{"formatVersion":1,"keys":[],"revocations":[]}\n' + it('uses bootstrap readiness as the recovery proof without a second health command', async () => { + const value = fixture({ + lifecycle: vi.fn(async (action: string) => + action === 'health' + ? diagnostic(1, 'not running') + : diagnostic() ) }) await expect( - fixture.manager.activatePublished( - 'host-1', - fixture.publishedIdentity - ) - ).resolves.toMatchObject({ - installationId: fixture.currentInstallationId - }) - expect(fixture.lifecycleActions).toEqual([ - 'bootstrap', - 'health' - ]) + value.manager.activateInstalled(HOST_ID) + ).resolves.toBeDefined() + expect(value.lease.runAgentLifecycleAction.mock.calls.map( + (call) => call[1] + )).toEqual(['health', 'bootstrap']) }) - it('rejects a package-published Agent identity mismatch before activation', async () => { - const fixture = await metadataOnlyHarness() + it('returns its cached identity until the Host is invalidated', async () => { + const value = fixture() - await expect( - fixture.manager.activatePublished('host-1', { - ...fixture.publishedIdentity, - agentVersion: '9.9.9' + const first = await value.manager.activateInstalled(HOST_ID) + const second = await value.manager.activateInstalled(HOST_ID) + expect(second).toEqual(first) + expect(value.acquire).toHaveBeenCalledOnce() + + value.manager.invalidateHost(HOST_ID) + await value.manager.activateInstalled(HOST_ID) + expect(value.acquire).toHaveBeenCalledTimes(2) + }) + + it('deduplicates concurrent activation for the same Host', async () => { + let releaseRead!: () => void + const readGate = new Promise((resolveRead) => { + releaseRead = resolveRead + }) + const value = fixture({ + readRegistry: vi.fn(async () => { + await readGate + return Buffer.from(JSON.stringify({ + formatVersion: 1, + current: { + installationId: INSTALLATION_ID, + agentVersion: runtimeLock.agentVersion, + manifestSha256: MANIFEST_SHA256, + arch: 'x64' + } + })) }) - ).rejects.toMatchObject({ reason: 'corrupt' }) - - expect(fixture.lifecycleActions).toEqual(['stop']) - }) - - it('does not transfer installer-verified Agent payloads back through SFTP', async () => { - const fixture = await metadataOnlyHarness() - - await expect( - fixture.manager.activatePublished( - 'host-1', - fixture.publishedIdentity - ) - ).resolves.toMatchObject({ - installationId: fixture.currentInstallationId }) - expect(fixture.lifecycleActions).toEqual([ - 'bootstrap', - 'health' - ]) - for (const file of fixture.bundle.manifest.files) { - expect(fixture.sftp.operations).not.toContain( - `read:.goodbuddy/agent/installations/` + - `${fixture.currentInstallationId}/${file.path}` - ) - } + const first = value.manager.activateInstalled(HOST_ID) + const second = value.manager.activateInstalled(HOST_ID) + releaseRead() + await expect(Promise.all([first, second])).resolves.toHaveLength(2) + expect(value.acquire).toHaveBeenCalledOnce() }) - it('rejects package-published Agent adoption after Host identity changes', async () => { - const fixture = await metadataOnlyHarness({ - resolverTargets: [target(), target(2)] + it('rejects incompatible registry identity before lifecycle activation', async () => { + const value = fixture({ + registry: { + formatVersion: 1, + current: { + installationId: INSTALLATION_ID, + agentVersion: '0.0.1', + manifestSha256: MANIFEST_SHA256, + arch: 'x64' + } + } }) await expect( - fixture.manager.activatePublished( - 'host-1', - fixture.publishedIdentity - ) + value.manager.activateInstalled(HOST_ID) ).rejects.toMatchObject({ - reason: 'host-identity-changed' + reason: 'incompatible' }) - - expect(fixture.lifecycleActions).toEqual(['stop']) + expect(value.lifecycle).not.toHaveBeenCalled() }) - it('stops a failed package-published Agent and restores registry bytes exactly', async () => { - const oldRegistry = legacyRegistryBytes() - const oldReleaseKeys = Buffer.from( - '{ "legacy": "release keys", "spacing": true }\n' - ) - const fixture = await metadataOnlyHarness({ - remoteRegistryBytes: oldRegistry, - remoteReleaseKeyBytes: oldReleaseKeys, - publishedLifecycleFailure: 'health', - emulatePublishedRegistry: true + it('accepts a newer independently published Agent with a compatible registered protocol', async () => { + const value = fixture({ + registry: { + formatVersion: 1, + current: { + installationId: INSTALLATION_ID, + agentVersion: '99.0.0', + manifestSha256: MANIFEST_SHA256, + arch: 'x64', + protocol: runtimeLock.protocol + } + } }) await expect( - fixture.manager.activatePublished( - 'host-1', - fixture.publishedIdentity - ) - ).rejects.toMatchObject({ reason: 'lifecycle' }) - - expect(fixture.lifecycleActions).toEqual([ - 'bootstrap', - 'health', - 'stop' - ]) - expect( - fixture.sftp.entries.get( - `${home}/.goodbuddy/agent/registry.json` - )?.contents - ).toEqual(oldRegistry) - expect( - fixture.sftp.entries.get( - `${home}/.goodbuddy/agent/release-keys.json` - )?.contents - ).toEqual(oldReleaseKeys) - }) - - it('stops a failed package-published Agent and restores global metadata absence', async () => { - const fixture = await metadataOnlyHarness({ - remoteRegistryAbsent: true, - remoteReleaseKeysAbsent: true, - publishedLifecycleFailure: 'health', - emulatePublishedRegistry: true - }) - - await expect( - fixture.manager.activatePublished( - 'host-1', - fixture.publishedIdentity - ) - ).rejects.toMatchObject({ reason: 'lifecycle' }) - - expect(fixture.lifecycleActions).toEqual([ - 'bootstrap', - 'health', - 'stop' - ]) - expect( - fixture.sftp.entries.has( - `${home}/.goodbuddy/agent/registry.json` - ) - ).toBe(false) - expect( - fixture.sftp.entries.has( - `${home}/.goodbuddy/agent/release-keys.json` - ) - ).toBe(false) - }) - - it('reuses a canonical older Host key subset containing the current signing key', async () => { - const fixture = await metadataOnlyHarness({ - hostRegistrySubset: true - }) - - await expect( - fixture.manager.activateInstalled('host-1') + value.manager.activateInstalled(HOST_ID) ).resolves.toMatchObject({ - installationId: fixture.installationId, - architecture: 'x64' + agentVersion: '99.0.0', + protocol: runtimeLock.protocol }) - expect(fixture.lifecycleActions).toEqual(['health']) }) - it('classifies an old Agent as incompatible before reading differing Host key bytes', async () => { - const fixture = await metadataOnlyHarness({ - currentAgentVersion: '0.9.0', - remoteReleaseKeyBytes: Buffer.from( - '{\n "formatVersion": 1,\n "keys": [],\n "revocations": []\n}\n' + it('preserves bounded lifecycle diagnostics', async () => { + const value = fixture({ + lifecycle: vi.fn(async (action: string) => + action === 'health' + ? diagnostic(1) + : diagnostic(2, 'entrypoint permission denied') ) }) await expect( - fixture.manager.activateInstalled('host-1') + value.manager.activateInstalled(HOST_ID) ).rejects.toMatchObject({ - reason: 'incompatible', + reason: 'lifecycle', message: expect.stringContaining( - 'lacks matching Agent installation resources' + 'entrypoint permission denied' ) }) - expect(fixture.sftp.operations).not.toContain( - 'read:.goodbuddy/agent/release-keys.json' - ) - expect(fixture.lifecycleActions).toEqual([]) }) - it('rejects a lock-matching Agent when the Host registry lacks its signing key', async () => { - const fixture = await metadataOnlyHarness({ - remoteReleaseKeyBytes: Buffer.from( - '{"formatVersion":1,"keys":[],"revocations":[]}\n' - ) + it('disposes active work and rejects future activation', async () => { + let releaseRead!: () => void + const readGate = new Promise((resolveRead) => { + releaseRead = resolveRead }) + const value = fixture({ + readRegistry: vi.fn(async () => { + await readGate + return Buffer.from('{}') + }) + }) + const active = value.manager.activateInstalled(HOST_ID) + const disposing = value.manager.dispose() + releaseRead() + await active.catch(() => undefined) + await disposing await expect( - fixture.manager.activateInstalled('host-1') - ).rejects.toMatchObject({ reason: 'corrupt' }) - expect(fixture.lifecycleActions).toEqual([]) + value.manager.activateInstalled(HOST_ID) + ).rejects.toThrow('disposed') }) - it('keeps a lock-matching Agent with an invalid signature classified as corrupt', async () => { - const fixture = await metadataOnlyHarness({ - corruptPath: 'manifest.sig' - }) - + it('classifies malformed registered state as corrupt', async () => { + const value = fixture({ registry: { formatVersion: 1 } }) await expect( - fixture.manager.activateInstalled('host-1') - ).rejects.toMatchObject({ reason: 'corrupt' }) - expect(fixture.lifecycleActions).toEqual([]) - }) - - it.each(['lib/agent.cjs'])( - 'rejects metadata-only Agent reuse when %s is corrupt', - async (corruptPath) => { - const fixture = await metadataOnlyHarness({ corruptPath }) - - await expect( - fixture.manager.activateInstalled('host-1') - ).rejects.toMatchObject({ reason: 'corrupt' }) - expect(fixture.lifecycleActions).toEqual([]) - } - ) - - it('delegates the large Node runtime hash check to Agent health', async () => { - const fixture = await metadataOnlyHarness({ - corruptPath: 'node' - }) - - await expect( - fixture.manager.activateInstalled('host-1') - ).rejects.toMatchObject({ reason: 'lifecycle' }) - expect(fixture.lifecycleActions).toEqual([ - 'health', - 'bootstrap', - 'health' - ]) - }) - - it('rejects metadata-only Agent reuse after Host identity changes', async () => { - const fixture = await metadataOnlyHarness({ - resolverTargets: [target(), target(2)] - }) - - await expect( - fixture.manager.activateInstalled('host-1') - ).rejects.toMatchObject({ - reason: 'host-identity-changed' - }) - expect(fixture.lifecycleActions).toEqual([]) - }) - - it('deduplicates installed activation and lets one waiter cancel', async () => { - let releaseGate!: () => void - const gate = new Promise((resolve) => { - releaseGate = resolve - }) - const fixture = await metadataOnlyHarness({ bootstrapGate: gate }) - const controller = new AbortController() - const canceled = fixture.manager.activateInstalled('host-1', { - signal: controller.signal - }) - const survivor = fixture.manager.activateInstalled('host-1') - await vi.waitFor(() => - expect(fixture.resolver.resolve).toHaveBeenCalledTimes(2) - ) - - controller.abort() - await expect(canceled).rejects.toMatchObject({ name: 'AbortError' }) - releaseGate() - await expect(survivor).resolves.toMatchObject({ - installationId: fixture.currentInstallationId - }) - expect(fixture.lifecycleActions).toEqual(['health']) - expect(fixture.release).toHaveBeenCalledOnce() - }) - - it('cancels installed activation when its final waiter leaves', async () => { - const fixture = await metadataOnlyHarness({ - bootstrapGate: new Promise(() => undefined) - }) - const controller = new AbortController() - const activation = fixture.manager.activateInstalled('host-1', { - signal: controller.signal - }) - await vi.waitFor(() => - expect(fixture.resolver.resolve).toHaveBeenCalledOnce() - ) - - controller.abort() - await expect(activation).rejects.toMatchObject({ name: 'AbortError' }) - await vi.waitFor(() => expect(fixture.release).toHaveBeenCalledOnce()) - }) - - it('dispose aborts active activation and rejects future calls', async () => { - const fixture = await metadataOnlyHarness({ - bootstrapGate: new Promise(() => undefined) - }) - const activation = fixture.manager.activateInstalled('host-1') - await vi.waitFor(() => - expect(fixture.resolver.resolve).toHaveBeenCalledOnce() - ) - - const first = fixture.manager.dispose() - expect(fixture.manager.dispose()).toBe(first) - await expect(activation).rejects.toMatchObject({ name: 'AbortError' }) - await first - await expect( - fixture.manager.activateInstalled('host-1') - ).rejects.toThrow('Agent installation manager is disposed') + value.manager.activateInstalled(HOST_ID) + ).rejects.toBeInstanceOf(AgentInstallationError) }) }) diff --git a/src/main/remote-agent/agent-installation-manager.ts b/src/main/remote-agent/agent-installation-manager.ts index 2249547b..54c6c041 100644 --- a/src/main/remote-agent/agent-installation-manager.ts +++ b/src/main/remote-agent/agent-installation-manager.ts @@ -1,12 +1,9 @@ -import { createHash, randomUUID } from 'node:crypto' -import { - type AgentArchitecture, - type AgentBundleManifest -} from '../../shared/agent-installation-contracts' +import type { AgentArchitecture } from '../../shared/agent-installation-contracts' import type { AgentBootstrapIncompatibleReason } from '../../shared/ssh-host-contracts' +import { + parseInstallationRegistryState +} from '../../shared/remote-environment-registry-contracts' import type { - BoundedSftpLimits, - SftpEntryMetadata, StagedSftp } from '../ssh/bounded-sftp' import { @@ -14,46 +11,28 @@ import { type VerifiedAgentInstallationId } from '../ssh/ssh-agent-command' import type { + AgentDiagnosticResult, SshConnectionLease, SshConnectionPool, SshConnectionPoolTarget } from '../ssh/ssh-connection-pool' -import type { - SshRemotePackageAgentIdentity -} from '../ssh/ssh-remote-package-bootstrap' -import { - parseInstallationRegistryState -} from '../../shared/remote-environment-registry-contracts' import type { BundledAgentResourcePaths } from './bundled-agent-resources' import { - assertAgentManifestMatchesRuntimeLock, - canonicalAgentReleaseKeyRegistryBytes, - parseAgentReleaseKeyRegistryBytes, - readAgentReleaseKeyRegistry, - readAgentRuntimeLock, - verifyAgentManifestSignature, - type AgentVerificationEnvironment, - type VerifiedAgentBundle + readAgentRuntimeLock } from './agent-bundle-verifier' -import { settleBoundedly } from './bounded-settlement' +import { boundedDiagnostic } from './bounded-diagnostic' +import { HostActivationCoordinator } from './host-activation-coordinator' import { isMissingPathError } from './path-errors' import { remoteHostTargetIdentityKey } from './remote-host-target-identity' -const MAXIMUM_INSTALLATION_FILES = 300 -const MAXIMUM_INSTALLATION_BYTES = 512 * 1024 * 1024 -const MAXIMUM_AGENT_FILE_BYTES = 256 * 1024 * 1024 -const METADATA_MODE = 0o644 const PRIVATE_FILE_MODE = 0o600 -const PRIVATE_DIRECTORY_MODE = 0o700 -const DISPOSE_WAIT_TIMEOUT_MS = 5_000 -const AGENT_REGISTRY_PATH = '.goodbuddy/agent/registry.json' -const RELEASE_KEYS_PATH = '.goodbuddy/agent/release-keys.json' const MAXIMUM_METADATA_BYTES = 1024 * 1024 +const AGENT_REGISTRY_PATH = '.goodbuddy/agent/registry.json' +const MAXIMUM_DIAGNOSTIC_CHARACTERS = 800 export type AgentInstallationPhase = | 'inspecting-host' | 'verifying-bundle' - | 'starting-agent' | 'checking-health' | 'complete' @@ -79,9 +58,6 @@ export type AgentActivationRequestOptions = { onProgress?: (phase: AgentInstallationPhase) => void } -export type PublishedAgentInstallationIdentity = - SshRemotePackageAgentIdentity - export class AgentInstallationError extends Error { constructor( message: string, @@ -98,313 +74,99 @@ export class AgentInstallationError extends Error { } } -type ActiveInstallation = { - promise: Promise - controller: AbortController - progressCallbacks: Set<(phase: AgentInstallationPhase) => void> - waiters: number - settled: boolean -} - -type CleanupEntry = { - path: string - type: 'file' | 'directory' -} - -type ManagedFileSnapshot = { - path: string - contents: Buffer | undefined - uid: number -} - export class AgentInstallationManager { readonly #resolver: AgentInstallationTargetResolver readonly #sshPool: Pick readonly #resourcePaths: BundledAgentResourcePaths - readonly #verificationEnvironment: AgentVerificationEnvironment - readonly #sftpLimits?: BoundedSftpLimits - readonly #maximumConcurrentHosts: number - readonly #active = new Map() - readonly #current = new Map< - string, - { targetKey: string; identity: AgentInstallationIdentity } - >() - readonly #cacheGenerations = new Map() - #closed = false - #disposePromise: Promise | undefined + readonly #coordinator: HostActivationCoordinator< + AgentInstallationIdentity, + AgentInstallationPhase + > constructor(options: { resolver: AgentInstallationTargetResolver sshPool: Pick resourcePaths: BundledAgentResourcePaths - verificationEnvironment?: AgentVerificationEnvironment - sftpLimits?: BoundedSftpLimits maximumConcurrentHosts?: number }) { this.#resolver = options.resolver this.#sshPool = options.sshPool this.#resourcePaths = options.resourcePaths - this.#verificationEnvironment = - options.verificationEnvironment ?? 'production' - this.#sftpLimits = options.sftpLimits - this.#maximumConcurrentHosts = - options.maximumConcurrentHosts ?? 8 - if ( - !Number.isSafeInteger(this.#maximumConcurrentHosts) || - this.#maximumConcurrentHosts <= 0 || - this.#maximumConcurrentHosts > 32 - ) { - throw new Error('Agent installation concurrency limit is invalid') - } + this.#coordinator = new HostActivationCoordinator({ + maximumConcurrentHosts: + options.maximumConcurrentHosts, + capacityError: () => + new AgentInstallationError( + 'Too many Agent activations are already running', + 'capacity' + ), + disposeMessage: + 'Agent installation manager is disposed' + }) } /** - * Verifies and starts the exact Agent selected by packaged trust metadata. - * This path never loads an installable Agent bundle or mutates SFTP state. + * Loads the current registered Agent identity and asks the Host Agent to + * prove process health. Payload verification stays on the Host and is only + * repeated when an unregistered installation is bootstrapped. */ async activateInstalled( hostId: string, options: AgentActivationRequestOptions = {} ): Promise { - return this.#request(hostId, 'activate', options) - } - - /** - * Adopts an exact Agent directory already published by the authenticated - * package installer. Packaged trust verifies the remote contents before - * canonical metadata and fixed lifecycle actions promote the candidate. - */ - async activatePublished( - hostId: string, - expectedIdentity: PublishedAgentInstallationIdentity, - options: AgentActivationRequestOptions = {} - ): Promise { - assertPublishedAgentIdentity(expectedIdentity) - return this.#request( + this.#coordinator.assertAvailable() + options.signal?.throwIfAborted() + emitProgress(options.onProgress, 'inspecting-host') + const earlyCached = + this.#coordinator.cachedForHost(hostId, '') + if (earlyCached !== undefined) { + emitProgress(options.onProgress, 'complete') + return earlyCached + } + const target = await this.#resolver.resolve(hostId) + this.#coordinator.assertAvailable() + options.signal?.throwIfAborted() + if (target.host.id !== hostId) { + throw new Error( + 'Resolved SSH host does not match the request' + ) + } + const targetKey = remoteHostTargetIdentityKey(target) + const cached = this.#coordinator.cached( hostId, - 'adopt', - options, - expectedIdentity + targetKey, + '' ) + if (cached !== undefined) { + emitProgress(options.onProgress, 'complete') + return cached + } + return this.#coordinator.run({ + hostId, + targetKey, + variantKey: '', + signal: options.signal, + onProgress: options.onProgress, + operation: (signal, progress) => + this.#activate(target, signal, progress) + }) } invalidateHost(hostId: string): void { - this.#current.delete(hostId) - this.#cacheGenerations.set( - hostId, - (this.#cacheGenerations.get(hostId) ?? 0) + 1 - ) - } - - async #request( - hostId: string, - mode: 'activate' | 'adopt', - options: AgentActivationRequestOptions, - expectedIdentity?: PublishedAgentInstallationIdentity - ): Promise { - this.#throwIfClosed() - options.signal?.throwIfAborted() - if (options.onProgress) { - try { - options.onProgress('inspecting-host') - } catch { - // Progress observers cannot alter the installation outcome. - } - } - const target = await this.#resolver.resolve(hostId) - this.#throwIfClosed() - options.signal?.throwIfAborted() - if (target.host.id !== hostId) { - throw new Error('Resolved SSH host does not match the request') - } - const targetKey = remoteHostTargetIdentityKey(target) - const cacheGeneration = - this.#cacheGenerations.get(hostId) ?? 0 - if (mode === 'activate') { - const current = this.#current.get(hostId) - if (current?.targetKey === targetKey) { - try { - options.onProgress?.('complete') - } catch { - // Progress observers cannot alter the cached result. - } - return current.identity - } - } - const operationKey = mode === 'adopt' - ? `${mode}:${targetKey}:${publishedAgentIdentityKey( - expectedIdentity! - )}` - : `${mode}:${targetKey}` - const existing = this.#active.get(operationKey) - if (existing) { - return this.#waitForActive(existing, options) - } - if (this.#active.size >= this.#maximumConcurrentHosts) { - throw new AgentInstallationError( - 'Too many Agent installations are already running', - 'capacity' - ) - } - const progressCallbacks = new Set< - (phase: AgentInstallationPhase) => void - >() - if (options.onProgress) { - progressCallbacks.add(options.onProgress) - } - const emitProgress = (phase: AgentInstallationPhase): void => { - for (const callback of progressCallbacks) { - try { - callback(phase) - } catch { - // Progress observers cannot alter the installation outcome. - } - } - } - const controller = new AbortController() - const promise = (mode === 'activate' - ? this.#activateInstalled( - target, - controller.signal, - emitProgress - ) - : this.#activatePublished( - target, - expectedIdentity!, - controller.signal, - emitProgress - )).then((identity) => { - if ( - mode === 'activate' && - (this.#cacheGenerations.get(hostId) ?? 0) === - cacheGeneration - ) { - this.#current.set(hostId, { targetKey, identity }) - } - return identity - }) - const active = { - promise, - controller, - progressCallbacks, - waiters: 0, - settled: false - } - this.#active.set(operationKey, active) - void promise.finally(() => { - active.settled = true - if (this.#active.get(operationKey) === active) { - this.#active.delete(operationKey) - } - }).catch(() => undefined) - return this.#waitForActive(active, options) + this.#coordinator.invalidate(hostId) } dispose(): Promise { - if (this.#disposePromise) { - return this.#disposePromise - } - this.#closed = true - this.#current.clear() - this.#cacheGenerations.clear() - const operations = [...this.#active.values()] - const reason = new DOMException( - 'Agent installation manager was disposed', - 'AbortError' - ) - for (const operation of operations) { - operation.controller.abort(reason) - } - this.#disposePromise = settleBoundedly( - operations.map((operation) => operation.promise), - DISPOSE_WAIT_TIMEOUT_MS - ) - return this.#disposePromise + return this.#coordinator.dispose() } - #throwIfClosed(): void { - if (this.#closed) { - throw new Error('Agent installation manager is disposed') - } - } - - async #waitForActive( - active: ActiveInstallation, - options: AgentActivationRequestOptions - ): Promise { - active.waiters += 1 - if (options.onProgress) { - active.progressCallbacks.add(options.onProgress) - } - try { - return await waitForOperation( - active.promise, - options.signal - ) - } finally { - if (options.onProgress) { - active.progressCallbacks.delete(options.onProgress) - } - active.waiters -= 1 - if ( - active.waiters === 0 && - !active.settled && - !active.controller.signal.aborted - ) { - active.controller.abort( - new DOMException( - 'Agent installation has no remaining waiters', - 'AbortError' - ) - ) - } - } - } - - async #activateInstalled( + async #activate( target: SshConnectionPoolTarget, signal: AbortSignal, progress: (phase: AgentInstallationPhase) => void - ): Promise { - let lease: SshConnectionLease | undefined - try { - lease = await this.#sshPool.acquire(target, signal) - assertLeaseMatchesTarget(lease, target) - const probe = await lease.runAgentBootstrapProbe(signal) - if (!probe.ready) { - throw new AgentInstallationError( - `Remote host cannot run the GoodBuddy Agent: ${probe.reason}`, - 'incompatible', - probe.reason - ) - } - progress('verifying-bundle') - const identity = await this.#reuseInstalledBundle( - target, - lease, - probe, - signal - ) - progress('complete') - return identity - } finally { - lease?.release() - } - } - - async #activatePublished( - target: SshConnectionPoolTarget, - expected: PublishedAgentInstallationIdentity, - signal: AbortSignal, - progress: (phase: AgentInstallationPhase) => void ): Promise { let lease: SshConnectionLease | undefined let sftp: StagedSftp | undefined - let registrySnapshots: readonly ManagedFileSnapshot[] | undefined - const cleanup: CleanupEntry[] = [] - const installationId = verifyAgentInstallationId( - expected.installationId - ) try { lease = await this.#sshPool.acquire(target, signal) assertLeaseMatchesTarget(lease, target) @@ -416,353 +178,107 @@ export class AgentInstallationManager { probe.reason ) } - if ( - expected.platform !== 'linux' || - expected.architecture !== probe.architecture - ) { - throw new AgentInstallationError( - 'Published Agent does not match the Host platform or architecture', - 'incompatible' - ) - } - progress('verifying-bundle') - const [registry, runtimeLock] = await Promise.all([ - readAgentReleaseKeyRegistry( - this.#resourcePaths.keyRegistryPath - ), - readAgentRuntimeLock(this.#resourcePaths.runtimeLockPath) - ]) - const canonicalRegistryBytes = - canonicalAgentReleaseKeyRegistryBytes(registry) + const runtimeLock = await readAgentRuntimeLock( + this.#resourcePaths.runtimeLockPath + ) sftp = await lease.openStagedSftp( - probe.canonicalHomeDirectory, - { - maximumFileBytes: Math.max( - MAXIMUM_AGENT_FILE_BYTES, - this.#sftpLimits?.maximumFileBytes ?? 0 - ), - maximumTotalBytes: Math.max( - MAXIMUM_INSTALLATION_BYTES + - MAXIMUM_METADATA_BYTES * 4, - this.#sftpLimits?.maximumTotalBytes ?? 0 - ), - maximumOperations: - this.#sftpLimits?.maximumOperations ?? 2_048, - operationTimeoutMs: - this.#sftpLimits?.operationTimeoutMs - }, - signal - ) - const destination = - `.goodbuddy/agent/installations/${installationId}` - const manifestBytes = await sftp.readFile( - `${destination}/manifest.json`, - signal - ) - const signatureFile = await sftp.readFile( - `${destination}/manifest.sig`, - signal - ) - const signatureBytes = decodeDetachedSignature( - signatureFile, - 'Agent detached signature' - ) - const manifest = verifyAgentManifestSignature( - manifestBytes, - signatureBytes, - registry, - this.#verificationEnvironment - ) - assertAgentManifestMatchesRuntimeLock( - manifest, - runtimeLock, - probe.architecture - ) - const bundle: VerifiedAgentBundle = { - bundleDirectory: destination, - manifest, - manifestSha256: sha256(manifestBytes) - } - assertPublishedAgentMatches(expected, bundle) - assertBundleCapacity( - manifest, - canonicalRegistryBytes.byteLength - ) - // The fixed SSH installer has already verified the complete published - // tree against this signed manifest. Adoption rechecks its immutable - // identity and metadata without transferring the payload back to Main. - await verifyRemoteInstallationFromMetadata( - sftp, - destination, - bundle, - manifestBytes, - signatureFile, - probe.uid, - false, - signal - ) - registrySnapshots = await snapshotManagedRegistries( - sftp, - probe.uid, - signal - ) - await installReleaseKeyRegistry( - sftp, - canonicalRegistryBytes, - probe.uid, - cleanup, - signal - ) - const currentTarget = await this.#resolver.resolve( - target.host.id - ) - if ( - remoteHostTargetIdentityKey(currentTarget) !== - remoteHostTargetIdentityKey(target) - ) { - throw new AgentInstallationError( - 'SSH host identity changed before Agent adoption', - 'host-identity-changed' - ) - } - - progress('starting-agent') - await expectLifecycleSuccess( - lease, - installationId, - 'bootstrap', - signal - ) - progress('checking-health') - await expectLifecycleSuccess( - lease, - installationId, - 'health', - signal - ) - progress('complete') - return publicIdentity(installationId, bundle) - } catch (error) { - if (lease) { - await stopFailedCandidate(lease, installationId) - } - if (registrySnapshots && sftp) { - await restoreManagedRegistries( - sftp, - registrySnapshots - ).catch((rollbackError: unknown) => { - throw new AggregateError( - [error, rollbackError], - 'Published Agent activation failed and its previous metadata state could not be restored' - ) - }) - } - if ( - error instanceof AgentInstallationError || - isAbortError(error) - ) { - throw error - } - throw new AgentInstallationError( - 'The published Host Agent could not be verified', - 'corrupt', - error - ) - } finally { - if (sftp) { - await cleanupOwnedStaging(sftp, cleanup) - } - sftp?.close() - lease?.release() - } - } - - async #reuseInstalledBundle( - target: SshConnectionPoolTarget, - lease: SshConnectionLease, - probe: { - architecture: AgentArchitecture - canonicalHomeDirectory: string - uid: number - }, - signal: AbortSignal - ): Promise { - const [registry, runtimeLock] = await Promise.all([ - readAgentReleaseKeyRegistry( - this.#resourcePaths.keyRegistryPath - ), - readAgentRuntimeLock(this.#resourcePaths.runtimeLockPath) - ]) - const canonicalRegistryBytes = - canonicalAgentReleaseKeyRegistryBytes(registry) - - let metadataSftp: StagedSftp | undefined - let installationSftp: StagedSftp | undefined - let currentMatchesLock = false - try { - metadataSftp = await lease.openStagedSftp( probe.canonicalHomeDirectory, { maximumFileBytes: MAXIMUM_METADATA_BYTES, - maximumTotalBytes: MAXIMUM_METADATA_BYTES * 4, - maximumOperations: 32, + maximumTotalBytes: MAXIMUM_METADATA_BYTES * 2, + maximumOperations: 8, operationTimeoutMs: 15_000 }, signal ) - const remoteRegistryBytes = await readVerifiedRemoteFile( - metadataSftp, + const metadata = await sftp.lstat( AGENT_REGISTRY_PATH, - probe.uid, - PRIVATE_FILE_MODE, signal ) - const remoteRegistry = parseInstallationRegistryState( + if ( + metadata.type !== 'file' || + metadata.uid !== probe.uid || + metadata.mode !== PRIVATE_FILE_MODE + ) { + throw new Error( + 'Installed Agent registry metadata is invalid' + ) + } + const registry = parseInstallationRegistryState( parseJsonBytes( - remoteRegistryBytes, + await sftp.readFile(AGENT_REGISTRY_PATH, signal), 'Installed Agent registry' ) ) - const current = remoteRegistry.current + const registered = registry.current + const registeredProtocol = + registered?.protocol if ( - current === undefined || - current.agentVersion !== runtimeLock.agentVersion || - current.arch !== probe.architecture || - current.installationId !== - `agent-${current.manifestSha256}` + registered === undefined || + ( + registeredProtocol === undefined + ? registered.agentVersion !== + runtimeLock.agentVersion + : registeredProtocol.major !== + runtimeLock.protocol.major || + registeredProtocol.minor > + runtimeLock.protocol.minor + ) || + registered.arch !== probe.architecture || + registered.installationId !== + `agent-${registered.manifestSha256}` ) { throw new AgentInstallationError( - 'This GoodBuddy package lacks matching Agent installation resources, and the Host has no matching current Agent', + 'The Host has no compatible current GoodBuddy Agent', 'incompatible' ) } - currentMatchesLock = true - const remoteReleaseKeyBytes = await readVerifiedRemoteFile( - metadataSftp, - RELEASE_KEYS_PATH, - probe.uid, - PRIVATE_FILE_MODE, - signal - ) - const remoteReleaseKeyRegistry = - parseAgentReleaseKeyRegistryBytes( - remoteReleaseKeyBytes, - 'Installed Agent release-key registry' - ) - const destination = - `.goodbuddy/agent/installations/${current.installationId}` - const manifestBytes = await metadataSftp.readFile( - `${destination}/manifest.json`, - signal - ) - const signatureFile = await metadataSftp.readFile( - `${destination}/manifest.sig`, - signal - ) - const signatureBytes = decodeDetachedSignature( - signatureFile, - 'Agent detached signature' - ) - const manifest = verifyAgentManifestSignature( - manifestBytes, - signatureBytes, - registry, - this.#verificationEnvironment - ) - verifyAgentManifestSignature( - manifestBytes, - signatureBytes, - remoteReleaseKeyRegistry, - this.#verificationEnvironment - ) - assertAgentManifestMatchesRuntimeLock( - manifest, - runtimeLock, - probe.architecture - ) - const manifestSha256 = sha256(manifestBytes) - if ( - manifestSha256 !== current.manifestSha256 || - manifest.signingKeyId.length < 1 - ) { - throw new Error( - 'Installed Agent manifest identity does not match its registry' - ) - } const installationId = verifyAgentInstallationId( - current.installationId + registered.installationId ) - const bundle = { - bundleDirectory: destination, - manifest, - manifestSha256 - } - assertBundleCapacity( - manifest, - canonicalRegistryBytes.byteLength - ) - metadataSftp.close() - metadataSftp = undefined - - installationSftp = await lease.openStagedSftp( - probe.canonicalHomeDirectory, - installationSftpLimits( - manifest, - canonicalRegistryBytes.byteLength, - this.#sftpLimits - ), - signal - ) - await verifyRemoteInstallationFromMetadata( - installationSftp, - destination, - bundle, - manifestBytes, - signatureFile, - probe.uid, - true, - signal - ) - const currentTarget = await this.#resolver.resolve( - target.host.id - ) - if ( - remoteHostTargetIdentityKey(currentTarget) !== - remoteHostTargetIdentityKey(target) - ) { - throw new AgentInstallationError( - 'SSH host identity changed before Agent activation', - 'host-identity-changed' - ) - } + sftp.close() + sftp = undefined + progress('checking-health') await ensureCurrentAgentHealthy( lease, installationId, signal ) - return publicIdentity(installationId, bundle) + progress('complete') + return { + installationId, + binaryDigest: `sha256:${registered.manifestSha256}`, + agentVersion: registered.agentVersion, + protocol: { + ...(registeredProtocol ?? runtimeLock.protocol) + }, + platform: 'linux', + architecture: registered.arch, + supervisor: 'detached-on-demand' + } } catch (error) { if (error instanceof AgentInstallationError) { throw error } - if (isMissingPathError(error) && !currentMatchesLock) { + if (isMissingPathError(error)) { throw new AgentInstallationError( - 'This GoodBuddy package lacks matching Agent installation resources, and the Host has no matching current Agent', + 'The Host has no compatible current GoodBuddy Agent', 'incompatible', error ) } throw new AgentInstallationError( - 'The existing Host Agent could not be verified', + 'The registered Host Agent could not be activated', 'corrupt', error ) } finally { - metadataSftp?.close() - installationSftp?.close() + sftp?.close() + lease?.release() } } + } function parseJsonBytes( @@ -778,21 +294,6 @@ function parseJsonBytes( } } -function decodeDetachedSignature( - value: Buffer, - description: string -): Buffer { - const text = value.toString('ascii') - if (!/^[A-Za-z0-9+/]{86}==\n$/u.test(text)) { - throw new Error(`${description} is not canonical Base64`) - } - const signature = Buffer.from(text.slice(0, -1), 'base64') - if (signature.byteLength !== 64) { - throw new Error(`${description} is not an Ed25519 signature`) - } - return signature -} - function assertLeaseMatchesTarget( lease: SshConnectionLease, target: SshConnectionPoolTarget @@ -804,516 +305,10 @@ function assertLeaseMatchesTarget( !/^[a-f0-9]{64}$/u.test( lease.identity.authenticationIdentity ) - ) { - throw new Error('SSH lease identity does not match the resolved host') - } -} - -function publicIdentity( - installationId: VerifiedAgentInstallationId, - bundle: VerifiedAgentBundle -): AgentInstallationIdentity { - return { - installationId, - binaryDigest: `sha256:${bundle.manifestSha256}`, - agentVersion: bundle.manifest.agentVersion, - protocol: { ...bundle.manifest.protocol }, - platform: 'linux', - architecture: bundle.manifest.arch, - supervisor: 'detached-on-demand' - } -} - -function assertPublishedAgentIdentity( - identity: PublishedAgentInstallationIdentity -): void { - const installationId = verifyAgentInstallationId( - identity.installationId - ) - if ( - !/^[a-f0-9]{64}$/u.test(identity.manifestSha256) || - installationId !== `agent-${identity.manifestSha256}` || - identity.binaryDigest !== - `sha256:${identity.manifestSha256}` || - identity.agentVersion.length < 1 || - identity.platform !== 'linux' || - (identity.architecture !== 'x64' && - identity.architecture !== 'arm64') || - !Number.isSafeInteger(identity.protocol.major) || - identity.protocol.major < 0 || - !Number.isSafeInteger(identity.protocol.minor) || - identity.protocol.minor < 0 || - identity.supervisor !== 'detached-on-demand' ) { throw new AgentInstallationError( - 'Published Agent identity is invalid', - 'corrupt' - ) - } -} - -function assertPublishedAgentMatches( - expected: PublishedAgentInstallationIdentity, - bundle: VerifiedAgentBundle -): void { - if ( - expected.installationId !== - `agent-${bundle.manifestSha256}` || - expected.agentVersion !== bundle.manifest.agentVersion || - expected.manifestSha256 !== bundle.manifestSha256 || - expected.binaryDigest !== - `sha256:${bundle.manifestSha256}` || - expected.platform !== bundle.manifest.platform || - expected.architecture !== bundle.manifest.arch || - expected.protocol.major !== bundle.manifest.protocol.major || - expected.protocol.minor !== bundle.manifest.protocol.minor || - expected.supervisor !== 'detached-on-demand' - ) { - throw new AgentInstallationError( - 'Published Agent does not match the authenticated package result', - 'corrupt' - ) - } -} - -function publishedAgentIdentityKey( - identity: PublishedAgentInstallationIdentity -): string { - return createHash('sha256') - .update(JSON.stringify(identity)) - .digest('hex') -} - -function assertBundleCapacity( - manifest: AgentBundleManifest, - registryBytes: number -): void { - const total = - manifest.files.reduce((sum, file) => sum + file.size, 0) + - registryBytes - if ( - manifest.files.length > MAXIMUM_INSTALLATION_FILES || - manifest.files.some( - (file) => file.size > MAXIMUM_AGENT_FILE_BYTES - ) || - !Number.isSafeInteger(total) || - total > MAXIMUM_INSTALLATION_BYTES - ) { - throw new Error('Agent bundle exceeds installation safety limits') - } -} - -function installationSftpLimits( - manifest: AgentBundleManifest, - registryBytes: number, - configured?: BoundedSftpLimits -): BoundedSftpLimits { - const largest = Math.max( - registryBytes, - ...manifest.files.map((file) => file.size), - 1024 * 1024 - ) - const payload = - manifest.files.reduce((sum, file) => sum + file.size, 0) + - registryBytes + - 2 * 1024 * 1024 - const reusableNodeBytes = - manifest.files.find( - (file) => - file.path === manifest.entrypoint.runtimePath - )?.size ?? 0 - return { - maximumFileBytes: Math.max( - largest, - configured?.maximumFileBytes ?? 0 - ), - maximumTotalBytes: Math.max( - payload * 2 + reusableNodeBytes, - configured?.maximumTotalBytes ?? 0 - ), - maximumOperations: - configured?.maximumOperations ?? 2_048, - operationTimeoutMs: configured?.operationTimeoutMs - } -} - -async function installReleaseKeyRegistry( - sftp: StagedSftp, - contents: Buffer, - uid: number, - cleanup: CleanupEntry[], - signal?: AbortSignal -): Promise { - const destination = '.goodbuddy/agent/release-keys.json' - const existing = await pathMetadata(sftp, destination, signal) - if (existing !== undefined) { - assertMetadata( - existing, - destination, - 'file', - uid, - PRIVATE_FILE_MODE, - undefined - ) - if ( - existing.size === contents.byteLength && - (await sftp.readFile(destination, signal)).equals(contents) - ) { - return - } - } - const temporary = - `.goodbuddy/agent/.release-keys-${randomUUID()}.tmp` - cleanup.push({ path: temporary, type: 'file' }) - await sftp.writeFile(temporary, contents, signal) - await sftp.chmod(temporary, PRIVATE_FILE_MODE, signal) - await verifyRemoteFile( - sftp, - temporary, - contents.byteLength, - sha256(contents), - uid, - PRIVATE_FILE_MODE, - signal - ) - await sftp.replaceFile(temporary, destination, signal) - cleanup.pop() - await verifyRemoteFile( - sftp, - destination, - contents.byteLength, - sha256(contents), - uid, - PRIVATE_FILE_MODE, - signal - ) -} - -async function snapshotManagedRegistries( - sftp: StagedSftp, - uid: number, - signal?: AbortSignal -): Promise { - const snapshots: ManagedFileSnapshot[] = [] - for (const path of [ - '.goodbuddy/agent/release-keys.json', - '.goodbuddy/agent/registry.json' - ]) { - const metadata = await pathMetadata(sftp, path, signal) - if (metadata === undefined) { - snapshots.push({ path, contents: undefined, uid }) - continue - } - assertMetadata( - metadata, - path, - 'file', - uid, - PRIVATE_FILE_MODE, - undefined - ) - snapshots.push({ - path, - contents: await sftp.readFile(path, signal), - uid - }) - } - return snapshots -} - -async function restoreManagedRegistries( - sftp: StagedSftp, - snapshots: readonly ManagedFileSnapshot[] -): Promise { - for (const snapshot of snapshots) { - const existing = await pathMetadata(sftp, snapshot.path) - if (snapshot.contents === undefined) { - if (existing !== undefined) { - assertMetadata( - existing, - snapshot.path, - 'file', - snapshot.uid, - PRIVATE_FILE_MODE, - undefined - ) - await sftp.unlink(snapshot.path) - } - continue - } - if ( - existing !== undefined && - existing.type === 'file' && - existing.mode === PRIVATE_FILE_MODE && - existing.size === snapshot.contents.byteLength && - (await sftp.readFile(snapshot.path)).equals(snapshot.contents) - ) { - continue - } - if (existing !== undefined) { - assertMetadata( - existing, - snapshot.path, - 'file', - snapshot.uid, - undefined, - undefined - ) - } - const temporary = - `.goodbuddy/agent/.registry-rollback-${randomUUID()}.tmp` - try { - await sftp.writeFile(temporary, snapshot.contents) - await sftp.chmod(temporary, PRIVATE_FILE_MODE) - await sftp.replaceFile(temporary, snapshot.path) - await verifyRemoteFile( - sftp, - snapshot.path, - snapshot.contents.byteLength, - sha256(snapshot.contents), - snapshot.uid, - PRIVATE_FILE_MODE - ) - } catch (error) { - await sftp.unlink(temporary).catch(() => undefined) - throw error - } - } -} - -async function stopFailedCandidate( - lease: SshConnectionLease, - installationId: VerifiedAgentInstallationId -): Promise { - if (!lease.isUsable()) { - return - } - try { - await lease.runAgentLifecycleAction( - installationId, - 'stop' - ) - } catch { - // The failed candidate is stopped best-effort before registry rollback. - } -} - -async function verifyRemoteInstallationFromMetadata( - sftp: StagedSftp, - destination: string, - bundle: VerifiedAgentBundle, - manifestBytes: Buffer, - signatureBytes: Buffer, - uid: number, - verifyCriticalContents: boolean, - signal?: AbortSignal -): Promise { - await assertRemoteMetadata( - sftp, - destination, - 'directory', - uid, - PRIVATE_DIRECTORY_MODE, - undefined, - signal - ) - const checkedDirectories = new Set() - for (const file of bundle.manifest.files) { - const parts = file.path.split('/') - let directory = destination - for (const part of parts.slice(0, -1)) { - directory = `${directory}/${part}` - if (!checkedDirectories.has(directory)) { - checkedDirectories.add(directory) - await assertRemoteMetadata( - sftp, - directory, - 'directory', - uid, - PRIVATE_DIRECTORY_MODE, - undefined, - signal - ) - } - } - const path = `${destination}/${file.path}` - const mode = file.mode === '0755' ? 0o755 : 0o644 - if ( - verifyCriticalContents && - file.path !== bundle.manifest.entrypoint.runtimePath - ) { - await verifyRemoteFile( - sftp, - path, - file.size, - file.sha256, - uid, - mode, - signal - ) - } else { - await assertRemoteMetadata( - sftp, - path, - 'file', - uid, - mode, - file.size, - signal - ) - } - } - for (const [metadataName, contents] of [ - ['manifest.json', manifestBytes], - ['manifest.sig', signatureBytes] - ] as const) { - const path = `${destination}/${metadataName}` - if (!verifyCriticalContents) { - await assertRemoteMetadata( - sftp, - path, - 'file', - uid, - METADATA_MODE, - contents.byteLength, - signal - ) - } else { - await verifyRemoteFile( - sftp, - path, - contents.byteLength, - sha256(contents), - uid, - METADATA_MODE, - signal - ) - } - } -} - -async function verifyRemoteFile( - sftp: StagedSftp, - path: string, - size: number, - digest: string, - uid: number, - mode: number, - signal?: AbortSignal -): Promise { - const contents = await readVerifiedRemoteFile( - sftp, - path, - uid, - mode, - signal, - size - ) - if (sha256(contents) !== digest) { - throw new Error(`Remote Agent file readback mismatch: ${path}`) - } -} - -async function readVerifiedRemoteFile( - sftp: StagedSftp, - path: string, - uid: number, - mode: number, - signal?: AbortSignal, - expectedSize?: number -): Promise { - const metadata = await sftp.stat(path, signal) - assertMetadata( - metadata, - path, - 'file', - uid, - mode, - expectedSize - ) - const contents = await sftp.readFile(path, signal) - if (contents.byteLength !== metadata.size) { - throw new Error(`Remote Agent file readback mismatch: ${path}`) - } - await assertRemoteMetadata( - sftp, - path, - 'file', - uid, - mode, - metadata.size, - signal - ) - return contents -} - -async function assertRemoteMetadata( - sftp: StagedSftp, - path: string, - type: 'file' | 'directory', - uid: number, - mode: number, - size: number | undefined, - signal?: AbortSignal -): Promise { - assertMetadata( - await sftp.stat(path, signal), - path, - type, - uid, - mode, - size - ) -} - -function assertMetadata( - metadata: SftpEntryMetadata, - path: string, - type: 'file' | 'directory', - uid: number, - mode: number | undefined, - size: number | undefined -): void { - if ( - metadata.type !== type || - metadata.uid !== uid || - (mode !== undefined && metadata.mode !== mode) || - (size !== undefined && metadata.size !== size) - ) { - throw new Error(`Remote Agent metadata mismatch: ${path}`) - } -} - -async function pathMetadata( - sftp: StagedSftp, - path: string, - signal?: AbortSignal -): Promise { - try { - return await sftp.lstat(path, signal) - } catch (error) { - if (isMissingPathError(error)) { - return undefined - } - throw error - } -} - -async function expectLifecycleSuccess( - lease: SshConnectionLease, - installationId: VerifiedAgentInstallationId, - action: 'bootstrap' | 'health', - signal?: AbortSignal -): Promise { - const result = await lease.runAgentLifecycleAction( - installationId, - action, - signal - ) - if (result.exitCode !== 0) { - throw new AgentInstallationError( - `GoodBuddy Agent ${action} failed`, - 'lifecycle' + 'SSH lease identity changed during Agent activation', + 'host-identity-changed' ) } } @@ -1331,91 +326,45 @@ async function ensureCurrentAgentHealthy( if (initial.exitCode === 0) { return } - await expectLifecycleSuccess( - lease, + const bootstrap = await lease.runAgentLifecycleAction( installationId, 'bootstrap', signal ) - await expectLifecycleSuccess( - lease, - installationId, - 'health', - signal + if (bootstrap.exitCode !== 0) { + throw new AgentInstallationError( + diagnosticMessage( + bootstrap, + 'GoodBuddy Agent bootstrap failed' + ), + 'lifecycle' + ) + } +} + +function diagnosticMessage( + result: AgentDiagnosticResult, + fallback: string +): string { + const detail = `${result.stderr}\n${result.stdout}` + const bounded = boundedDiagnostic( + detail, + MAXIMUM_DIAGNOSTIC_CHARACTERS ) + return bounded.length > 0 + ? `${fallback}: ${bounded}` + : `${fallback} (exit ${String(result.exitCode)})` } -async function cleanupOwnedStaging( - sftp: StagedSftp, - entries: readonly CleanupEntry[] -): Promise { - let complete = true - for (const entry of [...entries].reverse()) { - try { - if (entry.type === 'file') { - await sftp.unlink(entry.path) - } else { - await sftp.rmdir(entry.path) - } - } catch (error) { - if (!isMissingPathError(error)) { - complete = false - // Cleanup is best-effort and never widens beyond operation-owned paths. - } - } +function emitProgress( + callback: + | ((phase: AgentInstallationPhase) => void) + | undefined, + phase: AgentInstallationPhase +): void { + try { + callback?.(phase) + } catch { + // Progress observers cannot alter activation state. } - return complete -} - -function waitForOperation( - promise: Promise, - signal?: AbortSignal -): Promise { - if (!signal) { - return promise - } - if (signal.aborted) { - return Promise.reject( - signal.reason ?? - new DOMException('The operation was aborted', 'AbortError') - ) - } - return new Promise((resolve, reject) => { - const abort = (): void => { - reject( - signal.reason ?? - new DOMException('The operation was aborted', 'AbortError') - ) - } - signal.addEventListener('abort', abort, { once: true }) - promise.then( - (value) => { - signal.removeEventListener('abort', abort) - resolve(value) - }, - (error: unknown) => { - signal.removeEventListener('abort', abort) - reject(error) - } - ) - }) -} - -function isAbortError(error: unknown): boolean { - return ( - ( - error instanceof DOMException && - error.name === 'AbortError' - ) || - ( - typeof error === 'object' && - error !== null && - 'name' in error && - (error as { name?: unknown }).name === 'AbortError' - ) - ) -} - -function sha256(contents: Uint8Array): string { - return createHash('sha256').update(contents).digest('hex') } diff --git a/src/main/remote-agent/bounded-diagnostic.ts b/src/main/remote-agent/bounded-diagnostic.ts new file mode 100644 index 00000000..9f4459a2 --- /dev/null +++ b/src/main/remote-agent/bounded-diagnostic.ts @@ -0,0 +1,21 @@ +export function boundedDiagnostic( + value: string, + maximumCharacters = 800 +): string { + let printable = '' + for (const character of value) { + const code = character.charCodeAt(0) + if ( + code === 9 || + code === 10 || + code === 13 || + (code >= 32 && code !== 127) + ) { + printable += character + } + } + return printable + .replace(/\s+/gu, ' ') + .trim() + .slice(0, maximumCharacters) +} diff --git a/src/main/remote-agent/control-plane-package-installer.ts b/src/main/remote-agent/control-plane-package-installer.ts index 82b93157..d61f0950 100644 --- a/src/main/remote-agent/control-plane-package-installer.ts +++ b/src/main/remote-agent/control-plane-package-installer.ts @@ -11,12 +11,10 @@ import { fstatSync, fsyncSync, lstatSync, - linkSync, mkdirSync, mkdtempSync, openSync, readSync, - readdirSync, renameSync, rmSync, statSync, @@ -28,9 +26,7 @@ import { basename, dirname, join, - relative, - resolve, - sep + resolve } from 'node:path' import { crc32 } from 'node:zlib' @@ -154,7 +150,12 @@ type VerifiedPackage = { archiveSha256: string entries: Map descriptor: JsonRecord + descriptorBytes: Buffer + packageSignatureBytes: Buffer registry: TrustedRegistry + releaseKeyRegistryBytes: Buffer + agentRuntimeLockBytes: Buffer + remoteRuntimeLockBytes: Buffer agentManifest: JsonRecord runtimeManifest: JsonRecord agentManifestSha256: string @@ -166,6 +167,11 @@ type VerifiedPackage = { type PreparedState = { formatVersion: 1 archiveSha256: string + releaseKeyRegistrySha256: string + agentRuntimeLockSha256: string + remoteRuntimeLockSha256: string + packageDescriptorSha256: string + packageSignatureSha256: string agent: PackageInstallerAgentIdentity runtime: PackageInstallerRuntimeIdentity } @@ -543,7 +549,28 @@ function readEntry(handle: number, entries: Map, name: string) if (entry === undefined || entry.size > MAXIMUM_METADATA_BYTES) { throw new Error(`Agent package metadata is missing or too large: ${name}`) } - return streamEntry(handle, entry).bytes! + const actual = streamEntry(handle, entry) + if (actual.crc32 !== entry.checksum) { + throw new Error(`Agent package ZIP checksum mismatch: ${name}`) + } + return actual.bytes! +} + +function assertDeclaredMetadata( + name: string, + bytes: Buffer, + declared: ReadonlyMap +): void { + const expected = declared.get(name) + if ( + expected === undefined || + expected.size !== bytes.byteLength || + expected.sha256 !== sha256(bytes) + ) { + throw new Error( + `Agent package metadata digest mismatch: ${name}` + ) + } } function parseJson(bytes: Buffer, label: string): unknown { @@ -1372,24 +1399,44 @@ function verifyArchive( signatureBytes ) const declaredMap = new Map(declared.map((file) => [file.path, file])) + assertDeclaredMetadata( + 'agent-release-keys.json', + registryBytes, + declaredMap + ) emit('verifying-payload') - for (const entry of entries.values()) { - const actual = streamEntry(handle, entry) - if (actual.crc32 !== entry.checksum) { - throw new Error(`Agent package ZIP checksum mismatch: ${entry.name}`) - } - const expected = declaredMap.get(entry.name) - if (expected !== undefined && actual.sha256 !== expected.sha256) { - throw new Error(`Agent package payload digest mismatch: ${entry.name}`) - } - } const agentManifestBytes = readEntry(handle, entries, 'agent/manifest.json') + assertDeclaredMetadata( + 'agent/manifest.json', + agentManifestBytes, + declaredMap + ) + const agentRuntimeLockBytes = readEntry( + handle, + entries, + 'agent-runtime-lock.json' + ) + assertDeclaredMetadata( + 'agent-runtime-lock.json', + agentRuntimeLockBytes, + declaredMap + ) + const agentSignatureBytes = readEntry( + handle, + entries, + 'agent/manifest.sig' + ) + assertDeclaredMetadata( + 'agent/manifest.sig', + agentSignatureBytes, + declaredMap + ) const agentManifest = assertAgentManifest( agentManifestBytes, - readEntry(handle, entries, 'agent/manifest.sig'), + agentSignatureBytes, registry, parseCanonicalJson( - readEntry(handle, entries, 'agent-runtime-lock.json'), + agentRuntimeLockBytes, 'Agent runtime lock' ), descriptor, @@ -1403,16 +1450,39 @@ function verifyArchive( entries, `runtime/opencode/${runtimeDigest}/manifest.json` ) + assertDeclaredMetadata( + `runtime/opencode/${runtimeDigest}/manifest.json`, + runtimeManifestBytes, + declaredMap + ) + const remoteRuntimeLockBytes = readEntry( + handle, + entries, + 'remote-runtime-lock.json' + ) + assertDeclaredMetadata( + 'remote-runtime-lock.json', + remoteRuntimeLockBytes, + declaredMap + ) + const runtimeSignaturePath = + `runtime/opencode/${runtimeDigest}/manifest.sig` + const runtimeSignatureBytes = readEntry( + handle, + entries, + runtimeSignaturePath + ) + assertDeclaredMetadata( + runtimeSignaturePath, + runtimeSignatureBytes, + declaredMap + ) const runtime = assertRuntimeManifest( runtimeManifestBytes, - readEntry( - handle, - entries, - `runtime/opencode/${runtimeDigest}/manifest.sig` - ), + runtimeSignatureBytes, registry, parseCanonicalJson( - readEntry(handle, entries, 'remote-runtime-lock.json'), + remoteRuntimeLockBytes, 'Remote Runtime lock' ), descriptor, @@ -1427,7 +1497,12 @@ function verifyArchive( archiveSha256, entries, descriptor, + descriptorBytes, + packageSignatureBytes: signatureBytes, registry, + releaseKeyRegistryBytes: registryBytes, + agentRuntimeLockBytes, + remoteRuntimeLockBytes, agentManifest, runtimeManifest: runtime.manifest, agentManifestSha256, @@ -1512,6 +1587,31 @@ function persistPreparedState( } else { mkdirSync(preparedRoot, { recursive: false, mode: 0o700 }) } + writePreparedFile( + preparedRoot, + 'agent-release-keys.json', + verified.releaseKeyRegistryBytes + ) + writePreparedFile( + preparedRoot, + 'agent-runtime-lock.json', + verified.agentRuntimeLockBytes + ) + writePreparedFile( + preparedRoot, + 'remote-runtime-lock.json', + verified.remoteRuntimeLockBytes + ) + writePreparedFile( + preparedRoot, + PACKAGE_DESCRIPTOR, + verified.descriptorBytes + ) + writePreparedFile( + preparedRoot, + PACKAGE_SIGNATURE, + verified.packageSignatureBytes + ) const destination = join(preparedRoot, 'result.json') const temporary = join( preparedRoot, @@ -1520,6 +1620,16 @@ function persistPreparedState( const state: PreparedState = { formatVersion: 1, archiveSha256: verified.archiveSha256, + releaseKeyRegistrySha256: + sha256(verified.releaseKeyRegistryBytes), + agentRuntimeLockSha256: + sha256(verified.agentRuntimeLockBytes), + remoteRuntimeLockSha256: + sha256(verified.remoteRuntimeLockBytes), + packageDescriptorSha256: + sha256(verified.descriptorBytes), + packageSignatureSha256: + sha256(verified.packageSignatureBytes), agent: verified.agent, runtime: verified.runtime } @@ -1551,12 +1661,57 @@ function persistPreparedState( } } +function writePreparedFile( + directory: string, + name: string, + bytes: Buffer +): void { + if ( + bytes.byteLength <= 0 || + bytes.byteLength > MAXIMUM_METADATA_BYTES + ) { + throw new Error(`Prepared package metadata is invalid: ${name}`) + } + const destination = join(directory, name) + const temporary = join( + directory, + `.${name}-${process.pid}-${Date.now().toString(36)}.tmp` + ) + const handle = openSync( + temporary, + constants.O_WRONLY | constants.O_CREAT | constants.O_EXCL, + 0o600 + ) + try { + let offset = 0 + while (offset < bytes.length) { + offset += writeFileChunk(handle, bytes, offset) + } + fsyncSync(handle) + } finally { + closeSync(handle) + } + try { + chmodSync(temporary, 0o600) + renameSync(temporary, destination) + } finally { + if (existsSync(temporary)) { + unlinkSync(temporary) + } + } +} + function extractPayload( archive: string, - operationRoot: string, + destinationRoot: string, verified: VerifiedPackage -): string { - const temporary = mkdtempSync(join(operationRoot, '.commit-payload-')) +): void { + if (existsSync(destinationRoot)) { + throw new Error('Prepared package payload already exists') + } + const temporary = mkdtempSync( + join(dirname(destinationRoot), '.payload-') + ) try { mkdirSync(join(temporary, 'agent'), { recursive: true, mode: 0o700 }) mkdirSync(join(temporary, 'runtime'), { recursive: true, mode: 0o700 }) @@ -1598,7 +1753,9 @@ function extractPayload( actual.crc32 !== entry.checksum || actual.sha256 !== expected.sha256 ) { - throw new Error(`Extracted package payload verification failed: ${name}`) + throw new Error( + `Extracted package payload digest or checksum mismatch: ${name}` + ) } } } @@ -1610,7 +1767,7 @@ function extractPayload( } assertExtractedArchitectures(temporary, verified.agent.architecture) chmodSync(temporary, 0o700) - return temporary + renameSync(temporary, destinationRoot) } catch (error) { rmSync(temporary, { recursive: true, force: true }) throw error @@ -1628,13 +1785,45 @@ export function preparePackage(options: InstallerOptions): PackageInstallerResul const inputs = assertAbsoluteInputs(options) const progress = eventEmitter('prepare', options.emit) progress('validating') + const preparedRoot = join(inputs.operationRoot, 'prepared') + const preparedStatePath = join(preparedRoot, 'result.json') + if (existsSync(preparedStatePath)) { + const state = readPreparedState(preparedStatePath) + if (state.archiveSha256 !== inputs.expectedSha256) { + throw new Error( + 'Prepared package state does not match the requested archive' + ) + } + const result: PackageInstallerResult = { + type: 'result', + command: 'prepare', + status: 'prepared', + archiveSha256: state.archiveSha256, + agent: state.agent, + runtime: state.runtime + } + options.emit?.(result) + return result + } const verified = verifyArchive( inputs.archive, inputs.expectedSha256, progress ) - progress('persisting-prepared-state') - persistPreparedState(inputs.operationRoot, verified) + try { + mkdirSync(preparedRoot, { recursive: false, mode: 0o700 }) + progress('extracting-payload') + extractPayload( + inputs.archive, + join(preparedRoot, 'payload'), + verified + ) + progress('persisting-prepared-state') + persistPreparedState(inputs.operationRoot, verified) + } catch (error) { + rmSync(preparedRoot, { recursive: true, force: true }) + throw error + } const result: PackageInstallerResult = { type: 'result', command: 'prepare', @@ -1647,59 +1836,6 @@ export function preparePackage(options: InstallerOptions): PackageInstallerResul return result } -function listFiles(root: string): string[] { - const output: string[] = [] - const pending = [root] - while (pending.length > 0) { - const current = pending.pop()! - for (const entry of readdirSync(current, { withFileTypes: true })) { - const path = join(current, entry.name) - if (entry.isSymbolicLink()) { - throw new Error(`Prepared payload contains a symbolic link: ${path}`) - } - if (entry.isDirectory()) { - pending.push(path) - } else if (entry.isFile()) { - output.push(path) - } else { - throw new Error(`Prepared payload contains an unsupported entry: ${path}`) - } - } - } - return output.sort((left, right) => - Buffer.compare( - Buffer.from(relative(root, left).split(sep).join('/'), 'utf8'), - Buffer.from(relative(root, right).split(sep).join('/'), 'utf8') - ) - ) -} - -function directoriesEqual(left: string, right: string): boolean { - const leftFiles = listFiles(left) - const rightFiles = listFiles(right) - if (leftFiles.length !== rightFiles.length) { - return false - } - for (let index = 0; index < leftFiles.length; index += 1) { - const leftName = relative(left, leftFiles[index]!).split(sep).join('/') - const rightName = relative(right, rightFiles[index]!).split(sep).join('/') - const leftMetadata = statSync(leftFiles[index]!) - const rightMetadata = statSync(rightFiles[index]!) - if ( - leftName !== rightName || - leftMetadata.size !== rightMetadata.size || - ( - process.platform !== 'win32' && - (leftMetadata.mode & 0o777) !== (rightMetadata.mode & 0o777) - ) || - hashFile(leftFiles[index]!) !== hashFile(rightFiles[index]!) - ) { - return false - } - } - return true -} - type PublishedDirectory = { destination: string backupRoot?: string @@ -1724,10 +1860,6 @@ function publishDirectory( ) { throw new Error(`Existing digest destination has conflicting content: ${destination}`) } - if (directoriesEqual(source, destination)) { - rmSync(source, { recursive: true, force: true }) - return { destination } - } const backupRoot = mkdtempSync( join(operationRoot, '.replaced-destination-') ) @@ -1748,13 +1880,6 @@ function publishDirectory( try { renameSync(source, destination) } catch (error) { - if ( - existsSync(destination) && - directoriesEqual(source, destination) - ) { - rmSync(source, { recursive: true, force: true }) - return { destination } - } throw new Error( 'Prepared payload could not be atomically published on the managed filesystem', { cause: error } @@ -1780,6 +1905,94 @@ function ensureOwnedManagedHierarchy( } } +type LocalMetadataSnapshot = { + path: string + contents: Buffer | undefined +} + +function snapshotLocalMetadata( + paths: readonly string[] +): LocalMetadataSnapshot[] { + return paths.map((path) => ({ + path, + contents: existsSync(path) + ? readBoundedRegularFile( + path, + MAXIMUM_METADATA_BYTES, + 'Managed environment metadata', + '0600' + ) + : undefined + })) +} + +function writePrivateFileAtomic( + destination: string, + contents: Buffer +): void { + if ( + contents.byteLength <= 0 || + contents.byteLength > MAXIMUM_METADATA_BYTES + ) { + throw new Error('Managed environment metadata is invalid') + } + const temporary = join( + dirname(destination), + `.${basename(destination)}-${process.pid}-${Date.now().toString(36)}.tmp` + ) + const handle = openSync( + temporary, + constants.O_WRONLY | constants.O_CREAT | constants.O_EXCL, + 0o600 + ) + try { + let offset = 0 + while (offset < contents.length) { + offset += writeFileChunk(handle, contents, offset) + } + fsyncSync(handle) + } finally { + closeSync(handle) + } + try { + chmodSync(temporary, 0o600) + if (process.platform === 'win32' && existsSync(destination)) { + unlinkSync(destination) + } + renameSync(temporary, destination) + } finally { + if (existsSync(temporary)) { + unlinkSync(temporary) + } + } +} + +function restoreLocalMetadata( + snapshots: readonly LocalMetadataSnapshot[] +): void { + const errors: unknown[] = [] + for (const snapshot of snapshots) { + try { + if (snapshot.contents === undefined) { + rmSync(snapshot.path, { force: true }) + } else { + writePrivateFileAtomic( + snapshot.path, + snapshot.contents + ) + } + } catch (error) { + errors.push(error) + } + } + if (errors.length > 0) { + throw new AggregateError( + errors, + 'Managed environment metadata rollback was incomplete' + ) + } +} + function ensureOwnedManagedDirectory(path: string): void { try { mkdirSync(path, { recursive: false, mode: 0o700 }) @@ -1853,12 +2066,37 @@ function readPreparedState(path: string): PreparedState { const value = parseCanonicalJson(bytes, 'Prepared package state') exactKeys( value, - ['formatVersion', 'archiveSha256', 'agent', 'runtime'], + [ + 'formatVersion', + 'archiveSha256', + 'releaseKeyRegistrySha256', + 'agentRuntimeLockSha256', + 'remoteRuntimeLockSha256', + 'packageDescriptorSha256', + 'packageSignatureSha256', + 'agent', + 'runtime' + ], 'Prepared package state' ) if ( value.formatVersion !== 1 || !sha256Pattern.test(String(value.archiveSha256)) || + !sha256Pattern.test( + String(value.releaseKeyRegistrySha256) + ) || + !sha256Pattern.test( + String(value.agentRuntimeLockSha256) + ) || + !sha256Pattern.test( + String(value.remoteRuntimeLockSha256) + ) || + !sha256Pattern.test( + String(value.packageDescriptorSha256) + ) || + !sha256Pattern.test( + String(value.packageSignatureSha256) + ) || !isRecord(value.agent) || !isRecord(value.runtime) ) { @@ -1923,6 +2161,16 @@ function readPreparedState(path: string): PreparedState { return { formatVersion: 1, archiveSha256: String(value.archiveSha256), + releaseKeyRegistrySha256: + String(value.releaseKeyRegistrySha256), + agentRuntimeLockSha256: + String(value.agentRuntimeLockSha256), + remoteRuntimeLockSha256: + String(value.remoteRuntimeLockSha256), + packageDescriptorSha256: + String(value.packageDescriptorSha256), + packageSignatureSha256: + String(value.packageSignatureSha256), agent: { installationId: agent.installationId, agentVersion: String(agent.agentVersion), @@ -1947,34 +2195,6 @@ function readPreparedState(path: string): PreparedState { } } -function safeRegularFile( - path: string, - expectedMode: '0600' | '0644' | '0755', - expectedSize?: number -): boolean { - try { - const metadata = lstatSync(path) - const getuid = process.getuid - return ( - metadata.isFile() && - !metadata.isSymbolicLink() && - (getuid === undefined || metadata.uid === getuid.call(process)) && - (process.platform === 'win32' || - (metadata.mode & 0o777) === - ( - expectedMode === '0755' - ? 0o755 - : expectedMode === '0600' - ? 0o600 - : 0o644 - )) && - (expectedSize === undefined || metadata.size === expectedSize) - ) - } catch { - return false - } -} - function readBoundedRegularFile( path: string, maximumBytes: number, @@ -2016,297 +2236,137 @@ function readBoundedRegularFile( } } -function hashFile(path: string): string { - const handle = openSync( - path, - constants.O_RDONLY | (constants.O_NOFOLLOW ?? 0) - ) - try { - const snapshot = fstatSync(handle) - if (!snapshot.isFile()) { - throw new Error(`Installed payload is not a regular file: ${path}`) - } - const digest = hashArchive(handle, snapshot.size) - if (!sameSnapshot(snapshot, fstatSync(handle))) { - throw new Error(`Installed payload changed while it was hashed: ${path}`) - } - return digest - } finally { - closeSync(handle) - } -} - -function verifyAgentTree( - root: string, - verified: VerifiedPackage +function assertPreparedIdentity( + agentRoot: string, + runtimeRoot: string, + state: PreparedState, + releaseKeyRegistryBytes: Buffer, + agentRuntimeLockBytes: Buffer, + remoteRuntimeLockBytes: Buffer, + descriptorBytes: Buffer, + packageSignatureBytes: Buffer ): void { - const files = parseFiles(verified.agentManifest.files, 'Agent manifest') - const expected = new Set([ - ...files.map((file) => file.path), - 'manifest.json', - 'manifest.sig' - ]) - const actual = listFiles(root).map((path) => - relative(root, path).split(sep).join('/') + const descriptor = parseCanonicalJson( + descriptorBytes, + 'Prepared Agent package descriptor' ) - if ( - actual.length !== expected.size || - actual.some((path) => !expected.has(path)) - ) { - throw new Error('Prepared Agent payload contains undeclared or missing files') - } - for (const file of files) { - const path = join(root, ...file.path.split('/')) - if ( - !safeRegularFile(path, file.mode, file.size) || - hashFile(path) !== file.sha256 - ) { - throw new Error(`Prepared Agent payload verification failed: ${file.path}`) - } - } - for (const name of ['manifest.json', 'manifest.sig'] as const) { - const path = join(root, name) - const entry = verified.entries.get(`agent/${name}`) - if ( - entry === undefined || - !safeRegularFile(path, '0644', entry.size) || - hashFile(path) !== - streamVerifiedEntryDigest(verified, `agent/${name}`) - ) { - throw new Error(`Prepared Agent metadata verification failed: ${name}`) - } - } -} - -function verifyRuntimeTree( - root: string, - verified: VerifiedPackage -): void { - const files = parseFiles(verified.runtimeManifest.files, 'Runtime manifest') - const expected = new Set([ - ...files.map((file) => file.path), - 'manifest.json', - 'manifest.sig' - ]) - const actual = listFiles(root).map((path) => - relative(root, path).split(sep).join('/') + const declared = parseFiles( + descriptor.files, + 'Prepared Agent package' ) - if ( - actual.length !== expected.size || - actual.some((path) => !expected.has(path)) - ) { - throw new Error('Prepared Runtime payload contains undeclared or missing files') + const entries = new Map() + for (const file of declared) { + entries.set(file.path, { + name: file.path, + size: file.size, + checksum: 0, + mode: file.mode, + dataOffset: 0, + recordStart: 0, + recordEnd: 0 + }) } - for (const file of files) { - const path = join(root, ...file.path.split('/')) - if ( - !safeRegularFile(path, file.mode, file.size) || - hashFile(path) !== file.sha256 - ) { - throw new Error(`Prepared Runtime payload verification failed: ${file.path}`) - } + for (const name of [PACKAGE_DESCRIPTOR, PACKAGE_SIGNATURE]) { + entries.set(name, { + name, + size: name === PACKAGE_DESCRIPTOR + ? descriptorBytes.byteLength + : packageSignatureBytes.byteLength, + checksum: 0, + mode: '0644', + dataOffset: 0, + recordStart: 0, + recordEnd: 0 + }) } - const runtimePrefix = - `runtime/opencode/${verified.runtime.bundleDigest.slice('sha256:'.length)}/` - for (const name of ['manifest.json', 'manifest.sig'] as const) { - const path = join(root, name) - const entry = verified.entries.get(`${runtimePrefix}${name}`) - if ( - entry === undefined || - !safeRegularFile(path, '0644', entry.size) || - hashFile(path) !== - streamVerifiedEntryDigest(verified, `${runtimePrefix}${name}`) - ) { - throw new Error(`Prepared Runtime metadata verification failed: ${name}`) - } - } -} - -function streamVerifiedEntryDigest( - verified: VerifiedPackage, - name: string -): string { - const file = parseFiles( - verified.descriptor.files, - 'Agent package' - ).find((candidate) => candidate.path === name) - if (file === undefined) { - throw new Error(`Agent package file is missing: ${name}`) - } - return file.sha256 -} - -function tryReuseCurrentNode( - preparedRoot: string, - managedRoot: string, - verified: VerifiedPackage -): void { - const candidateRuntimePath = isRecord(verified.agentManifest.entrypoint) - ? verified.agentManifest.entrypoint.runtimePath - : undefined - const candidateNode = parseFiles( - verified.agentManifest.files, - 'Agent manifest' - ).find((file) => file.path === candidateRuntimePath) - if (candidateNode === undefined) { - return - } - const destination = join( - preparedRoot, - 'agent', - ...candidateNode.path.split('/') + const registry = parseRegistry(releaseKeyRegistryBytes) + const packageFiles = new Map( + assertOuterDescriptor( + descriptor, + descriptorBytes, + entries, + registry, + packageSignatureBytes + ).map((file) => [file.path, file]) ) - const linked = join(preparedRoot, '.reused-node') - const backup = join(preparedRoot, '.candidate-node') - let movedCandidate = false - try { - const registryPath = join(managedRoot, 'agent', 'registry.json') - const registryValue = parseJson( - readBoundedRegularFile( - registryPath, - MAXIMUM_METADATA_BYTES, - 'Installed Agent registry', - '0600' - ), - 'Installed Agent registry' - ) - if (!isRecord(registryValue)) { - return - } - exactKeys( - registryValue, - ['formatVersion', 'current'], - 'Installed Agent registry' - ) - if (registryValue.formatVersion !== 1 || !isRecord(registryValue.current)) { - return - } - const current = registryValue.current - exactKeys( - current, - ['installationId', 'agentVersion', 'manifestSha256', 'arch'], - 'Installed Agent registry current entry' - ) - if ( - typeof current.installationId !== 'string' || - typeof current.agentVersion !== 'string' || - !versionPattern.test(current.agentVersion) || - !sha256Pattern.test(String(current.manifestSha256)) || - current.installationId !== `agent-${String(current.manifestSha256)}` || - current.arch !== verified.agent.architecture - ) { - return - } - const root = join( - managedRoot, - 'agent', - 'installations', - current.installationId - ) - const manifestPath = join(root, 'manifest.json') - const signaturePath = join(root, 'manifest.sig') - const manifestBytes = readBoundedRegularFile( - manifestPath, + const agentManifestBytes = readBoundedRegularFile( + join(agentRoot, 'manifest.json'), + MAXIMUM_METADATA_BYTES, + 'Prepared Agent manifest', + '0644' + ) + const agentManifest = assertAgentManifest( + agentManifestBytes, + readBoundedRegularFile( + join(agentRoot, 'manifest.sig'), MAXIMUM_METADATA_BYTES, - 'Installed Agent manifest', + 'Prepared Agent manifest signature', '0644' - ) - const signatureBytes = readBoundedRegularFile( - signaturePath, + ), + registry, + parseCanonicalJson( + agentRuntimeLockBytes, + 'Prepared Agent runtime lock' + ), + descriptor, + packageFiles + ) + const runtime = assertRuntimeManifest( + readBoundedRegularFile( + join(runtimeRoot, 'manifest.json'), MAXIMUM_METADATA_BYTES, - 'Installed Agent manifest signature', + 'Prepared Runtime manifest', '0644' + ), + readBoundedRegularFile( + join(runtimeRoot, 'manifest.sig'), + MAXIMUM_METADATA_BYTES, + 'Prepared Runtime manifest signature', + '0644' + ), + registry, + parseCanonicalJson( + remoteRuntimeLockBytes, + 'Prepared Remote Runtime lock' + ), + descriptor, + packageFiles + ) + const agentManifestSha256 = sha256(agentManifestBytes) + const architecture = descriptor.architecture as Architecture + const expectedAgent: PackageInstallerAgentIdentity = { + installationId: `agent-${agentManifestSha256}`, + agentVersion: String(agentManifest.agentVersion), + manifestSha256: agentManifestSha256, + binaryDigest: `sha256:${agentManifestSha256}`, + platform: 'linux', + architecture, + protocol: protocol(agentManifest.protocol, 'Agent protocol'), + supervisor: 'detached-on-demand' + } + const expectedRuntime: PackageInstallerRuntimeIdentity = { + runtimeId: 'opencode', + runtimeVersion: String(runtime.manifest.runtimeVersion), + bundleDigest: String(runtime.manifest.bundleDigest), + manifestDigest: runtime.manifestDigest, + runtimeAdapterDigest: String(runtime.manifest.adapterDigest), + acpCapabilitiesDigest: String( + runtime.manifest.acpCapabilitiesDigest + ), + platform: 'linux', + architecture, + protocol: protocol( + runtime.manifest.protocol, + 'Runtime protocol' ) - const manifest = parseCanonicalJson(manifestBytes, 'Installed Agent manifest') - exactKeys( - manifest, - [ - 'formatVersion', - 'product', - 'agentVersion', - 'platform', - 'arch', - 'protocol', - 'signingKeyId', - 'entrypoint', - 'files', - 'licenses' - ], - 'Installed Agent manifest' + } + if ( + canonicalJson(state.agent) !== canonicalJson(expectedAgent) || + canonicalJson(state.runtime) !== canonicalJson(expectedRuntime) + ) { + throw new Error( + 'Prepared package identity does not match the authenticated archive' ) - verifySignature( - manifestBytes, - signatureBytes, - trustedProductionKey(verified.registry, manifest.signingKeyId), - AGENT_SIGNATURE_DOMAIN, - 'Installed Agent manifest' - ) - if ( - manifest.formatVersion !== 1 || - manifest.product !== 'GoodBuddy' || - manifest.platform !== 'linux' || - manifest.agentVersion !== current.agentVersion || - manifest.arch !== current.arch || - sha256(manifestBytes) !== current.manifestSha256 || - !isRecord(manifest.entrypoint) - ) { - return - } - const entrypoint = manifest.entrypoint - exactKeys( - entrypoint, - ['path', 'runtimePath', 'scriptPath'], - 'Installed Agent entrypoint' - ) - const currentNode = parseFiles( - manifest.files, - 'Installed Agent manifest' - ).find((file) => file.path === entrypoint.runtimePath) - if ( - currentNode === undefined || - canonicalJson(currentNode) !== canonicalJson(candidateNode) - ) { - return - } - const source = join(root, ...currentNode.path.split('/')) - if ( - !safeRegularFile(source, currentNode.mode, currentNode.size) || - hashFile(source) !== currentNode.sha256 || - !safeRegularFile(destination, candidateNode.mode, candidateNode.size) || - hashFile(destination) !== candidateNode.sha256 - ) { - return - } - linkSync(source, linked) - if ( - !safeRegularFile(linked, currentNode.mode, currentNode.size) || - lstatSync(linked).ino !== lstatSync(source).ino - ) { - unlinkSync(linked) - return - } - renameSync(destination, backup) - movedCandidate = true - renameSync(linked, destination) - unlinkSync(backup) - movedCandidate = false - } catch { - try { - if (existsSync(linked)) { - unlinkSync(linked) - } - if (movedCandidate && existsSync(backup)) { - if (existsSync(destination)) { - unlinkSync(destination) - } - renameSync(backup, destination) - movedCandidate = false - } else if (existsSync(backup)) { - unlinkSync(backup) - } - } catch { - // The normal candidate remains authoritative unless a swap completed. - } } } @@ -2326,84 +2386,146 @@ export function commitPackage(options: InstallerOptions): PackageInstallerResult if (state.archiveSha256 !== inputs.expectedSha256) { throw new Error('Prepared package state does not match the requested archive') } - progress('revalidating-archive') - const verified = verifyArchive( - inputs.archive, - inputs.expectedSha256, - progress + const releaseKeyRegistryBytes = readBoundedRegularFile( + join(preparedRoot, 'agent-release-keys.json'), + MAXIMUM_METADATA_BYTES, + 'Prepared Agent release-key registry', + '0600' + ) + const agentRuntimeLockBytes = readBoundedRegularFile( + join(preparedRoot, 'agent-runtime-lock.json'), + MAXIMUM_METADATA_BYTES, + 'Prepared Agent runtime lock', + '0600' + ) + const remoteRuntimeLockBytes = readBoundedRegularFile( + join(preparedRoot, 'remote-runtime-lock.json'), + MAXIMUM_METADATA_BYTES, + 'Prepared Remote Runtime lock', + '0600' + ) + const descriptorBytes = readBoundedRegularFile( + join(preparedRoot, PACKAGE_DESCRIPTOR), + MAXIMUM_METADATA_BYTES, + 'Prepared Agent package descriptor', + '0600' + ) + const packageSignatureBytes = readBoundedRegularFile( + join(preparedRoot, PACKAGE_SIGNATURE), + MAXIMUM_METADATA_BYTES, + 'Prepared Agent package signature', + '0600' ) if ( - state.archiveSha256 !== verified.archiveSha256 || - canonicalJson(state.agent) !== canonicalJson(verified.agent) || - canonicalJson(state.runtime) !== canonicalJson(verified.runtime) + sha256(releaseKeyRegistryBytes) !== + state.releaseKeyRegistrySha256 || + sha256(agentRuntimeLockBytes) !== + state.agentRuntimeLockSha256 || + sha256(remoteRuntimeLockBytes) !== + state.remoteRuntimeLockSha256 || + sha256(descriptorBytes) !== + state.packageDescriptorSha256 || + sha256(packageSignatureBytes) !== + state.packageSignatureSha256 ) { - throw new Error('Prepared package state does not match the authenticated archive') + throw new Error( + 'Prepared package metadata does not match its authenticated identity' + ) } - progress('extracting-payload') - const extractedRoot = extractPayload( - inputs.archive, - inputs.operationRoot, - verified + const payloadRoot = join(preparedRoot, 'payload') + if ( + !existsSync(payloadRoot) || + !lstatSync(payloadRoot).isDirectory() || + lstatSync(payloadRoot).isSymbolicLink() + ) { + throw new Error('Prepared package payload directory is invalid') + } + const agentSource = join(payloadRoot, 'agent') + const runtimeSource = join(payloadRoot, 'runtime') + const agentSourceExists = existsSync(agentSource) + const runtimeSourceExists = existsSync(runtimeSource) + if (agentSourceExists && runtimeSourceExists) { + assertPreparedIdentity( + agentSource, + runtimeSource, + state, + releaseKeyRegistryBytes, + agentRuntimeLockBytes, + remoteRuntimeLockBytes, + descriptorBytes, + packageSignatureBytes + ) + } + const home = resolve(options.homeDirectory ?? homedir()) + const managedRoot = join(home, '.goodbuddy') + ensureOwnedManagedHierarchy( + home, + state.runtime.runtimeId ) + const agentDestination = join( + managedRoot, + 'agent', + 'installations', + state.agent.installationId + ) + const runtimeDestination = join( + managedRoot, + 'runtimes', + state.runtime.runtimeId, + state.runtime.bundleDigest.slice('sha256:'.length) + ) + const metadataPaths = [ + join(managedRoot, 'agent', 'release-keys.json'), + join(managedRoot, 'runtimes', 'release-keys.json'), + join(managedRoot, 'runtimes', 'remote-runtime-lock.json') + ] as const + if (!agentSourceExists || !runtimeSourceExists) { + assertPreparedIdentity( + agentSourceExists ? agentSource : agentDestination, + runtimeSourceExists ? runtimeSource : runtimeDestination, + state, + releaseKeyRegistryBytes, + agentRuntimeLockBytes, + remoteRuntimeLockBytes, + descriptorBytes, + packageSignatureBytes + ) + } + progress('publishing-content') + const metadataSnapshots = snapshotLocalMetadata(metadataPaths) + const published: PublishedDirectory[] = [] try { - const home = resolve(options.homeDirectory ?? homedir()) - const managedRoot = join(home, '.goodbuddy') - ensureOwnedManagedHierarchy( - home, - verified.runtime.runtimeId - ) - tryReuseCurrentNode(extractedRoot, managedRoot, verified) - verifyAgentTree(join(extractedRoot, 'agent'), verified) - verifyRuntimeTree(join(extractedRoot, 'runtime'), verified) - progress('publishing-content') - const agentDestination = join( - managedRoot, - 'agent', - 'installations', - verified.agent.installationId - ) - const runtimeDestination = join( - managedRoot, - 'runtimes', - verified.runtime.runtimeId, - verified.runtime.bundleDigest.slice('sha256:'.length) - ) - const published: PublishedDirectory[] = [] - try { + if (agentSourceExists) { published.push( publishDirectory( - join(extractedRoot, 'agent'), + agentSource, agentDestination, inputs.operationRoot ) ) - verifyAgentTree(agentDestination, verified) + } + if (runtimeSourceExists) { published.push( publishDirectory( - join(extractedRoot, 'runtime'), + runtimeSource, runtimeDestination, inputs.operationRoot ) ) - verifyRuntimeTree(runtimeDestination, verified) - } catch (error) { - const rollbackErrors: unknown[] = [] - for (const entry of [...published].reverse()) { - try { - restoreReplacedDirectory(entry) - } catch (rollbackError) { - rollbackErrors.push(rollbackError) - } - } - if (rollbackErrors.length > 0) { - throw new PackageInstallerRollbackIncompleteError( - [error, ...rollbackErrors], - 'Package commit failed and a replaced managed destination could not be restored', - { cause: error } - ) - } - throw error } + progress('publishing-metadata') + writePrivateFileAtomic( + metadataPaths[0], + releaseKeyRegistryBytes + ) + writePrivateFileAtomic( + metadataPaths[1], + releaseKeyRegistryBytes + ) + writePrivateFileAtomic( + metadataPaths[2], + remoteRuntimeLockBytes + ) for (const entry of published) { discardReplacedDirectory(entry) } @@ -2411,14 +2533,34 @@ export function commitPackage(options: InstallerOptions): PackageInstallerResult type: 'result', command: 'commit', status: 'committed', - archiveSha256: verified.archiveSha256, - agent: verified.agent, - runtime: verified.runtime + archiveSha256: state.archiveSha256, + agent: state.agent, + runtime: state.runtime } options.emit?.(result) return result - } finally { - rmSync(extractedRoot, { recursive: true, force: true }) + } catch (error) { + const rollbackErrors: unknown[] = [] + try { + restoreLocalMetadata(metadataSnapshots) + } catch (rollbackError) { + rollbackErrors.push(rollbackError) + } + for (const entry of [...published].reverse()) { + try { + restoreReplacedDirectory(entry) + } catch (rollbackError) { + rollbackErrors.push(rollbackError) + } + } + if (rollbackErrors.length > 0) { + throw new PackageInstallerRollbackIncompleteError( + [error, ...rollbackErrors], + 'Package commit failed and managed state could not be fully restored', + { cause: error } + ) + } + throw error } } diff --git a/src/main/remote-agent/host-activation-coordinator.ts b/src/main/remote-agent/host-activation-coordinator.ts new file mode 100644 index 00000000..3da29764 --- /dev/null +++ b/src/main/remote-agent/host-activation-coordinator.ts @@ -0,0 +1,255 @@ +import { settleBoundedly } from './bounded-settlement' + +const DISPOSE_WAIT_TIMEOUT_MS = 5_000 + +type ActiveActivation = { + promise: Promise + controller: AbortController + progressCallbacks: Set<(phase: TPhase) => void> + waiters: number + settled: boolean +} + +export class HostActivationCoordinator< + TValue, + TPhase extends string +> { + readonly #maximumConcurrentHosts: number + readonly #capacityError: () => Error + readonly #disposeMessage: string + readonly #active = + new Map>() + readonly #current = new Map< + string, + { + targetKey: string + variantKey: string + value: TValue + } + >() + readonly #cacheGenerations = new Map() + #closed = false + #disposePromise: Promise | undefined + + constructor(options: { + maximumConcurrentHosts?: number + capacityError: () => Error + disposeMessage: string + }) { + this.#maximumConcurrentHosts = + options.maximumConcurrentHosts ?? 8 + this.#capacityError = options.capacityError + this.#disposeMessage = options.disposeMessage + if ( + !Number.isSafeInteger(this.#maximumConcurrentHosts) || + this.#maximumConcurrentHosts <= 0 || + this.#maximumConcurrentHosts > 32 + ) { + throw new Error( + 'Host activation concurrency limit is invalid' + ) + } + } + + assertAvailable(): void { + if (this.#closed) { + throw new Error(this.#disposeMessage) + } + } + + cached( + hostId: string, + targetKey: string, + variantKey: string + ): TValue | undefined { + this.assertAvailable() + const cached = this.#current.get(hostId) + return ( + cached?.targetKey === targetKey && + cached.variantKey === variantKey + ) + ? cached.value + : undefined + } + + cachedForHost( + hostId: string, + variantKey: string + ): TValue | undefined { + this.assertAvailable() + const cached = this.#current.get(hostId) + return cached?.variantKey === variantKey + ? cached.value + : undefined + } + + run(options: { + hostId: string + targetKey: string + variantKey: string + signal?: AbortSignal + onProgress?: (phase: TPhase) => void + operation: ( + signal: AbortSignal, + progress: (phase: TPhase) => void + ) => Promise + }): Promise { + this.assertAvailable() + options.signal?.throwIfAborted() + const operationKey = + `${options.targetKey}\0${options.variantKey}` + const existing = this.#active.get(operationKey) + if (existing) { + return this.#waitForActive(existing, options) + } + if (this.#active.size >= this.#maximumConcurrentHosts) { + throw this.#capacityError() + } + + const cacheGeneration = + this.#cacheGenerations.get(options.hostId) ?? 0 + const progressCallbacks = new Set< + (phase: TPhase) => void + >() + if (options.onProgress) { + progressCallbacks.add(options.onProgress) + } + const progress = (phase: TPhase): void => { + for (const callback of progressCallbacks) { + emitProgress(callback, phase) + } + } + const controller = new AbortController() + const promise = options.operation( + controller.signal, + progress + ).then((value) => { + if ( + (this.#cacheGenerations.get(options.hostId) ?? 0) === + cacheGeneration + ) { + this.#current.set(options.hostId, { + targetKey: options.targetKey, + variantKey: options.variantKey, + value + }) + } + return value + }) + const active: ActiveActivation = { + promise, + controller, + progressCallbacks, + waiters: 0, + settled: false + } + this.#active.set(operationKey, active) + void promise.finally(() => { + active.settled = true + if (this.#active.get(operationKey) === active) { + this.#active.delete(operationKey) + } + }).catch(() => undefined) + return this.#waitForActive(active, options) + } + + invalidate(hostId: string): void { + this.#current.delete(hostId) + this.#cacheGenerations.set( + hostId, + (this.#cacheGenerations.get(hostId) ?? 0) + 1 + ) + } + + dispose(): Promise { + if (this.#disposePromise) { + return this.#disposePromise + } + this.#closed = true + this.#current.clear() + this.#cacheGenerations.clear() + const operations = [...this.#active.values()] + const reason = new DOMException( + this.#disposeMessage, + 'AbortError' + ) + for (const operation of operations) { + operation.controller.abort(reason) + } + this.#disposePromise = settleBoundedly( + operations.map((operation) => operation.promise), + DISPOSE_WAIT_TIMEOUT_MS + ) + return this.#disposePromise + } + + async #waitForActive( + active: ActiveActivation, + options: { + signal?: AbortSignal + onProgress?: (phase: TPhase) => void + } + ): Promise { + active.waiters += 1 + if (options.onProgress) { + active.progressCallbacks.add(options.onProgress) + } + try { + return await waitForOperation( + active.promise, + options.signal + ) + } finally { + if (options.onProgress) { + active.progressCallbacks.delete(options.onProgress) + } + active.waiters -= 1 + if ( + active.waiters === 0 && + !active.settled && + !active.controller.signal.aborted + ) { + active.controller.abort( + new DOMException( + 'Host activation has no remaining waiters', + 'AbortError' + ) + ) + } + } + } +} + +function emitProgress( + callback: (phase: TPhase) => void, + phase: TPhase +): void { + try { + callback(phase) + } catch { + // Progress observers cannot alter activation state. + } +} + +function waitForOperation( + operation: Promise, + signal?: AbortSignal +): Promise { + if (!signal) { + return operation + } + signal.throwIfAborted() + return new Promise((resolve, reject) => { + const abort = (): void => reject( + signal.reason ?? + new DOMException( + 'The operation was aborted', + 'AbortError' + ) + ) + signal.addEventListener('abort', abort, { once: true }) + void operation.then(resolve, reject).finally(() => { + signal.removeEventListener('abort', abort) + }) + }) +} diff --git a/src/main/remote-agent/managed-remote-execution-services.ts b/src/main/remote-agent/managed-remote-execution-services.ts index 6977866d..94fdf8eb 100644 --- a/src/main/remote-agent/managed-remote-execution-services.ts +++ b/src/main/remote-agent/managed-remote-execution-services.ts @@ -21,13 +21,11 @@ import { RemoteRuntimeInstallationManager, type RemoteRuntimeActivator } from './remote-runtime-installation-manager' -import { - loadRemoteRuntimeVerificationMetadata -} from './remote-runtime-resource-loader' import { createManagedModelBridge, reconcileStartupModelCalls } from './managed-model-bridge' +import { boundedDiagnostic } from './bounded-diagnostic' const RUNTIME_BINDING_DATABASE_NAME = 'remote-runtime-bindings.sqlite' const MODEL_CALL_DATABASE_NAME = 'remote-model-calls-v2.sqlite' @@ -101,19 +99,9 @@ export class ManagedRemoteExecutionServices { ) ).installationId signal.throwIfAborted() - const current = await options.agentServices.targetResolver.resolve( - lease.identity.hostId - ) - signal.throwIfAborted() - if ( - runtimeId !== 'opencode' || - current.host.id !== lease.identity.hostId || - current.hostRevision !== lease.identity.hostRevision || - current.hostKeyGeneration !== - lease.identity.hostKeyGeneration - ) { + if (runtimeId !== 'opencode') { throw new Error( - 'Remote Agent or SSH host identity changed before Runtime activation' + 'Remote Runtime identity is unsupported' ) } const result = await lease.runAgentRuntimeAction( @@ -127,17 +115,20 @@ export class ManagedRemoteExecutionServices { signal ) if (result.exitCode !== 0) { - throw new Error('Remote Runtime activation failed') + const detail = boundedDiagnostic( + `${result.stderr}\n${result.stdout}` + ) + throw new Error( + detail.length > 0 + ? `Remote Runtime activation failed: ${detail}` + : `Remote Runtime activation failed (exit ${String(result.exitCode)})` + ) } } this.runtimeInstallationManager = new RemoteRuntimeInstallationManager({ resolver: options.agentServices.targetResolver, sshPool: options.agentServices.sshPool, - loadVerificationMetadata: () => - loadRemoteRuntimeVerificationMetadata( - this.runtimeResourcePaths - ), activate }) this.runtimeValidator = new ManagedRemoteProjectRuntimeValidator({ diff --git a/src/main/remote-agent/remote-environment-operation-store.test.ts b/src/main/remote-agent/remote-environment-operation-store.test.ts index 040536bc..d9ac1773 100644 --- a/src/main/remote-agent/remote-environment-operation-store.test.ts +++ b/src/main/remote-agent/remote-environment-operation-store.test.ts @@ -42,6 +42,39 @@ describe('RemoteEnvironmentOperationStore', () => { await expect(store.load(operation.hostId)).resolves.toBeUndefined() }) + it('persists bounded metadata snapshots for post-commit recovery', async () => { + const root = await mkdtemp( + join(tmpdir(), 'goodbuddy-environment-operation-') + ) + temporaryDirectories.push(root) + const store = new RemoteEnvironmentOperationStore(root) + const recovered: PendingRemoteEnvironmentOperation = { + ...operation, + version: 2, + metadataSnapshots: [ + '.goodbuddy/agent/release-keys.json', + '.goodbuddy/agent/registry.json', + '.goodbuddy/runtimes/release-keys.json', + '.goodbuddy/runtimes/remote-runtime-lock.json', + '.goodbuddy/runtimes/registry.json' + ].map((path, index) => ({ + path: path as never, + uid: 1000, + ...(index === 1 + ? {} + : { + contentsBase64: + Buffer.from(`metadata-${index}`).toString('base64') + }) + })) + } + + await store.save(recovered) + await expect(store.load(operation.hostId)).resolves.toEqual( + recovered + ) + }) + it('rejects a mismatched or oversized recovery record', async () => { const root = await mkdtemp( join(tmpdir(), 'goodbuddy-environment-operation-') @@ -58,7 +91,7 @@ describe('RemoteEnvironmentOperationStore', () => { const [record] = await readdir(files) await writeFile( join(files, record!), - Buffer.alloc(64 * 1024 + 1) + Buffer.alloc(8 * 1024 * 1024 + 1) ) await expect(store.load(operation.hostId)).rejects.toThrow( diff --git a/src/main/remote-agent/remote-environment-operation-store.ts b/src/main/remote-agent/remote-environment-operation-store.ts index 65159f0b..a1d723c5 100644 --- a/src/main/remote-agent/remote-environment-operation-store.ts +++ b/src/main/remote-agent/remote-environment-operation-store.ts @@ -6,13 +6,12 @@ import { writeJsonFileAtomically } from '../settings-file-utils' -const MAXIMUM_RECORD_BYTES = 64 * 1024 +const MAXIMUM_RECORD_BYTES = 8 * 1024 * 1024 const OPERATION_ID_PATTERN = /^[0-9a-f]{8}-[0-9a-f]{4}-[1-5][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/u const SHA256_PATTERN = /^[a-f0-9]{64}$/u -export type PendingRemoteEnvironmentOperation = { - version: 1 +type PendingRemoteEnvironmentOperationBase = { hostId: string targetIdentity: string operationId: string @@ -21,6 +20,28 @@ export type PendingRemoteEnvironmentOperation = { urls: readonly string[] } +export type PersistedRemoteEnvironmentMetadataSnapshot = { + path: + | '.goodbuddy/agent/release-keys.json' + | '.goodbuddy/agent/registry.json' + | '.goodbuddy/runtimes/release-keys.json' + | '.goodbuddy/runtimes/remote-runtime-lock.json' + | '.goodbuddy/runtimes/registry.json' + contentsBase64?: string + uid: number +} + +export type PendingRemoteEnvironmentOperation = + PendingRemoteEnvironmentOperationBase & + ( + | { version: 1 } + | { + version: 2 + metadataSnapshots: + readonly PersistedRemoteEnvironmentMetadataSnapshot[] + } + ) + export class RemoteEnvironmentOperationStore { readonly #directory: string @@ -91,11 +112,23 @@ function parsePendingOperation( value: unknown, expectedHostId: string ): PendingRemoteEnvironmentOperation { - if ( - typeof value !== 'object' || - value === null || - Object.keys(value).sort().join('\0') !== - [ + if (typeof value !== 'object' || value === null) { + throw new Error('远程环境恢复记录无效') + } + const record = value as Record + const version = record.version + const expectedKeys = version === 2 + ? [ + 'hostId', + 'metadataSnapshots', + 'operationId', + 'sha256', + 'size', + 'targetIdentity', + 'urls', + 'version' + ] + : [ 'hostId', 'operationId', 'sha256', @@ -103,13 +136,15 @@ function parsePendingOperation( 'targetIdentity', 'urls', 'version' - ].sort().join('\0') + ] + if ( + Object.keys(value).sort().join('\0') !== + expectedKeys.sort().join('\0') ) { throw new Error('远程环境恢复记录无效') } - const record = value as Record if ( - record.version !== 1 || + (version !== 1 && version !== 2) || record.hostId !== expectedHostId || typeof record.targetIdentity !== 'string' || !SHA256_PATTERN.test(record.targetIdentity) || @@ -129,8 +164,7 @@ function parsePendingOperation( ) { throw new Error('远程环境恢复记录无效') } - return { - version: 1, + const base: PendingRemoteEnvironmentOperationBase = { hostId: expectedHostId, targetIdentity: record.targetIdentity, operationId: record.operationId, @@ -138,4 +172,100 @@ function parsePendingOperation( sha256: record.sha256, urls: [...record.urls] as string[] } + if (version === 1) { + return { version: 1, ...base } + } + return { + version: 2, + ...base, + metadataSnapshots: parseMetadataSnapshots( + record.metadataSnapshots + ) + } +} + +const metadataPaths = + new Set([ + '.goodbuddy/agent/release-keys.json', + '.goodbuddy/agent/registry.json', + '.goodbuddy/runtimes/release-keys.json', + '.goodbuddy/runtimes/remote-runtime-lock.json', + '.goodbuddy/runtimes/registry.json' + ]) + +function parseMetadataSnapshots( + value: unknown +): readonly PersistedRemoteEnvironmentMetadataSnapshot[] { + if (!Array.isArray(value) || value.length !== metadataPaths.size) { + throw new Error('远程环境恢复记录无效') + } + const paths = new Set() + let totalBytes = 0 + const snapshots = value.map((item) => { + if ( + typeof item !== 'object' || + item === null || + !( + Object.keys(item).sort().join('\0') === + ['path', 'uid'].sort().join('\0') || + Object.keys(item).sort().join('\0') === + ['contentsBase64', 'path', 'uid'].sort().join('\0') + ) + ) { + throw new Error('远程环境恢复记录无效') + } + const snapshot = item as Record + if ( + typeof snapshot.path !== 'string' || + !metadataPaths.has( + snapshot.path as PersistedRemoteEnvironmentMetadataSnapshot['path'] + ) || + paths.has(snapshot.path) || + !Number.isSafeInteger(snapshot.uid) || + Number(snapshot.uid) < 0 + ) { + throw new Error('远程环境恢复记录无效') + } + paths.add(snapshot.path) + if (snapshot.contentsBase64 === undefined) { + return { + path: + snapshot.path as PersistedRemoteEnvironmentMetadataSnapshot['path'], + uid: Number(snapshot.uid) + } + } + if ( + typeof snapshot.contentsBase64 !== 'string' || + !/^(?:[A-Za-z0-9+/]{4})*(?:[A-Za-z0-9+/]{2}==|[A-Za-z0-9+/]{3}=)?$/u + .test(snapshot.contentsBase64) + ) { + throw new Error('远程环境恢复记录无效') + } + const contents = Buffer.from( + snapshot.contentsBase64, + 'base64' + ) + if ( + contents.toString('base64') !== + snapshot.contentsBase64 || + contents.byteLength > 1024 * 1024 + ) { + throw new Error('远程环境恢复记录无效') + } + totalBytes += contents.byteLength + return { + path: + snapshot.path as PersistedRemoteEnvironmentMetadataSnapshot['path'], + contentsBase64: snapshot.contentsBase64, + uid: Number(snapshot.uid) + } + }) + if ( + paths.size !== metadataPaths.size || + [...metadataPaths].some((path) => !paths.has(path)) || + totalBytes > 5 * 1024 * 1024 + ) { + throw new Error('远程环境恢复记录无效') + } + return snapshots } diff --git a/src/main/remote-agent/remote-environment-preparer.test.ts b/src/main/remote-agent/remote-environment-preparer.test.ts index b02f9a24..b6997848 100644 --- a/src/main/remote-agent/remote-environment-preparer.test.ts +++ b/src/main/remote-agent/remote-environment-preparer.test.ts @@ -100,6 +100,8 @@ type FixtureOptions = { prepare?: ReturnType prepareUploaded?: ReturnType commit?: ReturnType + commitStatus?: ReturnType + cleanup?: ReturnType uploadFile?: ReturnType activateAgent?: ReturnType activateRuntime?: ReturnType @@ -200,9 +202,22 @@ function fixture(options: FixtureOptions = {}) { close: vi.fn(() => calls.push('close-upload')) } const regularRelease = vi.fn(() => calls.push('release-probe')) - const stopCandidate = vi.fn(async () => { + const stopCandidate = vi.fn(async ( + _installationId?: string, + _action?: string + ) => { + void _installationId + void _action calls.push('stop-candidate') }) + const activateAgent = options.activateAgent ?? vi.fn(async () => { + calls.push('agent') + return { exitCode: 0, stdout: '{}', stderr: '' } + }) + const activateRuntime = options.activateRuntime ?? vi.fn(async () => { + calls.push('runtime') + return { exitCode: 0, stdout: '{}', stderr: '' } + }) const regularLease = { identity: leaseIdentity, isUsable: vi.fn(() => true), @@ -226,7 +241,26 @@ function fixture(options: FixtureOptions = {}) { calls.push('open-metadata') return metadata }), - runAgentLifecycleAction: stopCandidate, + runAgentLifecycleAction: vi.fn(async ( + installationId: string, + action: string + ) => { + if (action === 'stop') { + await stopCandidate(installationId, action) + return { exitCode: 0, stdout: '{}', stderr: '' } + } + return (activateAgent as ( + installationId: string, + action: string + ) => Promise)(installationId, action) + }), + runAgentRuntimeAction: vi.fn(async ( + installationId: string, + action: unknown + ) => (activateRuntime as ( + installationId: string, + action: unknown + ) => Promise)(installationId, action)), release: regularRelease } const prepare = options.prepare ?? vi.fn(async ( @@ -264,11 +298,11 @@ function fixture(options: FixtureOptions = {}) { identity: structuredClone(identity) } }) - const cleanup = vi.fn(async (operationId: string) => { + const cleanup = options.cleanup ?? vi.fn(async (operationId: string) => { calls.push('cleanup') return { cleaned: true, operationId } }) - const commitStatus = vi.fn(async ( + const commitStatus = options.commitStatus ?? vi.fn(async ( input: { operationId: string } ) => ({ committed: true, @@ -326,13 +360,6 @@ function fixture(options: FixtureOptions = {}) { calls.push('acquire-archive') return archive }) - const activateAgent = options.activateAgent ?? vi.fn(async () => { - calls.push('agent') - return identity.agent - }) - const activateRuntime = options.activateRuntime ?? vi.fn(async () => { - calls.push('runtime') - }) let pendingOperation = options.pendingOperation const operationStore = { load: vi.fn(async () => pendingOperation), @@ -367,12 +394,6 @@ function fixture(options: FixtureOptions = {}) { acquireInstallArchive, acquireGoodBuddyInstallArchive }, - agentInstallationManager: { - activatePublished: activateAgent - } as never, - runtimeInstallationManager: { - activatePublished: activateRuntime - } as never, operationStore }) return { @@ -425,13 +446,11 @@ describe('RemoteEnvironmentPreparer', () => { 'save-operation', 'prepare', 'open-metadata', + 'save-operation', 'resolve', 'commit', - 'resolve', 'agent', - 'resolve', 'runtime', - 'resolve', 'cleanup', 'remove-operation', 'close-metadata', @@ -447,23 +466,24 @@ describe('RemoteEnvironmentPreparer', () => { expect(remoteCandidate.operationId).toMatch(/^[0-9a-f-]{36}$/u) expect(value.commit.mock.calls[0]?.[0]).toEqual(remoteCandidate) expect(value.activateAgent).toHaveBeenCalledWith( - HOST_ID, - identity.agent, - expect.objectContaining({ signal: controller.signal }) + identity.agent.installationId, + 'adopt' ) expect(value.activateRuntime).toHaveBeenCalledWith( - HOST_ID, - identity.runtime, - expect.objectContaining({ - agentInstallationId: identity.agent.installationId, - signal: controller.signal - }) + identity.agent.installationId, + { + kind: 'runtime-activate', + runtimeId: identity.runtime.runtimeId, + bundleDigest: identity.runtime.bundleDigest, + architecture: identity.runtime.architecture, + forceVerification: true + } ) expect(value.cleanup).toHaveBeenCalledWith( remoteCandidate.operationId, { signal: controller.signal } ) - expect(value.operationStore.save).toHaveBeenCalledOnce() + expect(value.operationStore.save).toHaveBeenCalledTimes(2) expect(value.operationStore.remove).toHaveBeenCalledOnce() expect(progress.some((event) => event.method === 'remote-download' && @@ -495,6 +515,27 @@ describe('RemoteEnvironmentPreparer', () => { expect(value.archiveRelease).toHaveBeenCalledOnce() }) + it('keeps an adopted environment healthy when staging cleanup must be retried', async () => { + const value = fixture({ + cleanup: vi.fn(async (operationId: string) => ({ + cleaned: false, + operationId, + reason: 'cleanup-failed' + })) + }) + + await expect(value.preparer.prepare( + HOST_ID, + 'remote-download', + undefined, + new AbortController().signal + )).resolves.toBeUndefined() + expect(value.activateAgent).toHaveBeenCalledOnce() + expect(value.activateRuntime).toHaveBeenCalledOnce() + expect(value.stopCandidate).not.toHaveBeenCalled() + expect(value.operationStore.remove).not.toHaveBeenCalled() + }) + it('releases the archive and cleans the operation when a GoodBuddy upload fails', async () => { const uploadFailure = new Error('upload failed') const value = fixture({ @@ -684,12 +725,39 @@ describe('RemoteEnvironmentPreparer', () => { new AbortController().signal )).rejects.toBeInstanceOf(SshRemotePackageCommitIndeterminateError) expect(value.cleanup).not.toHaveBeenCalled() - expect(value.operationStore.save).toHaveBeenCalledOnce() + expect(value.operationStore.save).toHaveBeenCalledTimes(2) expect(value.operationStore.remove).not.toHaveBeenCalled() expect(value.activateAgent).not.toHaveBeenCalled() expect(value.activateRuntime).not.toHaveBeenCalled() }) + it('rolls metadata back when cancellation arrives with a successful commit result', async () => { + const controller = new AbortController() + const cancellation = + new DOMException('cancelled after commit', 'AbortError') + const value = fixture({ + commit: vi.fn(async (input: { operationId: string }) => { + controller.abort(cancellation) + return { + committed: true, + operationId: input.operationId, + identity + } + }) + }) + + await expect(value.preparer.prepare( + HOST_ID, + 'remote-download', + undefined, + controller.signal + )).rejects.toBe(cancellation) + expect(value.stopCandidate).toHaveBeenCalledOnce() + expect(value.cleanup).toHaveBeenCalledOnce() + expect(value.operationStore.remove).toHaveBeenCalledOnce() + expect(value.activateAgent).not.toHaveBeenCalled() + }) + it('keeps rollback-incomplete commits recoverable without cleanup', async () => { const value = fixture({ commit: vi.fn(async () => ({ @@ -710,7 +778,7 @@ describe('RemoteEnvironmentPreparer', () => { expect(value.operationStore.remove).not.toHaveBeenCalled() }) - it('reconciles and cleans a pending commit before starting new work', async () => { + it('resumes adoption for a committed operation instead of reinstalling it', async () => { const pendingOperationId = '00000000-0000-4000-8000-000000000777' const originalTarget = target() @@ -724,14 +792,21 @@ describe('RemoteEnvironmentPreparer', () => { const value = fixture({ targets: [renamedTarget], pendingOperation: { - version: 1, + version: 2, hostId: HOST_ID, targetIdentity: remoteHostRecoveryIdentityKey(originalTarget), operationId: pendingOperationId, size: candidate.size, sha256: candidate.sha256, - urls: candidate.urls + urls: candidate.urls, + metadataSnapshots: + REMOTE_ENVIRONMENT_METADATA_PATHS.map( + (path) => ({ + path, + uid: 1000 + }) + ) } }) @@ -751,10 +826,158 @@ describe('RemoteEnvironmentPreparer', () => { expect(value.cleanup.mock.calls[0]?.[0]).toBe( pendingOperationId ) + expect(value.activateAgent).toHaveBeenCalledOnce() + expect(value.activateRuntime).toHaveBeenCalledOnce() + expect(value.prepare).not.toHaveBeenCalled() + expect(value.operationStore.remove).toHaveBeenCalledOnce() + }) + + it('cleans a legacy pending operation and starts a fresh authenticated prepare', async () => { + const originalTarget = target() + const pendingOperationId = + '00000000-0000-4000-8000-000000000780' + const value = fixture({ + targets: [originalTarget], + pendingOperation: { + version: 1, + hostId: HOST_ID, + targetIdentity: + remoteHostRecoveryIdentityKey(originalTarget), + operationId: pendingOperationId, + size: candidate.size, + sha256: candidate.sha256, + urls: candidate.urls + } + }) + + await value.preparer.prepare( + HOST_ID, + 'remote-download', + undefined, + new AbortController().signal + ) + + expect(value.commitStatus).not.toHaveBeenCalled() + expect(value.cleanup.mock.calls[0]?.[0]).toBe( + pendingOperationId + ) expect(value.prepare).toHaveBeenCalledOnce() expect(value.operationStore.remove).toHaveBeenCalledTimes(2) }) + it('restores the durable snapshot when resumed commit does not complete', async () => { + const originalTarget = target() + const originals = new Map( + REMOTE_ENVIRONMENT_METADATA_PATHS.map( + (path, index) => [ + path, + Buffer.from(`before-commit-${index}`) + ] + ) + ) + const files = new Map( + REMOTE_ENVIRONMENT_METADATA_PATHS.map( + (path) => [path, Buffer.from('partial-commit')] + ) + ) + const value = fixture({ + targets: [originalTarget], + metadataFiles: files, + pendingOperation: { + version: 2, + hostId: HOST_ID, + targetIdentity: + remoteHostRecoveryIdentityKey(originalTarget), + operationId: + '00000000-0000-4000-8000-000000000781', + size: candidate.size, + sha256: candidate.sha256, + urls: candidate.urls, + metadataSnapshots: [...originals].map( + ([path, contents]) => ({ + path: path as never, + uid: 1000, + contentsBase64: contents.toString('base64') + }) + ) + }, + commitStatus: vi.fn(async () => ({ + committed: false, + reason: 'installer-failed' + })) + }) + + await value.preparer.prepare( + HOST_ID, + 'remote-download', + undefined, + new AbortController().signal + ) + + expect([...files]).toEqual([...originals]) + expect(value.prepare).toHaveBeenCalledOnce() + }) + + it('restores persisted pre-commit metadata when resumed Runtime adoption fails', async () => { + const originalTarget = target() + const originals = new Map( + REMOTE_ENVIRONMENT_METADATA_PATHS.map( + (path, index) => [ + path, + Buffer.from(`original-${index}`) + ] + ) + ) + const files = new Map( + REMOTE_ENVIRONMENT_METADATA_PATHS.map( + (path) => [path, Buffer.from('published')] + ) + ) + const runtimeFailure = new Error('runtime recovery failed') + const value = fixture({ + targets: [originalTarget], + metadataFiles: files, + pendingOperation: { + version: 2, + hostId: HOST_ID, + targetIdentity: + remoteHostRecoveryIdentityKey(originalTarget), + operationId: + '00000000-0000-4000-8000-000000000779', + size: candidate.size, + sha256: candidate.sha256, + urls: candidate.urls, + metadataSnapshots: [...originals].map( + ([path, contents]) => ({ + path: path as never, + uid: 1000, + contentsBase64: contents.toString('base64') + }) + ) + }, + activateAgent: vi.fn(async () => { + for (const path of REMOTE_ENVIRONMENT_METADATA_PATHS) { + files.set(path, Buffer.from('adopting')) + } + return { exitCode: 0, stdout: '{}', stderr: '' } + }), + activateRuntime: vi.fn(async () => { + throw runtimeFailure + }) + }) + + await expect(value.preparer.prepare( + HOST_ID, + 'remote-download', + undefined, + new AbortController().signal + )).rejects.toThrow('runtime recovery failed') + expect([...files]).toEqual([...originals]) + expect(value.stopCandidate).toHaveBeenCalledOnce() + expect(value.cleanup).not.toHaveBeenCalled() + expect(value.operationStore.remove).not.toHaveBeenCalled() + }) + it('retains pending recovery evidence when the real SSH target changes', async () => { const originalTarget = target() const changedTarget = target({ @@ -802,12 +1025,12 @@ describe('RemoteEnvironmentPreparer', () => { const value = fixture({ metadataFiles: files, activateAgent: vi.fn(async () => { + value.calls.push('agent') value.metadataFiles.clear() for (const path of REMOTE_ENVIRONMENT_METADATA_PATHS) { value.metadataFiles.set(path, Buffer.from('new')) } - return identity.agent - value.calls.push('agent') + return { exitCode: 0, stdout: '{}', stderr: '' } }), activateRuntime: vi.fn(async () => { throw runtimeFailure @@ -838,7 +1061,7 @@ describe('RemoteEnvironmentPreparer', () => { metadataReplaceFailure: rollbackFailure, activateAgent: vi.fn(async () => { files.set(path, Buffer.from('changed')) - return identity.agent + return { exitCode: 0, stdout: '{}', stderr: '' } }), activateRuntime: vi.fn(async () => { throw runtimeFailure diff --git a/src/main/remote-agent/remote-environment-preparer.ts b/src/main/remote-agent/remote-environment-preparer.ts index a69f688a..e683ed9d 100644 --- a/src/main/remote-agent/remote-environment-preparer.ts +++ b/src/main/remote-agent/remote-environment-preparer.ts @@ -8,6 +8,7 @@ import type { import type { StagedSftp } from '../ssh/bounded-sftp' import { verifyAgentInstallationId } from '../ssh/ssh-agent-command' import type { + AgentDiagnosticResult, SshConnectionLease, SshConnectionPool, SshRemotePackageBootstrapLease @@ -25,7 +26,6 @@ import { type SshRemotePackageIdentity } from '../ssh/ssh-remote-package-bootstrap' import type { - AgentInstallationManager, AgentInstallationTargetResolver } from './agent-installation-manager' import type { @@ -38,26 +38,41 @@ import { snapshotRemoteEnvironmentMetadata, type RemoteEnvironmentMetadataSnapshot } from './remote-environment-metadata' -import { - mapAgentInstallationPhase, - mapRuntimeInstallationPhase -} from './remote-environment-progress' import type { + PersistedRemoteEnvironmentMetadataSnapshot, RemoteEnvironmentOperationStore } from './remote-environment-operation-store' import type { RemoteEnvironmentPreparer as Preparer, RemoteEnvironmentUpdateProgressObserver } from './remote-environment-update-service' -import type { - RemoteRuntimeInstallationManager -} from './remote-runtime-installation-manager' import { remoteHostRecoveryIdentityKey } from './remote-host-target-identity' +import { boundedDiagnostic } from './bounded-diagnostic' const MAXIMUM_PACKAGE_BYTES = 512 * 1024 * 1024 const MAXIMUM_METADATA_BYTES = 1024 * 1024 +const MAXIMUM_DIAGNOSTIC_CHARACTERS = 800 + +function assertAgentCommandSucceeded( + result: AgentDiagnosticResult, + label: string +): void { + if (result.exitCode === 0) { + return + } + const detail = `${result.stderr}\n${result.stdout}` + const bounded = boundedDiagnostic( + detail, + MAXIMUM_DIAGNOSTIC_CHARACTERS + ) + throw new Error( + bounded.length > 0 + ? `${label}失败：${bounded}` + : `${label}失败，退出码 ${String(result.exitCode)}` + ) +} export type RemoteEnvironmentPreparerOptions = { resolver: AgentInstallationTargetResolver @@ -71,14 +86,6 @@ export type RemoteEnvironmentPreparerOptions = { | 'acquireInstallArchive' | 'acquireGoodBuddyInstallArchive' > - agentInstallationManager: Pick< - AgentInstallationManager, - 'activatePublished' - > - runtimeInstallationManager: Pick< - RemoteRuntimeInstallationManager, - 'activatePublished' - > operationStore: Pick< RemoteEnvironmentOperationStore, 'load' | 'save' | 'remove' @@ -95,10 +102,6 @@ export class RemoteEnvironmentPreparer implements Preparer { readonly #sshPool: RemoteEnvironmentPreparerOptions['sshPool'] readonly #agentPackageManager: RemoteEnvironmentPreparerOptions['agentPackageManager'] - readonly #agentInstallationManager: - RemoteEnvironmentPreparerOptions['agentInstallationManager'] - readonly #runtimeInstallationManager: - RemoteEnvironmentPreparerOptions['runtimeInstallationManager'] readonly #operationStore: RemoteEnvironmentPreparerOptions['operationStore'] @@ -106,10 +109,6 @@ export class RemoteEnvironmentPreparer implements Preparer { this.#resolver = options.resolver this.#sshPool = options.sshPool this.#agentPackageManager = options.agentPackageManager - this.#agentInstallationManager = - options.agentInstallationManager - this.#runtimeInstallationManager = - options.runtimeInstallationManager this.#operationStore = options.operationStore } @@ -135,12 +134,15 @@ export class RemoteEnvironmentPreparer implements Preparer { const target = await this.#resolver.resolve(hostId) signal.throwIfAborted() assertValidSshConnectionTarget(hostId, target) - await this.#reconcilePendingOperation( + const recovered = await this.#reconcilePendingOperation( hostId, target, emit, signal ) + if (recovered) { + return + } let probeLease: SshConnectionLease | undefined let bootstrapLease: @@ -304,6 +306,17 @@ export class RemoteEnvironmentPreparer implements Preparer { probe.uid, signal ) + await this.#operationStore.save({ + version: 2, + hostId, + targetIdentity: remoteHostRecoveryIdentityKey(target), + operationId, + size: remoteCandidate.size, + sha256: remoteCandidate.sha256, + urls: [...remoteCandidate.urls], + metadataSnapshots: + persistMetadataSnapshots(metadataSnapshots) + }) // Keep the full target re-resolution immediately adjacent to commit. await assertTargetCurrent(this.#resolver, target, signal) @@ -319,7 +332,6 @@ export class RemoteEnvironmentPreparer implements Preparer { } } ) - signal.throwIfAborted() if (!committed.committed) { if ( committed.reason === @@ -330,7 +342,7 @@ export class RemoteEnvironmentPreparer implements Preparer { ) } throw new Error( - `远端安装提交失败：${committed.reason}` + `远端安装提交失败：${committed.detail ?? committed.reason}` ) } if ( @@ -344,52 +356,34 @@ export class RemoteEnvironmentPreparer implements Preparer { } assertPackageIdentity(committed.identity, candidate) committedIdentity = committed.identity - - await assertTargetCurrent(this.#resolver, target, signal) - const activeAgent = - await this.#agentInstallationManager.activatePublished( - hostId, - committed.identity.agent, - { - signal, - onProgress: (phase) => { - const mapped = mapAgentInstallationPhase(phase) - if (mapped) { - emit(method, mapped) - } - } - } - ) signal.throwIfAborted() - await assertTargetCurrent(this.#resolver, target, signal) - await this.#runtimeInstallationManager.activatePublished( - hostId, - committed.identity.runtime, - { - agentInstallationId: activeAgent.installationId, - signal, - onProgress: (phase) => { - const mapped = mapRuntimeInstallationPhase(phase) - if (mapped) { - emit(method, mapped) - } - } - } - ) - signal.throwIfAborted() - await assertTargetCurrent(this.#resolver, target, signal) - - const cleanup = await bootstrapLease.cleanup(operationId, { + await this.#adoptCommittedEnvironment( + probeLease, + committed.identity, + method, + emit, signal - }) - if (!cleanup.cleaned) { - throw new Error( - `远程环境已安装，但暂存文件清理失败：${cleanup.reason}` + ) + + emit(method, 'finalizing') + try { + const cleanup = await bootstrapLease.cleanup( + operationId, + { signal } ) + if (cleanup.cleaned) { + operationCleaned = true + try { + await this.#operationStore.remove(hostId) + } catch { + // A stale local receipt is harmless after remote cleanup. + } + } + } catch { + // The environment is already healthy. Leave the bounded + // operation for a later maintenance retry. } - operationCleaned = true - await this.#operationStore.remove(hostId) } catch (error) { let rollbackError: unknown if ( @@ -440,6 +434,48 @@ export class RemoteEnvironmentPreparer implements Preparer { } } + async #adoptCommittedEnvironment( + lease: SshConnectionLease, + identity: SshRemotePackageIdentity, + method: RemoteEnvironmentPreparationMethod, + emit: ( + method: RemoteEnvironmentPreparationMethod, + phase: RemoteEnvironmentUpdateProgress['phase'] + ) => void, + signal: AbortSignal + ): Promise { + const installationId = verifyAgentInstallationId( + identity.agent.installationId + ) + emit(method, 'installing-agent') + assertAgentCommandSucceeded( + await lease.runAgentLifecycleAction( + installationId, + 'adopt', + signal + ), + 'GoodBuddy Agent 启动与健康检查' + ) + signal.throwIfAborted() + + emit(method, 'installing-runtime') + assertAgentCommandSucceeded( + await lease.runAgentRuntimeAction( + installationId, + { + kind: 'runtime-activate', + runtimeId: identity.runtime.runtimeId, + bundleDigest: identity.runtime.bundleDigest, + architecture: identity.runtime.architecture, + forceVerification: true + }, + signal + ), + 'OpenCode Runtime 激活' + ) + signal.throwIfAborted() + } + async #prepareUploadedArchive(options: { probeLease: SshConnectionLease bootstrapLease: SshRemotePackageBootstrapLease @@ -567,10 +603,10 @@ export class RemoteEnvironmentPreparer implements Preparer { phase: RemoteEnvironmentUpdateProgress['phase'] ) => void, signal: AbortSignal - ): Promise { + ): Promise { const pending = await this.#operationStore.load(hostId) if (!pending) { - return + return false } if ( pending.targetIdentity !== @@ -587,16 +623,42 @@ export class RemoteEnvironmentPreparer implements Preparer { sha256: pending.sha256, urls: pending.urls } - const lease = + const bootstrapLease = await this.#sshPool.acquireRemotePackageBootstrap( target, signal ) + let commandLease: SshConnectionLease | undefined + let recoveryMetadataSftp: StagedSftp | undefined try { - assertLeaseMatchesTarget(lease, target) - const status = await lease.commitStatus(candidate, { - signal - }) + assertLeaseMatchesTarget(bootstrapLease, target) + if (pending.version === 1) { + const cleanup = await bootstrapLease.cleanup( + pending.operationId, + { signal } + ) + if ( + !cleanup.cleaned && + cleanup.reason !== 'operation-unavailable' + ) { + throw new Error( + `旧版远程环境暂存清理失败：${cleanup.reason}` + ) + } + await this.#operationStore.remove(hostId) + return false + } + const status = await bootstrapLease.commitStatus( + candidate, + { signal } + ) + if ( + !status.committed && + status.reason === 'operation-unavailable' + ) { + await this.#operationStore.remove(hostId) + return false + } if ( !status.committed && status.reason === 'installer-rollback-incomplete' @@ -605,19 +667,83 @@ export class RemoteEnvironmentPreparer implements Preparer { '上一次远程环境发布失败且回滚结果不完整，请检查 Host 状态' ) } - const cleanup = await lease.cleanup( + commandLease = await this.#sshPool.acquire( + target, + signal + ) + assertLeaseMatchesTarget(commandLease, target) + const probe = + await commandLease.runAgentBootstrapProbe(signal) + if (!probe.ready) { + throw new Error( + `远端系统不能恢复 GoodBuddy 环境：${probe.reason}` + ) + } + recoveryMetadataSftp = + await commandLease.openStagedSftp( + probe.canonicalHomeDirectory, + { + maximumFileBytes: MAXIMUM_METADATA_BYTES, + maximumTotalBytes: + MAXIMUM_METADATA_BYTES * 24, + maximumOperations: 128 + }, + signal + ) + const recoverySnapshots = + restorePersistedMetadataSnapshots( + pending.metadataSnapshots, + probe.uid + ) + if (status.committed) { + try { + await this.#adoptCommittedEnvironment( + commandLease, + status.identity, + 'auto', + emit, + signal + ) + } catch (error) { + await stopCandidateBestEffort( + commandLease, + status.identity.agent.installationId + ) + try { + await restoreRemoteEnvironmentMetadata( + recoveryMetadataSftp, + recoverySnapshots + ) + } catch (rollbackError) { + throw new AggregateError( + [error, rollbackError], + '上一次远程环境恢复失败，且原有环境元数据未能完整恢复', + { cause: rollbackError } + ) + } + throw error + } + } else { + await restoreRemoteEnvironmentMetadata( + recoveryMetadataSftp, + recoverySnapshots + ) + } + const cleanup = await bootstrapLease.cleanup( pending.operationId, { signal } ) if ( - !cleanup.cleaned && - cleanup.reason !== 'operation-unavailable' + cleanup.cleaned || + cleanup.reason === 'operation-unavailable' ) { + await this.#operationStore.remove(hostId) + } else if (!status.committed) { throw new Error( - `上一次远程环境暂存清理失败：${cleanup.reason}` + `上一次未提交的远程环境暂存清理失败：${cleanup.reason}` ) } - await this.#operationStore.remove(hostId) + return status.committed } catch (error) { if ( error instanceof @@ -625,15 +751,59 @@ export class RemoteEnvironmentPreparer implements Preparer { ) { throw error } + const detail = error instanceof Error + ? error.message + : String(error) throw new SshRemotePackageCommitIndeterminateError( - '上一次远程环境提交结果仍不确定，请稍后重试' + `上一次远程环境恢复失败：${detail}` ) } finally { - lease.release() + recoveryMetadataSftp?.close() + commandLease?.release() + bootstrapLease.release() } } } +function persistMetadataSnapshots( + snapshots: readonly RemoteEnvironmentMetadataSnapshot[] +): readonly PersistedRemoteEnvironmentMetadataSnapshot[] { + return snapshots.map((snapshot) => ({ + path: snapshot.path, + uid: snapshot.uid, + ...(snapshot.contents === undefined + ? {} + : { + contentsBase64: + snapshot.contents.toString('base64') + }) + })) +} + +function restorePersistedMetadataSnapshots( + snapshots: + readonly PersistedRemoteEnvironmentMetadataSnapshot[], + uid: number +): readonly RemoteEnvironmentMetadataSnapshot[] { + if (snapshots.some((snapshot) => snapshot.uid !== uid)) { + throw new Error( + '远程环境恢复元数据与当前 SSH 用户不匹配' + ) + } + return snapshots.map((snapshot) => ({ + path: snapshot.path, + uid: snapshot.uid, + ...(snapshot.contentsBase64 === undefined + ? {} + : { + contents: Buffer.from( + snapshot.contentsBase64, + 'base64' + ) + }) + })) +} + async function resolvePreparationMethod( requested: RemoteEnvironmentPreparationMethod, lease: SshRemotePackageBootstrapLease, @@ -660,7 +830,7 @@ function assertPrepared( throw new Error( prepared.unavailable ? `远端环境准备不可用：${prepared.reason}` - : `远端环境准备失败：${prepared.reason}` + : `远端环境准备失败：${prepared.detail ?? prepared.reason}` ) } if (prepared.operationId !== operationId) { @@ -809,7 +979,6 @@ function mapBootstrapPhase( case 'verifying-zip': case 'verifying-payload': case 'validating-prepared-state': - case 'revalidating-archive': return 'verifying' case 'extracting': case 'preparing': @@ -819,6 +988,7 @@ function mapBootstrapPhase( case 'persisting-prepared-state': case 'extracting-payload': case 'publishing-content': + case 'publishing-metadata': case 'cleaning': return 'applying' } diff --git a/src/main/remote-agent/remote-environment-progress.ts b/src/main/remote-agent/remote-environment-progress.ts deleted file mode 100644 index faa8aed6..00000000 --- a/src/main/remote-agent/remote-environment-progress.ts +++ /dev/null @@ -1,35 +0,0 @@ -import type { RemoteEnvironmentUpdateProgress } from '../../shared/ssh-host-contracts' -import type { AgentInstallationPhase } from './agent-installation-manager' -import type { RemoteRuntimeInstallationPhase } from './remote-runtime-installation-manager' - -export function mapAgentInstallationPhase( - phase: AgentInstallationPhase -): RemoteEnvironmentUpdateProgress['phase'] | undefined { - switch (phase) { - case 'inspecting-host': - return 'probing' - case 'verifying-bundle': - return 'verifying' - case 'starting-agent': - return 'installing-agent' - case 'checking-health': - return 'checking-health' - case 'complete': - return undefined - } -} - -export function mapRuntimeInstallationPhase( - phase: RemoteRuntimeInstallationPhase -): RemoteEnvironmentUpdateProgress['phase'] | undefined { - switch (phase) { - case 'inspecting-host': - return 'probing' - case 'verifying-bundle': - return 'verifying' - case 'activating-runtime': - return 'installing-runtime' - case 'complete': - return undefined - } -} diff --git a/src/main/remote-agent/remote-runtime-installation-manager.test.ts b/src/main/remote-agent/remote-runtime-installation-manager.test.ts index 2a85dbf9..e9b673b6 100644 --- a/src/main/remote-agent/remote-runtime-installation-manager.test.ts +++ b/src/main/remote-agent/remote-runtime-installation-manager.test.ts @@ -1,1062 +1,311 @@ import { - createHash, - generateKeyPairSync, - sign -} from 'node:crypto' + readFileSync, + readdirSync +} from 'node:fs' import { - mkdir, - mkdtemp, - readFile, - writeFile -} from 'node:fs/promises' -import { tmpdir } from 'node:os' -import { join } from 'node:path' + join, + resolve +} from 'node:path' import { describe, expect, it, vi } from 'vitest' import type { - AgentReleaseKeyRegistry -} from '../../shared/agent-installation-contracts' -import { - digestRemoteRuntimeBundleIdentity, - digestRemoteRuntimeBundleManifest, - type RemoteRuntimeBundleManifest, - type RemoteRuntimeLock -} from '../../shared/remote-runtime-launch-contracts' -import { - runtimeManifestSignaturePayload -} from '../../shared/node/runtime-bundle-verifier' -import type { - SftpEntryMetadata, - StagedSftp -} from '../ssh/bounded-sftp' -import type { - SshConnectionLease, SshConnectionPoolTarget } from '../ssh/ssh-connection-pool' -import { verifyAgentInstallationId } from '../ssh/ssh-agent-command' import { - RemoteRuntimeInstallationManager, - type RemoteRuntimeActivator + RemoteRuntimeInstallationError, + RemoteRuntimeInstallationManager } from './remote-runtime-installation-manager' -import type { VerifiedRemoteRuntimeResourceBundle } from './remote-runtime-resource-loader' -type RemoteEntry = { - type: 'file' | 'directory' | 'symbolic-link' - mode: number - uid: number - contents?: Buffer +const HOST_ID = 'host-1' +const AGENT_ID = `agent-${'a'.repeat(64)}` as never +const runtimeRoot = resolve( + '.remote-runtime-resources', + 'linux-x64', + 'opencode' +) +const digestDirectory = readdirSync(runtimeRoot)[0]! +const manifest = JSON.parse( + readFileSync( + join(runtimeRoot, digestDirectory, 'manifest.json'), + 'utf8' + ) +) as { + runtimeId: string + runtimeVersion: string + architecture: 'x64' + bundleDigest: string + adapterDigest: string + acpCapabilitiesDigest: string +} +const entry = { + runtimeId: manifest.runtimeId, + runtimeVersion: manifest.runtimeVersion, + architecture: manifest.architecture, + bundleDigest: manifest.bundleDigest, + manifestDigest: `sha256:${'b'.repeat(64)}`, + runtimeAdapterDigest: manifest.adapterDigest, + acpCapabilitiesDigest: manifest.acpCapabilitiesDigest } -const home = '/home/tester' -const uid = 1000 - -function sha256(contents: Uint8Array): string { - return createHash('sha256').update(contents).digest('hex') -} - -function missing(): Error & { code: number } { - return Object.assign(new Error('missing'), { code: 2 }) -} - -class MemorySftp implements StagedSftp { - readonly stagingDirectory = home - readonly operations: string[] = [] - readonly entries = new Map([ - [home, { type: 'directory', mode: 0o700, uid }] - ]) - mutateRead?: (path: string, contents: Buffer) => Buffer - closed = false - - private absolute(path: string): string { - return `${home}/${path}` - } - - private metadata(entry: RemoteEntry): SftpEntryMetadata { - return { - type: entry.type, - size: entry.contents?.byteLength ?? 0, - mode: entry.mode, - uid: entry.uid, - gid: entry.uid, - atime: 1, - mtime: 1 - } - } - - async uploadFile(): Promise { - throw new Error('uploadFile is unused in this fixture') - } - - async mkdir(path: string): Promise { - this.operations.push(`mkdir:${path}`) - const absolute = this.absolute(path) - if (this.entries.has(absolute)) { - throw new Error('exists') - } - this.entries.set(absolute, { - type: 'directory', - mode: 0o700, - uid - }) - } - - async writeFile(path: string, contents: Buffer): Promise { - this.operations.push(`write:${path}`) - const absolute = this.absolute(path) - if (this.entries.has(absolute)) { - throw new Error('exists') - } - this.entries.set(absolute, { - type: 'file', - mode: 0o600, - uid, - contents: Buffer.from(contents) - }) - } - - async readFile(path: string): Promise { - this.operations.push(`read:${path}`) - const contents = Buffer.from( - this.entry(path).contents ?? Buffer.alloc(0) - ) - return this.mutateRead?.(path, contents) ?? contents - } - - async lstat(path: string): Promise { - return this.metadata(this.entry(path)) - } - - async stat(path: string): Promise { - const entry = this.entry(path) - if (entry.type === 'symbolic-link') { - throw new Error('symbolic link') - } - return this.metadata(entry) - } - - async chmod( - path: string, - mode: 0o600 | 0o644 | 0o700 | 0o755 - ): Promise { - this.operations.push(`chmod:${path}:${mode.toString(8)}`) - this.entry(path).mode = mode - } - - async setExecutable(path: string): Promise { - await this.chmod(path, 0o700) - } - - async rename(source: string, destination: string): Promise { - this.operations.push(`rename:${source}:${destination}`) - if (this.entries.has(this.absolute(destination))) { - throw new Error('destination exists') - } - this.moveTree(source, destination) - } - - async replaceFile( - source: string, - destination: string - ): Promise { - this.operations.push(`replace:${source}:${destination}`) - const sourceEntry = this.entry(source) - const destinationEntry = this.entries.get( - this.absolute(destination) - ) - if ( - sourceEntry.type !== 'file' || - (destinationEntry && destinationEntry.type !== 'file') - ) { - throw new Error('unsafe replacement') - } - this.entries.delete(this.absolute(source)) - this.entries.delete(this.absolute(destination)) - this.entries.set(this.absolute(destination), sourceEntry) - } - - async unlink(path: string): Promise { - this.operations.push(`unlink:${path}`) - if (this.entry(path).type !== 'file') { - throw new Error('not a file') - } - this.entries.delete(this.absolute(path)) - } - - async rmdir(path: string): Promise { - this.operations.push(`rmdir:${path}`) - const absolute = this.absolute(path) - if (this.entry(path).type !== 'directory') { - throw new Error('not a directory') - } - if ( - [...this.entries.keys()].some( - (candidate) => candidate.startsWith(`${absolute}/`) - ) - ) { - throw new Error('not empty') - } - this.entries.delete(absolute) - } - - close(): void { - this.closed = true - } - - add(path: string, entry: RemoteEntry): void { - this.entries.set(this.absolute(path), entry) - } - - private entry(path: string): RemoteEntry { - const entry = this.entries.get(this.absolute(path)) - if (!entry) { - throw missing() - } - return entry - } - - private moveTree(source: string, destination: string): void { - const sourceAbsolute = this.absolute(source) - const destinationAbsolute = this.absolute(destination) - const matches = [...this.entries.entries()].filter( - ([path]) => - path === sourceAbsolute || - path.startsWith(`${sourceAbsolute}/`) - ) - if (matches.length === 0) { - throw missing() - } - for (const [path] of matches) { - this.entries.delete(path) - } - for (const [path, entry] of matches) { - this.entries.set( - `${destinationAbsolute}${path.slice(sourceAbsolute.length)}`, - entry - ) - } - } -} - -const registry: AgentReleaseKeyRegistry = { - formatVersion: 1, - keys: [{ - keyId: 'test-key', - publicKeySpkiBase64: Buffer.from( - '302a300506032b6570032100000102030405060708090a0b0c0d0e0f101112131415161718191a1b1c1d1e1f', - 'hex' - ).toString('base64'), - environment: 'test' - }], - revocations: [] -} - -const runtimeLock: RemoteRuntimeLock = { - formatVersion: 1, - runtimes: { - opencode: { - version: '1.18.9', - provider: 'opencode', - entrypoint: 'bin/opencode', - entrypointIdentity: 'opencode-acp', - argvPrefix: ['acp'], - allowedEnvironmentNames: [ - 'HOME', - 'LANG', - 'LC_ALL', - 'PATH', - 'TMPDIR', - 'XDG_CACHE_HOME', - 'XDG_CONFIG_HOME', - 'XDG_DATA_HOME', - 'XDG_STATE_HOME' - ], - protocol: { major: 1, minor: 0 }, - targets: { - x64: { - package: 'opencode-linux-x64-baseline', - integrity: `sha512-${'A'.repeat(86)}==` - }, - arm64: { - package: 'opencode-linux-arm64', - integrity: `sha512-${'B'.repeat(86)}==` - } - } - } - } -} - -function canonical(value: unknown): Buffer { - return Buffer.from(`${JSON.stringify(value, null, 2)}\n`, 'utf8') -} - -function target( - revision = 1, - hostId = 'host-1' -): SshConnectionPoolTarget { +function target(): SshConnectionPoolTarget { return { host: { - id: hostId, - name: 'Host', - hostname: 'host.example', + id: HOST_ID, + name: 'Builder', + hostname: 'builder.example', port: 22, - username: 'tester', + username: 'goodbuddy', authentication: 'password', - password: 'not-logged', + password: 'secret', hostKey: { algorithm: 'ssh-ed25519', - publicKeyBase64: 'AAAA', - fingerprintSha256: `SHA256:${'a'.repeat(43)}`, - generation: revision + publicKeyBase64: 'a2V5', + fingerprintSha256: `SHA256:${'c'.repeat(43)}`, + generation: 2 } }, - hostRevision: revision, - hostKeyGeneration: revision + hostRevision: 3, + hostKeyGeneration: 2 } } -async function bundleFixture(): Promise< - VerifiedRemoteRuntimeResourceBundle -> { - const directory = await mkdtemp( - join(tmpdir(), 'runtime-manager-') - ) - const files = [ - { - path: 'bin/opencode', - contents: Buffer.from('opencode'), - mode: '0755' as const - }, - { - path: 'licenses/LICENSE', - contents: Buffer.from('license'), - mode: '0644' as const - } - ] - const initial: RemoteRuntimeBundleManifest = { - formatVersion: 2, - product: 'GoodBuddy', - runtimeId: 'opencode', - runtimeVersion: '1.18.9', - provider: 'opencode', - platform: 'linux', - architecture: 'x64', - signingKeyId: 'test-key', - bundleDigest: `sha256:${'0'.repeat(64)}`, - adapterDigest: `sha256:${'1'.repeat(64)}`, - sourcePackage: { - name: 'opencode-linux-x64-baseline', - integrity: runtimeLock.runtimes.opencode.targets.x64.integrity - }, - entrypoint: { - identity: 'opencode-acp', - path: 'bin/opencode', - sha256: sha256(files[0]!.contents), - argvPrefix: ['acp'] - }, - files: files.map((file) => ({ - path: file.path, - size: file.contents.byteLength, - sha256: sha256(file.contents), - mode: file.mode - })), - licenses: [{ - package: 'opencode', - version: '1.18.9', - spdx: 'MIT', - path: 'licenses/LICENSE' - }], - allowedEnvironmentNames: [ - 'HOME', - 'LANG', - 'LC_ALL', - 'PATH', - 'TMPDIR', - 'XDG_CACHE_HOME', - 'XDG_CONFIG_HOME', - 'XDG_DATA_HOME', - 'XDG_STATE_HOME' - ], - protocol: { major: 1, minor: 0 }, - acpCapabilitiesDigest: `sha256:${'3'.repeat(64)}`, - limits: { - maximumPromptRuntimeMilliseconds: 60_000, - maximumPromptInputBytes: 4096, - maximumPromptOutputBytes: 1024 * 1024 - } - } - const manifest = { - ...initial, - bundleDigest: await digestRemoteRuntimeBundleIdentity(initial) - } - for (const file of files) { - const destination = join( - directory, - ...file.path.split('/') - ) - await mkdir(join(destination, '..'), { recursive: true }) - await writeFile(destination, file.contents) - } - await writeFile( - join(directory, 'manifest.json'), - canonical(manifest) - ) - await writeFile( - join(directory, 'manifest.sig'), - Buffer.alloc(64, 7) - ) - return { - bundleDirectory: directory, - manifest, - manifestDigest: - await digestRemoteRuntimeBundleManifest(manifest), - canonicalReleaseKeyRegistryBytes: canonical(registry), - canonicalRemoteRuntimeLockBytes: canonical(runtimeLock) - } -} - -async function waitForGate( - gate: Promise, - signal?: AbortSignal -): Promise { - if (!signal) { - await gate - return - } - signal.throwIfAborted() - await new Promise((resolve, reject) => { - const abort = (): void => { - reject( - signal.reason ?? - new DOMException('The operation was aborted', 'AbortError') - ) - } - signal.addEventListener('abort', abort, { once: true }) - gate.then( - () => { - signal.removeEventListener('abort', abort) - resolve() - }, - (error: unknown) => { - signal.removeEventListener('abort', abort) - reject(error) - } - ) - }) -} - -async function metadataOnlyHarness(options: { - corruptPath?: string - remoteReleaseKeyBytes?: Buffer - remoteRuntimeLockBytes?: Buffer - remoteReleaseKeysAbsent?: boolean - remoteRuntimeLockAbsent?: boolean - resolverTargets?: SshConnectionPoolTarget[] - runtimeRegistryBytes?: Buffer - runtimeRegistryAbsent?: boolean - activationFailure?: boolean - activationMutatesRegistry?: boolean - bootstrapGate?: Promise +function fixture(options: { + registryEntry?: typeof entry | undefined + includeAdapter?: boolean + activate?: ReturnType + readRegistry?: () => Promise } = {}) { - const baseBundle = await bundleFixture() - const keyPair = generateKeyPairSync('ed25519') - const signedRegistry: AgentReleaseKeyRegistry = { - formatVersion: 1, - keys: [{ - keyId: 'test-key', - publicKeySpkiBase64: keyPair.publicKey.export({ - format: 'der', - type: 'spki' - }).toString('base64'), - environment: 'production' - }], - revocations: [] - } - const manifestBytes = canonical(baseBundle.manifest) - const signatureBytes = Buffer.from( - `${sign( - null, - runtimeManifestSignaturePayload(manifestBytes), - keyPair.privateKey - ).toString('base64')}\n` - ) - const releaseKeyRegistryBytes = canonical(signedRegistry) - const remoteRuntimeLockBytes = canonical(runtimeLock) - const bundle: VerifiedRemoteRuntimeResourceBundle = { - bundleDirectory: baseBundle.bundleDirectory, - manifest: baseBundle.manifest, - manifestDigest: baseBundle.manifestDigest, - canonicalReleaseKeyRegistryBytes: - releaseKeyRegistryBytes, - canonicalRemoteRuntimeLockBytes: - remoteRuntimeLockBytes - } - const sftp = new MemorySftp() - const destination = - `.goodbuddy/runtimes/opencode/${ - bundle.manifest.bundleDigest.slice('sha256:'.length) - }` - for (const path of [ - '.goodbuddy', - '.goodbuddy/runtimes', - '.goodbuddy/runtimes/opencode', - destination, - `${destination}/bin`, - `${destination}/licenses` - ]) { - sftp.add(path, { - type: 'directory', - mode: 0o700, - uid - }) - } - const runtimeRegistryBytes = canonical({ - formatVersion: 1, - current: [{ - runtimeId: 'opencode', - runtimeVersion: bundle.manifest.runtimeVersion, - architecture: bundle.manifest.architecture, - bundleDigest: bundle.manifest.bundleDigest, - manifestDigest: bundle.manifestDigest, - acpCapabilitiesDigest: - bundle.manifest.acpCapabilitiesDigest - }] - }) - if (!options.remoteReleaseKeysAbsent) { - sftp.add('.goodbuddy/runtimes/release-keys.json', { - type: 'file', - mode: 0o600, - uid, - contents: - options.remoteReleaseKeyBytes ?? - releaseKeyRegistryBytes - }) - } - if (!options.remoteRuntimeLockAbsent) { - sftp.add('.goodbuddy/runtimes/remote-runtime-lock.json', { - type: 'file', - mode: 0o600, - uid, - contents: - options.remoteRuntimeLockBytes ?? - remoteRuntimeLockBytes - }) - } - if (!options.runtimeRegistryAbsent) { - sftp.add('.goodbuddy/runtimes/registry.json', { - type: 'file', - mode: 0o600, - uid, - contents: - options.runtimeRegistryBytes ?? runtimeRegistryBytes - }) - } - for (const file of bundle.manifest.files) { - const contents = await readFile( - join(bundle.bundleDirectory, ...file.path.split('/')) - ) - sftp.add(`${destination}/${file.path}`, { - type: 'file', - mode: file.mode === '0755' ? 0o755 : 0o644, - uid, - contents: - options.corruptPath === file.path - ? Buffer.alloc(contents.byteLength, 0x78) - : contents - }) - } - sftp.add(`${destination}/manifest.json`, { - type: 'file', - mode: 0o644, - uid, - contents: manifestBytes - }) - sftp.add(`${destination}/manifest.sig`, { - type: 'file', - mode: 0o644, - uid, - contents: - options.corruptPath === 'manifest.sig' - ? Buffer.from(`${'A'.repeat(86)}==\n`) - : signatureBytes - }) - - const release = vi.fn() - const activate = vi.fn(async () => { - if (options.activationMutatesRegistry) { - sftp.add('.goodbuddy/runtimes/registry.json', { - type: 'file', - mode: 0o600, - uid, - contents: Buffer.from('changed registry bytes\n') - }) - } - if ( - options.activationFailure || - options.corruptPath !== undefined && - options.corruptPath !== 'manifest.sig' - ) { - throw new Error('Agent Runtime verification failed') + const calls: string[] = [] + const registryEntry = + 'registryEntry' in options + ? options.registryEntry + : entry + const storedEntry = registryEntry === undefined + ? undefined + : options.includeAdapter === false + ? Object.fromEntries( + Object.entries(registryEntry).filter( + ([key]) => key !== 'runtimeAdapterDigest' + ) + ) + : registryEntry + const readRegistry = + options.readRegistry ?? + vi.fn(async () => Buffer.from(JSON.stringify({ + formatVersion: 1, + current: storedEntry === undefined ? [] : [storedEntry] + }))) + const readFile = vi.fn(async (path: string) => { + calls.push(`read:${path}`) + if (path.endsWith('registry.json')) { + return readRegistry() } + return Buffer.from(JSON.stringify(manifest)) }) + const close = vi.fn(() => calls.push('close-sftp')) + const release = vi.fn(() => calls.push('release')) const lease = { identity: { - hostId: 'host-1', - hostRevision: 1, - hostKeyGeneration: 1, - authenticationIdentity: 'b'.repeat(64) + hostId: HOST_ID, + hostRevision: 3, + hostKeyGeneration: 2, + authenticationIdentity: 'd'.repeat(64) }, - isUsable: () => true, - runAgentBootstrapProbe: vi.fn(async (signal?: AbortSignal) => { - if (options.bootstrapGate) { - await waitForGate(options.bootstrapGate, signal) - } - return { + runAgentBootstrapProbe: vi.fn(async () => ({ ready: true, platform: 'linux', architecture: 'x64', - canonicalHomeDirectory: home, - uid, - shell: '/bin/bash', + canonicalHomeDirectory: '/home/goodbuddy', + uid: 1000, + shell: '/bin/sh', procfs: 'ready' - } as const - }), - openStagedSftp: vi.fn(async () => sftp), - release - } as unknown as SshConnectionLease - let resolveCount = 0 - const targets = options.resolverTargets ?? [target()] + })), + openStagedSftp: vi.fn(async () => ({ + lstat: vi.fn(async (path: string) => ({ + type: 'file', + size: 512, + mode: path.endsWith('registry.json') + ? 0o600 + : 0o644, + uid: 1000, + gid: 1000, + atime: 0, + mtime: 0 + })), + readFile, + close + })), + release, + isUsable: vi.fn(() => true) + } + const activate = + options.activate ?? + vi.fn(async () => { + calls.push('activate') + }) + const acquire = vi.fn(async () => lease as never) const resolver = { - resolve: vi.fn(async () => - targets[Math.min(resolveCount++, targets.length - 1)]! - ) + resolve: vi.fn(async () => target()) } const manager = new RemoteRuntimeInstallationManager({ resolver, - sshPool: { acquire: vi.fn(async () => lease) }, - loadVerificationMetadata: async () => ({ - releaseKeyRegistry: signedRegistry, - runtimeLock, - canonicalReleaseKeyRegistryBytes: - releaseKeyRegistryBytes, - canonicalRemoteRuntimeLockBytes: - remoteRuntimeLockBytes - }), - activate + sshPool: { acquire }, + activate: activate as never }) return { manager, - bundle, - publishedIdentity: { - runtimeId: 'opencode' as const, - runtimeVersion: bundle.manifest.runtimeVersion, - bundleDigest: bundle.manifest.bundleDigest, - manifestDigest: bundle.manifestDigest, - runtimeAdapterDigest: bundle.manifest.adapterDigest, - acpCapabilitiesDigest: - bundle.manifest.acpCapabilitiesDigest, - platform: 'linux' as const, - architecture: bundle.manifest.architecture, - protocol: { ...bundle.manifest.protocol } - }, - activate, - destination, - release, + calls, resolver, - sftp + lease, + acquire, + activate, + readFile, + readRegistry, + close, + release } } describe('RemoteRuntimeInstallationManager', () => { - it('cryptographically reuses an exact current Host Runtime when bundle resources are absent', async () => { - const fixture = await metadataOnlyHarness() - const agentInstallationId = - verifyAgentInstallationId('agent-current') + it('activates a registered Runtime without reading its payload', async () => { + const value = fixture() + const phases: string[] = [] - await expect( - fixture.manager.activateInstalled('host-1', { - agentInstallationId - }) - ).resolves.toMatchObject({ - runtimeId: 'opencode', - runtimeVersion: fixture.bundle.manifest.runtimeVersion, - bundleDigest: fixture.bundle.manifest.bundleDigest, - architecture: 'x64' + await expect(value.manager.activateInstalled( + HOST_ID, + { + agentInstallationId: AGENT_ID, + onProgress: (phase) => phases.push(phase) + } + )).resolves.toEqual({ + ...entry, + platform: 'linux' }) - expect(fixture.activate).toHaveBeenCalledOnce() - expect(fixture.activate.mock.calls[0]?.[4]).toBe( - agentInstallationId + expect(value.readFile.mock.calls.map( + (call) => call[0] + )).toEqual(['.goodbuddy/runtimes/registry.json']) + expect(value.activate).toHaveBeenCalledWith( + value.lease, + entry.runtimeId, + entry.bundleDigest, + entry.architecture, + AGENT_ID, + expect.any(AbortSignal) ) - expect( - fixture.sftp.operations.some((operation) => - operation.startsWith('write:') - ) - ).toBe(false) - expect(fixture.release).toHaveBeenCalledOnce() + expect(phases).toEqual([ + 'inspecting-host', + 'verifying-bundle', + 'activating-runtime', + 'complete' + ]) }) - it('reuses the current Runtime identity until the Host is invalidated', async () => { - const fixture = await metadataOnlyHarness() - const agentInstallationId = - verifyAgentInstallationId('agent-current') + it('reads only the signed manifest metadata for a legacy registry entry', async () => { + const value = fixture({ includeAdapter: false }) - const first = await fixture.manager.activateInstalled('host-1', { - agentInstallationId - }) await expect( - fixture.manager.activateInstalled('host-1', { - agentInstallationId + value.manager.activateInstalled(HOST_ID) + ).resolves.toMatchObject({ + runtimeAdapterDigest: manifest.adapterDigest + }) + expect(value.readFile.mock.calls.map( + (call) => call[0] + )).toEqual([ + '.goodbuddy/runtimes/registry.json', + `.goodbuddy/runtimes/opencode/${digestDirectory}/manifest.json` + ]) + }) + + it('caches activation until the Host is invalidated', async () => { + const value = fixture() + const first = await value.manager.activateInstalled(HOST_ID) + const second = await value.manager.activateInstalled(HOST_ID) + expect(second).toEqual(first) + expect(value.acquire).toHaveBeenCalledOnce() + + value.manager.invalidateHost(HOST_ID) + await value.manager.activateInstalled(HOST_ID) + expect(value.acquire).toHaveBeenCalledTimes(2) + }) + + it('deduplicates concurrent activation for one Agent identity', async () => { + let releaseRead!: () => void + const readGate = new Promise((resolveRead) => { + releaseRead = resolveRead + }) + const value = fixture({ + readRegistry: vi.fn(async () => { + await readGate + return Buffer.from(JSON.stringify({ + formatVersion: 1, + current: [entry] + })) }) - ).resolves.toEqual(first) - expect(fixture.activate).toHaveBeenCalledOnce() - expect(fixture.release).toHaveBeenCalledOnce() + }) - fixture.manager.invalidateHost('host-1') - await expect( - fixture.manager.activateInstalled('host-1', { - agentInstallationId - }) - ).resolves.toEqual(first) - expect(fixture.activate).toHaveBeenCalledTimes(2) - expect(fixture.release).toHaveBeenCalledTimes(2) + const first = value.manager.activateInstalled(HOST_ID, { + agentInstallationId: AGENT_ID + }) + const second = value.manager.activateInstalled(HOST_ID, { + agentInstallationId: AGENT_ID + }) + releaseRead() + await expect(Promise.all([first, second])).resolves.toHaveLength(2) + expect(value.acquire).toHaveBeenCalledOnce() }) - it('activates an exact installed Runtime without loading or publishing installable payloads', async () => { - const fixture = await metadataOnlyHarness() - + it('classifies a missing Runtime registry entry as incompatible', async () => { + const value = fixture({ registryEntry: undefined }) await expect( - fixture.manager.activateInstalled('host-1') - ).resolves.toMatchObject({ - runtimeId: 'opencode', - bundleDigest: fixture.bundle.manifest.bundleDigest, - architecture: 'x64' - }) - - expect(fixture.activate).toHaveBeenCalledOnce() - expect( - fixture.sftp.operations.filter((operation) => - /^(?:mkdir|write|chmod|rename|replace|unlink|rmdir):/u - .test(operation) - ) - ).toEqual([]) - }) - - it('adopts the exact package-published Runtime without loading or mutating payloads', async () => { - const fixture = await metadataOnlyHarness() - - await expect( - fixture.manager.activatePublished( - 'host-1', - fixture.publishedIdentity - ) - ).resolves.toEqual({ - runtimeId: 'opencode', - runtimeVersion: fixture.bundle.manifest.runtimeVersion, - bundleDigest: fixture.bundle.manifest.bundleDigest, - manifestDigest: fixture.bundle.manifestDigest, - runtimeAdapterDigest: - fixture.bundle.manifest.adapterDigest, - acpCapabilitiesDigest: - fixture.bundle.manifest.acpCapabilitiesDigest, - platform: 'linux', - architecture: 'x64' - }) - - expect(fixture.activate).toHaveBeenCalledOnce() - expect( - fixture.sftp.operations.filter((operation) => - /^(?:mkdir|write|chmod|rename|replace|unlink|rmdir):/u - .test(operation) - ) - ).toEqual([]) - }) - - it('adopts a package-published Runtime when all global Runtime metadata is absent', async () => { - const fixture = await metadataOnlyHarness({ - remoteReleaseKeysAbsent: true, - remoteRuntimeLockAbsent: true, - runtimeRegistryAbsent: true - }) - - await expect( - fixture.manager.activatePublished( - 'host-1', - fixture.publishedIdentity - ) - ).resolves.toMatchObject({ - runtimeId: 'opencode', - bundleDigest: fixture.bundle.manifest.bundleDigest - }) - - expect(fixture.activate).toHaveBeenCalledOnce() - expect( - fixture.sftp.entries.has( - `${home}/.goodbuddy/runtimes/release-keys.json` - ) - ).toBe(true) - expect( - fixture.sftp.entries.has( - `${home}/.goodbuddy/runtimes/remote-runtime-lock.json` - ) - ).toBe(true) - expect( - fixture.sftp.entries.has( - `${home}/.goodbuddy/runtimes/registry.json` - ) - ).toBe(false) - }) - - it('verifies a published Runtime with packaged trust instead of stale Host metadata', async () => { - const fixture = await metadataOnlyHarness({ - remoteReleaseKeyBytes: canonical({ - formatVersion: 1, - keys: [], - revocations: [] - }), - remoteRuntimeLockBytes: Buffer.from( - '{ "legacy": "runtime lock" }\n' - ) - }) - - await expect( - fixture.manager.activatePublished( - 'host-1', - fixture.publishedIdentity - ) - ).resolves.toMatchObject({ - runtimeId: 'opencode' - }) - expect(fixture.activate).toHaveBeenCalledOnce() - }) - - it('rejects a package-published Runtime identity mismatch before activation', async () => { - const fixture = await metadataOnlyHarness() - - await expect( - fixture.manager.activatePublished('host-1', { - ...fixture.publishedIdentity, - runtimeAdapterDigest: `sha256:${'f'.repeat(64)}` - }) - ).rejects.toMatchObject({ reason: 'corrupt' }) - - expect(fixture.activate).not.toHaveBeenCalled() - }) - - it('does not transfer installer-verified Runtime payloads back through SFTP', async () => { - const fixture = await metadataOnlyHarness() - - await expect( - fixture.manager.activatePublished( - 'host-1', - fixture.publishedIdentity - ) - ).resolves.toMatchObject({ - bundleDigest: fixture.bundle.manifest.bundleDigest - }) - - expect(fixture.activate).toHaveBeenCalledOnce() - for (const file of fixture.bundle.manifest.files) { - expect(fixture.sftp.operations).not.toContain( - `read:${fixture.destination}/${file.path}` - ) - } - }) - - it('rejects package-published Runtime adoption after Host identity changes', async () => { - const fixture = await metadataOnlyHarness({ - resolverTargets: [target(), target(2)] - }) - - await expect( - fixture.manager.activatePublished( - 'host-1', - fixture.publishedIdentity - ) + value.manager.activateInstalled(HOST_ID) ).rejects.toMatchObject({ - reason: 'host-identity-changed' + reason: 'incompatible' }) - - expect(fixture.activate).not.toHaveBeenCalled() + expect(value.activate).not.toHaveBeenCalled() }) - it('restores exact Runtime registry bytes when published activation fails', async () => { - const oldRegistry = Buffer.from( - '{ "legacy": true, "spacing": "preserved" }\n' - ) - const oldReleaseKeys = Buffer.from( - '{ "legacy": "release keys" }\n' - ) - const oldRuntimeLock = Buffer.from( - '{ "legacy": "runtime lock" }\n' - ) - const fixture = await metadataOnlyHarness({ - runtimeRegistryBytes: oldRegistry, - remoteReleaseKeyBytes: oldReleaseKeys, - remoteRuntimeLockBytes: oldRuntimeLock, - activationFailure: true, - activationMutatesRegistry: true - }) - - await expect( - fixture.manager.activatePublished( - 'host-1', - fixture.publishedIdentity - ) - ).rejects.toMatchObject({ reason: 'activation' }) - - expect( - fixture.sftp.entries.get( - `${home}/.goodbuddy/runtimes/registry.json` - )?.contents - ).toEqual(oldRegistry) - expect( - fixture.sftp.entries.get( - `${home}/.goodbuddy/runtimes/release-keys.json` - )?.contents - ).toEqual(oldReleaseKeys) - expect( - fixture.sftp.entries.get( - `${home}/.goodbuddy/runtimes/remote-runtime-lock.json` - )?.contents - ).toEqual(oldRuntimeLock) - }) - - it('restores absent Runtime metadata when published activation fails', async () => { - const fixture = await metadataOnlyHarness({ - runtimeRegistryAbsent: true, - remoteReleaseKeysAbsent: true, - remoteRuntimeLockAbsent: true, - activationFailure: true, - activationMutatesRegistry: true - }) - - await expect( - fixture.manager.activatePublished( - 'host-1', - fixture.publishedIdentity - ) - ).rejects.toMatchObject({ reason: 'activation' }) - - expect( - fixture.sftp.entries.has( - `${home}/.goodbuddy/runtimes/registry.json` - ) - ).toBe(false) - expect( - fixture.sftp.entries.has( - `${home}/.goodbuddy/runtimes/release-keys.json` - ) - ).toBe(false) - expect( - fixture.sftp.entries.has( - `${home}/.goodbuddy/runtimes/remote-runtime-lock.json` - ) - ).toBe(false) - }) - - it('rejects metadata-only Runtime reuse when trust metadata differs', async () => { - const fixture = await metadataOnlyHarness({ - remoteReleaseKeyBytes: canonical({ - formatVersion: 1, - keys: [], - revocations: [] + it('preserves concrete Agent activation failures', async () => { + const failure = new Error('entrypoint permission denied') + const value = fixture({ + activate: vi.fn(async () => { + throw failure }) }) - await expect( - fixture.manager.activateInstalled('host-1') - ).rejects.toMatchObject({ reason: 'corrupt' }) - expect(fixture.activate).not.toHaveBeenCalled() - }) - - it('rejects metadata-only Runtime reuse when its signature is corrupt', async () => { - const fixture = await metadataOnlyHarness({ - corruptPath: 'manifest.sig' - }) - - await expect( - fixture.manager.activateInstalled('host-1') - ).rejects.toMatchObject({ reason: 'corrupt' }) - expect(fixture.activate).not.toHaveBeenCalled() - }) - - it('delegates exact payload re-verification to Agent activation', async () => { - const fixture = await metadataOnlyHarness({ - corruptPath: 'bin/opencode' - }) - - await expect( - fixture.manager.activateInstalled('host-1') - ).rejects.toMatchObject({ reason: 'activation' }) - expect(fixture.activate).toHaveBeenCalledOnce() - }) - - it('rejects metadata-only Runtime reuse after Host identity changes', async () => { - const fixture = await metadataOnlyHarness({ - resolverTargets: [target(), target(2)] - }) - - await expect( - fixture.manager.activateInstalled('host-1') + value.manager.activateInstalled(HOST_ID) ).rejects.toMatchObject({ - reason: 'host-identity-changed' + reason: 'corrupt', + message: expect.stringContaining( + 'entrypoint permission denied' + ) }) - expect(fixture.activate).not.toHaveBeenCalled() }) - it('deduplicates installed activation and lets one waiter cancel', async () => { - let releaseGate!: () => void - const gate = new Promise((resolve) => { - releaseGate = resolve - }) - const fixture = await metadataOnlyHarness({ bootstrapGate: gate }) - const controller = new AbortController() - const canceled = fixture.manager.activateInstalled('host-1', { - signal: controller.signal - }) - const survivor = fixture.manager.activateInstalled('host-1') - await vi.waitFor(() => - expect(fixture.resolver.resolve).toHaveBeenCalledTimes(2) + it('rejects a mismatched legacy manifest before activation', async () => { + const value = fixture({ includeAdapter: false }) + value.readFile.mockImplementation(async (path: string) => + path.endsWith('registry.json') + ? Buffer.from(JSON.stringify({ + formatVersion: 1, + current: [ + Object.fromEntries( + Object.entries(entry).filter( + ([key]) => + key !== 'runtimeAdapterDigest' + ) + ) + ] + })) + : Buffer.from(JSON.stringify({ + ...manifest, + runtimeVersion: '99.0.0' + })) ) - controller.abort() - await expect(canceled).rejects.toMatchObject({ name: 'AbortError' }) - releaseGate() - await expect(survivor).resolves.toMatchObject({ runtimeId: 'opencode' }) - expect(fixture.activate).toHaveBeenCalledOnce() - expect(fixture.release).toHaveBeenCalledOnce() - }) - - it('cancels installed activation when its final waiter leaves', async () => { - const fixture = await metadataOnlyHarness({ - bootstrapGate: new Promise(() => undefined) - }) - const controller = new AbortController() - const activation = fixture.manager.activateInstalled('host-1', { - signal: controller.signal - }) - await vi.waitFor(() => - expect(fixture.resolver.resolve).toHaveBeenCalledOnce() - ) - - controller.abort() - await expect(activation).rejects.toMatchObject({ name: 'AbortError' }) - await vi.waitFor(() => expect(fixture.release).toHaveBeenCalledOnce()) - }) - - it('dispose aborts active activation and rejects future calls', async () => { - const fixture = await metadataOnlyHarness({ - bootstrapGate: new Promise(() => undefined) - }) - const activation = fixture.manager.activateInstalled('host-1') - await vi.waitFor(() => - expect(fixture.resolver.resolve).toHaveBeenCalledOnce() - ) - - const first = fixture.manager.dispose() - expect(fixture.manager.dispose()).toBe(first) - await expect(activation).rejects.toMatchObject({ name: 'AbortError' }) - await first await expect( - fixture.manager.activateInstalled('host-1') - ).rejects.toThrow('Remote Runtime installation manager is disposed') + value.manager.activateInstalled(HOST_ID) + ).rejects.toBeInstanceOf( + RemoteRuntimeInstallationError + ) + expect(value.activate).not.toHaveBeenCalled() }) }) diff --git a/src/main/remote-agent/remote-runtime-installation-manager.ts b/src/main/remote-agent/remote-runtime-installation-manager.ts index 3ea0a55f..f3373621 100644 --- a/src/main/remote-agent/remote-runtime-installation-manager.ts +++ b/src/main/remote-agent/remote-runtime-installation-manager.ts @@ -1,60 +1,28 @@ -import { createHash, randomUUID } from 'node:crypto' -import { - agentReleaseKeyRegistrySchema, - type AgentArchitecture, - type AgentReleaseKeyRegistry -} from '../../shared/agent-installation-contracts' +import type { AgentArchitecture } from '../../shared/agent-installation-contracts' import type { AgentBootstrapIncompatibleReason } from '../../shared/ssh-host-contracts' -import { - assertRuntimeManifestMatchesLock, - verifyRuntimeManifestSignature -} from '../../shared/node/runtime-bundle-verifier' import { parseRuntimeRegistryState } from '../../shared/remote-environment-registry-contracts' import { - digestRemoteRuntimeBundleManifest, - remoteRuntimeLockSchema, - type RemoteRuntimeBundleManifest, - type RemoteRuntimeLock + remoteRuntimeBundleManifestSchema } from '../../shared/remote-runtime-launch-contracts' -import { sha256DigestSchema } from '../../shared/agent-protocol/contracts' -import type { - BoundedSftpLimits, - SftpEntryMetadata, - StagedSftp -} from '../ssh/bounded-sftp' +import type { StagedSftp } from '../ssh/bounded-sftp' +import type { VerifiedAgentInstallationId } from '../ssh/ssh-agent-command' import type { SshConnectionLease, SshConnectionPool, SshConnectionPoolTarget } from '../ssh/ssh-connection-pool' -import type { - SshRemotePackageRuntimeIdentity -} from '../ssh/ssh-remote-package-bootstrap' -import type { VerifiedAgentInstallationId } from '../ssh/ssh-agent-command' -import { settleBoundedly } from './bounded-settlement' -import { - parseAgentReleaseKeyRegistryBytes -} from './agent-bundle-verifier' +import { HostActivationCoordinator } from './host-activation-coordinator' +import { boundedDiagnostic } from './bounded-diagnostic' import { isMissingPathError } from './path-errors' import { remoteHostTargetIdentityKey } from './remote-host-target-identity' -const MAXIMUM_INSTALLATION_FILES = 200 -const MAXIMUM_INSTALLATION_BYTES = 512 * 1024 * 1024 -const MAXIMUM_RUNTIME_FILE_BYTES = 256 * 1024 * 1024 const MAXIMUM_METADATA_BYTES = 1024 * 1024 -const MAXIMUM_CLEANUP_ENTRIES = 512 -const METADATA_MODE = 0o644 const PRIVATE_FILE_MODE = 0o600 -const PRIVATE_DIRECTORY_MODE = 0o700 -const DISPOSE_WAIT_TIMEOUT_MS = 5_000 - -const RUNTIME_ROOT = '.goodbuddy/runtimes' -const OPENCODE_ROOT = `${RUNTIME_ROOT}/opencode` -const RELEASE_KEYS_PATH = `${RUNTIME_ROOT}/release-keys.json` -const RUNTIME_LOCK_PATH = `${RUNTIME_ROOT}/remote-runtime-lock.json` -const RUNTIME_REGISTRY_PATH = `${RUNTIME_ROOT}/registry.json` +const RUNTIME_REGISTRY_PATH = + '.goodbuddy/runtimes/registry.json' +const OPENCODE_ROOT = '.goodbuddy/runtimes/opencode' export type RemoteRuntimeInstallationPhase = | 'inspecting-host' @@ -83,9 +51,6 @@ export type RemoteRuntimeActivationRequestOptions = { agentInstallationId?: VerifiedAgentInstallationId } -export type PublishedRemoteRuntimeInstallationIdentity = - SshRemotePackageRuntimeIdentity - export class RemoteRuntimeInstallationError extends Error { constructor( message: string, @@ -102,24 +67,6 @@ export class RemoteRuntimeInstallationError extends Error { } } -type RuntimeBundleBase = { - bundleDirectory: string - manifest: RemoteRuntimeBundleManifest - manifestDigest: string -} - -export type RemoteRuntimeInstallationVerificationMetadata = { - releaseKeyRegistry: AgentReleaseKeyRegistry - runtimeLock: RemoteRuntimeLock - canonicalReleaseKeyRegistryBytes: Uint8Array - canonicalRemoteRuntimeLockBytes: Uint8Array -} - -export type RemoteRuntimeInstallationVerificationMetadataLoader = - ( - architecture: AgentArchitecture - ) => Promise - export type RemoteRuntimeActivator = ( lease: SshConnectionLease, runtimeId: string, @@ -129,776 +76,305 @@ export type RemoteRuntimeActivator = ( signal: AbortSignal ) => Promise -type ActiveInstallation = { - promise: Promise - controller: AbortController - progressCallbacks: Set< - (phase: RemoteRuntimeInstallationPhase) => void - > - waiters: number - settled: boolean -} - -type CleanupEntry = { - path: string - type: 'file' | 'directory' -} - -type ManagedFileSnapshot = { - path: string - contents: Buffer | undefined - uid: number -} - -type LoadedBundle = RuntimeBundleBase & { - releaseKeyRegistryBytes: Buffer - remoteRuntimeLockBytes: Buffer -} - export class RemoteRuntimeInstallationManager { readonly #resolver: RemoteRuntimeInstallationTargetResolver readonly #sshPool: Pick - readonly #loadVerificationMetadata?: - RemoteRuntimeInstallationVerificationMetadataLoader readonly #activate: RemoteRuntimeActivator - readonly #sftpLimits?: BoundedSftpLimits - readonly #maximumConcurrentHosts: number - readonly #active = new Map() - readonly #current = new Map< - string, - { - targetKey: string - agentKey: string - identity: RemoteRuntimeInstallationIdentity - } - >() - readonly #cacheGenerations = new Map() - #closed = false - #disposePromise: Promise | undefined + readonly #coordinator: HostActivationCoordinator< + RemoteRuntimeInstallationIdentity, + RemoteRuntimeInstallationPhase + > constructor(options: { resolver: RemoteRuntimeInstallationTargetResolver sshPool: Pick - loadVerificationMetadata?: - RemoteRuntimeInstallationVerificationMetadataLoader activate: RemoteRuntimeActivator - sftpLimits?: BoundedSftpLimits maximumConcurrentHosts?: number }) { this.#resolver = options.resolver this.#sshPool = options.sshPool - this.#loadVerificationMetadata = - options.loadVerificationMetadata this.#activate = options.activate - this.#sftpLimits = options.sftpLimits - this.#maximumConcurrentHosts = - options.maximumConcurrentHosts ?? 8 - if ( - !Number.isSafeInteger(this.#maximumConcurrentHosts) || - this.#maximumConcurrentHosts <= 0 || - this.#maximumConcurrentHosts > 32 - ) { - throw new Error( - 'Remote Runtime installation concurrency limit is invalid' - ) - } + this.#coordinator = new HostActivationCoordinator({ + maximumConcurrentHosts: + options.maximumConcurrentHosts, + capacityError: () => + new RemoteRuntimeInstallationError( + 'Too many Runtime activations are already running', + 'capacity' + ), + disposeMessage: + 'Remote Runtime activation manager is disposed' + }) } /** - * Verifies and activates the installed Runtime selected by packaged trust - * metadata without loading or publishing installable Runtime payloads. + * Loads the current Runtime registry entry and delegates bounded manifest + * and entrypoint checks to the Agent. Main never traverses Runtime payloads. */ async activateInstalled( hostId: string, options: RemoteRuntimeActivationRequestOptions = {} ): Promise { - return this.#request(hostId, 'activate', options) - } - - /** - * Verifies and activates the exact Runtime directory already published by - * the authenticated package installer, installing canonical metadata but - * never loading or staging payloads. - */ - async activatePublished( - hostId: string, - expectedIdentity: PublishedRemoteRuntimeInstallationIdentity, - options: RemoteRuntimeActivationRequestOptions = {} - ): Promise { - assertPublishedRuntimeIdentity(expectedIdentity) - return this.#request( - hostId, - 'adopt', - options, - expectedIdentity - ) - } - - invalidateHost(hostId: string): void { - this.#current.delete(hostId) - this.#cacheGenerations.set( - hostId, - (this.#cacheGenerations.get(hostId) ?? 0) + 1 - ) - } - - async #request( - hostId: string, - mode: 'activate' | 'adopt', - options: RemoteRuntimeActivationRequestOptions, - expectedIdentity?: PublishedRemoteRuntimeInstallationIdentity - ): Promise { - this.#throwIfClosed() + this.#coordinator.assertAvailable() options.signal?.throwIfAborted() emitOne(options.onProgress, 'inspecting-host') + const agentKey = options.agentInstallationId ?? '' + const earlyCached = + this.#coordinator.cachedForHost(hostId, agentKey) + if (earlyCached !== undefined) { + emitOne(options.onProgress, 'complete') + return earlyCached + } const target = await this.#resolver.resolve(hostId) - this.#throwIfClosed() + this.#coordinator.assertAvailable() options.signal?.throwIfAborted() if (target.host.id !== hostId) { throw new RemoteRuntimeInstallationError( - 'Resolved SSH host does not match the Runtime installation request', + 'Resolved SSH host does not match the Runtime activation request', 'host-identity-changed' ) } const targetKey = remoteHostTargetIdentityKey(target) - const agentKey = options.agentInstallationId ?? '' - const cacheGeneration = - this.#cacheGenerations.get(hostId) ?? 0 - if (mode === 'activate') { - const current = this.#current.get(hostId) - if ( - current?.targetKey === targetKey && - current.agentKey === agentKey - ) { - emitOne(options.onProgress, 'complete') - return current.identity - } + const cached = this.#coordinator.cached( + hostId, + targetKey, + agentKey + ) + if (cached !== undefined) { + emitOne(options.onProgress, 'complete') + return cached } - const operationKey = mode === 'adopt' - ? `${mode}:${targetKey}:${publishedRuntimeIdentityKey( - expectedIdentity! - )}:${agentKey}` - : `${mode}:${targetKey}:${agentKey}` - const existing = this.#active.get(operationKey) - if (existing) { - return this.#waitForActive(existing, options) - } - if (this.#active.size >= this.#maximumConcurrentHosts) { - throw new RemoteRuntimeInstallationError( - 'Too many remote Runtime installations are already running', - 'capacity' - ) - } - - const progressCallbacks = new Set< - (phase: RemoteRuntimeInstallationPhase) => void - >() - const controller = new AbortController() - const progress = ( - phase: RemoteRuntimeInstallationPhase - ): void => { - for (const callback of progressCallbacks) { - emitOne(callback, phase) - } - } - const promise = (mode === 'activate' - ? this.#activateInstalled( + return this.#coordinator.run({ + hostId, + targetKey, + variantKey: agentKey, + signal: options.signal, + onProgress: options.onProgress, + operation: (signal, progress) => + this.#activateRegistered( target, options.agentInstallationId, - controller.signal, + signal, progress ) - : this.#activatePublished( - target, - expectedIdentity!, - options.agentInstallationId, - controller.signal, - progress - )).then((identity) => { - if ( - mode === 'activate' && - (this.#cacheGenerations.get(hostId) ?? 0) === - cacheGeneration - ) { - this.#current.set(hostId, { - targetKey, - agentKey, - identity - }) - } - return identity - }) - const active: ActiveInstallation = { - promise, - controller, - progressCallbacks, - waiters: 0, - settled: false - } - this.#active.set(operationKey, active) - void active.promise.finally(() => { - active.settled = true - if (this.#active.get(operationKey) === active) { - this.#active.delete(operationKey) - } - }).catch(() => undefined) - return this.#waitForActive(active, options) + }) + } + + invalidateHost(hostId: string): void { + this.#coordinator.invalidate(hostId) } dispose(): Promise { - if (this.#disposePromise) { - return this.#disposePromise - } - this.#closed = true - this.#current.clear() - this.#cacheGenerations.clear() - const operations = [...this.#active.values()] - const reason = new DOMException( - 'Remote Runtime installation manager was disposed', - 'AbortError' - ) - for (const operation of operations) { - operation.controller.abort(reason) - } - this.#disposePromise = settleBoundedly( - operations.map((operation) => operation.promise), - DISPOSE_WAIT_TIMEOUT_MS - ) - return this.#disposePromise + return this.#coordinator.dispose() } - #throwIfClosed(): void { - if (this.#closed) { - throw new Error( - 'Remote Runtime installation manager is disposed' - ) - } - } - - async #waitForActive( - active: ActiveInstallation, - options: RemoteRuntimeActivationRequestOptions - ): Promise { - active.waiters += 1 - if (options.onProgress) { - active.progressCallbacks.add(options.onProgress) - } - try { - return await waitForOperation(active.promise, options.signal) - } finally { - if (options.onProgress) { - active.progressCallbacks.delete(options.onProgress) - } - active.waiters -= 1 - if ( - active.waiters === 0 && - !active.settled && - !active.controller.signal.aborted - ) { - active.controller.abort( - new DOMException( - 'Remote Runtime installation has no remaining waiters', - 'AbortError' - ) - ) - } - } - } - - async #activateInstalled( + async #activateRegistered( target: SshConnectionPoolTarget, agentInstallationId: VerifiedAgentInstallationId | undefined, signal: AbortSignal, progress: (phase: RemoteRuntimeInstallationPhase) => void - ): Promise { - let lease: SshConnectionLease | undefined - try { - lease = await this.#sshPool.acquire(target, signal) - assertLeaseMatchesTarget(lease, target) - const probe = await lease.runAgentBootstrapProbe(signal) - if (!probe.ready) { - throw new RemoteRuntimeInstallationError( - `Remote host cannot activate the OpenCode Runtime: ${probe.reason}`, - 'incompatible', - probe.reason - ) - } - if ( - probe.platform !== 'linux' || - (probe.architecture !== 'x64' && - probe.architecture !== 'arm64') - ) { - throw new RemoteRuntimeInstallationError( - 'Remote host platform or architecture is unsupported', - 'incompatible' - ) - } - progress('verifying-bundle') - return await this.#reuseInstalledBundle( - target, - lease, - probe, - agentInstallationId, - signal, - progress - ) - } catch (error) { - if ( - error instanceof RemoteRuntimeInstallationError || - isAbortError(error) - ) { - throw error - } - throw new RemoteRuntimeInstallationError( - 'Remote Runtime activation data is corrupt or unsafe', - 'corrupt', - safeErrorDetail(error) - ) - } finally { - lease?.release() - } - } - - async #activatePublished( - target: SshConnectionPoolTarget, - expected: PublishedRemoteRuntimeInstallationIdentity, - agentInstallationId: VerifiedAgentInstallationId | undefined, - signal: AbortSignal, - progress: (phase: RemoteRuntimeInstallationPhase) => void ): Promise { let lease: SshConnectionLease | undefined let sftp: StagedSftp | undefined - let metadataSnapshots: readonly ManagedFileSnapshot[] | undefined - const cleanup: CleanupEntry[] = [] try { lease = await this.#sshPool.acquire(target, signal) assertLeaseMatchesTarget(lease, target) const probe = await lease.runAgentBootstrapProbe(signal) if (!probe.ready) { throw new RemoteRuntimeInstallationError( - `Remote host cannot activate the published OpenCode Runtime: ${probe.reason}`, + `Remote host cannot activate OpenCode Runtime: ${probe.reason}`, 'incompatible', probe.reason ) } if ( - probe.platform !== expected.platform || - probe.architecture !== expected.architecture + probe.platform !== 'linux' || + ( + probe.architecture !== 'x64' && + probe.architecture !== 'arm64' + ) ) { throw new RemoteRuntimeInstallationError( - 'Published Runtime does not match the Host platform or architecture', + 'Remote host platform or architecture is unsupported', 'incompatible' ) } progress('verifying-bundle') - const metadata = await this.#loadPublishedVerificationMetadata( - probe.architecture - ) sftp = await lease.openStagedSftp( - probe.canonicalHomeDirectory, - { - maximumFileBytes: Math.max( - MAXIMUM_RUNTIME_FILE_BYTES, - this.#sftpLimits?.maximumFileBytes ?? 0 - ), - maximumTotalBytes: Math.max( - MAXIMUM_INSTALLATION_BYTES + - MAXIMUM_METADATA_BYTES * 6, - this.#sftpLimits?.maximumTotalBytes ?? 0 - ), - maximumOperations: - this.#sftpLimits?.maximumOperations ?? 2_048, - operationTimeoutMs: - this.#sftpLimits?.operationTimeoutMs - }, - signal - ) - const destination = - `${OPENCODE_ROOT}/${digestDirectoryName( - expected.bundleDigest - )}` - const manifestBytes = await sftp.readFile( - `${destination}/manifest.json`, - signal - ) - const signatureFile = await sftp.readFile( - `${destination}/manifest.sig`, - signal - ) - const signature = decodeDetachedSignature( - signatureFile, - 'Runtime detached signature' - ) - const manifest = await verifyRuntimeManifestSignature( - manifestBytes, - signature, - metadata.releaseKeyRegistry - ) - assertRuntimeManifestMatchesLock( - manifest, - metadata.runtimeLock, - probe.architecture - ) - const manifestDigest = - await digestRemoteRuntimeBundleManifest(manifest) - const bundle: LoadedBundle = { - bundleDirectory: destination, - manifest, - manifestDigest, - releaseKeyRegistryBytes: - metadata.releaseKeyRegistryBytes, - remoteRuntimeLockBytes: - metadata.remoteRuntimeLockBytes - } - assertPublishedRuntimeMatches(expected, bundle) - assertBundleCapacity(bundle) - // The fixed SSH installer has already verified the complete published - // tree against this signed manifest. Adoption rechecks its immutable - // identity and metadata without transferring the payload back to Main. - await verifyRemoteBundleFromMetadata( - sftp, - destination, - bundle, - manifestBytes, - signatureFile, - probe.uid, - signal - ) - metadataSnapshots = [] - for (const path of [ - RELEASE_KEYS_PATH, - RUNTIME_LOCK_PATH, - RUNTIME_REGISTRY_PATH - ]) { - metadataSnapshots = [ - ...metadataSnapshots, - await snapshotManagedFile( - sftp, - path, - probe.uid, - signal - ) - ] - } - await installPrivateMetadata( - sftp, - RELEASE_KEYS_PATH, - '.release-keys', - metadata.releaseKeyRegistryBytes, - probe.uid, - cleanup, - signal - ) - await installPrivateMetadata( - sftp, - RUNTIME_LOCK_PATH, - '.remote-runtime-lock', - metadata.remoteRuntimeLockBytes, - probe.uid, - cleanup, - signal - ) - await assertCurrentTarget( - this.#resolver, - lease, - target, - signal - ) - progress('activating-runtime') - await activateRuntime( - this.#activate, - lease, - bundle, - agentInstallationId, - signal - ) - progress('complete') - return publicIdentity(bundle) - } catch (error) { - if (metadataSnapshots && sftp) { - await restoreManagedFiles(sftp, metadataSnapshots).catch( - (rollbackError: unknown) => { - throw new AggregateError( - [error, rollbackError], - 'Published Runtime activation failed and its previous metadata state could not be restored' - ) - } - ) - } - if ( - error instanceof RemoteRuntimeInstallationError || - isAbortError(error) - ) { - throw error - } - throw new RemoteRuntimeInstallationError( - 'The published Host OpenCode Runtime could not be verified', - 'corrupt', - safeErrorDetail(error) - ) - } finally { - if (sftp) { - await cleanupOwnedStaging(sftp, cleanup) - } - sftp?.close() - lease?.release() - } - } - - async #loadPublishedVerificationMetadata( - architecture: AgentArchitecture - ): Promise<{ - releaseKeyRegistry: AgentReleaseKeyRegistry - runtimeLock: RemoteRuntimeLock - releaseKeyRegistryBytes: Buffer - remoteRuntimeLockBytes: Buffer - }> { - const loadMetadata = this.#loadVerificationMetadata - if (loadMetadata === undefined) { - throw new RemoteRuntimeInstallationError( - 'This package cannot verify a Host Runtime', - 'incompatible' - ) - } - const metadata = await loadMetadata(architecture) - const releaseKeyRegistryBytes = canonicalJsonBytes( - metadata.canonicalReleaseKeyRegistryBytes, - agentReleaseKeyRegistrySchema, - 'Runtime release-key registry' - ) - const remoteRuntimeLockBytes = canonicalJsonBytes( - metadata.canonicalRemoteRuntimeLockBytes, - remoteRuntimeLockSchema, - 'Remote Runtime lock' - ) - const releaseKeyRegistry = - agentReleaseKeyRegistrySchema.parse( - metadata.releaseKeyRegistry - ) - const runtimeLock = remoteRuntimeLockSchema.parse( - metadata.runtimeLock - ) - if ( - !canonicalJsonValueBytes(releaseKeyRegistry).equals( - releaseKeyRegistryBytes - ) || - !canonicalJsonValueBytes(runtimeLock).equals( - remoteRuntimeLockBytes - ) - ) { - throw new Error( - 'Runtime verification metadata values do not match their canonical bytes' - ) - } - return { - releaseKeyRegistry, - runtimeLock, - releaseKeyRegistryBytes, - remoteRuntimeLockBytes - } - } - - async #reuseInstalledBundle( - target: SshConnectionPoolTarget, - lease: SshConnectionLease, - probe: { - architecture: AgentArchitecture - canonicalHomeDirectory: string - uid: number - }, - agentInstallationId: VerifiedAgentInstallationId | undefined, - signal: AbortSignal, - progress: (phase: RemoteRuntimeInstallationPhase) => void - ): Promise { - let metadataSftp: StagedSftp | undefined - try { - const { - releaseKeyRegistry, - runtimeLock, - releaseKeyRegistryBytes, - remoteRuntimeLockBytes - } = await this.#loadPublishedVerificationMetadata( - probe.architecture - ) - - metadataSftp = await lease.openStagedSftp( probe.canonicalHomeDirectory, { maximumFileBytes: MAXIMUM_METADATA_BYTES, - maximumTotalBytes: MAXIMUM_METADATA_BYTES * 6, - maximumOperations: 48, + maximumTotalBytes: MAXIMUM_METADATA_BYTES * 3, + maximumOperations: 12, operationTimeoutMs: 15_000 }, signal ) - const [ - remoteRegistryBytes, - remoteReleaseKeyBytes, - remoteRuntimeLockFileBytes - ] = await Promise.all([ - metadataSftp.readFile(RUNTIME_REGISTRY_PATH, signal), - metadataSftp.readFile(RELEASE_KEYS_PATH, signal), - metadataSftp.readFile(RUNTIME_LOCK_PATH, signal) - ]) - const remoteReleaseKeyRegistryBytes = - Buffer.from(remoteReleaseKeyBytes) - const remoteReleaseKeyRegistry = - parseAgentReleaseKeyRegistryBytes( - remoteReleaseKeyRegistryBytes, - 'Installed Runtime release-key registry' + await assertPrivateMetadata( + sftp, + RUNTIME_REGISTRY_PATH, + probe.uid, + signal ) - if (!remoteRuntimeLockFileBytes.equals(remoteRuntimeLockBytes)) { - throw new Error( - 'Installed Runtime lock does not match this GoodBuddy build' - ) - } - const remoteRegistry = parseRuntimeRegistryState( + const registry = parseRuntimeRegistryState( parseJsonBytes( - remoteRegistryBytes, + await sftp.readFile( + RUNTIME_REGISTRY_PATH, + signal + ), 'Installed Runtime registry' ) ) - const current = remoteRegistry.current.find( + const current = registry.current.find( (entry) => entry.runtimeId === 'opencode' && entry.architecture === probe.architecture ) - if ( - current === undefined || - current.runtimeVersion !== - runtimeLock.runtimes.opencode.version - ) { + if (current === undefined) { throw new RemoteRuntimeInstallationError( - 'This package does not include Runtime installation resources and the Host has no matching current OpenCode Runtime', + 'The Host has no current OpenCode Runtime for this architecture', 'incompatible' ) } - const destination = - `${OPENCODE_ROOT}/${digestDirectoryName(current.bundleDigest)}` - const manifestBytes = await metadataSftp.readFile( - `${destination}/manifest.json`, - signal - ) - const signatureFile = await metadataSftp.readFile( - `${destination}/manifest.sig`, - signal - ) - const signature = decodeDetachedSignature( - signatureFile, - 'Runtime detached signature' - ) - const manifest = await verifyRuntimeManifestSignature( - manifestBytes, - signature, - releaseKeyRegistry - ) - await verifyRuntimeManifestSignature( - manifestBytes, - signature, - remoteReleaseKeyRegistry - ) - assertRuntimeManifestMatchesLock( - manifest, - runtimeLock, - probe.architecture - ) - const manifestDigest = - await digestRemoteRuntimeBundleManifest(manifest) - if ( - manifest.bundleDigest !== current.bundleDigest || - manifestDigest !== current.manifestDigest || - manifest.acpCapabilitiesDigest !== - current.acpCapabilitiesDigest - ) { - throw new Error( - 'Installed Runtime manifest identity does not match its registry' + + let runtimeAdapterDigest = + current.runtimeAdapterDigest + if (runtimeAdapterDigest === undefined) { + const manifestPath = + `${OPENCODE_ROOT}/${digestDirectoryName( + current.bundleDigest + )}/manifest.json` + await assertPublicMetadata( + sftp, + manifestPath, + probe.uid, + signal ) + const manifest = + remoteRuntimeBundleManifestSchema.parse( + parseJsonBytes( + await sftp.readFile(manifestPath, signal), + 'Installed Runtime manifest' + ) + ) + if ( + manifest.runtimeId !== current.runtimeId || + manifest.runtimeVersion !== + current.runtimeVersion || + manifest.bundleDigest !== current.bundleDigest + ) { + throw new Error( + 'Installed Runtime manifest identity does not match its registry' + ) + } + runtimeAdapterDigest = manifest.adapterDigest } - const bundle: LoadedBundle = { - bundleDirectory: destination, - manifest, - manifestDigest, - releaseKeyRegistryBytes, - remoteRuntimeLockBytes - } - assertBundleCapacity(bundle) - await verifyRemoteFile( - metadataSftp, - RUNTIME_REGISTRY_PATH, - remoteRegistryBytes.byteLength, - sha256(remoteRegistryBytes), - probe.uid, - PRIVATE_FILE_MODE, - signal - ) - await verifyRemoteFile( - metadataSftp, - RELEASE_KEYS_PATH, - remoteReleaseKeyRegistryBytes.byteLength, - sha256(remoteReleaseKeyRegistryBytes), - probe.uid, - PRIVATE_FILE_MODE, - signal - ) - await verifyRemoteFile( - metadataSftp, - RUNTIME_LOCK_PATH, - remoteRuntimeLockBytes.byteLength, - sha256(remoteRuntimeLockBytes), - probe.uid, - PRIVATE_FILE_MODE, - signal - ) - await verifyRemoteBundleFromMetadata( - metadataSftp, - destination, - bundle, - manifestBytes, - signatureFile, - probe.uid, - signal - ) - metadataSftp.close() - metadataSftp = undefined - await assertCurrentTarget( - this.#resolver, - lease, - target, - signal - ) + sftp.close() + sftp = undefined + progress('activating-runtime') - await activateRuntime( - this.#activate, + await this.#activate( lease, - bundle, + current.runtimeId, + current.bundleDigest, + current.architecture, agentInstallationId, signal ) progress('complete') - return publicIdentity(bundle) + return { + runtimeId: current.runtimeId, + runtimeVersion: current.runtimeVersion, + bundleDigest: current.bundleDigest, + manifestDigest: current.manifestDigest, + runtimeAdapterDigest, + acpCapabilitiesDigest: + current.acpCapabilitiesDigest, + platform: 'linux', + architecture: current.architecture + } } catch (error) { - rethrowAbort(error) if (error instanceof RemoteRuntimeInstallationError) { throw error } if (isMissingPathError(error)) { throw new RemoteRuntimeInstallationError( - 'This package does not include Runtime installation resources and the Host has no matching current OpenCode Runtime', + 'The Host has no current OpenCode Runtime', 'incompatible', - safeErrorDetail(error) + error ) } throw new RemoteRuntimeInstallationError( - 'The existing Host OpenCode Runtime could not be verified', + `The registered Host OpenCode Runtime could not be activated: ${safeErrorDetail(error)}`, 'corrupt', - safeErrorDetail(error) + error ) } finally { - metadataSftp?.close() + sftp?.close() + lease?.release() } } + +} + +async function assertPrivateMetadata( + sftp: StagedSftp, + path: string, + uid: number, + signal: AbortSignal +): Promise { + const metadata = await sftp.lstat(path, signal) + if ( + metadata.type !== 'file' || + metadata.uid !== uid || + metadata.mode !== PRIVATE_FILE_MODE || + metadata.size > MAXIMUM_METADATA_BYTES + ) { + throw new Error( + `Remote Runtime metadata is invalid: ${path}` + ) + } +} + +async function assertPublicMetadata( + sftp: StagedSftp, + path: string, + uid: number, + signal: AbortSignal +): Promise { + const metadata = await sftp.lstat(path, signal) + if ( + metadata.type !== 'file' || + metadata.uid !== uid || + metadata.mode !== 0o644 || + metadata.size > MAXIMUM_METADATA_BYTES + ) { + throw new Error( + `Remote Runtime manifest metadata is invalid: ${path}` + ) + } +} + +function digestDirectoryName(bundleDigest: string): string { + if (!/^sha256:[a-f0-9]{64}$/u.test(bundleDigest)) { + throw new Error('Runtime bundle digest is invalid') + } + return bundleDigest.slice('sha256:'.length) +} + +function parseJsonBytes( + value: Buffer, + description: string +): unknown { + try { + return JSON.parse(value.toString('utf8')) as unknown + } catch (error) { + throw new Error(`${description} is not valid JSON`, { + cause: error + }) + } } function assertLeaseMatchesTarget( @@ -915,631 +391,18 @@ function assertLeaseMatchesTarget( ) ) { throw new RemoteRuntimeInstallationError( - 'SSH lease identity changed during Runtime installation', + 'SSH lease identity changed during Runtime activation', 'host-identity-changed' ) } } -async function assertCurrentTarget( - resolver: RemoteRuntimeInstallationTargetResolver, - lease: SshConnectionLease, - originalTarget: SshConnectionPoolTarget, - signal: AbortSignal -): Promise { - signal.throwIfAborted() - const currentTarget = await resolver.resolve( - originalTarget.host.id - ) - signal.throwIfAborted() - if ( - remoteHostTargetIdentityKey(currentTarget) !== - remoteHostTargetIdentityKey(originalTarget) - ) { - throw new RemoteRuntimeInstallationError( - 'SSH host identity changed before Runtime publication or activation', - 'host-identity-changed' - ) - } - assertLeaseMatchesTarget(lease, currentTarget) +function safeErrorDetail(error: unknown): string { + const value = error instanceof Error + ? error.message + : String(error) + return boundedDiagnostic(value) } - -function publicIdentity( - bundle: LoadedBundle -): RemoteRuntimeInstallationIdentity { - return { - runtimeId: bundle.manifest.runtimeId, - runtimeVersion: bundle.manifest.runtimeVersion, - bundleDigest: bundle.manifest.bundleDigest, - manifestDigest: bundle.manifestDigest, - runtimeAdapterDigest: bundle.manifest.adapterDigest, - acpCapabilitiesDigest: - bundle.manifest.acpCapabilitiesDigest, - platform: bundle.manifest.platform, - architecture: bundle.manifest.architecture - } -} - -function assertPublishedRuntimeIdentity( - identity: PublishedRemoteRuntimeInstallationIdentity -): void { - if ( - identity.runtimeId !== 'opencode' || - identity.runtimeVersion.length < 1 || - !sha256DigestSchema.safeParse(identity.bundleDigest).success || - !sha256DigestSchema.safeParse(identity.manifestDigest).success || - !sha256DigestSchema.safeParse( - identity.runtimeAdapterDigest - ).success || - !sha256DigestSchema.safeParse( - identity.acpCapabilitiesDigest - ).success || - identity.platform !== 'linux' || - (identity.architecture !== 'x64' && - identity.architecture !== 'arm64') || - !Number.isSafeInteger(identity.protocol.major) || - identity.protocol.major < 0 || - !Number.isSafeInteger(identity.protocol.minor) || - identity.protocol.minor < 0 - ) { - throw new RemoteRuntimeInstallationError( - 'Published Runtime identity is invalid', - 'corrupt' - ) - } -} - -function assertPublishedRuntimeMatches( - expected: PublishedRemoteRuntimeInstallationIdentity, - bundle: LoadedBundle -): void { - if ( - expected.runtimeId !== bundle.manifest.runtimeId || - expected.runtimeVersion !== bundle.manifest.runtimeVersion || - expected.bundleDigest !== bundle.manifest.bundleDigest || - expected.manifestDigest !== bundle.manifestDigest || - expected.runtimeAdapterDigest !== bundle.manifest.adapterDigest || - expected.acpCapabilitiesDigest !== - bundle.manifest.acpCapabilitiesDigest || - expected.platform !== bundle.manifest.platform || - expected.architecture !== bundle.manifest.architecture || - expected.protocol.major !== bundle.manifest.protocol.major || - expected.protocol.minor !== bundle.manifest.protocol.minor - ) { - throw new RemoteRuntimeInstallationError( - 'Published Runtime does not match the authenticated package result', - 'corrupt' - ) - } -} - -function publishedRuntimeIdentityKey( - identity: PublishedRemoteRuntimeInstallationIdentity -): string { - return createHash('sha256') - .update(JSON.stringify(identity)) - .digest('hex') -} - -function digestDirectoryName(bundleDigest: string): string { - if (!sha256DigestSchema.safeParse(bundleDigest).success) { - throw new Error('Runtime bundle digest is invalid') - } - return bundleDigest.slice('sha256:'.length) -} - -function assertBundleCapacity(bundle: LoadedBundle): void { - const metadataBytes = - bundle.releaseKeyRegistryBytes.byteLength + - bundle.remoteRuntimeLockBytes.byteLength - const payloadBytes = bundle.manifest.files.reduce( - (sum, file) => sum + file.size, - 0 - ) - const total = payloadBytes + metadataBytes - if ( - bundle.manifest.files.length > MAXIMUM_INSTALLATION_FILES || - bundle.manifest.files.some( - (file) => file.size > MAXIMUM_RUNTIME_FILE_BYTES - ) || - bundle.releaseKeyRegistryBytes.byteLength > - MAXIMUM_METADATA_BYTES || - bundle.remoteRuntimeLockBytes.byteLength > - MAXIMUM_METADATA_BYTES || - !Number.isSafeInteger(total) || - total > MAXIMUM_INSTALLATION_BYTES - ) { - throw new RemoteRuntimeInstallationError( - 'OpenCode Runtime bundle exceeds installation safety limits', - 'capacity' - ) - } -} - -async function installPrivateMetadata( - sftp: StagedSftp, - destination: string, - temporaryPrefix: string, - contents: Buffer, - uid: number, - cleanup: CleanupEntry[], - signal: AbortSignal -): Promise { - const existing = await pathMetadata(sftp, destination, signal) - if (existing !== undefined) { - assertMetadata( - existing, - destination, - 'file', - uid, - PRIVATE_FILE_MODE, - undefined - ) - if ( - existing.size === contents.byteLength && - (await sftp.readFile(destination, signal)).equals(contents) - ) { - return - } - } - const temporary = - `${RUNTIME_ROOT}/${temporaryPrefix}-${randomUUID()}.tmp` - trackCleanup(cleanup, { path: temporary, type: 'file' }) - await sftp.writeFile(temporary, contents, signal) - await sftp.chmod(temporary, PRIVATE_FILE_MODE, signal) - await verifyRemoteFile( - sftp, - temporary, - contents.byteLength, - sha256(contents), - uid, - PRIVATE_FILE_MODE, - signal - ) - await sftp.replaceFile(temporary, destination, signal) - removeCleanup(cleanup, temporary) - await verifyRemoteFile( - sftp, - destination, - contents.byteLength, - sha256(contents), - uid, - PRIVATE_FILE_MODE, - signal - ) -} - -async function snapshotManagedFile( - sftp: StagedSftp, - path: string, - uid: number, - signal: AbortSignal -): Promise { - const metadata = await pathMetadata(sftp, path, signal) - if (metadata === undefined) { - return { path, contents: undefined, uid } - } - assertMetadata( - metadata, - path, - 'file', - uid, - PRIVATE_FILE_MODE, - undefined - ) - return { - path, - contents: await sftp.readFile(path, signal), - uid - } -} - -async function restoreManagedFile( - sftp: StagedSftp, - snapshot: ManagedFileSnapshot -): Promise { - const existing = await pathMetadata(sftp, snapshot.path) - if (snapshot.contents === undefined) { - if (existing !== undefined) { - assertMetadata( - existing, - snapshot.path, - 'file', - snapshot.uid, - PRIVATE_FILE_MODE, - undefined - ) - await sftp.unlink(snapshot.path) - } - return - } - if ( - existing !== undefined && - existing.type === 'file' && - existing.uid === snapshot.uid && - existing.mode === PRIVATE_FILE_MODE && - existing.size === snapshot.contents.byteLength && - (await sftp.readFile(snapshot.path)).equals(snapshot.contents) - ) { - return - } - if (existing !== undefined) { - assertMetadata( - existing, - snapshot.path, - 'file', - snapshot.uid, - undefined, - undefined - ) - } - const temporary = - `${RUNTIME_ROOT}/.registry-rollback-${randomUUID()}.tmp` - try { - await sftp.writeFile(temporary, snapshot.contents) - await sftp.chmod(temporary, PRIVATE_FILE_MODE) - await sftp.replaceFile(temporary, snapshot.path) - await verifyRemoteFile( - sftp, - snapshot.path, - snapshot.contents.byteLength, - sha256(snapshot.contents), - snapshot.uid, - PRIVATE_FILE_MODE, - new AbortController().signal - ) - } catch (error) { - await sftp.unlink(temporary).catch(() => undefined) - throw error - } -} - -async function restoreManagedFiles( - sftp: StagedSftp, - snapshots: readonly ManagedFileSnapshot[] -): Promise { - const errors: unknown[] = [] - for (const snapshot of snapshots) { - try { - await restoreManagedFile(sftp, snapshot) - } catch (error) { - errors.push(error) - } - } - if (errors.length > 0) { - throw new AggregateError( - errors, - 'Remote Runtime metadata rollback was incomplete' - ) - } -} - -async function verifyRemoteBundleFromMetadata( - sftp: StagedSftp, - destination: string, - bundle: LoadedBundle, - manifestBytes: Buffer, - signatureBytes: Buffer, - uid: number, - signal: AbortSignal -): Promise { - await assertRemoteMetadata( - sftp, - destination, - 'directory', - uid, - PRIVATE_DIRECTORY_MODE, - undefined, - signal - ) - const checkedDirectories = new Set() - for (const file of bundle.manifest.files) { - const parts = file.path.split('/') - let directory = destination - for (const part of parts.slice(0, -1)) { - directory = `${directory}/${part}` - if (!checkedDirectories.has(directory)) { - checkedDirectories.add(directory) - await assertRemoteMetadata( - sftp, - directory, - 'directory', - uid, - PRIVATE_DIRECTORY_MODE, - undefined, - signal - ) - } - } - const path = `${destination}/${file.path}` - const mode = file.mode === '0755' ? 0o755 : 0o644 - await assertRemoteMetadata( - sftp, - path, - 'file', - uid, - mode, - file.size, - signal - ) - } - for (const [metadataName, contents] of [ - ['manifest.json', manifestBytes], - ['manifest.sig', signatureBytes] - ] as const) { - if (contents.byteLength > MAXIMUM_METADATA_BYTES) { - throw new Error('Runtime metadata exceeds its safety limit') - } - const path = `${destination}/${metadataName}` - await assertRemoteMetadata( - sftp, - path, - 'file', - uid, - METADATA_MODE, - contents.byteLength, - signal - ) - } -} - -async function verifyRemoteFile( - sftp: StagedSftp, - path: string, - size: number, - digest: string, - uid: number, - mode: number, - signal: AbortSignal -): Promise { - await assertRemoteMetadata( - sftp, - path, - 'file', - uid, - mode, - size, - signal - ) - const contents = await sftp.readFile(path, signal) - if (contents.byteLength !== size || sha256(contents) !== digest) { - throw new Error(`Remote Runtime file readback mismatch: ${path}`) - } - await assertRemoteMetadata( - sftp, - path, - 'file', - uid, - mode, - size, - signal - ) -} - -async function assertRemoteMetadata( - sftp: StagedSftp, - path: string, - type: 'file' | 'directory', - uid: number, - mode: number, - size: number | undefined, - signal: AbortSignal -): Promise { - assertMetadata( - await sftp.stat(path, signal), - path, - type, - uid, - mode, - size - ) -} - -function assertMetadata( - metadata: SftpEntryMetadata, - path: string, - type: 'file' | 'directory', - uid: number, - mode: number | undefined, - size: number | undefined -): void { - if ( - metadata.type !== type || - metadata.uid !== uid || - (mode !== undefined && metadata.mode !== mode) || - (size !== undefined && metadata.size !== size) - ) { - throw new Error(`Remote Runtime metadata mismatch: ${path}`) - } -} - -async function pathMetadata( - sftp: StagedSftp, - path: string, - signal?: AbortSignal -): Promise { - try { - return await sftp.lstat(path, signal) - } catch (error) { - if (isMissingPathError(error)) { - return undefined - } - throw error - } -} - -async function activateRuntime( - activate: RemoteRuntimeActivator, - lease: SshConnectionLease, - bundle: LoadedBundle, - agentInstallationId: VerifiedAgentInstallationId | undefined, - signal: AbortSignal -): Promise { - signal.throwIfAborted() - try { - await activate( - lease, - bundle.manifest.runtimeId, - bundle.manifest.bundleDigest, - bundle.manifest.architecture, - agentInstallationId, - signal - ) - } catch (error) { - rethrowAbort(error) - throw new RemoteRuntimeInstallationError( - 'OpenCode Runtime activation failed', - 'activation', - safeErrorDetail(error) - ) - } -} - -function canonicalJsonBytes( - input: Uint8Array | undefined, - schema: { parse(value: unknown): T }, - label: string -): Buffer { - if (input === undefined) { - throw new Error(`${label} bytes are missing`) - } - const bytes = Buffer.from(input) - if ( - bytes.byteLength === 0 || - bytes.byteLength > MAXIMUM_METADATA_BYTES - ) { - throw new Error(`${label} exceeds its safety limit`) - } - let parsedJson: unknown - try { - parsedJson = JSON.parse(bytes.toString('utf8')) - } catch (error) { - throw new Error(`${label} is invalid JSON`, { cause: error }) - } - const parsed = schema.parse(parsedJson) - const canonical = Buffer.from( - `${JSON.stringify(parsed, null, 2)}\n`, - 'utf8' - ) - if (!canonical.equals(bytes)) { - throw new Error(`${label} bytes are not canonical`) - } - return canonical -} - -function canonicalJsonValueBytes(value: unknown): Buffer { - return Buffer.from(`${JSON.stringify(value, null, 2)}\n`, 'utf8') -} - -function parseJsonBytes( - value: Buffer, - description: string -): unknown { - try { - return JSON.parse(value.toString('utf8')) as unknown - } catch (error) { - throw new Error(`${description} is not valid JSON`, { - cause: error - }) - } -} - -function decodeDetachedSignature( - value: Buffer, - description: string -): Buffer { - const text = value.toString('ascii') - if (!/^[A-Za-z0-9+/]{86}==\n$/u.test(text)) { - throw new Error(`${description} is not canonical Base64`) - } - const signature = Buffer.from(text.slice(0, -1), 'base64') - if (signature.byteLength !== 64) { - throw new Error(`${description} is not an Ed25519 signature`) - } - return signature -} - -function trackCleanup( - cleanup: CleanupEntry[], - entry: CleanupEntry -): void { - if (cleanup.length >= MAXIMUM_CLEANUP_ENTRIES) { - throw new RemoteRuntimeInstallationError( - 'Runtime cleanup inventory exceeds its safety limit', - 'capacity' - ) - } - cleanup.push(entry) -} - -function removeCleanup( - cleanup: CleanupEntry[], - path: string -): void { - const index = cleanup.findIndex((entry) => entry.path === path) - if (index >= 0) { - cleanup.splice(index, 1) - } -} - -async function cleanupOwnedStaging( - sftp: StagedSftp, - entries: readonly CleanupEntry[] -): Promise { - let complete = true - for (const entry of [...entries] - .slice(0, MAXIMUM_CLEANUP_ENTRIES) - .reverse()) { - try { - if (entry.type === 'file') { - await sftp.unlink(entry.path) - } else { - await sftp.rmdir(entry.path) - } - } catch (error) { - if (!isMissingPathError(error)) { - complete = false - // Cleanup never widens beyond operation-owned temporary paths. - } - } - } - return complete -} - -function waitForOperation( - promise: Promise, - signal?: AbortSignal -): Promise { - if (!signal) { - return promise - } - if (signal.aborted) { - return Promise.reject( - signal.reason ?? - new DOMException('The operation was aborted', 'AbortError') - ) - } - return new Promise((resolve, reject) => { - const abort = (): void => { - reject( - signal.reason ?? - new DOMException('The operation was aborted', 'AbortError') - ) - } - signal.addEventListener('abort', abort, { once: true }) - promise.then( - (value) => { - signal.removeEventListener('abort', abort) - resolve(value) - }, - (error: unknown) => { - signal.removeEventListener('abort', abort) - reject(error) - } - ) - }) -} - function emitOne( callback: | ((phase: RemoteRuntimeInstallationPhase) => void) @@ -1549,35 +412,6 @@ function emitOne( try { callback?.(phase) } catch { - // Progress observers cannot alter installation outcomes. + // Progress observers cannot alter activation state. } } - -function isAbortError(error: unknown): boolean { - return ( - typeof error === 'object' && - error !== null && - 'name' in error && - (error as { name?: unknown }).name === 'AbortError' - ) -} - -function rethrowAbort(error: unknown): void { - if (isAbortError(error)) { - throw error - } -} - -function safeErrorDetail(error: unknown): unknown { - if (error instanceof Error) { - return { - name: error.name, - message: error.message - } - } - return undefined -} - -function sha256(contents: Uint8Array): string { - return createHash('sha256').update(contents).digest('hex') -} diff --git a/src/main/ssh/ssh-agent-command.ts b/src/main/ssh/ssh-agent-command.ts index eee265ae..53374b26 100644 --- a/src/main/ssh/ssh-agent-command.ts +++ b/src/main/ssh/ssh-agent-command.ts @@ -24,6 +24,7 @@ export const AGENT_BOOTSTRAP_PROBE_COMMAND = [ ].join('; ') const lifecycleActions = [ + 'adopt', 'bootstrap', 'health', 'status', @@ -48,6 +49,7 @@ export type AgentRuntimeActivationAction = { runtimeId: typeof RUNTIME_ID bundleDigest: string architecture: AgentRuntimeArchitecture + forceVerification?: true } export type FixedAgentSshAction = @@ -232,7 +234,10 @@ export function buildFixedAgentCliArgv( '--bundle-digest', action.bundleDigest, '--architecture', - action.architecture + action.architecture, + ...(action.forceVerification === true + ? ['--force-verification', 'true'] + : []) ] } } diff --git a/src/main/ssh/ssh-remote-package-bootstrap.test.ts b/src/main/ssh/ssh-remote-package-bootstrap.test.ts index c5c1c98c..1b071d2d 100644 --- a/src/main/ssh/ssh-remote-package-bootstrap.test.ts +++ b/src/main/ssh/ssh-remote-package-bootstrap.test.ts @@ -508,10 +508,13 @@ describe("fixed SSH remote package bootstrap", () => { SSH_REMOTE_PACKAGE_BOOTSTRAP_SCRIPT.match( /\[ "\$installer_output_size" -gt 0 \]/gu, ), - ).toHaveLength(4); + ).toHaveLength(3); expect(SSH_REMOTE_PACKAGE_BOOTSTRAP_SCRIPT).toContain( '[ "$installer_output_size" -le 49152 ]', ); + expect(SSH_REMOTE_PACKAGE_BOOTSTRAP_SCRIPT).toContain( + 'action=commit', + ); }); it("parses bounded split NDJSON progress and a prepared result", async () => { @@ -677,6 +680,7 @@ describe("fixed SSH remote package bootstrap", () => { prepared: false, unavailable: false, reason: "installer-failed", + detail: "archive verification failed", }); const rollbackFailure = createChannel((_payload, active) => { @@ -692,6 +696,7 @@ describe("fixed SSH remote package bootstrap", () => { ).resolves.toEqual({ committed: false, reason: "installer-rollback-incomplete", + detail: "managed destination restore failed", }); }); diff --git a/src/main/ssh/ssh-remote-package-bootstrap.ts b/src/main/ssh/ssh-remote-package-bootstrap.ts index 90b9c318..0fc8adfb 100644 --- a/src/main/ssh/ssh-remote-package-bootstrap.ts +++ b/src/main/ssh/ssh-remote-package-bootstrap.ts @@ -46,9 +46,9 @@ const progressPhases = [ "verifying-payload", "persisting-prepared-state", "validating-prepared-state", - "revalidating-archive", "extracting-payload", "publishing-content", + "publishing-metadata", ] as const; const unavailableReasons = [ @@ -166,6 +166,7 @@ export type SshRemotePackageBootstrapPrepareResult = prepared: false; unavailable: false; reason: SshRemotePackageBootstrapFailureReason; + detail?: string; }; export type SshRemotePackageUploadStagingResult = @@ -195,6 +196,7 @@ export type SshRemotePackageBootstrapCommitResult = | { committed: false; reason: SshRemotePackageBootstrapFailureReason; + detail?: string; }; export type SshRemotePackageBootstrapCleanupResult = @@ -268,6 +270,7 @@ type TerminalMessage = type: "result"; status: "failed"; reason: SshRemotePackageBootstrapFailureReason; + detail?: string; } | { type: "result"; @@ -467,23 +470,29 @@ if [ "$action" = prepare-status ]; then fi if [ "$action" = commit-status ]; then installer_output="$operation_root/installer-commit.ndjson" - if [ ! -d "$operation_root" ] || [ -L "$operation_root" ] || - [ ! -f "$installer_output" ] || [ -L "$installer_output" ]; then - stop failed operation-unavailable + if [ -d "$operation_root" ] && [ ! -L "$operation_root" ] && + [ -f "$installer_output" ] && [ ! -L "$installer_output" ]; then + installer_output_size=$(wc -c < "$installer_output" 2>/dev/null) || + stop failed operation-unavailable + set -- $installer_output_size + installer_output_size=${SHELL_FIRST_POSITIONAL_OR_EMPTY} + case "$installer_output_size" in + ""|*[!0-9]*) stop failed operation-unavailable ;; + esac + [ "$installer_output_size" -le 49152 ] || + stop failed operation-unavailable + terminal_line=$(tail -n 1 "$installer_output" 2>/dev/null) || + stop failed operation-unavailable + if printf %s "$terminal_line" | grep '"type":"result"' >/dev/null 2>&1 || + printf %s "$terminal_line" | grep '"type":"error"' >/dev/null 2>&1; then + cat -- "$installer_output" || stop failed operation-unavailable + exit 0 + fi fi - installer_output_size=$(wc -c < "$installer_output" 2>/dev/null) || - stop failed operation-unavailable - set -- $installer_output_size - installer_output_size=${SHELL_FIRST_POSITIONAL_OR_EMPTY} - case "$installer_output_size" in - ""|*[!0-9]*) stop failed operation-unavailable ;; - esac - [ "$installer_output_size" -gt 0 ] || - stop failed operation-unavailable - [ "$installer_output_size" -le 49152 ] || - stop failed operation-unavailable - cat -- "$installer_output" || stop failed operation-unavailable - exit 0 + # A process or channel loss may leave a partial publication without a + # terminal line. The installer commit is idempotent and completes it from + # the authenticated prepared state. + action=commit fi if [ "$action" = commit ]; then if [ ! -d "$operation_root" ] || [ -L "$operation_root" ] || @@ -1109,6 +1118,7 @@ function parseMessage( message.status === "rollback-incomplete" ? "installer-rollback-incomplete" : "installer-failed", + detail: message.message, }, }; } @@ -1444,6 +1454,9 @@ export function createSshRemotePackageBootstrapExecutor( prepared: false, unavailable: false, reason: result.reason, + ...(result.detail === undefined + ? {} + : { detail: result.detail }), }; } throw new Error("Agent 远程安装准备返回了无效结果"); @@ -1473,7 +1486,13 @@ export function createSshRemotePackageBootstrapExecutor( }; } if (result.status === "failed") { - return { committed: false, reason: result.reason }; + return { + committed: false, + reason: result.reason, + ...(result.detail === undefined + ? {} + : { detail: result.detail }), + }; } throw new Error("Agent 远程安装提交状态返回了无效结果"); }; @@ -1582,7 +1601,13 @@ export function createSshRemotePackageBootstrapExecutor( }; } if (result.status === "failed") { - return { committed: false, reason: result.reason }; + return { + committed: false, + reason: result.reason, + ...(result.detail === undefined + ? {} + : { detail: result.detail }), + }; } throw new Error("Agent 远程安装提交返回了无效结果"); }, diff --git a/src/shared/node/runtime-bundle-verifier.ts b/src/shared/node/runtime-bundle-verifier.ts index bf509cb4..610e5d0a 100644 --- a/src/shared/node/runtime-bundle-verifier.ts +++ b/src/shared/node/runtime-bundle-verifier.ts @@ -33,6 +33,10 @@ import { type RemoteRuntimeBundleManifest, type RemoteRuntimeLock } from '../remote-runtime-launch-contracts' +import { + runtimeRegistryEntrySchema, + type RuntimeRegistryEntry +} from '../remote-environment-registry-contracts' export type InstalledBundleVerificationEnvironment = | 'production' @@ -63,6 +67,11 @@ export type VerifyRuntimeBundleOptions = { uid?: number } +export type LoadRegisteredRuntimeBundleOptions = + VerifyRuntimeBundleOptions & { + registered: RuntimeRegistryEntry + } + export async function verifyRuntimeBundle( bundleDirectoryInput: string, options: VerifyRuntimeBundleOptions @@ -179,6 +188,121 @@ export async function verifyRuntimeBundle( } } +/** + * Reconstructs a Runtime identity that was fully verified when it was + * registered. Normal capabilities and prompt launches use this bounded + * metadata path instead of hashing the complete Runtime payload again. + */ +export async function loadRegisteredRuntimeBundle( + bundleDirectoryInput: string, + options: LoadRegisteredRuntimeBundleOptions +): Promise { + const bundleDirectory = assertAbsoluteManagedPath( + resolve(bundleDirectoryInput) + ) + const registered = runtimeRegistryEntrySchema.parse( + options.registered + ) + const rootStat = await lstat(bundleDirectory) + assertOwnedDirectory( + rootStat, + 'Runtime bundle directory', + options.uid + ) + if ( + shouldEnforceMode(options) && + modeString(rootStat.mode) !== '0700' + ) { + throw new Error( + 'Runtime bundle directory permissions must be 0700' + ) + } + if ( + basename(bundleDirectory) !== + registered.bundleDigest.slice('sha256:'.length) + ) { + throw new Error( + 'Registered Runtime digest does not match its managed directory' + ) + } + + const manifestBytes = await readMetadataFile( + join(bundleDirectory, MANIFEST_FILE_NAME), + 'Runtime manifest', + options + ) + const signatureBytes = await readSignature( + join(bundleDirectory, SIGNATURE_FILE_NAME), + options + ) + const manifest = await verifyRuntimeManifestSignature( + manifestBytes, + signatureBytes, + options.releaseKeyRegistry, + options.verificationEnvironment ?? 'production' + ) + assertRuntimeManifestMatchesLock( + manifest, + remoteRuntimeLockSchema.parse(options.runtimeLock), + options.architecture + ) + const manifestDigest = + await digestRemoteRuntimeBundleManifest(manifest) + if ( + manifest.runtimeId !== registered.runtimeId || + manifest.runtimeVersion !== registered.runtimeVersion || + manifest.architecture !== registered.architecture || + manifest.bundleDigest !== registered.bundleDigest || + manifestDigest !== registered.manifestDigest || + ( + registered.runtimeAdapterDigest !== undefined && + manifest.adapterDigest !== registered.runtimeAdapterDigest + ) || + manifest.acpCapabilitiesDigest !== + registered.acpCapabilitiesDigest + ) { + throw new Error( + 'Runtime manifest does not match its registered identity' + ) + } + + const executableRecord = manifest.files.find( + (file) => file.path === manifest.entrypoint.path + ) + if (executableRecord === undefined) { + throw new Error( + 'Registered Runtime entrypoint is not declared' + ) + } + const executablePath = join( + bundleDirectory, + ...manifest.entrypoint.path.split('/') + ) + const executableStat = await lstat(executablePath) + assertOwnedRegularFile( + executableStat, + 'Runtime executable', + options.uid + ) + if ( + executableStat.size !== executableRecord.size || + ( + shouldEnforceMode(options) && + modeString(executableStat.mode) !== executableRecord.mode + ) + ) { + throw new Error( + 'Registered Runtime entrypoint metadata changed' + ) + } + return { + bundleDirectory, + executablePath, + manifest, + manifestDigest + } +} + export function canonicalRuntimeManifestBytes( manifest: RemoteRuntimeBundleManifest ): Buffer { diff --git a/src/shared/remote-environment-registry-contracts.ts b/src/shared/remote-environment-registry-contracts.ts index 50e9494c..c8eb6584 100644 --- a/src/shared/remote-environment-registry-contracts.ts +++ b/src/shared/remote-environment-registry-contracts.ts @@ -16,7 +16,14 @@ export const installationRegistryEntrySchema = z installationId: installationRegistryIdSchema, agentVersion: componentVersionSchema, manifestSha256: z.string().regex(/^[a-f0-9]{64}$/u), - arch: z.enum(['x64', 'arm64']) + arch: z.enum(['x64', 'arm64']), + protocol: z + .object({ + major: z.number().int().min(0).max(65_535), + minor: z.number().int().min(0).max(65_535) + }) + .strict() + .optional() }) .strict() @@ -137,6 +144,7 @@ export const runtimeRegistryEntrySchema = z architecture: z.enum(['x64', 'arm64']), bundleDigest: sha256DigestSchema, manifestDigest: sha256DigestSchema, + runtimeAdapterDigest: sha256DigestSchema.optional(), acpCapabilitiesDigest: sha256DigestSchema }) .strict() @@ -219,7 +227,10 @@ function canonicalInstallationEntry( installationId: entry.installationId, agentVersion: entry.agentVersion, manifestSha256: entry.manifestSha256, - arch: entry.arch + arch: entry.arch, + ...(entry.protocol === undefined + ? {} + : { protocol: entry.protocol }) }) } @@ -233,6 +244,12 @@ function canonicalRuntimeEntry( architecture: entry.architecture, bundleDigest: entry.bundleDigest, manifestDigest: entry.manifestDigest, + ...(entry.runtimeAdapterDigest === undefined + ? {} + : { + runtimeAdapterDigest: + entry.runtimeAdapterDigest + }), acpCapabilitiesDigest: entry.acpCapabilitiesDigest }) } @@ -245,6 +262,7 @@ function installationEntryEquals( left.installationId === right.installationId && left.agentVersion === right.agentVersion && left.manifestSha256 === right.manifestSha256 && - left.arch === right.arch + left.arch === right.arch && + JSON.stringify(left.protocol) === JSON.stringify(right.protocol) ) } diff --git a/tests/agent-package.test.ts b/tests/agent-package.test.ts index 1c7dedb5..9dfe724b 100644 --- a/tests/agent-package.test.ts +++ b/tests/agent-package.test.ts @@ -12,6 +12,7 @@ import { mkdtempSync, readFileSync, readdirSync, + renameSync, rmSync, symlinkSync, writeFileSync @@ -497,7 +498,15 @@ describe('compound Agent packages', () => { }) expect(events.at(-1)).toEqual(prepared) expect(readdirSync(join(operationRoot, 'prepared'))) - .toEqual(['result.json']) + .toEqual([ + 'agent-package.json', + 'agent-package.sig', + 'agent-release-keys.json', + 'agent-runtime-lock.json', + 'payload', + 'remote-runtime-lock.json', + 'result.json' + ]) expectGlobalMetadataUnchanged(globalMetadata) const cliOperationRoot = join(temporaryRoot, 'remote-cli-operation') @@ -569,13 +578,23 @@ describe('compound Agent packages', () => { commitEvents.filter( (event) => event.type === 'progress' && - event.phase === 'extracting-payload' + event.phase === 'publishing-content' ) ).toHaveLength(1) expect(readdirSync(join(operationRoot, 'prepared'))) - .toEqual(['result.json']) + .toEqual([ + 'agent-package.json', + 'agent-package.sig', + 'agent-release-keys.json', + 'agent-runtime-lock.json', + 'payload', + 'remote-runtime-lock.json', + 'result.json' + ]) expect(readdirSync(operationRoot)).toEqual(['prepared']) - expectGlobalMetadataUnchanged(globalMetadata) + expectRegistriesUnchangedAndPackageTrustPublished( + globalMetadata + ) packageInstaller.preparePackage({ operationRoot, @@ -591,7 +610,76 @@ describe('compound Agent packages', () => { homeDirectory }) ).not.toThrow() - expectGlobalMetadataUnchanged(globalMetadata) + expectRegistriesUnchangedAndPackageTrustPublished( + globalMetadata + ) + }) + + it('resumes commit after an Agent directory was already published', () => { + const operationRoot = join( + temporaryRoot, + 'partial-commit-operation' + ) + const homeDirectory = join( + temporaryRoot, + 'partial-commit-home' + ) + const prepared = packageInstaller.preparePackage({ + operationRoot, + archive: packagePath, + expectedSha256: packageResult.sha256, + homeDirectory + }) + const agentSource = join( + operationRoot, + 'prepared', + 'payload', + 'agent' + ) + const agentDestination = join( + homeDirectory, + '.goodbuddy', + 'agent', + 'installations', + prepared.agent.installationId + ) + mkdirSync(dirname(agentDestination), { + recursive: true, + mode: 0o700 + }) + renameSync(agentSource, agentDestination) + + expect( + packageInstaller.commitPackage({ + operationRoot, + archive: packagePath, + expectedSha256: packageResult.sha256, + homeDirectory + }) + ).toMatchObject({ + status: 'committed', + agent: prepared.agent, + runtime: prepared.runtime + }) + expect( + lstatSync(join(agentDestination, 'goodbuddy-agent')) + .isFile() + ).toBe(true) + expect( + lstatSync( + join( + homeDirectory, + '.goodbuddy', + 'runtimes', + 'opencode', + prepared.runtime.bundleDigest.slice( + 'sha256:'.length + ), + 'bin', + 'opencode' + ) + ).isFile() + ).toBe(true) }) it('requires untampered prepared state before commit mutation', () => { @@ -816,7 +904,9 @@ describe('compound Agent packages', () => { expect( readFileSync(join(agentDestination, 'manifest.json')) ).toBeTruthy() - expectGlobalMetadataUnchanged(globalMetadata) + expectRegistriesUnchangedAndPackageTrustPublished( + globalMetadata + ) }) it('restores a replaced Agent directory when Runtime publication fails', () => { @@ -861,7 +951,7 @@ describe('compound Agent packages', () => { expect(readdirSync(agentDestination)).toEqual(['old-marker']) }) - it('reuses only an identical trusted installed Node without changing global metadata', () => { + it('publishes each Agent payload independently of existing installations', () => { const variantAgent = join(temporaryRoot, 'reuse-variant-agent') writeAgentBundle(variantAgent, 'x64') writeFileSync( @@ -999,7 +1089,7 @@ describe('compound Agent packages', () => { ) expect( lstatSync(identical.currentNode).ino - ).toBe( + ).not.toBe( lstatSync( installedVariantNode( identical.homeDirectory, @@ -1007,7 +1097,9 @@ describe('compound Agent packages', () => { ) ).ino ) - expectGlobalMetadataUnchanged(identical.globalMetadata) + expectRegistriesUnchangedAndPackageTrustPublished( + identical.globalMetadata + ) const changed = installCurrent('changed') const changedResult = prepareAndCommit({ @@ -1029,7 +1121,9 @@ describe('compound Agent packages', () => { ) ).ino ) - expectGlobalMetadataUnchanged(changed.globalMetadata) + expectRegistriesUnchangedAndPackageTrustPublished( + changed.globalMetadata + ) const corrupt = installCurrent('corrupt') writeFileSync(corrupt.currentNode, Buffer.from('corrupt Node')) @@ -1044,7 +1138,9 @@ describe('compound Agent packages', () => { ) ).ino ) - expectGlobalMetadataUnchanged(corrupt.globalMetadata) + expectRegistriesUnchangedAndPackageTrustPublished( + corrupt.globalMetadata + ) const untrusted = installCurrent('untrusted') const currentRoot = dirname(untrusted.currentNode) @@ -1063,7 +1159,9 @@ describe('compound Agent packages', () => { ) ).ino ) - expectGlobalMetadataUnchanged(untrusted.globalMetadata) + expectRegistriesUnchangedAndPackageTrustPublished( + untrusted.globalMetadata + ) }) it('fails the remote installer closed on traversal, duplicates, corruption, and hash mismatch', () => { @@ -2285,3 +2383,20 @@ function expectGlobalMetadataUnchanged( expect(readFileSync(path)).toEqual(bytes) } } + +function expectRegistriesUnchangedAndPackageTrustPublished( + files: ReadonlyMap +): void { + for (const [path, bytes] of files) { + if (path.endsWith('registry.json')) { + expect(readFileSync(path)).toEqual(bytes) + continue + } + const actual = JSON.parse(readFileSync(path, 'utf8')) + expect(actual).toEqual( + path.endsWith('remote-runtime-lock.json') + ? remoteRuntimeLock + : registry + ) + } +}