runtime: formalize required tools contract (#708)

* runtime: switch default base image to holon-base v0.1.0

* runtime: formalize required tools contract

- add built-in runtime tools contract and installer script generator
- refactor composed image build to use contract-driven install with fail-fast verification
- add runtime tools contract docs and unit tests
- remove old inline node-major parsing/install path from runtime build

* runtime: address review feedback for tools installer

- fix fd download URL/version to avoid 404 in integration builds
- remove mutable exported required tools slice
- add dnf/yum cache cleanup and include ripgrep in yum path
- restore gh-webhook extension install (best effort)
- avoid Dockerfile heredoc dependency by copying installer script file
- align plan doc required list wording with command-based contract

* runtime: pin yq version for deterministic builds

Use a fixed yq release URL instead of latest to avoid non-deterministic composed image builds.

* runtime: add apt retry for integration stability

Mitigate transient apt mirror 5xx in ubuntu-based integration flows by retrying apt-get update/install with Acquire::Retries.

* runtime: require Node 20+ in composed image

Fix integration failure in solve-matrix-pr-fix-flow caused by legacy Node from ubuntu:22.04 package repos. Ensure Node 20+ via NodeSource when needed.

---------

Co-authored-by: jolestar <host-user@example.com>

Author: jolestar

cmd/holon/runner_test.go

@@ -10,6 +10,7 @@ import (
 	"testing"
 	"time"
 
+	"github.com/holon-run/holon/pkg/image"
 	"github.com/holon-run/holon/pkg/runtime/docker"
 )
 
@@ -703,8 +704,8 @@ func TestRunner_Integration(t *testing.T) {
 	mockRuntime := &MockRuntime{
 		RunHolonFunc: func(ctx context.Context, cfg *docker.ContainerConfig) (string, error) {
 			// Verify all expected values are in the config
-			if cfg.BaseImage != "golang:1.22" {
-				t.Errorf("Expected BaseImage to be 'golang:1.22', got %q", cfg.BaseImage)
+			if cfg.BaseImage != image.DefaultImage {
+				t.Errorf("Expected BaseImage to be %q, got %q", image.DefaultImage, cfg.BaseImage)
 			}
 			if cfg.AgentBundle == "" {
 				t.Errorf("Expected AgentBundle to be set")
@@ -756,7 +757,7 @@ func TestRunner_Integration(t *testing.T) {
 		WorkspacePath: workspaceDir,
 		ContextPath:   contextDir,
 		OutDir:        outDir,
-		BaseImage:     "golang:1.22",
+		BaseImage:     image.DefaultImage,
 		AgentBundle:   bundlePath,
 		AgentHome:     t.TempDir(),
 		RoleName:      "coder",

docs/runtime-tools-contract-plan.md

@@ -0,0 +1,113 @@
+# Runtime Tools Contract 重构方案
+
+## 1. 背景与问题
+
+当前 `buildComposedImageFromBundle` 在 `pkg/runtime/docker/runtime.go` 内部内联了工具安装逻辑（Node、git、gh、gh-webhook 等），存在几个问题：
+
+1. 工具契约是隐式的，没有正式定义哪些工具是必须有的。
+2. 安装逻辑硬编码在字符串 Dockerfile 中，维护成本高，扩展困难。
+3. 当前 required tools 列表未正式化，难以作为稳定契约演进。
+4. 缺少正式契约导致工具保证边界不清晰，出现运行时不确定性。
+
+## 2. 目标
+
+1. 定义正式的 Runtime Tools Contract（仅 required）。
+2. 将 composed image 构建流程改为“内置契约驱动”，由 Holon 内部维护 required tools 列表。
+3. 保持默认行为可用：始终使用内置默认 required tools。
+4. 通过 fail-fast 明确缺失工具，降低运行时不确定性。
+
+## 3. 非目标
+
+1. 不在本阶段实现“容器启动后在线安装工具”。
+2. 不在本阶段支持所有包管理器生态（先覆盖 apt/dnf/yum）。
+3. 不在本阶段做复杂版本求解（先支持固定版本/latest）。
+4. 不为契约提供项目级配置或 CLI 覆盖能力。
+
+## 4. 契约定义（v1）
+
+新增文档：`docs/runtime-tools-contract.md`（后续实现时补齐）
+
+契约只维护一个 `required` 列表（v1，按命令名定义）：
+
+- `bash`, `git`, `curl`, `jq`, `rg`, `find`, `sed`, `awk`, `xargs`
+- `tar`, `gzip`, `unzip`
+- `python3`
+- `node`, `npm`
+- `gh`
+- `yq`
+- `fd`（Ubuntu 实际包通常为 `fdfind`，需做命令别名）
+- `make`, `patch`
+
+## 5. 配置模型
+
+不提供用户配置入口。工具契约由 Holon 内部固定维护（代码内置常量 + 文档）。
+
+## 6. 代码重构设计
+
+## 6.1 新增模块
+
+新增 `pkg/runtime/tools`（建议）：
+
+1. `contract.go`
+- 定义 `ToolContract`, `ToolSpec`。
+- 提供内置 `required` 列表（单一事实来源）。
+
+2. `resolver.go`
+- 根据基础镜像可用包管理器生成安装计划 `InstallPlan`。
+
+3. `installer_script.go`
+- 生成安装脚本片段（apt/dnf/yum）。
+- 处理 `fd`/`fdfind` 兼容和软链。
+
+## 6.2 `buildComposedImageFromBundle` 重构点
+
+将 `runtime.go` 中当前内联 Dockerfile 拼接拆为：
+
+1. 读取内置 tools contract（单一来源）。
+2. 生成安装计划（仅 required）。
+3. 生成结构化 Dockerfile 片段：
+- base setup
+- install required tools（失败即退出）
+- 解包 agent bundle
+4. 保持现有镜像 tag 计算方式和缓存语义不变。
+
+## 7. 失败策略
+
+1. required tools 安装失败：构建失败，报明确错误。
+2. 无支持包管理器：如果 required 中有未满足项，则失败并输出缺失列表。
+
+## 8. 测试计划
+
+### 8.1 单元测试
+
+1. contract 常量与解析测试（内置 required 列表）
+2. install plan 测试（apt/dnf/yum/unknown）
+3. installer script 生成测试（required 安装路径）
+4. required 缺失时报错信息测试
+
+### 8.2 集成测试
+
+1. 默认内置契约下 composed image 构建成功
+2. required tools 缺失时自动安装（支持包管理器）
+3. 故意注入不存在工具时 required fail-fast（测试桩）
+
+## 9. 迁移与兼容策略
+
+本次按“无兼容包袱”执行（项目尚未正式发布）：
+
+1. 保留旧逻辑仅作为过渡分支内实现细节，不保留外部行为承诺。
+2. 文档统一切换到 Runtime Tools Contract 概念。
+3. 相关 prompt/skills 文档改为依赖内置 required 契约，不再引用能力文件。
+
+## 10. 实施分解
+
+1. 第一步：落地 contract 数据结构和内置 required 列表
+2. 第二步：重构 composed image 构建为内置契约驱动安装
+3. 第三步：文档与 prompt 更新，补齐 e2e 用例
+
+## 11. 验收标准
+
+1. `run/solve/serve` 在默认契约下行为稳定且可重复。
+2. 自定义镜像场景下，Holon 根据内置 required 列表自动补齐（在支持的包管理器上）。
+3. required 不满足时 fail-fast，错误信息可诊断。
+4. CI 覆盖 required 的成功与失败路径。

docs/runtime-tools-contract.md

@@ -0,0 +1,40 @@
+# Runtime Tools Contract
+
+This document defines Holon's built-in runtime tools contract.
+
+## Scope
+
+- This contract is internal to Holon runtime.
+- It has no project-level config and no CLI override.
+- Custom images can preinstall these tools; Holon still verifies and installs missing tools during composed-image build.
+
+## Required Tools
+
+The following commands are required in runtime containers:
+
+- `bash`
+- `git`
+- `curl`
+- `jq`
+- `rg`
+- `find`
+- `sed`
+- `awk`
+- `xargs`
+- `tar`
+- `gzip`
+- `unzip`
+- `python3`
+- `node` (20+)
+- `npm`
+- `gh`
+- `yq`
+- `fd`
+- `make`
+- `patch`
+
+## Behavior
+
+- Holon installs missing required tools when building composed images.
+- Supported package-manager families: `apt-get`, `dnf`, `yum`.
+- If required tools cannot be ensured, build fails fast with a clear missing-tools error.

pkg/config/config_test.go

@@ -4,6 +4,8 @@ import (
 	"os"
 	"path/filepath"
 	"testing"
+
+	"github.com/holon-run/holon/pkg/image"
 )
 
 func TestLoad_NoConfigFile(t *testing.T) {
@@ -200,24 +202,24 @@ func TestResolveBaseImage(t *testing.T) {
 			name:         "CLI overrides config",
 			baseImage:    "python:3.11",
 			cliValue:     "node:20",
-			defaultValue: "golang:1.22",
+			defaultValue: image.DefaultImage,
 			wantValue:    "node:20",
 			wantSource:   "cli",
 		},
 		{
 			name:         "Config overrides default",
 			baseImage:    "python:3.11",
 			cliValue:     "",
-			defaultValue: "golang:1.22",
+			defaultValue: image.DefaultImage,
 			wantValue:    "python:3.11",
 			wantSource:   "config",
 		},
 		{
 			name:         "Default when no CLI or config",
 			baseImage:    "",
 			cliValue:     "",
-			defaultValue: "golang:1.22",
-			wantValue:    "golang:1.22",
+			defaultValue: image.DefaultImage,
+			wantValue:    image.DefaultImage,
 			wantSource:   "default",
 		},
 	}

pkg/image/detect.go

@@ -14,7 +14,7 @@ import (
 )
 
 // DefaultImage is the fallback Docker image used when no language signal is detected.
-const DefaultImage = "golang:1.22"
+const DefaultImage = "ghcr.io/holon-run/holon-base:0.1.0"
 
 // Detector detects the appropriate Docker base image for a workspace.
 type Detector struct {
@@ -82,7 +82,7 @@ func (d *Detector) Detect() *DetectResult {
 		return &DetectResult{
 			Image:     DefaultImage,
 			Signals:   []string{},
-			Rationale: "No language signals detected, using default Go image",
+			Rationale: "No language signals detected, using default base image",
 		}
 	}
 
@@ -146,7 +146,7 @@ func (d *Detector) DetectDebug() *DebugDetectResult {
 		result = &DetectResult{
 			Image:     DefaultImage,
 			Signals:   []string{},
-			Rationale: "No language signals detected, using default Go image",
+			Rationale: "No language signals detected, using default base image",
 		}
 	} else {
 		bestSignal := d.scoreSignals(signals)

pkg/image/detect_test.go

@@ -151,8 +151,8 @@ func TestDetect_NoSignal(t *testing.T) {
 	createFile(t, dir, "README.md", "# Test\n")
 
 	result := Detect(dir)
-	if result.Image != "golang:1.22" {
-		t.Errorf("Expected default golang:1.22, got %s", result.Image)
+	if result.Image != DefaultImage {
+		t.Errorf("Expected default %s, got %s", DefaultImage, result.Image)
 	}
 	if len(result.Signals) != 0 {
 		t.Errorf("Expected no signals, got %v", result.Signals)
@@ -170,8 +170,8 @@ func TestDetect_SkipsNodeModules(t *testing.T) {
 
 	result := Detect(dir)
 	// Should return default, not node:22
-	if result.Image != "golang:1.22" {
-		t.Errorf("Expected default golang:1.22 (node_modules should be skipped), got %s", result.Image)
+	if result.Image != DefaultImage {
+		t.Errorf("Expected default %s (node_modules should be skipped), got %s", DefaultImage, result.Image)
 	}
 }
 
@@ -186,8 +186,8 @@ func TestDetect_SkipsVendor(t *testing.T) {
 
 	result := Detect(dir)
 	// Should return default, not golang:1.23
-	if result.Image != "golang:1.22" {
-		t.Errorf("Expected default golang:1.22 (vendor should be skipped), got %s", result.Image)
+	if result.Image != DefaultImage {
+		t.Errorf("Expected default %s (vendor should be skipped), got %s", DefaultImage, result.Image)
 	}
 }
 
@@ -203,8 +203,8 @@ func TestDetect_SkipsHiddenFiles(t *testing.T) {
 
 	result := Detect(dir)
 	// Should return default, not node:22
-	if result.Image != "golang:1.22" {
-		t.Errorf("Expected default golang:1.22 (hidden files should be skipped), got %s", result.Image)
+	if result.Image != DefaultImage {
+		t.Errorf("Expected default %s (hidden files should be skipped), got %s", DefaultImage, result.Image)
 	}
 }
 
@@ -250,11 +250,11 @@ func TestFormatResult(t *testing.T) {
 		{
 			name: "no signals",
 			result: &DetectResult{
-				Image:     "golang:1.22",
+				Image:     DefaultImage,
 				Signals:   []string{},
-				Rationale: "No language signals detected, using default Go image",
+				Rationale: "No language signals detected, using default base image",
 			},
-			expected: "Detected image: golang:1.22 (signals: none) - No language signals detected, using default Go image",
+			expected: "Detected image: " + DefaultImage + " (signals: none) - No language signals detected, using default base image",
 		},
 		{
 			name: "disabled",
@@ -684,8 +684,8 @@ func TestDetect_ScanMode_EmptyDirectory(t *testing.T) {
 	// Empty directory with no signals
 
 	result := Detect(dir)
-	if result.Image != "golang:1.22" {
-		t.Errorf("Expected default golang:1.22, got %s", result.Image)
+	if result.Image != DefaultImage {
+		t.Errorf("Expected default %s, got %s", DefaultImage, result.Image)
 	}
 
 	// Check scan mode - should be full-recursive (no root signals found)