From 52376fb71e3866181fc1eb3b8f94c584d98603c1 Mon Sep 17 00:00:00 2001 From: Codex Date: Mon, 8 Jun 2026 11:21:34 +0800 Subject: [PATCH] =?UTF-8?q?=E6=94=AF=E6=8C=81=20gitbundle=20=E8=B5=84?= =?UTF-8?q?=E6=BA=90=E8=A3=85=E9=85=8D?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- docs/reference/spec-v01-agentrun-runner.md | 26 +- docs/reference/spec-v01-backend-codex.md | 10 +- .../spec-v01-hwlab-manual-dispatch.md | 39 ++- docs/reference/spec-v01-runtime-assembly.md | 70 ++--- docs/reference/spec-v01-validation.md | 8 +- src/common/types.ts | 29 +- src/common/validation.ts | 115 +++----- src/mgr/result.ts | 9 +- src/mgr/store.ts | 10 +- src/runner/resource-bundle.ts | 260 +++++++++--------- src/runner/run-once.ts | 6 +- .../cases/50-hwlab-manual-dispatch.ts | 67 ++--- .../cases/60-hwlab-baseline-contract.ts | 2 +- 13 files changed, 287 insertions(+), 364 deletions(-) diff --git a/docs/reference/spec-v01-agentrun-runner.md b/docs/reference/spec-v01-agentrun-runner.md index 19f0432..284c4aa 100644 --- a/docs/reference/spec-v01-agentrun-runner.md +++ b/docs/reference/spec-v01-agentrun-runner.md @@ -30,7 +30,7 @@ Runner Secret 只能通过 Kubernetes Secret projection、ServiceAccount/RBAC Kubernetes Job runner 必须把 credential source 与 runtime home 分开：Secret volume 只读挂在 `/var/run/agentrun/secrets/...`，`/home/agentrun` 由 `emptyDir` 提供可写空间，`CODEX_HOME` 指向当前 run/profile 的 writable runtime home，`AGENTRUN_CODEX_SECRET_HOME` 指向当前 `backendProfile` 对应的只读 projection。runner/backend 在启动 provider 前只复制授权文件，不打印内容。`codex`、`deepseek` 与 `minimax-m3` profile 不得共享同一个可写 runtime home，除非它们运行在不同的 per-run Kubernetes Job 且该目录由 Job 独占 emptyDir 提供。 -RuntimeAssembly P0 中 `SessionRef` 可以显式为 `null`，runner 不得把完整 `CODEX_HOME`、Secret projection 或节点 host path 当作 session store。`ResourceBundleRef` P0 收敛为 Git-only；runner 已支持把 `repoUrl + full commitId` checkout 到 `AGENTRUN_WORKSPACE_ROOT` 下的隔离目录，并记录 commit/tree 摘要，不能把用户上传文件或 env dump 混入 Git-only bundle。`toolAliases`、`promptRefs` 和 `skillRefs` 都属于该 Git-only bundle 的非敏感子资源：runner 必须在同一 checkout 中解析、校验和装配，不能从镜像默认目录、host path、旧 prompt 常量或用户长 prompt 中补齐。 +RuntimeAssembly P0 中 `SessionRef` 可以显式为 `null`，runner 不得把完整 `CODEX_HOME`、Secret projection 或节点 host path 当作 session store。`ResourceBundleRef` P0 收敛为 `kind="gitbundle"`；runner 已支持把 `repoUrl + full commitId + bundles[]` checkout 到 `AGENTRUN_WORKSPACE_ROOT` 下的隔离目录，按 `subpath -> target_path` 复制到 workspace，并记录 commit/tree/bundles 摘要。工具来自 workspace `tools/`，skill 来自 workspace `.agents/skills`，不能把用户上传文件、inline seed、旧字段或 env dump 混入 gitbundle。 ### v0.1.1 Session state 持久化（per-session RWO PVC 直接挂载） @@ -64,16 +64,22 @@ volumeMounts: mountPath: /home/agentrun/.codex-/ # <-- 唯一改这一行 ``` -### ResourceBundle 子资源装配 +### ResourceBundle gitbundle 装配 -Runner materialize `ResourceBundleRef` 后必须按固定顺序处理子资源：先创建 `toolAliases` wrapper，再装配 `skillRefs` registry，最后读取 `promptRefs` 并生成当前 command 的 assembled initial prompt 摘要。任何子资源缺失或非法都必须按对应 failureKind 阻塞当前 command，不得继续运行后让模型自行猜测。 +Runner materialize `ResourceBundleRef.kind="gitbundle"` 后必须按固定顺序处理资源：先 checkout repo/commit，再按 `bundles[]` 复制文件或目录，再准备 workspace `tools/`，再发现 `.agents/skills`，最后读取 `promptRefs` 并生成当前 command 的 assembled initial prompt 摘要。旧字段输入必须由 schema 校验直接拒绝，不得在 runner 里兼容。 -`skillRefs` 聚合规则： +gitbundle skill 聚合规则： -- 聚合目录默认在 materialized workspace 下的 `.agents/skills`，每个 skill 使用稳定目录名，例如 `.agents/skills//SKILL.md`。 +- 聚合目录固定在 materialized workspace 下的 `.agents/skills`，每个 skill 使用稳定目录名，例如 `.agents/skills//SKILL.md`。 - Runner 必须把该聚合目录通过环境或 backend option 暴露给 Codex runtime；对于需要兼容 Codex skill discovery 的实现，应设置 `AGENTRUN_SKILLS_DIRS` 或等价字段，并可同步设置业务方约定的 `_CODE_AGENT_SKILLS_DIRS`。 -- 聚合只允许 symlink 或 copy 当前 bundle 内的 skill root，不允许引用 `/app/skills`、host path、Secret volume 或用户上传临时目录。 -- Event/result 只输出 skill name、manifest path 摘要、hash、bytes、version/commit metadata、required 和 aggregate target。 +- 聚合只允许 copy `bundles[]` 指定的 Git 子树，不允许引用 `/app/skills`、host path、Secret volume 或用户上传临时目录。 +- Event/result 只输出 skill name、manifest path 摘要、hash、bytes、summary 和 target。 + +workspace `tools/` 装配规则： + +- runner 把 workspace `tools/` 追加到 `PATH`；repo 内的短命令文件本身承担 wrapper 语义。 +- `tools/` 顶层 `.ts` 脚本必须带 shebang；带 shebang 的脚本会被 `chmod +x`。 +- Event/result 只输出工具文件名、hash、bytes、shebang 摘要和 count，不输出脚本文本。 `promptRefs` 装配规则： @@ -92,7 +98,7 @@ Runner 承接的是 HWLAB v0.2 原有 Code Agent 的执行层经验，不承接 | cancel/interrupt | `internal/cloud/server-code-agent-http.ts`、`internal/cloud/codex-stdio-session.ts` | runner 必须轮询 manager cancel 状态并中止 backend；backend 不支持精确 interrupt 时终止受控进程组。 | | runnerTrace 事件可见性 | `internal/cloud/code-agent-trace-store.ts` | backend 输出必须转成 manager events；每个 terminal/错误/取消都要有事件和 final status。 | | workspace-write 边界 | `internal/cloud/code-agent-contract.ts` | runner 只使用 ResourceBundleRef materialized workspace，不猜 HWLAB Pod 的 `/workspace/hwlab` 或 host path。 | -| prompt/skill 装配 | `internal/cloud/codex-stdio-session.ts`、`internal/cloud/codex-stdio-session-helpers.ts` | HWLAB 旧业务 prompt 与 skill discovery 经验迁入 ResourceBundleRef `promptRefs`/`skillRefs`；runner 只按 Git commit/path 装配，不内建 HWLAB 业务。 | +| prompt/skill 装配 | `internal/cloud/codex-stdio-session.ts`、`internal/cloud/codex-stdio-session-helpers.ts` | HWLAB 旧业务 prompt 与 skill discovery 经验迁入 ResourceBundleRef `promptRefs` 和 gitbundle `.agents/skills`；runner 只按 Git commit/path 装配，不内建 HWLAB 业务。 | | Secret 与 writable CODEX_HOME 分离 | `internal/cloud/code-agent-contract.ts`、`docs/reference/code-agent-chat-readiness.md` | profile Secret 只读投影，复制到当前 run/profile writable runtime home；不同 profile 不共享 runtime home。 | | bounded stdout/stderr | `docs/reference/code-agent-chat-readiness.md` | `command_output` 记录摘要、字节数、截断标记和必要引用；不得把大输出直接塞进单个 event/result。 | @@ -196,7 +202,7 @@ HWLAB v0.2 原有 Code Agent 在 cloud-api 进程内执行，失败时依赖本 ### T7 Resource prompt/skill 装配 -阅读本文和 [spec-v01-runtime-assembly.md](spec-v01-runtime-assembly.md)，然后创建一个带 `ResourceBundleRef.promptRefs`、`skillRefs` 和 `toolAliases` 的真实或自测试 run。确认 runner 从同一 full commit checkout 装配 prompt、skill 和工具 alias；新 thread 首轮显示 `initialPromptInjected=true`，assistant 能看见 required skill 摘要；第二轮 resume 显示 `initialPromptInjected=false`，且没有拼接第一轮历史 prompt。删除 required skill 或 prompt 后，command 必须 blocked 为 `skill-unavailable` 或 `prompt-unavailable`。 +阅读本文和 [spec-v01-runtime-assembly.md](spec-v01-runtime-assembly.md)，然后创建一个带 `ResourceBundleRef.kind="gitbundle"`、`bundles[]` 和 `promptRefs` 的真实或自测试 run。确认 runner 从同一 full commit checkout 装配 prompt、workspace tools 和 `.agents/skills`；新 thread 首轮显示 `initialPromptInjected=true`，assistant 能看见 gitbundle skill 摘要；第二轮 resume 显示 `initialPromptInjected=false`，且没有拼接第一轮历史 prompt。旧字段请求必须 schema-invalid，required prompt 缺失必须 blocked 为 `prompt-unavailable`。 ## 规格的实现情况 @@ -207,7 +213,7 @@ HWLAB v0.2 原有 Code Agent 在 cloud-api 进程内执行，失败时依赖本 | host process runner | 已实现 | `runner start` 和 `src/runner/main.ts` 进入同一套 `runOnce`，可通过 manager register/claim/poll/report 执行自测试，并支持 `--one-shot` 或 idle timeout 控制。 | | claim/lease/report client | 已实现/已通过 stale lease recovery 复测 | 已拆出 runner manager API client，覆盖 register、claim、lease heartbeat、poll command、ack、append event、command status 和必要 run status；replacement runner 遇到旧 lease 时会等待 stale lease 并重试 claim，live runtime 通过 manager 写入 Postgres durable store。 | | cancel observation | 已实现最小闭环 | runner 在 backend 执行期间轮询 run/command cancel，触发 AbortController 中止 Codex stdio backend，并按 `cancelled` 上报 command/run 终态。 | -| SessionRef/ResourceBundleRef 消费 | 已实现最小闭环/待 promptRefs 与 skillRefs | runner 会使用 run 中的 SessionRef threadId 执行 resume，并 materialize Git-only ResourceBundleRef 到隔离 workspace 后再启动 backend；per-session PVC 直接挂载已通过 HWLAB v0.2 原入口恢复复测，`toolAliases` 已实现，`promptRefs` 和 `skillRefs` 装配按本规格待补齐。 | +| SessionRef/ResourceBundleRef 消费 | 已实现最小闭环 | runner 会使用 run 中的 SessionRef threadId 执行 resume，并 materialize `kind="gitbundle"` ResourceBundleRef 到隔离 workspace 后再启动 backend；per-session PVC 直接挂载已通过 HWLAB v0.2 原入口恢复复测，`tools/` PATH、`promptRefs` 和 `.agents/skills` 装配已实现。 | | 同 run/runner 多 turn | 已实现最小闭环 | runner 在同一 Job 中 materialize bundle 一次后循环 poll command；普通 turn completed 只终结 command，run 保持可继续接后续 turn，直到 idle timeout 或 run terminal。 | | runner redaction | 已实现主路径 | runner/backend event 和 Job 输出使用 redaction；复杂审计仍按 [spec-v01-validation.md](spec-v01-validation.md) 的人工验收抽查。 | | `deepseek` profile runner selection | 已实现/已通过主闭环 | Runner Job 和 host runner 已按 run `backendProfile` 选择 matching SecretRef、projection、`CODEX_HOME` 和 backend metadata；真实 Kubernetes Job 已完成 `codex -> deepseek -> codex` 切换联调。 | diff --git a/docs/reference/spec-v01-backend-codex.md b/docs/reference/spec-v01-backend-codex.md index 58c6a83..4d4da82 100644 --- a/docs/reference/spec-v01-backend-codex.md +++ b/docs/reference/spec-v01-backend-codex.md @@ -20,7 +20,7 @@ codex app-server --listen stdio:// Adapter 通过 stdin 写入换行分隔 JSON-RPC 请求，通过 stdout 逐行读取 JSON-RPC response 和 notification，stderr 只作为有界诊断日志。最小请求序列是 `initialize`、`thread/start` 或 `thread/resume`、`turn/start`；response 中必须提取 thread/turn identity，notification 和后续输出必须归一化为 `backend_status`、`assistant_message`、`tool_call`、`command_output`、`error` 和 `terminal_status` events。运行中 steer 使用同一 app-server 进程的 `turn/steer` JSON-RPC 方法，参数为 `threadId`、`expectedTurnId` 和文本 `input` 数组；取消/中断使用 `turn/interrupt`，参数为 `threadId` 和 `turnId`。已有 `SessionRef.threadId` 时只能执行 Codex stdio 原生 `thread/resume` 后接 `turn/start`；当 `thread/resume` 返回 `no rollout found for thread id` 或任何其他协议错误时，adapter 必须输出 `thread-resume-failed` 并终止当前 turn。adapter 不得启动替代 `thread/start`、拼接历史 prompt、回写新 threadId 或用其他上下文模拟继续会话。 -若 run 的 `ResourceBundleRef` 包含 `promptRefs` 或 `skillRefs`，Codex adapter 只能消费 runner 已装配好的有界 `initialPrompt`、skill summary 和 skill registry path。对新 thread，adapter 在首个 `turn/start` 中把 `initialPrompt` 和 skill facts 放在用户 message 之前；对 `thread/resume`，adapter 不重复注入 `initialPrompt`，只发送当前 command 的用户 message。当前 Codex app-server 若只有 `input: [{ type: "text", text }]`，允许使用结构化文本前缀承载 initial prompt；若后续 app-server 支持 developer/runtime instruction item，优先映射到该标准 item。无论哪种 wire shape，events 只记录 prompt/skill 的 path/hash/bytes/injected 状态，不输出全文。 +若 run 的 `ResourceBundleRef` 包含 `promptRefs` 或 gitbundle `.agents/skills`，Codex adapter 只能消费 runner 已装配好的有界 `initialPrompt`、skill summary 和 skill registry path。对新 thread，adapter 在首个 `turn/start` 中把 `initialPrompt` 和 skill facts 放在用户 message 之前；对 `thread/resume`，adapter 不重复注入 `initialPrompt`，只发送当前 command 的用户 message。当前 Codex app-server 若只有 `input: [{ type: "text", text }]`，允许使用结构化文本前缀承载 initial prompt；若后续 app-server 支持 developer/runtime instruction item，优先映射到该标准 item。无论哪种 wire shape，events 只记录 prompt/skill 的 path/hash/bytes/injected 状态，不输出全文。 不得把以下路径作为 `v0.1` Codex stdio backend 的正式实现或综合联调通过证据：直接 Responses HTTP 代理、OpenAI SDK wrapper、`codex exec` 一次性命令输出、fake provider、固定文本回复、只读 shortcut 或本地 shell 模拟。裸 HTTP 或 `codex exec --json` 可以作为 provider/upstream 诊断，但最终通过必须来自 app-server stdio turn。 @@ -37,7 +37,7 @@ Adapter 通过 stdin 写入换行分隔 JSON-RPC 请求，通过 stdout 逐行 这些参考用于协议和质量标准，不复制 UniDesk/HWLAB 的业务 prompt、硬件路径、tenant policy、hostPath Secret 做法或任何明文密钥。 -业务 prompt 与 skill 迁移必须通过 [spec-v01-runtime-assembly.md](spec-v01-runtime-assembly.md) 的 `ResourceBundleRef.promptRefs` 和 `skillRefs` 完成。Codex backend 不内建 HWLAB 或 UniDesk 的业务文本；缺少 required prompt/skill 时必须由 runner/manager 返回装配 blocker，不能落到 Codex 默认 skill 列表、用户长 prompt 或文本 fallback。 +业务 prompt 与 skill 必须通过 [spec-v01-runtime-assembly.md](spec-v01-runtime-assembly.md) 的 `ResourceBundleRef.promptRefs` 和 gitbundle `.agents/skills` 完成。Codex backend 不内建 HWLAB 或 UniDesk 的业务文本；缺少 required prompt 时必须由 runner/manager 返回装配 blocker，不能落到 Codex 默认 skill 列表、用户长 prompt 或文本 fallback。 ## v0.1 Profile 定义 @@ -147,9 +147,9 @@ Run 的 `executionPolicy.secretScope` 应引用与 `backendProfile` 匹配的 pr 5. `AGENTRUN_SESSION_PVC_NAME` 未设 + `thread/resume` 失败：仍走 `thread-resume-failed`，不升级为 `session-store-evicted`。 6. `codex_rollout_subdir` 走 env `AGENTRUN_CODEX_ROLLOUT_SUBDIR`，默认 `sessions`；codex CLI 改子目录时只改 env，不改装配。 -### T8 Initial prompt and skill refs +### T8 Initial prompt and gitbundle skills -阅读本文和 [spec-v01-runtime-assembly.md](spec-v01-runtime-assembly.md)，然后用 fake app-server 或真实 Codex stdio run 验证 `ResourceBundleRef.promptRefs` 与 `skillRefs`。首轮无 threadId 时，`turn/start` input 必须包含 initial prompt 与 skill facts，并记录 `initialPromptInjected=true`；第二轮带同一 `threadId` resume 时，`turn/start` input 只能包含当前用户 message，记录 `initialPromptInjected=false`，且不得拼接第一轮 prompt、assistant 回复或旧 skill facts。required prompt/skill 缺失时不得调用 Codex provider。 +阅读本文和 [spec-v01-runtime-assembly.md](spec-v01-runtime-assembly.md)，然后用 fake app-server 或真实 Codex stdio run 验证 `ResourceBundleRef.promptRefs` 与 gitbundle `.agents/skills`。首轮无 threadId 时，`turn/start` input 必须包含 initial prompt 与 skill facts，并记录 `initialPromptInjected=true`；第二轮带同一 `threadId` resume 时，`turn/start` input 只能包含当前用户 message，记录 `initialPromptInjected=false`，且不得拼接第一轮 prompt、assistant 回复或旧 skill facts。required prompt 缺失时不得调用 Codex provider。 ## 规格的实现情况 @@ -157,7 +157,7 @@ Run 的 `executionPolicy.secretScope` 应引用与 `backendProfile` 匹配的 pr | --- | --- | --- | | Codex stdio backend/profile 规格 | 已定义 | 本文为 v0.1 Codex app-server stdio backend kind 和 profile 权威。 | | Codex Secret projection | 已实现/已通过主闭环 | runner Job 使用只读 Secret projection 和 writable `CODEX_HOME`，Codex 测试凭据来自 `agentrun-v01-provider-codex` 的 `auth.json`/`config.toml`。 | -| Codex adapter | 已实现主路径/待 initial prompt 与 skill refs 接入 | 当前代码已实现受控 `codex app-server --listen stdio://`、`initialize`/`thread/start`/`thread/resume`/`turn/start` response 校验、stale rollout `thread-resume-failed`、stderr 有界诊断、spawn/JSON parse/response invalid/timeout/provider 5xx/invalid tool-call availability failureKind，以及包含 retry error notification 的 fake app-server 自测试；`ResourceBundleRef.promptRefs` thread-start 注入和 `skillRefs` facts/registry 消费待实现。 | +| Codex adapter | 已实现主路径和 initial prompt/gitbundle skills 接入 | 当前代码已实现受控 `codex app-server --listen stdio://`、`initialize`/`thread/start`/`thread/resume`/`turn/start` response 校验、stale rollout `thread-resume-failed`、stderr 有界诊断、spawn/JSON parse/response invalid/timeout/provider 5xx/invalid tool-call availability failureKind，以及包含 retry error notification 的 fake app-server 自测试；`ResourceBundleRef.promptRefs` thread-start 注入和 gitbundle skill facts/registry 消费已接入。 | | 错误可观测与脱敏 | 已实现主路径 | child env、cwd、workspace 和 Codex home 只输出摘要；stderr tail 有界且标记截断；事件和 failure 统一走 redaction。 | | 真实 provider turn | 已通过主闭环 | 真实 Codex provider turn 已经通过 RESTful API 和 CLI 综合联调；每次发布仍按 [spec-v01-validation.md](spec-v01-validation.md) 手动复验。 | | `deepseek` profile | 已实现/已通过主闭环 | 代码已支持 `agentrun-v01-provider-deepseek`、独立 `CODEX_HOME`、同一 `codex app-server --listen stdio://` 协议和 profile metadata；真实 Kubernetes SecretRef、runner Job 和 Codex stdio turn 已通过主闭环。 | diff --git a/docs/reference/spec-v01-hwlab-manual-dispatch.md b/docs/reference/spec-v01-hwlab-manual-dispatch.md index c4f01db..438b6bb 100644 --- a/docs/reference/spec-v01-hwlab-manual-dispatch.md +++ b/docs/reference/spec-v01-hwlab-manual-dispatch.md @@ -50,7 +50,7 @@ AgentRun `v0.1` 承接 HWLAB v0.2 时，只吸收原有 Code Agent 的通用执 | conversation/session/thread 复用 | `internal/cloud/codex-stdio-session.ts`、`internal/cloud/code-agent-session-registry.ts` | `SessionRef` 保存 session/thread 摘要；同一 run/runner Job 处理后续 command，不重新 materialize bundle；runner 内每 turn 有 thread 则 resume，无 thread 则 start | [spec-v01-runtime-assembly.md](spec-v01-runtime-assembly.md)、[spec-v01-agentrun-runner.md](spec-v01-agentrun-runner.md) | | 固定 repo workspace 执行 | `internal/cloud/code-agent-contract.ts`、`docs/reference/code-agent-chat-readiness.md` | `ResourceBundleRef` 使用 Git-only `repoUrl + full commitId` checkout 到隔离 workspace | [spec-v01-runtime-assembly.md](spec-v01-runtime-assembly.md)、[spec-v01-agentrun-runner.md](spec-v01-agentrun-runner.md) | | 初始业务 prompt 注入 | `internal/cloud/codex-stdio-session.ts` 的 boundary instructions、`internal/cloud/codex-stdio-session-helpers.ts` 的 `buildCodexUserPrompt()` | HWLAB 把稳定业务 instruction 文件放入同一 Git bundle，并通过 `ResourceBundleRef.promptRefs` 指定；AgentRun 只在新 thread 首轮注入，resume 不重复注入 | [spec-v01-runtime-assembly.md](spec-v01-runtime-assembly.md)、[spec-v01-backend-codex.md](spec-v01-backend-codex.md) | -| skill discovery 与 skill facts | `internal/cloud/skills-store.ts`、`internal/cloud/codex-stdio-session-helpers.ts` 的 `discoverSkillsForStdio()` 和 `codexSidecarSkillsPrompt()` | HWLAB 把 required skill manifest 放入同一 Git bundle，并通过 `ResourceBundleRef.skillRefs` 指定；AgentRun 聚合到 runner workspace skill registry 并向 Codex 暴露有界 skill facts | [spec-v01-runtime-assembly.md](spec-v01-runtime-assembly.md)、[spec-v01-agentrun-runner.md](spec-v01-agentrun-runner.md) | +| skill discovery 与 skill facts | `internal/cloud/skills-store.ts`、`internal/cloud/codex-stdio-session-helpers.ts` 的 `discoverSkillsForStdio()` 和 `codexSidecarSkillsPrompt()` | HWLAB 把完整 `skills/` 子树通过 `kind="gitbundle"` 复制到 workspace `.agents/skills`；AgentRun 发现多文件 skill 并向 Codex 暴露有界 skill facts | [spec-v01-runtime-assembly.md](spec-v01-runtime-assembly.md)、[spec-v01-agentrun-runner.md](spec-v01-agentrun-runner.md) | | provider profile 隔离和 Secret 不泄露 | `internal/cloud/code-agent-contract.ts`、`docs/reference/code-agent-chat-readiness.md` | `ProfileRef/SecretRef` profile-scoped 投影、缺失为 `secret-unavailable`、禁止 fallback 和泄露值 | [spec-v01-runtime-assembly.md](spec-v01-runtime-assembly.md)、[spec-v01-backend-adapter.md](spec-v01-backend-adapter.md) | | HWPOD/HWLAB runtime 短期 env 注入 | HWLAB Cloud API 的 Code Agent env assembly（历史实现名可能含 device-pod） | `runner-jobs.transientEnv` 只在本次 Kubernetes Job env 中生效；只记录 name/count，不保存或输出 value | [spec-v01-agentrun-mgr.md](spec-v01-agentrun-mgr.md)、[spec-v01-secret-distribution.md](spec-v01-secret-distribution.md) | | UniDesk SSH passthrough | HWLAB Code Agent 通过 `tran` 访问 G14/D601/HWLAB/GitHub 维护面 | `toolCredentials[].tool=unidesk-ssh` 注入 `UNIDESK_SSH_CLIENT_TOKEN`，`transientEnv` 只注入非敏感 `UNIDESK_MAIN_SERVER_IP`；UniDesk frontend 负责 route allowlist | [spec-v01-runtime-assembly.md](spec-v01-runtime-assembly.md)、[spec-v01-secret-distribution.md](spec-v01-secret-distribution.md) | @@ -88,17 +88,16 @@ HWLAB canary 创建 run 时应使用以下字段口径： | `providerId` | `G14`，只表示目标 provider，不授予 HWLAB 业务权限。 | | `backendProfile` | `deepseek`、`codex` 或 `minimax-m3`，由 HWLAB 或调度方显式选择；缺少 matching SecretRef 必须失败，不 fallback。 | | `workspaceRef` | 必须引用 ResourceBundleRef 中的 Git-only full commit；不得由 runner 猜 host path。 | -| `resourceBundleRef.promptRefs[]` | 用于承接 HWLAB 稳定初始 prompt，例如 `hwlab-v02-runtime`、`hwpod-runtime-policy`；必须来自同一 full commit，`inject=thread-start`，新 thread 首轮注入，resume 不注入。 | -| `resourceBundleRef.skillRefs[]` | 用于承接 HWLAB required skills，例如 `hwpod-cli`、`hwpod-ctl`；必须来自同一 full commit 的 `SKILL.md`，required skill 缺失时 blocked，不能让模型默认 skill 列表替代。 | -| `resourceBundleRef.toolAliases[]` | 用于暴露短入口，例如 `hwpod`；缺 alias 时修 runner/bundle，不改走长路径 wrapper。 | -| `resourceBundleRef.workspaceFiles[]` | 用于承接 HWLAB 编排器生成的非敏感 run-local workspace 文件，例如 CaseRun 预装 `.hwlab/hwpod-spec.yaml`；runner 启动 backend 前写入，result/event 只输出 path、bytes、sha256，不把文件正文并入 prompt。 | +| `resourceBundleRef.kind` | 必须是 `gitbundle`。 | +| `resourceBundleRef.bundles[]` | 用于承接 HWLAB 固定工具和 skill 子树，默认 `tools -> tools`、`skills -> .agents/skills`；旧字段不得再发送。 | +| `resourceBundleRef.promptRefs[]` | 用于承接 HWLAB 稳定初始 prompt，例如 `hwlab-v02-runtime`；必须来自同一 full commit，`inject=thread-start`，新 thread 首轮注入，resume 不注入。 | | `executionPolicy` | sandbox、network、timeout、secretScope 必须显式，不得由 HWLAB 扩大 AgentRun Secret 范围。 | | `executionPolicy.secretScope.toolCredentials[]` | 需要 UniDesk SSH passthrough 时必须声明 `tool=unidesk-ssh`、`purpose=ssh-passthrough`、SecretRef `agentrun-v01-tool-unidesk-ssh`、projection env `UNIDESK_SSH_CLIENT_TOKEN`；不得把 token 放入 command payload 或 runner-job transientEnv。 | | `traceSink` | 可指向 HWLAB trace adapter；为 `null` 时 HWLAB 仍可通过 AgentRun events 轮询。 | `tenantId` / `projectId` 是 AgentRun manager 的 policy 边界，不是 HWLAB Workbench project。HWLAB adapter 可以把业务 project/workspace 写入 `metadata.hwlabProjectId`、`metadata.hwlabWorkspaceId` 或 `workspaceRef`，但不得覆盖 AgentRun `projectId=pikasTech/HWLAB`；否则 manager 必须按 `tenant-policy-denied` 拒绝。`providerProfile` 是 HWLAB 入口字段，进入 AgentRun 后必须映射为 `backendProfile`；同一个 HWLAB session 的后续 turn 应继承 session provider profile，不能被 stale workspace provider 覆盖。 -Command 第一阶段要求 `type=turn` 和 `type=steer`。`turn` 保存用户原始 prompt、conversation metadata、profile 选择和 HWLAB trace correlation；稳定业务 prompt、skill 清单、工具入口和 run-local workspace 文件不写入 command payload，而是通过 `ResourceBundleRef.promptRefs`、`skillRefs`、`toolAliases` 和 `workspaceFiles` 装配。`steer` 保存运行中引导文本，并由 runner 在同 run active turn 期间转发到 backend。业务 cancel 仍走 run/command cancel API，不用 `steer` 伪装。不得把 cookie、session token、provider credential、HWPOD internal token、Secret value、历史消息或大段 skill manifest 写入 payload。 +Command 第一阶段要求 `type=turn` 和 `type=steer`。`turn` 保存用户原始 prompt、conversation metadata、profile 选择和 HWLAB trace correlation；稳定业务 prompt、skill 清单和工具入口不写入 command payload，而是通过 `ResourceBundleRef.kind="gitbundle"` 的 `bundles[]` 与 `promptRefs` 装配。`steer` 保存运行中引导文本，并由 runner 在同 run active turn 期间转发到 backend。业务 cancel 仍走 run/command cancel API，不用 `steer` 伪装。不得把 cookie、session token、provider credential、HWPOD internal token、Secret value、历史消息或大段 skill manifest 写入 payload。 ## 需要补齐的能力 @@ -148,28 +147,24 @@ AgentRun 需要提供 durable cancel 能力，建议形态为 `POST /api/v1/runs ### P1 ResourceBundleRef / bundle materialization -`ResourceBundleRef` 必须按 Git-only 模型落地：`repoUrl + full commitId` 是唯一内容身份。runner 只能 checkout 到允许 workspace 前缀，不能覆盖 `/app`、Secret projection、profile runtime home 或 session 目录。第一阶段支持 `subdir`、`sparsePaths`、`submodules=false`、`lfs=false`、`credentialRef` 的最小字段即可。HWLAB canary 只需要 `pikasTech/HWLAB` 固定 full commit 的普通 checkout；用户上传文件和对象存储 artifact 不进入 `v0.1`。 +`ResourceBundleRef` 必须按 `kind="gitbundle"` 模型落地：`repoUrl + full commitId + bundles[]` 是唯一内容身份。runner 只能 checkout 到允许 workspace 前缀，不能覆盖 `/app`、Secret projection、profile runtime home 或 session 目录。HWLAB canary 默认只复制 `tools -> tools` 和 `skills -> .agents/skills`；用户上传文件、inline seed、对象存储 artifact 和旧字段不进入 `v0.1`。 ### P1 Resource prompt/skill assembly -HWLAB 旧 Code Agent 的业务 prompt 和 skill 注入必须迁移为 `ResourceBundleRef` 子资源，而不是继续依赖 cloud-api 进程内硬编码 prompt、`/app/skills` 镜像目录、用户长 prompt 或 Codex 默认 skill registry。HWLAB dispatcher 创建 run 时应指定： +HWLAB 旧 Code Agent 的业务 prompt 和 skill 注入必须收敛为 `gitbundle` 子树和 `promptRefs`，而不是继续依赖 cloud-api 进程内硬编码 prompt、`/app/skills` 镜像目录、用户长 prompt、旧 seed 或 Codex 默认 skill registry。HWLAB dispatcher 创建 run 时应指定： ```json { "resourceBundleRef": { - "kind": "git", + "kind": "gitbundle", "repoUrl": "git@github.com:pikasTech/HWLAB.git", "commitId": "", - "toolAliases": [ - { "name": "hwpod", "path": "tools/hwpod-cli.ts", "kind": "bun-script" } + "bundles": [ + { "name": "hwlab-tools", "subpath": "tools", "target_path": "tools" }, + { "name": "hwlab-agent-skills", "subpath": "skills", "target_path": ".agents/skills" } ], "promptRefs": [ - { "name": "hwlab-v02-runtime", "path": "internal/agent/prompts/hwlab-v02-runtime.md", "inject": "thread-start", "required": true }, - { "name": "hwpod-runtime-policy", "path": "internal/agent/prompts/hwpod-runtime-policy.md", "inject": "thread-start", "required": true } - ], - "skillRefs": [ - { "name": "hwpod-cli", "path": "skills/hwpod-cli/SKILL.md", "required": true, "aggregateAs": "hwpod-cli" }, - { "name": "hwpod-ctl", "path": "skills/hwpod-ctl/SKILL.md", "required": true, "aggregateAs": "hwpod-ctl" } + { "name": "hwlab-v02-runtime", "path": "internal/agent/prompts/hwlab-v02-runtime.md", "inject": "thread-start", "required": true } ] } } @@ -187,7 +182,7 @@ HWLAB 旧 Code Agent 的业务 prompt 和 skill 注入必须迁移为 `ResourceB | 2 | trace/result 元语 | 标准 event 子集、terminal result envelope、bounded output metadata | HWLAB 可由 events 稳定生成 result/trace；partial 不误报 completed。 | | 3 | cancel 闭环 | durable cancel API、runner cancel poll、backend interrupt/process group stop | pending/running/terminal 后 cancel 均幂等且可见。 | | 4 | ResourceBundleRef materialization | Git-only checkout、workspace 前缀、commit/tree 摘要、failureKind | 使用 full commit；不接受 branch/tag/HEAD；不覆盖 Secret/session/runtime home。 | -| 5 | Resource prompt/skill assembly | `promptRefs` thread-start 注入、`skillRefs` registry 聚合、required blocker、hash/bytes 可见 | 简短 HWLAB prompt 能看到业务 instruction 和 required skill；resume 不重复注入；缺失直接 blocked。 | +| 5 | Resource prompt/skill assembly | `promptRefs` thread-start 注入、gitbundle skillDirs 发现、hash/bytes 可见 | 简短 HWLAB prompt 能看到业务 instruction 和 gitbundle skills；resume 不重复注入；旧字段直接拒绝。 | | 6 | SessionRef 持久化与 runner 多 turn | session record/store、thread resume、runner command loop、TTL/GC、profile 隔离 | 同一 conversation 连续两轮复用同一 run/runner Job；第二轮不重新 materialize bundle、不重复注入 initial prompt；不同 profile 不污染。 | | 7 | HWLAB v0.2 canary | HWLAB dispatcher adapter、traceId 映射、result/trace 转换 | 普通自然语言最短 turn 真实 completed 且 reply 非空；HWPOD 仍由 HWLAB 授权。 | @@ -219,17 +214,17 @@ HWLAB 旧 Code Agent 的业务 prompt 和 skill 注入必须迁移为 `ResourceB ### T7 HWLAB prompt/skill 装配 -阅读本文和 [spec-v01-runtime-assembly.md](spec-v01-runtime-assembly.md)，然后用 HWLAB canary `ResourceBundleRef` 指定 `promptRefs`、`skillRefs` 和 `toolAliases`。首轮 Web/CLI 简短 prompt 只写“编译 D601-F103-V2”或等价自然语言，确认 Codex turn 能看到 HWLAB runtime prompt、`hwpod-cli`/`hwpod-ctl` skill facts 和 `hwpod` alias；第二轮 continuation 使用同一 thread resume，确认 `initialPromptInjected=false`，没有手工拼接历史；删除 required skill/prompt 后确认 blocked 而不是 fallback 到默认 Codex 5 个系统 skill。 +阅读本文和 [spec-v01-runtime-assembly.md](spec-v01-runtime-assembly.md)，然后用 HWLAB canary `ResourceBundleRef.kind="gitbundle"` 指定 `bundles[]` 和 `promptRefs`。首轮 Web/CLI 简短 prompt 只写“编译 D601-F103-V2”或等价自然语言，确认 Codex turn 能看到 HWLAB runtime prompt、`.agents/skills` 中的 `hwpod-cli`/`hwpod-ctl` skill facts 和 `tools/hwpod` 命令；第二轮 continuation 使用同一 thread resume，确认 `initialPromptInjected=false`，没有手工拼接历史；旧字段请求必须 schema-invalid。 ### T8 DS 短 prompt 真实验收 阅读本文、[spec-v01-backend-codex.md](spec-v01-backend-codex.md) 和 HWLAB `spec-v02-hwlab-cli.md`，然后必须用正式 HWLAB CLI/Web 等价短连接入口提交真实 `backendProfile=deepseek` 的短 prompt 到 AgentRun runtime，不允许用长提示词把规则补给模型。验收至少包含三条 prompt： -1. “不调用工具的情况下，你可见的 skill 有哪些？”确认回复包含 `ResourceBundleRef.skillRefs` 中的 HWLAB required skill，例如 `hwpod-cli` 和 `hwpod-ctl`，并且不只返回 Codex 默认 5 个系统 skill。 +1. “不调用工具的情况下，你可见的 skill 有哪些？”确认回复包含 gitbundle `.agents/skills` 中的 HWLAB skill，例如 `hwpod-cli` 和 `hwpod-ctl`，并且不只返回 Codex 默认 5 个系统 skill。 2. “你当前 HWLAB 初始规则里，D601-F103-V2 应该走哪个标准入口？请只回答入口和禁止路径。”确认回复能说出 `hwpod`、`hwpod-cli`/`hwpod-ctl`、assembled runtime env、禁止旧 Device Pod/profile/device-pod-cli fallback、禁止 session-token fallback 和禁止长路径 wrapper。 3. “编译 D601-F103-V2。”确认短 prompt 能按注入规则触发 `hwpod-cli -> hwpod-compiler-cli -> /v1/hwpod-node-ops -> hwpod-node` 正向链路，而不是要求用户补充长 prompt。 -上述三条必须来自真实 DS/DeepSeek profile 的 Codex stdio `thread/start`/`turn/start` 和后续 `thread/resume` 事件；trace/result 必须显示 `initialPromptInjected=true` 的首轮、skill refs 摘要、真实 provider profile、terminal status，以及 continuation 时 `initialPromptInjected=false`。如果回复只列出 Codex 默认系统 skill、不能识别 HWLAB 初始规则或需要用户长 prompt 才能触发 `hwpod`，验收失败。 +上述三条必须来自真实 DS/DeepSeek profile 的 Codex stdio `thread/start`/`turn/start` 和后续 `thread/resume` 事件；trace/result 必须显示 `initialPromptInjected=true` 的首轮、gitbundle skillDirs 摘要、真实 provider profile、terminal status，以及 continuation 时 `initialPromptInjected=false`。如果回复只列出 Codex 默认系统 skill、不能识别 HWLAB 初始规则或需要用户长 prompt 才能触发 `hwpod`，验收失败。 ## 实现状态 @@ -240,6 +235,6 @@ HWLAB 旧 Code Agent 的业务 prompt 和 skill 注入必须迁移为 `ResourceB | cancel | 已实现最小闭环 | 已提供 run/command cancel API；pending cancel 会阻止新 runner Job，running runner 通过轮询触发 backend abort，终态写入 event、command state 和 run status。 | | SessionRef | 已实现最小持久化 | run 可携带 `sessionRef`，manager 保存 session/thread，runner 会按 threadId resume，result envelope 暴露脱敏 session 摘要；TTL/GC 仍按后续运维策略细化。 | | SessionRef | v0.1.1 已实现/已通过 HWLAB v0.2 原入口复测 | 在「metadata-only 最小持久化」基础上把 session 真实持久化：每个 session 绑 RWO PVC（`agentrun-v01-session-`），runner Job 把 PVC 直接挂到 `${CODEX_HOME}/`，codex app-server 自己落盘；HWLAB 原入口已验证 runner pod 删除后同 session/thread/PVC 可以恢复，仍禁止 fake 续接。 | -| ResourceBundleRef | 已实现 Git-only materialization/promptRefs/skillRefs/workspaceFiles 装配 | run 可携带 `repoUrl + full commitId`，runner checkout 到 `AGENTRUN_WORKSPACE_ROOT` 下的隔离目录并记录 commit/tree/workspace 摘要；`toolAliases`、`promptRefs` thread-start 注入、`skillRefs` registry 聚合和有界 workspace seed 文件写入已实现；上传文件和对象存储仍不进入 v0.1。 | +| ResourceBundleRef | 已实现 `kind="gitbundle"` materialization/promptRefs/tools/skillDirs 装配 | run 可携带 `repoUrl + full commitId + bundles[]`，runner checkout 到 `AGENTRUN_WORKSPACE_ROOT` 下的隔离目录并记录 commit/tree/workspace/bundles 摘要；`tools/` PATH、`promptRefs` thread-start 注入和 `.agents/skills` 目录发现已实现；上传文件、inline seed 和对象存储不进入 v0.1。 | | 同 run/runner 多 turn | 已实现最小闭环 | runner Job 在 idle timeout 内持续 poll 同一 run 的后续 command；普通 turn completed 不终结 run，bundle 只 materialize 一次，command result 按 commandId 独立聚合。 | | HWLAB v0.2 canary | 已实现/已通过 HWLAB v0.2 原入口复测 | HWLAB dispatcher adapter 已调 AgentRun 手动调度 API，并能转换 result/trace；MiniMax-M3 显式 session、provider profile 继承和 runner pod 删除后的同 session resume 已通过原入口 CLI 复测。 | diff --git a/docs/reference/spec-v01-runtime-assembly.md b/docs/reference/spec-v01-runtime-assembly.md index 03ac334..99bd4b7 100644 --- a/docs/reference/spec-v01-runtime-assembly.md +++ b/docs/reference/spec-v01-runtime-assembly.md @@ -13,7 +13,7 @@ | `BackendImageRef` | `image` | digest-pinned backend/runner 镜像。 | API KEY、profile config、用户代码、session 文件。 | | `ProfileRef` | `profile`、`secretRef` | provider profile 和 API KEY/配置 SecretRef。 | backend 镜像、session、repo 文件、GitHub/业务工具 credential。 | | `SessionRef` | `sessionId` 或 `null` | backend 会话文件持久化引用；P0 可以为 `null`。 | API KEY、完整 `CODEX_HOME`、Git workspace。 | -| `ResourceBundleRef` | `repoUrl`、`commitId`，可选 `toolAliases`、`promptRefs`、`skillRefs`、`workspaceFiles` | 初始代码/文件输入，以及同一 commit 下的非敏感工具别名、初始 prompt、skill manifest 和有界 workspace seed 文件；P0 固定 Git-only。 | 上传文件、对象存储 artifact、inline env、Secret value、会话历史。 | +| `ResourceBundleRef` | `kind="gitbundle"`、`repoUrl`、`commitId`、`bundles[]`、可选 `promptRefs` | 初始代码/文件输入、工具目录、skill 目录和同一 commit 下的稳定初始 prompt；P0 固定 Git-only gitbundle。 | 上传文件、对象存储 artifact、inline env、Secret value、会话历史、旧 inline seed。 | P0 最小 JSON 形态： @@ -28,12 +28,14 @@ P0 最小 JSON 形态： }, "sessionRef": null, "resourceBundleRef": { + "kind": "gitbundle", "repoUrl": "git@github.com:pikasTech/unidesk.git", "commitId": "", - "toolAliases": [], - "promptRefs": [], - "skillRefs": [], - "workspaceFiles": [] + "bundles": [ + { "name": "tools", "subpath": "tools", "target_path": "tools" }, + { "name": "skills", "subpath": "skills", "target_path": ".agents/skills" } + ], + "promptRefs": [] } } ``` @@ -154,16 +156,17 @@ HWLAB Workbench 的 project/workspace 不属于 RuntimeAssembly 四要素，也 ### ResourceBundleRef -- P0 固定 Git-only，由 `repoUrl + full commitId` 决定内容身份。 +- P0 固定 `kind="gitbundle"`，由 `repoUrl + full commitId + bundles[]` 决定内容身份。 - `commitId` 必须是不可变 full commit sha，不能是 branch、tag 或 `HEAD`。 -- 可选扩展只允许 `subdir`、`sparsePaths`、`submodules=false`、`lfs=false`、`credentialRef`、`toolAliases`、`promptRefs`、`skillRefs`、`workspaceFiles`；默认不启用。 +- `bundles[]` 每一项只允许 `{ name?, repoUrl?, commitId?, subpath, target_path }`；缺省 repo/commit 继承顶层。 +- `subpath` 必须留在 checkout 内，`target_path` 必须留在 runner workspace 内；runner 按 `subpath -> target_path` 复制文件或目录。 - `credentialRef` 只用于拉取私有 Git repo，不等同于 backend API KEY。 -- 不支持上传文件、对象存储 artifact、任意 ConfigMap 文件袋或 inline env；后续需要时另写版本规格。 -- 面向 HWLAB 手动调度 canary，runner materialization 必须把 Git-only bundle checkout 到允许 workspace 前缀，并在 event/result 中记录 repo、full commit、checkout path 和 tree 摘要；不得隐式使用 manager Pod、host path 或镜像内旧代码。 +- 不支持上传文件、对象存储 artifact、任意 ConfigMap 文件袋、inline seed 或旧字段；旧 `toolAliases`、`skillRefs`、`workspaceFiles`、`subdir`、`sparsePaths` 输入必须直接 schema-invalid。 +- 面向 HWLAB 手动调度 canary，默认 bundle 把 repo 的 `tools/` 复制到 workspace `tools/`，把 `skills/` 复制到 workspace `.agents/skills/`；event/result 必须记录 repo、full commit、checkout tree、bundle 列表、workspace 摘要、tools 和 skillDirs 摘要。 -#### toolAliases +#### tools 目录 -`toolAliases` 用于把 bundle 内的受控脚本暴露为 runner PATH 中的短命令。每个 alias 只能指向当前 checkout 内的相对路径，不能覆盖 runner 镜像里已有非 AgentRun wrapper 命令；materialization event 只输出 alias 名称、kind、目标 path hash 和 wrapper 摘要，不输出脚本全文。缺少 required 工具入口时必须返回 `resource-tool-unavailable` 或等价 blocker，不能要求业务 prompt 改走长路径 wrapper。 +runner 对 workspace `tools/` 做统一装配：顶层带 shebang 的脚本会被 `chmod +x`，`tools/` 目录会追加到 `PATH`。`.ts` 工具脚本必须以 `#!/usr/bin/env bun` 或等价 shebang 开头；缺 shebang 必须 blocked 为 schema-invalid。短命令名称来自 repo 内真实文件，例如 `tools/hwpod`，不再由 runner 生成 wrapper。 #### promptRefs @@ -189,34 +192,9 @@ HWLAB Workbench 的 project/workspace 不属于 RuntimeAssembly 四要素，也 - `promptRefs` 不得读取 Secret、env、token、profile config 或 session 文件；需要 credential 的内容必须通过 `ProfileRef`、`toolCredentials` 或 `transientEnv` 的正式路径装配。 - `promptRefs` 缺失且 `required=true` 时，run/command 必须 blocked；不得 fallback 到用户 prompt、旧硬编码 prompt、模型默认 system prompt 或历史上下文拼接。 -#### skillRefs +#### skill 目录 -`skillRefs` 用于按同一 `ResourceBundleRef` checkout 装配 skill manifest。它只描述非敏感 skill 文件、聚合方式和 required 语义；运行时 credential 仍走 `toolCredentials` 或其他 SecretRef 路径。 - -最小形态： - -```json -{ - "name": "hwpod-cli", - "path": "skills/hwpod-cli/SKILL.md", - "required": true, - "aggregateAs": "hwpod-cli" -} -``` - -规则： - -- `path` 必须指向当前 checkout 内的 `SKILL.md`，或后续规格显式允许的 skill root；不能引用 runner 镜像、host path、ConfigMap 或外部 URL。 -- runner 必须把 skill 聚合到当前 workspace 的标准 skill registry，例如 `$WORKSPACE/.agents/skills//SKILL.md`，并设置 backend 可见的 skill dirs 环境或等价配置。 -- skill discovery fact 只输出 skill name、summary、manifest path、hash、version/commit metadata 和 count；不得输出大段 manifest 正文，除非 agent 在 turn 中按需读取文件。 -- `required=true` 的 skill 缺失、不可读或 manifest 无法解析时，run/command 必须 blocked 为 `skill-unavailable`，不能让模型凭默认 Codex skill registry 猜测，也不能把用户长 prompt 当作替代 skill。 -- `skillRefs` 与 `promptRefs` 必须来自同一 `repoUrl + commitId`，以避免业务 prompt、skill manifest 和工具 alias 版本漂移。 - -#### workspaceFiles - -`workspaceFiles` 用于在 runner 启动 backend 前，把少量非敏感、run-local 的 UTF-8 文本文件写入 materialized workspace。每个文件只能写到 workspace 相对路径，禁止绝对路径、`..` 和目录根；数量、单文件大小和总大小必须有上限。materialization event 与 result 只输出 path、bytes、sha256、count 和 `valuesPrinted=false`，不输出文件内容。 - -`workspaceFiles` 适合承载 CaseRun 这类编排器生成的 run-local 配置，例如 `.hwlab/hwpod-spec.yaml`。它不替代 git source、promptRefs、skillRefs、toolCredentials 或 SecretRef；不得用于传递 token、provider config、历史消息、大文件 artifact 或任务答案。若业务必须让 agent 修改该文件，应由 prompt 明确说明修改目标；否则 seed file 应被视为运行环境输入，而不是 agent 需要手工创建的任务。 +skill 只来自 gitbundle 复制进 workspace 的 `.agents/skills//SKILL.md`。runner 发现直接子目录中的 `SKILL.md` 后，把 `.agents/skills` 暴露给 backend，并在 initial prompt 中加入有界 skill facts。多文件 skill 的 `references/`、`scripts/` 和后续新增文件跟随目录一起复制；event/result 只输出 skill name、manifest path 摘要、hash、bytes 和 summary，不输出大段 manifest 正文。runner 不读取镜像默认 skill、host path、ConfigMap、用户长 prompt 或旧 `skillRefs`。 #### 初始 prompt 与 session 边界 @@ -229,9 +207,9 @@ HWLAB Workbench 的 project/workspace 不属于 RuntimeAssembly 四要素，也 3. Manager 或 runner Job render 只使用解析后的 image、SecretRef、sessionRef、Git commit 和 projection intent。 4. Runner materialize profile Secret 到 writable runtime home。 5. Runner materialize tool credential 到该 run 允许的 env/file projection；未实现的 tool scope 必须显式 failed/blocked，不能静默跳过后让 agent 自己猜凭据。 -6. Runner materialize Git-only resource bundle 到 workspace；P0 未实现时必须显式记录为 deferred 或 null，不能猜测 host path。 -7. Runner 在 materialized bundle 内解析 `toolAliases`、`promptRefs`、`skillRefs` 和 `workspaceFiles`：创建工具 wrapper、聚合 skill registry、读取并校验 thread-start prompt、写入 workspace seed 文件，写入有界 assembly event。 -8. Runner 启动 backend，并在 event 中记录 image digest、profile、SecretRef 名称/key、tool credential scope、sessionRef、repoUrl/commitId、promptRefs、skillRefs 和 workspace file hash/bytes 摘要。 +6. Runner materialize `kind="gitbundle"` resource bundle 到 workspace；P0 未实现时必须显式 blocked，不能猜测 host path。 +7. Runner 按 `bundles[]` 复制目录或文件，准备 workspace `tools/`、发现 `.agents/skills`，读取并校验 `promptRefs`，写入有界 assembly event。 +8. Runner 启动 backend，并在 event 中记录 image digest、profile、SecretRef 名称/key、tool credential scope、sessionRef、repoUrl/commitId、bundles、promptRefs、tools 和 skillDirs 摘要。 任何一个要素缺失或不合法，都必须按该要素失败；不得静默 fallback。 @@ -267,13 +245,13 @@ HWLAB Workbench 的 project/workspace 不属于 RuntimeAssembly 四要素，也 ### A4 ResourceBundleRef 验收 -- P0 ResourceBundle 只能是 Git-only：`repoUrl + full commitId`。 +- P0 ResourceBundle 只能是 `kind="gitbundle"`：`repoUrl + full commitId + bundles[]`。 - `commitId` 不是 branch/tag/HEAD。 - checkout 只能进入允许 workspace 前缀，不能覆盖 `/app`、Secret projection、profile runtime home 或 session 目录。 - run payload 不携带文件正文、env dump、Secret value 或大型 artifact。 +- 若提供 `bundles[]`，必须能看到每个 `subpath -> target_path` 的复制摘要；旧字段输入必须 schema-invalid。 - 若提供 `promptRefs`，必须能看到每个 prompt 的 `name/path/sha256/bytes/inject`，新 thread 首轮 `initialPromptInjected=true`，resume turn `initialPromptInjected=false`。 -- 若提供 `skillRefs`，必须能看到 skill registry 聚合摘要、required skill 名称和 manifest hash；required skill 缺失必须 blocked，不能显示模型默认 skill 列表当作业务 skill。 -- 若提供 `workspaceFiles`，必须能看到每个文件的相对路径、bytes、sha256 和 materialized count；backend 启动前 workspace 内应已存在这些文件，event/result 不得打印文件正文。 +- 若 bundle 复制了 `.agents/skills`，必须能看到 skillDirs 聚合摘要、skill 名称和 manifest hash；不能显示模型默认 skill 列表当作业务 skill。 ### A5 综合验收 @@ -283,7 +261,7 @@ HWLAB Workbench 的 project/workspace 不属于 RuntimeAssembly 四要素，也 2. 用哪一个 profile 和 SecretRef。 3. 是否使用 session；若不用，必须明确为 `null`/deferred。 4. 使用哪一个 Git repo 和 full commit；若 P0 尚未 materialize，必须明确为 deferred，不能隐式使用 host path。 -5. 是否装配 tool aliases、初始 prompt 和 skill refs；若提供，必须能回答 name/path/hash/inject/required 和是否注入，不能只依赖模型默认 prompt 或默认 skill registry。 +5. 是否装配 gitbundle bundles、workspace tools、初始 prompt 和 skillDirs；若提供，必须能回答 name/path/hash/inject/required 和是否注入，不能只依赖模型默认 prompt 或默认 skill registry。 6. 是否装配 tool credential；若需要 GitHub PR 能力，必须能回答 tool、purpose、SecretRef 和 projection kind，不能只在运行时 shell 中偶然存在 token。 ## 实现状态 @@ -294,5 +272,5 @@ HWLAB Workbench 的 project/workspace 不属于 RuntimeAssembly 四要素，也 | `ProfileRef` | 已实现/已通过 HWLAB v0.2 原入口复测 | `codex`、`deepseek` 与 `minimax-m3` 已通过 SecretRef、writable runtime home 和真实 stdio turn 验证；MiniMax-M3 已通过 HWLAB 显式 session 原入口复测，后续只允许作为 profile/config/SecretRef 选择，不新增直连 backend。 | | `SessionRef` | 已实现最小持久化 | manager 持久化 `sessionId/conversationId/threadId`，run 创建会解析既有 session，runner 按 threadId resume；session 不保存 credential 文件，TTL/GC 后续细化。 | | `SessionRef` | v0.1.1 已实现/已通过 HWLAB v0.2 原入口复测 | manager 持久化 `sessionId/conversationId/threadId` + 每个 session 绑 RWO PVC（`agentrun-v01-session-`），runner Job 把 PVC 直接挂到 `${CODEX_HOME}/`，codex app-server 自己落盘；runner pod 删除后 replacement runner 仍复用同一 SessionRef/PVC/thread，禁止 copy/restore、replacement threadId 和 fake resume。 | -| `ResourceBundleRef` | 已实现 Git-only materialization/promptRefs/skillRefs/workspaceFiles 装配 | `repoUrl + full commitId` 已进入 run schema 和 runner checkout，workspace 受 `AGENTRUN_WORKSPACE_ROOT` 限制，event/result 记录 commit/tree/workspace 摘要；`toolAliases`、`promptRefs` thread-start 注入、`skillRefs` registry 聚合和有界 `workspaceFiles` 写入已实现。 | +| `ResourceBundleRef` | 已实现 `kind="gitbundle"` materialization/promptRefs/tools/skillDirs 装配 | `repoUrl + full commitId + bundles[]` 已进入 run schema 和 runner checkout，workspace 受 `AGENTRUN_WORKSPACE_ROOT` 限制，event/result 记录 commit/tree/workspace/bundles 摘要；`tools/` PATH、`promptRefs` thread-start 注入和 `.agents/skills` 目录发现已实现。 | | `toolCredentials` | 已实现最小 env projection | GitHub PR 和 UniDesk SSH passthrough 等 agent shell/tool 授权通过装配 SPEC 的 SecretRef 进入 runner；v0.1 支持 `tool=github` 与 `tool=unidesk-ssh`、`projection.kind=env`，runner Job 使用 `valueFrom.secretKeyRef` 注入，不用 `transientEnv` 绕过。 | diff --git a/docs/reference/spec-v01-validation.md b/docs/reference/spec-v01-validation.md index 15c5544..02bed9d 100644 --- a/docs/reference/spec-v01-validation.md +++ b/docs/reference/spec-v01-validation.md @@ -24,7 +24,7 @@ - Postgres adapter：migration、事务、run/command/event round-trip、重启后可查询。 - Secret 分发：SecretRef schema、missing secret failure、redaction。 - AgentRun Queue：task schema、attempt 状态机、summary/stats/read cursor、Queue 与 Session 引用边界、旧 MiniMax/OpenCode 直连入口废弃和 redaction。 -- HWLAB v0.2 基线承接：可以用 fake backend/临时 manager 做组件自测试，覆盖 event contract、result completed 防误判、bounded output、runner job status、SessionRef profile 隔离、ResourceBundleRef 失败分类、`promptRefs`/`skillRefs` 装配和 backend preflight redaction；这些自测试不能替代真实 `agentrun-v01` CLI 交互验收。 +- HWLAB v0.2 基线承接：可以用 fake backend/临时 manager 做组件自测试，覆盖 event contract、result completed 防误判、bounded output、runner job status、SessionRef profile 隔离、ResourceBundleRef 失败分类、`promptRefs`/gitbundle skillDirs 装配和 backend preflight redaction；这些自测试不能替代真实 `agentrun-v01` CLI 交互验收。 自测试应使用 Bun + TypeScript 运行，Codex 相关自测试可以使用 fake app-server JSON-RPC client 模拟 `initialize`、`thread/start`、`thread/resume`、`turn/start`、assistant 输出、协议错误、timeout 和 transport close。 @@ -59,7 +59,7 @@ 6. manager 可查询 command state、append-only events、terminal_status 和 redacted logPath/job identity。 7. 重启 `agentrun-mgr` 后，run、command、events 和 terminal_status 仍可从 Postgres 查询。 8. 日志、event、CLI 输出和 health 中没有 provider credential、DSN password、token 或 URL credential 明文。 -9. 若变更涉及 RuntimeAssembly，必须能追溯 `BackendImageRef`、`ProfileRef`、`SessionRef` 和 `ResourceBundleRef` 的装配状态；未提供 session/resource 时必须显式为 `null`，提供时必须能查到 session/thread 和 Git commit/tree/workspace 摘要，不能由 runner 隐式猜测。若提供 `promptRefs` 或 `skillRefs`，必须能查到 name/path/hash/bytes/required/injected 摘要；required 缺失必须 blocked，不能 fallback 到模型默认 prompt 或默认 skill registry。 +9. 若变更涉及 RuntimeAssembly，必须能追溯 `BackendImageRef`、`ProfileRef`、`SessionRef` 和 `ResourceBundleRef` 的装配状态；未提供 session/resource 时必须显式为 `null`，提供时必须能查到 session/thread 和 Git commit/tree/workspace/bundles 摘要，不能由 runner 隐式猜测。若提供 `promptRefs` 或 gitbundle skills，必须能查到 name/path/hash/bytes/injected 摘要；required prompt 缺失必须 blocked，不能 fallback 到模型默认 prompt 或默认 skill registry。 ### CLI 交互联调标准 @@ -105,8 +105,8 @@ CLI 与 RESTful API 可以复用同一个真实 run 做联调。若两者观察 | cancel | 对 pending/running/terminal 分别调用 cancel | cancel 幂等，pending 不再启动 runner，running 收敛为 cancelled 或既有 terminal，events/result 可见。 | | SessionRef | 连续两轮使用同一 sessionRef 或 conversation/session/thread 摘要 | 第二轮可 resume backend thread；session 不包含 credential 文件或完整 CODEX_HOME。 | | ResourceBundleRef | 使用 `repoUrl + full commitId` 启动 runner | runner checkout 到允许 workspace，event/result 能回答 repo、commit、workspace 摘要；不使用 branch/tag/HEAD 或 host path。 | -| Resource prompt/skill assembly | 使用同一 `ResourceBundleRef` 指定 `promptRefs`、`skillRefs` 和 `toolAliases` | 新 thread 首轮注入 initial prompt 和 skill facts；resume 不重复注入；required prompt/skill 缺失 blocked；不使用用户长 prompt、旧硬编码 prompt、镜像 `/app/skills` 或默认 Codex skill registry 替代。 | -| DS 短 prompt 探测 | 通过正式 CLI/Web 等价入口向真实 `backendProfile=deepseek` 发送短 prompt | “可见 skill”回复包含业务 `skillRefs` 而不只是 Codex 默认系统 skill；“当前 HWLAB 初始规则”能回答 hwpod/HWPOD 四要素/禁止路径；“编译 D601-F103-V2”能触发 `hwpod-cli -> hwpod-compiler-cli -> /v1/hwpod-node-ops -> hwpod-node` 正向链路。 | +| Resource prompt/skill assembly | 使用同一 `ResourceBundleRef.kind="gitbundle"` 指定 `bundles[]` 和 `promptRefs` | 新 thread 首轮注入 initial prompt 和 gitbundle skill facts；resume 不重复注入；required prompt 缺失 blocked；不使用用户长 prompt、旧硬编码 prompt、镜像 `/app/skills` 或默认 Codex skill registry 替代。 | +| DS 短 prompt 探测 | 通过正式 CLI/Web 等价入口向真实 `backendProfile=deepseek` 发送短 prompt | “可见 skill”回复包含 gitbundle `.agents/skills` 中的业务 skill 而不只是 Codex 默认系统 skill；“当前 HWLAB 初始规则”能回答 hwpod/HWPOD 四要素/禁止路径；“编译 D601-F103-V2”能触发 `hwpod -> hwpod-cli -> hwpod-compiler-cli -> /v1/hwpod-node-ops -> hwpod-node` 正向链路。 | | ProfileRef/SecretRef | 分别验证 `codex`、`deepseek` 与 `minimax-m3` profile | 只使用当前 profile SecretRef；缺失时 `secret-unavailable`，不 fallback，不泄露 Secret 值。 | | bounded output | 触发工具/命令输出摘要 | result/event 只含摘要、字节数、截断标记和必要引用，不把大 stdout/stderr 塞入单个 JSON 响应。 | diff --git a/src/common/types.ts b/src/common/types.ts index 271ec96..66fda4b 100644 --- a/src/common/types.ts +++ b/src/common/types.ts @@ -56,34 +56,25 @@ export interface SecretRef extends JsonRecord { mountPath?: string; } +export interface GitBundleItemRef extends JsonRecord { + name?: string; + repoUrl?: string; + commitId?: string; + subpath: string; + targetPath: string; +} + export interface ResourceBundleRef extends JsonRecord { - kind: "git"; + kind: "gitbundle"; repoUrl: string; commitId: string; - subdir?: string; - sparsePaths?: string[]; - toolAliases?: Array<{ - name: string; - path: string; - kind: "node-script" | "bun-script" | "sh-script" | "executable"; - }>; + bundles: GitBundleItemRef[]; promptRefs?: Array<{ name: string; path: string; inject?: "thread-start"; required?: boolean; }>; - skillRefs?: Array<{ - name: string; - path: string; - required?: boolean; - aggregateAs?: string; - }>; - workspaceFiles?: Array<{ - path: string; - content: string; - encoding?: "utf8"; - }>; submodules?: false; lfs?: false; credentialRef?: SecretRef; diff --git a/src/common/validation.ts b/src/common/validation.ts index 989acef..27d337f 100644 --- a/src/common/validation.ts +++ b/src/common/validation.ts @@ -83,26 +83,13 @@ export function validateResourceBundleRef(value: unknown): ResourceBundleRef | n if (value === undefined || value === null) return null; const record = asRecord(value, "resourceBundleRef"); const kind = requiredString(record, "kind"); - if (kind !== "git") throw new AgentRunError("schema-invalid", "resourceBundleRef.kind must be git in v0.1", { httpStatus: 400 }); + if (kind !== "gitbundle") throw new AgentRunError("schema-invalid", "resourceBundleRef.kind must be gitbundle", { httpStatus: 400 }); const repoUrl = requiredString(record, "repoUrl"); const commitId = requiredString(record, "commitId"); - if (!/^[0-9a-f]{40}$/u.test(commitId)) throw new AgentRunError("schema-invalid", "resourceBundleRef.commitId must be a full 40-character git commit sha", { httpStatus: 400 }); - const result: ResourceBundleRef = { kind: "git", repoUrl, commitId }; - const subdir = optionalString(record.subdir); - if (subdir) { - if (subdir.startsWith("/") || subdir.includes("..")) throw new AgentRunError("schema-invalid", "resourceBundleRef.subdir must stay within the checkout", { httpStatus: 400 }); - result.subdir = subdir; - } - if (record.sparsePaths !== undefined) { - if (!Array.isArray(record.sparsePaths) || !record.sparsePaths.every((item) => typeof item === "string" && item.length > 0 && !item.startsWith("/") && !item.includes(".."))) { - throw new AgentRunError("schema-invalid", "resourceBundleRef.sparsePaths must be relative path strings", { httpStatus: 400 }); - } - result.sparsePaths = record.sparsePaths as string[]; - } - if (record.toolAliases !== undefined) result.toolAliases = validateResourceToolAliases(record.toolAliases); + validateCommitId(commitId, "resourceBundleRef.commitId"); + rejectLegacyResourceBundleFields(record); + const result: ResourceBundleRef = { kind: "gitbundle", repoUrl, commitId, bundles: validateResourceGitBundles(record.bundles, repoUrl, commitId) }; if (record.promptRefs !== undefined) result.promptRefs = validateResourcePromptRefs(record.promptRefs); - if (record.skillRefs !== undefined) result.skillRefs = validateResourceSkillRefs(record.skillRefs); - if (record.workspaceFiles !== undefined) result.workspaceFiles = validateResourceWorkspaceFiles(record.workspaceFiles); if (record.submodules !== undefined && record.submodules !== false) throw new AgentRunError("schema-invalid", "resourceBundleRef.submodules can only be false in v0.1", { httpStatus: 400 }); if (record.lfs !== undefined && record.lfs !== false) throw new AgentRunError("schema-invalid", "resourceBundleRef.lfs can only be false in v0.1", { httpStatus: 400 }); if (record.submodules === false) result.submodules = false; @@ -111,24 +98,39 @@ export function validateResourceBundleRef(value: unknown): ResourceBundleRef | n return result; } -function validateResourceToolAliases(value: unknown): NonNullable { - if (!Array.isArray(value)) throw new AgentRunError("schema-invalid", "resourceBundleRef.toolAliases must be an array", { httpStatus: 400 }); - if (value.length > 16) throw new AgentRunError("schema-invalid", "resourceBundleRef.toolAliases must contain at most 16 entries", { httpStatus: 400 }); +function rejectLegacyResourceBundleFields(record: JsonRecord): void { + for (const field of ["toolAliases", "skillRefs", "workspaceFiles", "subdir", "sparsePaths"] as const) { + if (record[field] !== undefined) throw new AgentRunError("schema-invalid", `resourceBundleRef.${field} is removed; use resourceBundleRef.bundles[] with kind=gitbundle`, { httpStatus: 400 }); + } +} + +function validateResourceGitBundles(value: unknown, defaultRepoUrl: string, defaultCommitId: string): ResourceBundleRef["bundles"] { + if (!Array.isArray(value)) throw new AgentRunError("schema-invalid", "resourceBundleRef.bundles must be an array", { httpStatus: 400 }); + if (value.length === 0) throw new AgentRunError("schema-invalid", "resourceBundleRef.bundles must contain at least one entry", { httpStatus: 400 }); + if (value.length > 64) throw new AgentRunError("schema-invalid", "resourceBundleRef.bundles must contain at most 64 entries", { httpStatus: 400 }); const seen = new Set(); return value.map((entry, index) => { - const record = asRecord(entry, `resourceBundleRef.toolAliases[${index}]`); - const name = requiredString(record, "name"); - if (!/^[a-z][a-z0-9._-]{0,62}$/u.test(name)) throw new AgentRunError("schema-invalid", `resourceBundleRef.toolAliases[${index}].name must be a lowercase command name`, { httpStatus: 400 }); - if (seen.has(name)) throw new AgentRunError("schema-invalid", `resourceBundleRef.toolAliases name ${name} is duplicated`, { httpStatus: 400 }); - seen.add(name); - const aliasPath = requiredString(record, "path"); - if (aliasPath.startsWith("/") || aliasPath.includes("..")) throw new AgentRunError("schema-invalid", `resourceBundleRef.toolAliases[${index}].path must stay within the checkout`, { httpStatus: 400 }); - const kind = requiredString(record, "kind"); - if (kind !== "node-script" && kind !== "bun-script" && kind !== "sh-script" && kind !== "executable") throw new AgentRunError("schema-invalid", `resourceBundleRef.toolAliases[${index}].kind is not supported in v0.1`, { httpStatus: 400, details: { allowedKinds: ["node-script", "bun-script", "sh-script", "executable"] } }); - return { name, path: aliasPath, kind }; + const record = asRecord(entry, `resourceBundleRef.bundles[${index}]`); + const name = optionalString(record.name); + if (name) validateResourceName(name, `resourceBundleRef.bundles[${index}].name`); + const repoUrl = optionalString(record.repoUrl) ?? defaultRepoUrl; + const commitId = optionalString(record.commitId) ?? defaultCommitId; + validateCommitId(commitId, `resourceBundleRef.bundles[${index}].commitId`); + const subpath = validateBundleSubpath(requiredString(record, "subpath"), `resourceBundleRef.bundles[${index}].subpath`); + const rawTargetPath = typeof record.targetPath === "string" ? record.targetPath : record.target_path; + if (typeof rawTargetPath !== "string" || rawTargetPath.trim().length === 0) throw new AgentRunError("schema-invalid", `resourceBundleRef.bundles[${index}].target_path is required`, { httpStatus: 400 }); + const targetPath = validateWorkspaceRelativePath(rawTargetPath.trim(), `resourceBundleRef.bundles[${index}].target_path`); + const identity = `${repoUrl}\0${commitId}\0${subpath}\0${targetPath}`; + if (seen.has(identity)) throw new AgentRunError("schema-invalid", `resourceBundleRef.bundles[${index}] duplicates an earlier bundle target`, { httpStatus: 400 }); + seen.add(identity); + return { ...(name ? { name } : {}), ...(repoUrl === defaultRepoUrl ? {} : { repoUrl }), ...(commitId === defaultCommitId ? {} : { commitId }), subpath, targetPath }; }); } +function validateCommitId(commitId: string, fieldName: string): void { + if (!/^[0-9a-f]{40}$/u.test(commitId)) throw new AgentRunError("schema-invalid", `${fieldName} must be a full 40-character git commit sha`, { httpStatus: 400 }); +} + function validateResourcePromptRefs(value: unknown): NonNullable { if (!Array.isArray(value)) throw new AgentRunError("schema-invalid", "resourceBundleRef.promptRefs must be an array", { httpStatus: 400 }); if (value.length > 16) throw new AgentRunError("schema-invalid", "resourceBundleRef.promptRefs must contain at most 16 entries", { httpStatus: 400 }); @@ -147,62 +149,23 @@ function validateResourcePromptRefs(value: unknown): NonNullable { - if (!Array.isArray(value)) throw new AgentRunError("schema-invalid", "resourceBundleRef.skillRefs must be an array", { httpStatus: 400 }); - if (value.length > 32) throw new AgentRunError("schema-invalid", "resourceBundleRef.skillRefs must contain at most 32 entries", { httpStatus: 400 }); - const seen = new Set(); - return value.map((entry, index) => { - const record = asRecord(entry, `resourceBundleRef.skillRefs[${index}]`); - const name = validateResourceName(requiredString(record, "name"), `resourceBundleRef.skillRefs[${index}].name`); - if (seen.has(name)) throw new AgentRunError("schema-invalid", `resourceBundleRef.skillRefs name ${name} is duplicated`, { httpStatus: 400 }); - seen.add(name); - const skillPath = validateBundleRelativePath(requiredString(record, "path"), `resourceBundleRef.skillRefs[${index}].path`); - if (!skillPath.endsWith("SKILL.md")) throw new AgentRunError("schema-invalid", `resourceBundleRef.skillRefs[${index}].path must point to SKILL.md in v0.1`, { httpStatus: 400 }); - const required = record.required === undefined ? false : record.required; - if (typeof required !== "boolean") throw new AgentRunError("schema-invalid", `resourceBundleRef.skillRefs[${index}].required must be boolean`, { httpStatus: 400 }); - const aggregateAs = optionalString(record.aggregateAs); - if (aggregateAs) validateResourceName(aggregateAs, `resourceBundleRef.skillRefs[${index}].aggregateAs`); - return { name, path: skillPath, required, ...(aggregateAs ? { aggregateAs } : {}) }; - }); -} - -const maxWorkspaceFiles = Number.MAX_SAFE_INTEGER; -const maxWorkspaceFileBytes = 128 * 1024; -const maxWorkspaceFilesTotalBytes = 4 * 1024 * 1024; - -function validateResourceWorkspaceFiles(value: unknown): NonNullable { - if (!Array.isArray(value)) throw new AgentRunError("schema-invalid", "resourceBundleRef.workspaceFiles must be an array", { httpStatus: 400 }); - if (value.length > maxWorkspaceFiles) throw new AgentRunError("schema-invalid", `resourceBundleRef.workspaceFiles must contain at most ${maxWorkspaceFiles} entries`, { httpStatus: 400 }); - const seen = new Set(); - let totalBytes = 0; - return value.map((entry, index) => { - const record = asRecord(entry, `resourceBundleRef.workspaceFiles[${index}]`); - const filePath = validateWorkspaceRelativePath(requiredString(record, "path"), `resourceBundleRef.workspaceFiles[${index}].path`); - if (seen.has(filePath)) throw new AgentRunError("schema-invalid", `resourceBundleRef.workspaceFiles path ${filePath} is duplicated`, { httpStatus: 400 }); - seen.add(filePath); - if (typeof record.content !== "string") throw new AgentRunError("schema-invalid", `resourceBundleRef.workspaceFiles[${index}].content must be a utf8 string`, { httpStatus: 400 }); - const encoding = optionalString(record.encoding) ?? "utf8"; - if (encoding !== "utf8") throw new AgentRunError("schema-invalid", `resourceBundleRef.workspaceFiles[${index}].encoding must be utf8`, { httpStatus: 400 }); - const bytes = Buffer.byteLength(record.content, "utf8"); - if (bytes > maxWorkspaceFileBytes) throw new AgentRunError("schema-invalid", `resourceBundleRef.workspaceFiles[${index}] exceeds the per-file size limit`, { httpStatus: 400, details: { path: filePath, bytes, maxWorkspaceFileBytes, valuesPrinted: false } }); - totalBytes += bytes; - if (totalBytes > maxWorkspaceFilesTotalBytes) throw new AgentRunError("schema-invalid", "resourceBundleRef.workspaceFiles exceeds the total size limit", { httpStatus: 400, details: { totalBytes, maxWorkspaceFilesTotalBytes, valuesPrinted: false } }); - return { path: filePath, content: record.content, encoding: "utf8" as const }; - }); -} - function validateResourceName(name: string, fieldName: string): string { if (!/^[a-z][a-z0-9._-]{0,62}$/u.test(name)) throw new AgentRunError("schema-invalid", `${fieldName} must be a lowercase resource name`, { httpStatus: 400 }); return name; } +function validateBundleSubpath(relativePath: string, fieldName: string): string { + if (relativePath.startsWith("/") || relativePath.includes("..") || relativePath.includes("\\")) throw new AgentRunError("schema-invalid", `${fieldName} must stay within the checkout`, { httpStatus: 400 }); + return relativePath; +} + function validateBundleRelativePath(relativePath: string, fieldName: string): string { - if (relativePath.startsWith("/") || relativePath.includes("..")) throw new AgentRunError("schema-invalid", `${fieldName} must stay within the checkout`, { httpStatus: 400 }); + if (relativePath === "." || relativePath.startsWith("/") || relativePath.includes("..") || relativePath.includes("\\")) throw new AgentRunError("schema-invalid", `${fieldName} must stay within the checkout`, { httpStatus: 400 }); return relativePath; } function validateWorkspaceRelativePath(relativePath: string, fieldName: string): string { - if (relativePath === "." || relativePath.startsWith("/") || relativePath.includes("..")) throw new AgentRunError("schema-invalid", `${fieldName} must stay within the workspace`, { httpStatus: 400 }); + if (relativePath === "." || relativePath.startsWith("/") || relativePath.includes("..") || relativePath.includes("\\")) throw new AgentRunError("schema-invalid", `${fieldName} must stay within the workspace`, { httpStatus: 400 }); return relativePath; } diff --git a/src/mgr/result.ts b/src/mgr/result.ts index 570e45a..92b43dc 100644 --- a/src/mgr/result.ts +++ b/src/mgr/result.ts @@ -172,11 +172,12 @@ function resourceBundleSummary(run: RunRecord, events: RunEvent[]): JsonRecord | kind: run.resourceBundleRef.kind, repoUrl: run.resourceBundleRef.repoUrl, commitId: run.resourceBundleRef.commitId, - subdir: run.resourceBundleRef.subdir ?? null, - toolAliases: run.resourceBundleRef.toolAliases ? { count: run.resourceBundleRef.toolAliases.length, names: run.resourceBundleRef.toolAliases.map((item) => item.name), valuesPrinted: false } : { count: 0, names: [], valuesPrinted: false }, + bundles: { + count: run.resourceBundleRef.bundles.length, + items: run.resourceBundleRef.bundles.map((item) => ({ name: item.name ?? null, repoUrl: item.repoUrl ?? run.resourceBundleRef?.repoUrl ?? null, commitId: item.commitId ?? run.resourceBundleRef?.commitId ?? null, subpath: item.subpath, targetPath: item.targetPath, valuesPrinted: false })), + valuesPrinted: false, + }, promptRefs: run.resourceBundleRef.promptRefs ? { count: run.resourceBundleRef.promptRefs.length, names: run.resourceBundleRef.promptRefs.map((item) => item.name), required: run.resourceBundleRef.promptRefs.filter((item) => item.required === true).map((item) => item.name), valuesPrinted: false } : { count: 0, names: [], required: [], valuesPrinted: false }, - skillRefs: run.resourceBundleRef.skillRefs ? { count: run.resourceBundleRef.skillRefs.length, names: run.resourceBundleRef.skillRefs.map((item) => item.name), required: run.resourceBundleRef.skillRefs.filter((item) => item.required === true).map((item) => item.name), valuesPrinted: false } : { count: 0, names: [], required: [], valuesPrinted: false }, - workspaceFiles: run.resourceBundleRef.workspaceFiles ? { count: run.resourceBundleRef.workspaceFiles.length, paths: run.resourceBundleRef.workspaceFiles.map((item) => item.path), valuesPrinted: false } : { count: 0, paths: [], valuesPrinted: false }, materialized: materialized as JsonValue, }; } diff --git a/src/mgr/store.ts b/src/mgr/store.ts index ae57844..feab101 100644 --- a/src/mgr/store.ts +++ b/src/mgr/store.ts @@ -732,12 +732,12 @@ export function summarizeResourceBundleRef(resourceBundleRef: RunRecord["resourc kind: resourceBundleRef.kind, repoUrl: resourceBundleRef.repoUrl, commitId: resourceBundleRef.commitId, - subdir: resourceBundleRef.subdir ?? null, - sparsePathCount: resourceBundleRef.sparsePaths?.length ?? 0, - toolAliases: resourceBundleRef.toolAliases ? { count: resourceBundleRef.toolAliases.length, names: resourceBundleRef.toolAliases.map((item) => item.name), valuesPrinted: false } : { count: 0, names: [], valuesPrinted: false }, + bundles: { + count: resourceBundleRef.bundles.length, + items: resourceBundleRef.bundles.map((item) => ({ name: item.name ?? null, repoUrl: item.repoUrl ?? resourceBundleRef.repoUrl, commitId: item.commitId ?? resourceBundleRef.commitId, subpath: item.subpath, targetPath: item.targetPath, valuesPrinted: false })), + valuesPrinted: false, + }, promptRefs: resourceBundleRef.promptRefs ? { count: resourceBundleRef.promptRefs.length, names: resourceBundleRef.promptRefs.map((item) => item.name), required: resourceBundleRef.promptRefs.filter((item) => item.required === true).map((item) => item.name), valuesPrinted: false } : { count: 0, names: [], required: [], valuesPrinted: false }, - skillRefs: resourceBundleRef.skillRefs ? { count: resourceBundleRef.skillRefs.length, names: resourceBundleRef.skillRefs.map((item) => item.name), required: resourceBundleRef.skillRefs.filter((item) => item.required === true).map((item) => item.name), valuesPrinted: false } : { count: 0, names: [], required: [], valuesPrinted: false }, - workspaceFiles: resourceBundleRef.workspaceFiles ? { count: resourceBundleRef.workspaceFiles.length, paths: resourceBundleRef.workspaceFiles.map((item) => item.path), valuesPrinted: false } : { count: 0, paths: [], valuesPrinted: false }, submodules: resourceBundleRef.submodules ?? false, lfs: resourceBundleRef.lfs ?? false, credentialRef: resourceBundleRef.credentialRef ? { name: resourceBundleRef.credentialRef.name, namespace: resourceBundleRef.credentialRef.namespace ?? null, keys: resourceBundleRef.credentialRef.keys ?? [], valuesPrinted: false } : null, diff --git a/src/runner/resource-bundle.ts b/src/runner/resource-bundle.ts index f404350..658deea 100644 --- a/src/runner/resource-bundle.ts +++ b/src/runner/resource-bundle.ts @@ -1,6 +1,6 @@ import { spawn } from "node:child_process"; import { createHash } from "node:crypto"; -import { chmod, cp, mkdir, readFile, rm, writeFile } from "node:fs/promises"; +import { chmod, cp, mkdir, readdir, readFile, rm, stat } from "node:fs/promises"; import path from "node:path"; import { AgentRunError } from "../common/errors.js"; import { redactText } from "../common/redaction.js"; @@ -40,70 +40,135 @@ interface MaterializedSkillRef { summary: string; } +interface GitCheckout { + repoUrl: string; + commitId: string; + checkoutPath: string; + treeId: string; +} + +interface MaterializedGitBundle { + name: string | null; + repoUrl: string; + commitId: string; + subpath: string; + targetPath: string; + sourceKind: "file" | "directory"; + sourceBytes: number | null; +} + export async function materializeResourceBundle(resourceBundleRef: ResourceBundleRef | null | undefined, env: NodeJS.ProcessEnv = process.env): Promise { if (!resourceBundleRef) return null; const workspaceRoot = path.resolve(env.AGENTRUN_WORKSPACE_ROOT ?? "/home/agentrun/workspaces"); - const checkoutPath = path.join(workspaceRoot, stableHash({ repoUrl: resourceBundleRef.repoUrl, commitId: resourceBundleRef.commitId }).slice(0, 16)); - await mkdir(checkoutPath, { recursive: true }); - await git(["init"], checkoutPath); - await git(["remote", "remove", "origin"], checkoutPath, { allowFailure: true }); - await git(["remote", "add", "origin", resourceBundleRef.repoUrl], checkoutPath); - if (resourceBundleRef.sparsePaths && resourceBundleRef.sparsePaths.length > 0) { - await git(["config", "core.sparseCheckout", "true"], checkoutPath); - await mkdir(path.join(checkoutPath, ".git", "info"), { recursive: true }); - await writeFile(path.join(checkoutPath, ".git", "info", "sparse-checkout"), `${resourceBundleRef.sparsePaths.join("\n")}\n`, "utf8"); - } - await git(["fetch", "--depth", "1", "origin", resourceBundleRef.commitId], checkoutPath); - await git(["checkout", "--detach", resourceBundleRef.commitId], checkoutPath); - const actualCommit = (await git(["rev-parse", "HEAD"], checkoutPath)).stdout.trim(); - if (actualCommit !== resourceBundleRef.commitId) throw new AgentRunError("infra-failed", "resource bundle checkout did not land on requested commit", { httpStatus: 500, details: { expectedCommit: resourceBundleRef.commitId, actualCommit } }); - const treeId = (await git(["rev-parse", "HEAD^{tree}"], checkoutPath)).stdout.trim(); - const workspacePath = resolveWorkspacePath(checkoutPath, resourceBundleRef.subdir); - const toolAliases = await materializeToolAliases(checkoutPath, resourceBundleRef.toolAliases ?? [], env); - const skills = await materializeSkillRefs(checkoutPath, workspacePath, resourceBundleRef.skillRefs ?? []); - const prompts = await materializePromptRefs(checkoutPath, resourceBundleRef.promptRefs ?? []); - const workspaceFiles = await materializeWorkspaceFiles(workspacePath, resourceBundleRef.workspaceFiles ?? []); + const runScope = env.AGENTRUN_RUN_ID ?? env.AGENTRUN_ATTEMPT_ID ?? "standalone"; + const assemblyRoot = path.join(workspaceRoot, `gitbundle-${stableHash({ runScope, resourceBundleRef }).slice(0, 16)}`); + const checkoutRoot = path.join(assemblyRoot, "checkouts"); + const workspacePath = path.join(assemblyRoot, "workspace"); + await rm(assemblyRoot, { recursive: true, force: true }); + await mkdir(checkoutRoot, { recursive: true }); + await mkdir(workspacePath, { recursive: true }); + const checkoutCache = new Map>(); + const checkoutFor = (repoUrl: string, commitId: string) => { + const key = stableHash({ repoUrl, commitId }); + let checkout = checkoutCache.get(key); + if (!checkout) { + checkout = checkoutGitCommit(checkoutRoot, repoUrl, commitId); + checkoutCache.set(key, checkout); + } + return checkout; + }; + const materializedBundles = await materializeGitBundles(workspacePath, resourceBundleRef, checkoutFor); + const defaultCheckout = await checkoutFor(resourceBundleRef.repoUrl, resourceBundleRef.commitId); + const tools = await prepareGitBundleTools(workspacePath); + const skills = await discoverGitBundleSkills(workspacePath); + const prompts = await materializePromptRefs(defaultCheckout.checkoutPath, resourceBundleRef.promptRefs ?? []); const initialPrompt = assembleInitialPrompt(prompts.items, skills.items); return { workspacePath, - ...(toolAliases.binPath ? { binPath: toolAliases.binPath } : {}), + ...(tools.binPath ? { binPath: tools.binPath } : {}), ...(skills.skillsDir ? { skillsDir: skills.skillsDir } : {}), ...(initialPrompt ? { initialPrompt } : {}), event: { phase: "resource-bundle-materialized", - kind: "git", + kind: "gitbundle", repoUrl: resourceBundleRef.repoUrl, commitId: resourceBundleRef.commitId, - treeId, - checkoutPath: pathSummary(checkoutPath), + treeId: defaultCheckout.treeId, + checkoutPath: pathSummary(defaultCheckout.checkoutPath), workspacePath: pathSummary(workspacePath), - subdir: resourceBundleRef.subdir ?? null, - sparsePathCount: resourceBundleRef.sparsePaths?.length ?? 0, - toolAliases: toolAliases.event, - skillRefs: skills.event, + bundles: { + count: materializedBundles.length, + items: materializedBundles.map((item) => ({ ...item, valuesPrinted: false })), + valuesPrinted: false, + }, + tools: tools.event, + skillDirs: skills.event, promptRefs: prompts.event, - workspaceFiles: workspaceFiles.event, - initialPrompt: initialPrompt?.summary ?? { available: false, bytes: 0, sha256: null, promptRefCount: prompts.items.length, skillRefCount: skills.items.length, valuesPrinted: false }, + initialPrompt: initialPrompt?.summary ?? { available: false, bytes: 0, sha256: null, promptRefCount: prompts.items.length, skillCount: skills.items.length, valuesPrinted: false }, valuesPrinted: false, }, }; } -async function materializeToolAliases(checkoutPath: string, aliases: NonNullable, env: NodeJS.ProcessEnv): Promise<{ binPath?: string; event: JsonRecord }> { - if (aliases.length === 0) return { event: { count: 0, names: [], binPath: null, valuesPrinted: false } }; - const binPath = path.resolve(env.AGENTRUN_RESOURCE_BIN_PATH ?? path.join(path.dirname(checkoutPath), ".bin")); - await mkdir(binPath, { recursive: true }); - const names: string[] = []; - for (const alias of aliases) { - const target = resolveBundlePath(checkoutPath, alias.path, `toolAliases.${alias.name}.path`); - const wrapper = path.join(binPath, alias.name); - const content = aliasWrapper(alias.kind, target); - await assertAliasWrapperWritable(wrapper, alias.name); - await writeFile(wrapper, content, "utf8"); - await chmod(wrapper, 0o755); - names.push(alias.name); +async function checkoutGitCommit(checkoutRoot: string, repoUrl: string, commitId: string): Promise { + const checkoutPath = path.join(checkoutRoot, stableHash({ repoUrl, commitId }).slice(0, 16)); + await mkdir(checkoutPath, { recursive: true }); + await git(["init"], checkoutPath); + await git(["remote", "remove", "origin"], checkoutPath, { allowFailure: true }); + await git(["remote", "add", "origin", repoUrl], checkoutPath); + await git(["fetch", "--depth", "1", "origin", commitId], checkoutPath); + await git(["checkout", "--detach", commitId], checkoutPath); + const actualCommit = (await git(["rev-parse", "HEAD"], checkoutPath)).stdout.trim(); + if (actualCommit !== commitId) throw new AgentRunError("infra-failed", "gitbundle checkout did not land on requested commit", { httpStatus: 500, details: { expectedCommit: commitId, actualCommit } }); + const treeId = (await git(["rev-parse", "HEAD^{tree}"], checkoutPath)).stdout.trim(); + return { repoUrl, commitId, checkoutPath, treeId }; +} + +async function materializeGitBundles(workspacePath: string, resourceBundleRef: ResourceBundleRef, checkoutFor: (repoUrl: string, commitId: string) => Promise): Promise { + const items: MaterializedGitBundle[] = []; + for (const [index, bundle] of resourceBundleRef.bundles.entries()) { + const repoUrl = bundle.repoUrl ?? resourceBundleRef.repoUrl; + const commitId = bundle.commitId ?? resourceBundleRef.commitId; + const checkout = await checkoutFor(repoUrl, commitId); + const source = resolveBundlePath(checkout.checkoutPath, bundle.subpath, `bundles[${index}].subpath`); + const target = resolveWorkspaceTargetPath(workspacePath, bundle.targetPath, `bundles[${index}].target_path`); + let sourceStat; + try { + sourceStat = await stat(source); + } catch (error) { + throw new AgentRunError("schema-invalid", `gitbundle subpath ${bundle.subpath} is not readable`, { httpStatus: 400, details: { index, subpath: bundle.subpath, error: fileErrorSummary(error), valuesPrinted: false } }); + } + await mkdir(path.dirname(target), { recursive: true }); + await rm(target, { recursive: true, force: true }); + await cp(source, target, { recursive: true, force: true, dereference: false }); + items.push({ name: bundle.name ?? null, repoUrl, commitId, subpath: bundle.subpath, targetPath: bundle.targetPath, sourceKind: sourceStat.isDirectory() ? "directory" : "file", sourceBytes: sourceStat.isFile() ? sourceStat.size : null }); } - return { binPath, event: { count: names.length, names, binPath: pathSummary(binPath), valuesPrinted: false } }; + return items; +} + +async function prepareGitBundleTools(workspacePath: string): Promise<{ binPath?: string; event: JsonRecord }> { + const binPath = path.join(workspacePath, "tools"); + let entries; + try { + entries = await readdir(binPath, { withFileTypes: true }); + } catch (error) { + if (error && typeof error === "object" && "code" in error && (error as { code?: unknown }).code === "ENOENT") return { event: { count: 0, names: [], binPath: null, valuesPrinted: false } }; + throw error; + } + const names: string[] = []; + const items: JsonRecord[] = []; + for (const entry of entries) { + if (!entry.isFile()) continue; + const filePath = path.join(binPath, entry.name); + const text = await readFile(filePath, "utf8"); + const firstLine = text.split(/\r?\n/u, 1)[0] ?? ""; + if (entry.name.endsWith(".ts") && !firstLine.startsWith("#!")) throw new AgentRunError("schema-invalid", `gitbundle tool ${entry.name} must start with a shebang`, { httpStatus: 400 }); + if (!firstLine.startsWith("#!")) continue; + await chmod(filePath, 0o755); + names.push(entry.name); + items.push({ name: entry.name, sha256: sha256Text(text), bytes: Buffer.byteLength(text, "utf8"), shebang: firstLine.slice(0, 80), valuesPrinted: false }); + } + return { binPath, event: { count: names.length, names, items, binPath: pathSummary(binPath), valuesPrinted: false } }; } async function materializePromptRefs(checkoutPath: string, refs: NonNullable): Promise<{ items: MaterializedPromptRef[]; event: JsonRecord }> { @@ -142,41 +207,39 @@ async function materializePromptRefs(checkoutPath: string, refs: NonNullable): Promise<{ items: MaterializedSkillRef[]; skillsDir?: string; event: JsonRecord }> { - if (refs.length === 0) return { items: [], event: { count: 0, materializedCount: 0, names: [], skillsDir: null, items: [], valuesPrinted: false } }; +async function discoverGitBundleSkills(workspacePath: string): Promise<{ items: MaterializedSkillRef[]; skillsDir?: string; event: JsonRecord }> { const skillsDir = path.join(workspacePath, ".agents", "skills"); - await mkdir(skillsDir, { recursive: true }); + let entries; + try { + entries = await readdir(skillsDir, { withFileTypes: true }); + } catch (error) { + if (error && typeof error === "object" && "code" in error && (error as { code?: unknown }).code === "ENOENT") return { items: [], event: { count: 0, materializedCount: 0, names: [], skillsDir: null, items: [], valuesPrinted: false } }; + throw error; + } const items: MaterializedSkillRef[] = []; const eventItems: JsonRecord[] = []; - for (const ref of refs) { - const manifestPath = resolveBundlePath(checkoutPath, ref.path, `skillRefs.${ref.name}.path`); - const required = ref.required === true; + for (const entry of entries) { + if (!entry.isDirectory()) continue; + const aggregateAs = entry.name; + const manifestPath = path.join(skillsDir, aggregateAs, "SKILL.md"); let manifestText: string; try { manifestText = await readFile(manifestPath, "utf8"); } catch (error) { - if (required) throw new AgentRunError("skill-unavailable", `required resource skill ${ref.name} is not readable`, { httpStatus: 400, details: { name: ref.name, path: ref.path, error: fileErrorSummary(error), valuesPrinted: false } }); - eventItems.push({ name: ref.name, path: ref.path, required, aggregateAs: ref.aggregateAs ?? ref.name, status: "missing", valuesPrinted: false }); + eventItems.push({ name: aggregateAs, path: `.agents/skills/${aggregateAs}/SKILL.md`, required: true, aggregateAs, status: "missing", error: fileErrorSummary(error), valuesPrinted: false }); continue; } - const aggregateAs = ref.aggregateAs ?? ref.name; - const sourceRoot = path.dirname(manifestPath); - const targetRoot = path.join(skillsDir, aggregateAs); - if (path.resolve(sourceRoot) !== path.resolve(targetRoot)) { - await rm(targetRoot, { recursive: true, force: true }); - await cp(sourceRoot, targetRoot, { recursive: true, force: true, dereference: false }); - } const bytes = Buffer.byteLength(manifestText, "utf8"); const sha = sha256Text(manifestText); const summary = skillSummary(manifestText); - items.push({ name: ref.name, path: ref.path, aggregateAs, required, registryPath: path.join(targetRoot, "SKILL.md"), manifestBytes: bytes, manifestSha256: sha, summary }); - eventItems.push({ name: ref.name, path: ref.path, aggregateAs, required, status: "materialized", manifestSha256: sha, manifestBytes: bytes, registryPath: pathSummary(path.join(targetRoot, "SKILL.md")), summary, valuesPrinted: false }); + items.push({ name: aggregateAs, path: `.agents/skills/${aggregateAs}/SKILL.md`, aggregateAs, required: true, registryPath: manifestPath, manifestBytes: bytes, manifestSha256: sha, summary }); + eventItems.push({ name: aggregateAs, path: `.agents/skills/${aggregateAs}/SKILL.md`, aggregateAs, required: true, status: "materialized", manifestSha256: sha, manifestBytes: bytes, registryPath: pathSummary(manifestPath), summary, valuesPrinted: false }); } return { items, skillsDir, event: { - count: refs.length, + count: entries.filter((entry) => entry.isDirectory()).length, materializedCount: items.length, names: items.map((item) => item.name), skillsDir: pathSummary(skillsDir), @@ -186,50 +249,25 @@ async function materializeSkillRefs(checkoutPath: string, workspacePath: string, }; } -async function materializeWorkspaceFiles(workspacePath: string, files: NonNullable): Promise<{ event: JsonRecord }> { - if (files.length === 0) return { event: { count: 0, materializedCount: 0, items: [], totalBytes: 0, valuesPrinted: false } }; - const eventItems: JsonRecord[] = []; - let totalBytes = 0; - for (const file of files) { - const target = resolveWorkspaceFilePath(workspacePath, file.path, `workspaceFiles.${file.path}.path`); - const content = file.content; - const bytes = Buffer.byteLength(content, "utf8"); - await mkdir(path.dirname(target), { recursive: true }); - await writeFile(target, content, "utf8"); - totalBytes += bytes; - eventItems.push({ path: file.path, encoding: file.encoding ?? "utf8", status: "materialized", bytes, sha256: sha256Text(content), valuesPrinted: false }); - } - return { - event: { - count: files.length, - materializedCount: eventItems.length, - paths: eventItems.map((item) => item.path), - items: eventItems, - totalBytes, - valuesPrinted: false, - }, - }; -} - -function assembleInitialPrompt(promptRefs: MaterializedPromptRef[], skillRefs: MaterializedSkillRef[]): InitialPromptAssembly | undefined { - if (promptRefs.length === 0 && skillRefs.length === 0) return undefined; +function assembleInitialPrompt(promptRefs: MaterializedPromptRef[], skills: MaterializedSkillRef[]): InitialPromptAssembly | undefined { + if (promptRefs.length === 0 && skills.length === 0) return undefined; const sections: string[] = [ - "AgentRun initial runtime instructions. These instructions are assembled from ResourceBundleRef promptRefs and skillRefs for the first thread-start turn only.", + "AgentRun initial runtime instructions. These instructions are assembled from ResourceBundleRef promptRefs and gitbundle skill directories for the first thread-start turn only.", ]; for (const prompt of promptRefs) { sections.push([`## Resource Prompt: ${prompt.name}`, `path: ${prompt.path}`, prompt.text].join("\n")); } - if (skillRefs.length > 0) { + if (skills.length > 0) { const lines = [ "## Resource Skills", "The following required runtime skills are mounted in the current workspace. Use these bundle skills instead of default model skill guesses.", - ...skillRefs.map((skill) => `- ${skill.name}: ${skill.summary || "No summary provided."} manifest=.agents/skills/${skill.aggregateAs}/SKILL.md source=${skill.path} required=${skill.required}`), + ...skills.map((skill) => `- ${skill.name}: ${skill.summary || "No summary provided."} manifest=.agents/skills/${skill.aggregateAs}/SKILL.md source=${skill.path} required=${skill.required}`), ]; sections.push(lines.join("\n")); } const text = sections.join("\n\n"); const bytes = Buffer.byteLength(text, "utf8"); - if (bytes > maxInitialPromptBytes) throw new AgentRunError("prompt-too-large", "assembled initial prompt exceeds the total size limit", { httpStatus: 400, details: { bytes, maxInitialPromptBytes, promptRefCount: promptRefs.length, skillRefCount: skillRefs.length, valuesPrinted: false } }); + if (bytes > maxInitialPromptBytes) throw new AgentRunError("prompt-too-large", "assembled initial prompt exceeds the total size limit", { httpStatus: 400, details: { bytes, maxInitialPromptBytes, promptRefCount: promptRefs.length, skillCount: skills.length, valuesPrinted: false } }); return { text, summary: { @@ -238,8 +276,8 @@ function assembleInitialPrompt(promptRefs: MaterializedPromptRef[], skillRefs: M sha256: sha256Text(text), promptRefCount: promptRefs.length, promptRefNames: promptRefs.map((item) => item.name), - skillRefCount: skillRefs.length, - skillRefNames: skillRefs.map((item) => item.name), + skillCount: skills.length, + skillNames: skills.map((item) => item.name), valuesPrinted: false, }, }; @@ -269,25 +307,6 @@ function fileErrorSummary(error: unknown): JsonRecord { return { code: typeof record.code === "string" ? record.code : null, message: typeof record.message === "string" ? redactText(record.message).slice(0, 300) : null }; } -function aliasWrapper(kind: string, target: string): string { - if (kind === "node-script") return `#!/usr/bin/env sh\n# agentrun-resource-alias-wrapper\nexec node ${shellArg(target)} "$@"\n`; - if (kind === "bun-script") return `#!/usr/bin/env sh\n# agentrun-resource-alias-wrapper\nexec bun ${shellArg(target)} "$@"\n`; - if (kind === "sh-script") return `#!/usr/bin/env sh\n# agentrun-resource-alias-wrapper\nexec sh ${shellArg(target)} "$@"\n`; - return `#!/usr/bin/env sh\n# agentrun-resource-alias-wrapper\nexec ${shellArg(target)} "$@"\n`; -} - -async function assertAliasWrapperWritable(wrapper: string, name: string): Promise { - try { - const existing = await readFile(wrapper, "utf8"); - if (existing.includes("agentrun-resource-alias-wrapper")) return; - throw new AgentRunError("schema-invalid", `resource bundle tool alias ${name} would overwrite an existing command`, { httpStatus: 409, details: { wrapper: pathSummary(wrapper) } }); - } catch (error) { - if (error instanceof AgentRunError) throw error; - if (error && typeof error === "object" && "code" in error && (error as { code?: unknown }).code === "ENOENT") return; - throw error; - } -} - async function git(args: string[], cwd: string, options: { allowFailure?: boolean } = {}): Promise<{ stdout: string; stderr: string }> { const child = spawn("git", args, { cwd, stdio: ["ignore", "pipe", "pipe"] }); let stdout = ""; @@ -308,11 +327,6 @@ async function git(args: string[], cwd: string, options: { allowFailure?: boolea return { stdout, stderr }; } -function resolveWorkspacePath(checkoutPath: string, subdir: string | undefined): string { - if (!subdir) return checkoutPath; - return resolveBundlePath(checkoutPath, subdir, "resourceBundleRef.subdir"); -} - function resolveBundlePath(checkoutPath: string, relativePath: string, fieldName: string): string { const resolved = path.resolve(checkoutPath, relativePath); const root = path.resolve(checkoutPath); @@ -320,17 +334,13 @@ function resolveBundlePath(checkoutPath: string, relativePath: string, fieldName return resolved; } -function resolveWorkspaceFilePath(workspacePath: string, relativePath: string, fieldName: string): string { +function resolveWorkspaceTargetPath(workspacePath: string, relativePath: string, fieldName: string): string { const resolved = path.resolve(workspacePath, relativePath); const root = path.resolve(workspacePath); if (resolved === root || !resolved.startsWith(`${root}${path.sep}`)) throw new AgentRunError("schema-invalid", `${fieldName} escaped workspace`, { httpStatus: 400 }); return resolved; } -function shellArg(value: string): string { - return `'${value.replace(/'/gu, `'"'"'`)}'`; -} - function pathSummary(value: string): JsonRecord { const parts = value.split(/[\\/]+/u).filter(Boolean); return { absolute: path.isAbsolute(value), basename: parts.at(-1) ?? null, depth: parts.length, fingerprint: stableHash(value).slice(0, 16), valuePrinted: false }; diff --git a/src/runner/run-once.ts b/src/runner/run-once.ts index 0833d09..7b7cdd4 100644 --- a/src/runner/run-once.ts +++ b/src/runner/run-once.ts @@ -95,7 +95,7 @@ export async function runOnce(options: RunnerOnceOptions): Promise { if (!materializationAttempted) { materializationAttempted = true; try { - const materialized = await materializeResourceBundle(claimed.resourceBundleRef ?? null, options.env ?? process.env); + const materialized = await materializeResourceBundle(claimed.resourceBundleRef ?? null, resourceMaterializationEnv(options.env ?? process.env, options.runId, attemptId)); if (materialized) { workspacePath = materialized.workspacePath; resourceEnv = resourceEnvForMaterialized(options.env ?? process.env, materialized); @@ -145,6 +145,10 @@ function withResourceAssembly(options: RunnerOnceOptions, resourceEnv: NodeJS.Pr }; } +function resourceMaterializationEnv(env: NodeJS.ProcessEnv, runId: string, attemptId: string): NodeJS.ProcessEnv { + return { ...env, AGENTRUN_RUN_ID: env.AGENTRUN_RUN_ID ?? runId, AGENTRUN_ATTEMPT_ID: env.AGENTRUN_ATTEMPT_ID ?? attemptId }; +} + function resourceEnvForMaterialized(env: NodeJS.ProcessEnv, materialized: Awaited>): NodeJS.ProcessEnv | undefined { if (!materialized) return undefined; let next: NodeJS.ProcessEnv | undefined; diff --git a/src/selftest/cases/50-hwlab-manual-dispatch.ts b/src/selftest/cases/50-hwlab-manual-dispatch.ts index b342057..0a74185 100644 --- a/src/selftest/cases/50-hwlab-manual-dispatch.ts +++ b/src/selftest/cases/50-hwlab-manual-dispatch.ts @@ -7,12 +7,11 @@ import { startManagerServer } from "../../mgr/server.js"; import { ManagerClient } from "../../mgr/client.js"; import { MemoryAgentRunStore } from "../../mgr/store.js"; import { runOnce } from "../../runner/run-once.js"; -import { stableHash } from "../../common/validation.js"; import type { JsonRecord, ResourceBundleRef } from "../../common/types.js"; import { assertNoSecretLeak, type SelfTestCase, type SelfTestContext } from "../harness.js"; const execFile = promisify(execFileCallback); -type LocalBundle = { repoUrl: string; commitId: string; toolAliases?: ResourceBundleRef["toolAliases"]; promptRefs?: ResourceBundleRef["promptRefs"]; skillRefs?: ResourceBundleRef["skillRefs"]; workspaceFiles?: ResourceBundleRef["workspaceFiles"] }; +type LocalBundle = { repoUrl: string; commitId: string; bundles?: ResourceBundleRef["bundles"]; promptRefs?: ResourceBundleRef["promptRefs"] }; const selfTest: SelfTestCase = async (context) => { const containerfile = await readFile(path.join(context.root, "deploy/container/Containerfile"), "utf8"); @@ -49,10 +48,6 @@ console.log(JSON.stringify({ apiVersion: manifest.apiVersion, kind: manifest.kin const assemblyBundle: LocalBundle = { ...bundle, promptRefs: [{ name: "hwlab-v02-runtime", path: "internal/agent/prompts/hwlab-v02-runtime.md", inject: "thread-start", required: true }], - skillRefs: [ - { name: "hwpod-cli", path: "skills/hwpod-cli/SKILL.md", required: true, aggregateAs: "hwpod-cli" }, - { name: "hwpod-ctl", path: "skills/hwpod-ctl/SKILL.md", required: true, aggregateAs: "hwpod-ctl" }, - ], }; const first = await createHwlabRun(client, context, bundle, "hwlab-session-1", "hello bundle", "hwlab-command-1"); const created = await client.post(`/api/v1/runs/${first.runId}/runner-jobs`, { commandId: first.commandId, idempotencyKey: "hwlab-trace-1" }) as JsonRecord; @@ -66,7 +61,6 @@ console.log(JSON.stringify({ apiVersion: manifest.apiVersion, kind: manifest.kin ); const manifest = JSON.parse(await readFile(createdManifest, "utf8")) as JsonRecord; assert.ok(JSON.stringify(manifest).includes("AGENTRUN_RESOURCE_BUNDLE_JSON")); - assert.equal(runnerEnvValue(manifest, "AGENTRUN_RESOURCE_BIN_PATH"), "/usr/local/bin"); assert.ok(JSON.stringify(manifest).includes("/opt/agentrun/deploy/runtime/boot/agentrun-runner.sh")); assert.ok(JSON.stringify(manifest).includes("AGENTRUN_BOOT_COMMIT")); assertNoSecretLeak(created); @@ -84,16 +78,8 @@ console.log(JSON.stringify({ apiVersion: manifest.apiVersion, kind: manifest.kin ); const sessionRun = await createHwlabRun(client, context, bundle, "hwlab-session-resume", "hello session", "hwlab-command-session"); - const resourceBin = path.join(context.tmp, "resource-bin"); - const runResult = await runOnce({ managerUrl: server.baseUrl, runId: sessionRun.runId, codexCommand: context.fakeCodexCommand, codexArgs: context.fakeCodexArgs, codexHome: context.codexHome, env: { CODEX_HOME: context.codexHome, AGENTRUN_WORKSPACE_ROOT: path.join(context.tmp, "workspaces"), AGENTRUN_RESOURCE_BIN_PATH: resourceBin }, oneShot: true }); + const runResult = await runOnce({ managerUrl: server.baseUrl, runId: sessionRun.runId, codexCommand: context.fakeCodexCommand, codexArgs: context.fakeCodexArgs, codexHome: context.codexHome, env: { CODEX_HOME: context.codexHome, AGENTRUN_WORKSPACE_ROOT: path.join(context.tmp, "workspaces") }, oneShot: true }); assert.equal(runResult.terminalStatus, "completed"); - const hwpod = await execFile(path.join(resourceBin, "hwpod"), ["profile", "list"]); - assert.match(hwpod.stdout, /"argv":\["profile","list"\]/u); - await writeFile(path.join(resourceBin, "blocked"), "#!/usr/bin/env sh\necho existing\n", "utf8"); - const blockedRun = await createHwlabRun(client, context, { ...bundle, toolAliases: [{ name: "blocked", path: "tools/hwpod-cli.mjs", kind: "node-script" }] }, "hwlab-session-blocked-alias", "blocked alias", "hwlab-command-blocked-alias"); - const blockedResult = await runOnce({ managerUrl: server.baseUrl, runId: blockedRun.runId, codexCommand: context.fakeCodexCommand, codexArgs: context.fakeCodexArgs, codexHome: context.codexHome, env: { CODEX_HOME: context.codexHome, AGENTRUN_WORKSPACE_ROOT: path.join(context.tmp, "workspaces-blocked"), AGENTRUN_RESOURCE_BIN_PATH: resourceBin }, oneShot: true }); - assert.equal(blockedResult.terminalStatus, "blocked"); - assert.equal(blockedResult.failureKind, "schema-invalid"); const session = await store.getSession("hwlab-session-resume"); assert.equal(session?.threadId, "thread_selftest_1"); const resultEnvelope = await client.get(`/api/v1/runs/${sessionRun.runId}/commands/${sessionRun.commandId}/result`) as JsonRecord; @@ -101,26 +87,14 @@ console.log(JSON.stringify({ apiVersion: manifest.apiVersion, kind: manifest.kin assert.equal(resultEnvelope.reply, "fake codex stdio reply"); assert.equal(((resultEnvelope.sessionRef as JsonRecord).threadId), "thread_selftest_1"); assert.equal(((resultEnvelope.resourceBundleRef as JsonRecord).commitId), bundle.commitId); - assert.deepEqual(((resultEnvelope.resourceBundleRef as JsonRecord).toolAliases as JsonRecord).names, ["hwpod"]); + assert.equal(((resultEnvelope.resourceBundleRef as JsonRecord).kind), "gitbundle"); + const resultBundleTargets = (((resultEnvelope.resourceBundleRef as JsonRecord).bundles as JsonRecord).items as JsonRecord[]).map((item) => item.targetPath); + assert.deepEqual(resultBundleTargets, ["tools", ".agents/skills"]); const materialized = ((resultEnvelope.resourceBundleRef as JsonRecord).materialized as JsonRecord); - assert.deepEqual(((materialized.toolAliases as JsonRecord).names), ["hwpod"]); + assert.deepEqual(((materialized.tools as JsonRecord).names), ["hwpod"]); + assert.deepEqual(((materialized.skillDirs as JsonRecord).names), ["hwpod-cli", "hwpod-ctl"]); assertNoSecretLeak(resultEnvelope); - const seededRun = await createHwlabRun(client, context, { ...bundle, workspaceFiles: [{ path: ".hwlab/hwpod-spec.yaml", content: "apiVersion: hwlab.dev/v0alpha1\nkind: Hwpod\n", encoding: "utf8" }] }, "hwlab-session-seeded", "inspect seeded spec", "hwlab-command-seeded"); - const seededRoot = path.join(context.tmp, "workspaces-seeded"); - const seededResult = await runOnce({ managerUrl: server.baseUrl, runId: seededRun.runId, commandId: seededRun.commandId, codexCommand: context.fakeCodexCommand, codexArgs: context.fakeCodexArgs, codexHome: context.codexHome, env: { CODEX_HOME: context.codexHome, AGENTRUN_WORKSPACE_ROOT: seededRoot }, oneShot: true }) as JsonRecord; - assert.equal(seededResult.terminalStatus, "completed"); - const seededEnvelope = await client.get(`/api/v1/runs/${seededRun.runId}/commands/${seededRun.commandId}/result`) as JsonRecord; - const seededResource = seededEnvelope.resourceBundleRef as JsonRecord; - assert.deepEqual(((seededResource.workspaceFiles as JsonRecord).paths), [".hwlab/hwpod-spec.yaml"]); - const seededMaterialized = seededResource.materialized as JsonRecord; - const seededWorkspaceFiles = seededMaterialized.workspaceFiles as JsonRecord; - assert.equal(seededWorkspaceFiles.count, 1); - assert.deepEqual(seededWorkspaceFiles.paths, [".hwlab/hwpod-spec.yaml"]); - assert.equal(JSON.stringify(seededWorkspaceFiles).includes("apiVersion"), false); - const seededWorkspace = path.join(seededRoot, stableHash({ repoUrl: bundle.repoUrl, commitId: bundle.commitId }).slice(0, 16)); - assert.equal(await readTextIfExists(path.join(seededWorkspace, ".hwlab", "hwpod-spec.yaml")), "apiVersion: hwlab.dev/v0alpha1\nkind: Hwpod\n"); - const assemblyRun = await createHwlabRun(client, context, assemblyBundle, "hwlab-session-assembly", "list visible bundle skills without tools", "hwlab-command-assembly-1"); const assemblyInputFile = path.join(context.tmp, "fake-codex-turn-input-assembly.jsonl"); const assemblyRunner = runOnce({ managerUrl: server.baseUrl, runId: assemblyRun.runId, commandId: assemblyRun.commandId, codexCommand: context.fakeCodexCommand, codexArgs: context.fakeCodexArgs, codexHome: context.codexHome, env: { CODEX_HOME: context.codexHome, AGENTRUN_WORKSPACE_ROOT: path.join(context.tmp, "workspaces-assembly"), AGENTRUN_FAKE_CODEX_TURN_INPUT_FILE: assemblyInputFile }, idleTimeoutMs: 500, pollIntervalMs: 50 }); @@ -150,10 +124,11 @@ console.log(JSON.stringify({ apiVersion: manifest.apiVersion, kind: manifest.kin const assemblyEnvelope = await client.get(`/api/v1/runs/${assemblyRun.runId}/commands/${assemblyRun.commandId}/result`) as JsonRecord; const assemblyResource = assemblyEnvelope.resourceBundleRef as JsonRecord; assert.deepEqual(((assemblyResource.promptRefs as JsonRecord).names), ["hwlab-v02-runtime"]); - assert.deepEqual(((assemblyResource.skillRefs as JsonRecord).names), ["hwpod-cli", "hwpod-ctl"]); + const assemblyBundleTargets = ((assemblyResource.bundles as JsonRecord).items as JsonRecord[]).map((item) => item.targetPath); + assert.deepEqual(assemblyBundleTargets, ["tools", ".agents/skills"]); const assemblyMaterialized = assemblyResource.materialized as JsonRecord; assert.deepEqual(((assemblyMaterialized.promptRefs as JsonRecord).names), ["hwlab-v02-runtime"]); - assert.deepEqual(((assemblyMaterialized.skillRefs as JsonRecord).names), ["hwpod-cli", "hwpod-ctl"]); + assert.deepEqual(((assemblyMaterialized.skillDirs as JsonRecord).names), ["hwpod-cli", "hwpod-ctl"]); assert.equal(((assemblyMaterialized.initialPrompt as JsonRecord).available), true); assertNoSecretLeak(assemblyEnvelope); @@ -162,11 +137,6 @@ console.log(JSON.stringify({ apiVersion: manifest.apiVersion, kind: manifest.kin assert.equal(missingPromptResult.terminalStatus, "blocked"); assert.equal(missingPromptResult.failureKind, "prompt-unavailable"); - const missingSkillRun = await createHwlabRun(client, context, { ...bundle, skillRefs: [{ name: "missing-skill", path: "skills/missing-skill/SKILL.md", required: true }] }, "hwlab-session-missing-skill", "missing skill", "hwlab-command-missing-skill"); - const missingSkillResult = await runOnce({ managerUrl: server.baseUrl, runId: missingSkillRun.runId, codexCommand: context.fakeCodexCommand, codexArgs: context.fakeCodexArgs, codexHome: context.codexHome, env: { CODEX_HOME: context.codexHome, AGENTRUN_WORKSPACE_ROOT: path.join(context.tmp, "workspaces-missing-skill") }, oneShot: true }) as JsonRecord; - assert.equal(missingSkillResult.terminalStatus, "blocked"); - assert.equal(missingSkillResult.failureKind, "skill-unavailable"); - const resumed = await createHwlabRun(client, context, bundle, "hwlab-session-resume", "hello resumed", "hwlab-command-session-resumed"); const resumedRun = await client.get(`/api/v1/runs/${resumed.runId}`) as JsonRecord; assert.equal(((resumedRun.sessionRef as JsonRecord).threadId), "thread_selftest_1"); @@ -225,7 +195,7 @@ console.log(JSON.stringify({ apiVersion: manifest.apiVersion, kind: manifest.kin const runningResult = await running; assert.equal(runningResult.terminalStatus, "cancelled"); - return { name: "hwlab-manual-dispatch", tests: ["runner-job-idempotency", "pending-cancel", "result-envelope", "session-ref-resume", "resource-bundle-materialization", "resource-bundle-tool-alias", "resource-bundle-workspace-files", "resource-prompt-skill-assembly", "resource-prompt-skill-required-blockers", "same-run-runner-multiturn", "running-steer", "running-cancel"] }; + return { name: "hwlab-manual-dispatch", tests: ["runner-job-idempotency", "pending-cancel", "result-envelope", "session-ref-resume", "resource-gitbundle-materialization", "gitbundle-tools-path", "gitbundle-skill-dir-assembly", "resource-prompt-required-blocker", "same-run-runner-multiturn", "running-steer", "running-cancel"] }; } finally { await new Promise((resolve) => server.server.close(() => resolve())); } @@ -237,6 +207,7 @@ async function createLocalGitBundle(context: SelfTestContext): Promise { - const toolAliases = bundle.toolAliases ?? [{ name: "hwpod", path: "tools/hwpod-cli.mjs", kind: "node-script" }]; - const resourceBundleRef: ResourceBundleRef = { kind: "git", repoUrl: bundle.repoUrl, commitId: bundle.commitId, toolAliases, submodules: false, lfs: false }; + const resourceBundleRef: ResourceBundleRef = { kind: "gitbundle", repoUrl: bundle.repoUrl, commitId: bundle.commitId, bundles: bundle.bundles ?? defaultGitBundles(), submodules: false, lfs: false }; if (bundle.promptRefs) resourceBundleRef.promptRefs = bundle.promptRefs; - if (bundle.skillRefs) resourceBundleRef.skillRefs = bundle.skillRefs; - if (bundle.workspaceFiles) resourceBundleRef.workspaceFiles = bundle.workspaceFiles; const run = await client.post("/api/v1/runs", { tenantId: "hwlab", projectId: "pikasTech/HWLAB", @@ -299,6 +267,13 @@ async function createHwlabRun(client: ManagerClient, context: SelfTestContext, b return { runId: run.id, commandId: command.id }; } +function defaultGitBundles(): ResourceBundleRef["bundles"] { + return [ + { name: "hwlab-tools", subpath: "tools", targetPath: "tools" }, + { name: "hwlab-agent-skills", subpath: "skills", targetPath: ".agents/skills" }, + ]; +} + async function waitForCommandState(client: ManagerClient, runId: string, commandId: string, state: string): Promise { const deadline = Date.now() + 5_000; while (Date.now() < deadline) { diff --git a/src/selftest/cases/60-hwlab-baseline-contract.ts b/src/selftest/cases/60-hwlab-baseline-contract.ts index 17072fa..3993443 100644 --- a/src/selftest/cases/60-hwlab-baseline-contract.ts +++ b/src/selftest/cases/60-hwlab-baseline-contract.ts @@ -167,7 +167,7 @@ async function assertResourceBundleFailure(client: ManagerClient, context: SelfT const repo = await createLocalGitRepo(context); const run = await client.post("/api/v1/runs", { ...runPayload(context, "codex", "selftest-bad-bundle-session"), - resourceBundleRef: { kind: "git", repoUrl: repo.repoUrl, commitId: "0000000000000000000000000000000000000000", submodules: false, lfs: false }, + resourceBundleRef: { kind: "gitbundle", repoUrl: repo.repoUrl, commitId: "0000000000000000000000000000000000000000", bundles: [{ name: "tools", subpath: "tools", targetPath: "tools" }], submodules: false, lfs: false }, }) as { id: string }; const command = await client.post(`/api/v1/runs/${run.id}/commands`, { type: "turn", payload: { prompt: "bad bundle" }, idempotencyKey: "selftest-bad-bundle" }) as { id: string }; const result = await runOnce({ managerUrl, runId: run.id, commandId: command.id, codexCommand: context.fakeCodexCommand, codexArgs: context.fakeCodexArgs, codexHome: context.codexHome, env: { CODEX_HOME: context.codexHome, AGENTRUN_WORKSPACE_ROOT: path.join(context.tmp, "bad-bundle-workspaces") }, oneShot: true }) as JsonRecord;