From ce57a1603b6623a43b9dd8af9a6e2d2c88f2760d Mon Sep 17 00:00:00 2001 From: crispinhu Date: Thu, 19 Nov 2026 22:24:00 +0800 Subject: [PATCH 01/13] fix(runner): install the Linux Docker helper on macOS --- deploy/bind-cli.sh | 63 +++++++++++--- deploy/bind_cli_docker_runner_test.go | 117 ++++++++++++++++++++++++++ docs/deployment.md | 2 + internal/runner/daemon.go | 2 + internal/runner/update.go | 52 +++++++++--- internal/runner/update_test.go | 64 ++++++++++++++ internal/runtime/mcp_call.go | 21 +++-- 7 files changed, 290 insertions(+), 31 deletions(-) create mode 100644 deploy/bind_cli_docker_runner_test.go diff --git a/deploy/bind-cli.sh b/deploy/bind-cli.sh index a9d0233c2..d3bf6b696 100755 --- a/deploy/bind-cli.sh +++ b/deploy/bind-cli.sh @@ -25,7 +25,7 @@ # --uninstall 卸载:通知平台注销机器、停止服务、删除全部文件和配置 # # 默认直接从平台下载对应 OS/架构的二进制(由服务端 /runners/agentflow-runner 分发)。 -# 脚本安装 agentflow-runner 和跨沙箱 Gate MCP helper、写配置并启动 +# 脚本安装 agentflow-runner 和跨沙箱 Git/MCP、Gate MCP helper、写配置并启动 # daemon。Runner 仅向平台发起出站 HTTPS,不开放任何入站端口。 set -euo pipefail @@ -343,6 +343,7 @@ RUNNER_HOME="${HOME}/.agentflow-runner" ENV_FILE="${RUNNER_HOME}/env" STATE_FILE="${RUNNER_HOME}/state.json" BINARY="${BIN_DIR}/agentflow-runner" +DOCKER_RUNNER_BINARY="${BIN_DIR}/agentflow-runner-linux-${ARCH}" GATE_BINARY_PATTERN="${BIN_DIR}/agentflow-gate-mcp-{os}-{arch}" PLIST="${HOME}/Library/LaunchAgents/com.agentflow.runner.plist" UNIT="${HOME}/.config/systemd/user/agentflow-runner.service" @@ -421,6 +422,9 @@ if [[ "$UNINSTALL" == "1" ]]; then info "已清理 runner Docker 沙箱和临时镜像" fi rm -f "$BINARY" + if [[ "$OS" == "darwin" ]]; then + rm -f "$DOCKER_RUNNER_BINARY" + fi rm -f "${BIN_DIR}"/agentflow-gate-mcp-darwin-amd64 \ "${BIN_DIR}"/agentflow-gate-mcp-darwin-arm64 \ "${BIN_DIR}"/agentflow-gate-mcp-linux-amd64 \ @@ -537,6 +541,31 @@ case "$(printf '%s' "${AGENTFLOW_BROWSER:-}" | tr '[:upper:]' '[:lower:]')" in esac # ---------- 1. 安装二进制 ---------- +download_runner_binary() { + local target_os="$1" url + if [[ -n "$DOWNLOAD_URL" && ( "$target_os" == "$OS" || "$DOWNLOAD_URL" == *"{os}"* ) ]]; then + url="${DOWNLOAD_URL//\{os\}/$target_os}" + url="${url//\{arch\}/$ARCH}" + else + url="${SERVER}/runners/agentflow-runner?os=${target_os}&arch=${ARCH}" + fi + info "从 ${url} 下载 agentflow-runner(${target_os}/${ARCH})..." + curl -fsSL "$url" -o "$TEMP_BINARY" && [[ -s "$TEMP_BINARY" ]] +} + +build_runner_binary() { + local target_os="$1" source="$2" + info "从源码 ${source} 构建 agentflow-runner(${target_os}/${ARCH})..." + (cd "$source" && CGO_ENABLED=0 GOOS="$target_os" GOARCH="$ARCH" go build -o "$TEMP_BINARY" ./cmd/agentflow-runner) +} + +publish_runner_binary() { + [[ -s "$TEMP_BINARY" ]] || fail "下载或构建的 runner 二进制为空" + chmod +x "$TEMP_BINARY" + mv -f "$TEMP_BINARY" "$1" + TEMP_BINARY="" +} + install_binary() { mkdir -p "$BIN_DIR" TEMP_BINARY=$(mktemp "${BIN_DIR}/.agentflow-runner.XXXXXX") @@ -544,14 +573,10 @@ install_binary() { [[ -f "$LOCAL_BINARY" ]] || fail "本地二进制不存在: $LOCAL_BINARY" cp "$LOCAL_BINARY" "$TEMP_BINARY" elif [[ -n "$DOWNLOAD_URL" ]]; then - URL="${DOWNLOAD_URL//\{os\}/$OS}" - URL="${URL//\{arch\}/$ARCH}" - info "从 ${URL} 下载二进制..." - curl -fsSL "$URL" -o "$TEMP_BINARY" + download_runner_binary "$OS" else # 默认:平台直接分发对应 OS/架构的二进制,无需本机 Go 工具链。 - info "从 ${SERVER} 下载 agentflow-runner(${OS}/${ARCH})..." - if curl -fsSL "${SERVER}/runners/agentflow-runner?os=${OS}&arch=${ARCH}" -o "$TEMP_BINARY"; then + if download_runner_binary "$OS"; then : else # 平台未配置分发:回退到本地源码构建(--source 或当前目录为源码 checkout)。 @@ -564,15 +589,25 @@ install_binary() { 3) 本命令追加 --from <已编译的 agentflow-runner 二进制路径>" fi command -v go >/dev/null 2>&1 || fail "本机未安装 Go,无法从源码构建;请使用 --from 提供二进制" - info "从源码 ${SRC} 构建(${OS}/${ARCH})..." - (cd "$SRC" && CGO_ENABLED=0 GOOS="$OS" GOARCH="$ARCH" go build -o "$TEMP_BINARY" ./cmd/agentflow-runner) \ + build_runner_binary "$OS" "$SRC" \ || fail "源码构建失败;请检查 Go 版本(需 1.22+)或改用 --from" fi fi - [[ -s "$TEMP_BINARY" ]] || fail "下载或构建的 runner 二进制为空" - chmod +x "$TEMP_BINARY" - mv -f "$TEMP_BINARY" "$BINARY" + publish_runner_binary "$BINARY" +} + +install_docker_runner_binary() { + local source="${SOURCE_DIR:-$PWD}" + TEMP_BINARY=$(mktemp "${BIN_DIR}/.agentflow-runner.XXXXXX") + if download_runner_binary linux || + { [[ -d "$source/cmd/agentflow-runner" ]] && command -v go >/dev/null 2>&1 && + build_runner_binary linux "$source" && [[ -s "$TEMP_BINARY" ]]; }; then + publish_runner_binary "$DOCKER_RUNNER_BINARY" + return + fi + rm -f "$TEMP_BINARY" TEMP_BINARY="" + warn "无法获取 Linux/${ARCH} Git/MCP helper,Docker 工作区需要该文件:${DOCKER_RUNNER_BINARY}" } TEMP_BINARY="" @@ -597,11 +632,11 @@ install_gate_binary() { chmod +x "$target" } -# Host sandbox uses the native helper. Docker always uses Linux; on a macOS -# runner both artifacts are therefore required. +# Docker on macOS needs Linux versions of both the Gate MCP and Git/MCP helpers. install_gate_binary "$OS" "$ARCH" if [[ "$OS" != "linux" ]]; then install_gate_binary linux "$ARCH" + install_docker_runner_binary fi if [[ "$UPGRADE" == "1" ]]; then diff --git a/deploy/bind_cli_docker_runner_test.go b/deploy/bind_cli_docker_runner_test.go new file mode 100644 index 000000000..9c3899a1b --- /dev/null +++ b/deploy/bind_cli_docker_runner_test.go @@ -0,0 +1,117 @@ +package deploy + +import ( + "fmt" + "net/http" + "net/http/httptest" + "os" + "os/exec" + "path/filepath" + "testing" +) + +func TestBindCLIInstallsDockerRunnerHelper(t *testing.T) { + curl, err := exec.LookPath("curl") + if err != nil { + t.Skip("curl is required for the runner installer") + } + for _, tc := range []struct { + name, hostOS, arch, unameArch string + upgrade, missingArtifact bool + }{ + {name: "macOS_install", hostOS: "darwin", arch: "arm64", unameArch: "arm64"}, + {name: "macOS_upgrade", hostOS: "darwin", arch: "amd64", unameArch: "x86_64", upgrade: true}, + {name: "Linux_install", hostOS: "linux", arch: "arm64", unameArch: "aarch64"}, + {name: "macOS_preserves_existing_helper_on_failed_download", hostOS: "darwin", arch: "arm64", unameArch: "arm64", missingArtifact: true}, + } { + t.Run(tc.name, func(t *testing.T) { + fixtureHome := t.TempDir() + bin := filepath.Join(fixtureHome, "bin") + if err := os.Mkdir(bin, 0o755); err != nil { + t.Fatal(err) + } + uname := fmt.Sprintf("#!/bin/sh\ncase \"$1\" in -s) echo %s ;; -m) echo %s ;; esac\n", tc.hostOS, tc.unameArch) + if err := os.WriteFile(filepath.Join(bin, "uname"), []byte(uname), 0o755); err != nil { + t.Fatal(err) + } + server := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, req *http.Request) { + targetOS, arch := req.URL.Query().Get("os"), req.URL.Query().Get("arch") + if arch != tc.arch || (targetOS != tc.hostOS && targetOS != "linux") { + http.NotFound(w, req) + return + } + switch req.URL.Path { + case "/runners/agentflow-runner": + if tc.missingArtifact && targetOS == "linux" { + http.NotFound(w, req) + return + } + fmt.Fprintf(w, "runner %s/%s", targetOS, arch) + case "/runners/agentflow-gate-mcp": + fmt.Fprintf(w, "gate %s/%s", targetOS, arch) + default: + http.NotFound(w, req) + } + })) + defer server.Close() + args := []string{"bind-cli.sh", "--bin-dir", bin, "--no-start"} + helper := filepath.Join(bin, "agentflow-runner-linux-"+tc.arch) + statePath := filepath.Join(fixtureHome, ".agentflow-runner", "state.json") + const state = `{"runnerId":"fixture"}` + if tc.upgrade { + if err := os.Mkdir(filepath.Dir(statePath), 0o700); err != nil { + t.Fatal(err) + } + for path, data := range map[string]string{ + statePath: state, + filepath.Join(filepath.Dir(statePath), "env"): "AGENTFLOW_SERVER_URL=" + server.URL + "\n", + filepath.Join(bin, "agentflow-runner"): "old host runner", + } { + if err := os.WriteFile(path, []byte(data), 0o700); err != nil { + t.Fatal(err) + } + } + args = append(args, "--upgrade") + } else { + args = append(args, "--server", server.URL, "--token", "fixture") + } + if tc.missingArtifact { + if err := os.WriteFile(helper, []byte("old Linux helper"), 0o755); err != nil { + t.Fatal(err) + } + } + cmd := exec.Command("/bin/bash", args...) + cmd.Env = []string{"HOME=" + fixtureHome, "PATH=" + bin + ":" + filepath.Dir(curl) + ":/usr/bin:/bin", "AGENTFLOW_BROWSER=off"} + if out, err := cmd.CombinedOutput(); err != nil { + t.Fatalf("install: %v\n%s", err, out) + } + assertArtifact := func(path, want string) { + t.Helper() + got, err := os.ReadFile(path) + if err != nil || string(got) != want { + t.Fatalf("%s = %q, %v; want %q", filepath.Base(path), got, err, want) + } + if info, err := os.Stat(path); err != nil || info.Mode().Perm()&0o100 == 0 { + t.Fatalf("%s is not executable: %v", path, err) + } + } + assertArtifact(filepath.Join(bin, "agentflow-runner"), "runner "+tc.hostOS+"/"+tc.arch) + switch { + case tc.hostOS == "linux": + if _, err := os.Stat(helper); !os.IsNotExist(err) { + t.Fatalf("Linux install wrote a duplicate runner: %v", err) + } + case tc.missingArtifact: + assertArtifact(helper, "old Linux helper") + default: + assertArtifact(helper, "runner linux/"+tc.arch) + assertArtifact(filepath.Join(bin, "agentflow-gate-mcp-linux-"+tc.arch), "gate linux/"+tc.arch) + } + if tc.upgrade { + if got, err := os.ReadFile(statePath); err != nil || string(got) != state { + t.Fatalf("upgrade changed runner state: %q, %v", got, err) + } + } + }) + } +} diff --git a/docs/deployment.md b/docs/deployment.md index 0d1c79995..218893119 100644 --- a/docs/deployment.md +++ b/docs/deployment.md @@ -133,6 +133,8 @@ The upstream process roles remain `-role api`, `-role worker` and `-role all`. A Personal runners are connected from the execution-machine page with a short-lived binding code. The installer is served at `/runners/install.sh`. `AGENTFLOW_RUNNER_BINARY` can point to binaries with `{os}` and `{arch}` substitutions. Container images bundle Linux/macOS amd64/arm64 runner and gate binaries. Native source installations can build on demand with Go. +The macOS installer places the matching Linux runner next to the macOS executable. Docker workspaces use it for Git credentials and MCP calls. When platform updates are enabled, macOS runners also synchronize this helper at startup and retry if it is missing. + A platform administrator can share one CodeBuddy API Key under **Platform administration → Shared CodeBuddy Key** (平台共享 CodeBuddy Key): pick the network environment that issued it and the models members may use (the first is the default). Members without a key of their own then chat and run SOPs on it, limited to those models; a role configured with another model runs on the default and the run says so. Members with their own key keep using it with any model. Scheduled tasks, clarification, reports, bots and run evaluation still need the runner's own key. A scheduled task uses the key for its selected CLI and does not borrow the shared CodeBuddy key. The key is stored in the database like personal keys and is never shown again after saving. `AGENTFLOW_ASSISTANT_SPONSOR_LOGIN`, which lent one account's key limited to `deepseek-v4.1-flash`, still applies while no shared key is configured. Configure provider credentials in the platform UI, not the host's global CLI configuration. Credentials are bound to the responsible actor by the upstream runtime. The home composer and SOP roles each choose a built-in CLI independently. Select the executor beside the home model selector; its API key (and optional Codex/Claude base URL) comes from your personal settings. Changing the executor preserves the draft; saved conversations record the executor used. Main Bot writes still pass through the platform tool gateway and its approval checks. Requirement clarification and notifications continue to use CodeBuddy. A scheduled assistant task can select any supported CLI and runs as an ordinary chat turn; Codex and Claude Code still need that account's own credential. Live model tests are opt-in; set `AGENTFLOW_LIVE_TESTS=1` only for the acceptance suites that need to load local credentials. diff --git a/internal/runner/daemon.go b/internal/runner/daemon.go index f3c8c1696..c1c035288 100644 --- a/internal/runner/daemon.go +++ b/internal/runner/daemon.go @@ -153,6 +153,7 @@ func (d *Daemon) Run(ctx context.Context) error { if err := d.ensureRegistered(ctx); err != nil { return err } + d.refreshDockerRunnerHelper(ctx, false) d.refreshRuntimes(ctx) claimCtx, cancelClaim := context.WithCancel(ctx) defer cancelClaim() @@ -380,6 +381,7 @@ func (d *Daemon) rescanLoop(ctx context.Context) { return case <-ticker.C: d.refreshRuntimes(ctx) + d.refreshDockerRunnerHelper(ctx, true) d.reapIdleRunSandboxes(ctx, runSandboxIdleTTL) } } diff --git a/internal/runner/update.go b/internal/runner/update.go index fddfee923..d14784bfb 100644 --- a/internal/runner/update.go +++ b/internal/runner/update.go @@ -16,6 +16,8 @@ import ( "strings" "sync/atomic" "time" + + flowruntime "agentflow/internal/runtime" ) // ErrUpdateReady tells the entry point to exec the newly installed binary. @@ -51,14 +53,40 @@ func (d *Daemon) checkGateMCPUpdates(ctx context.Context) error { for _, targetOS := range targetOSes { path := strings.ReplaceAll(strings.ReplaceAll(pattern, "{os}", targetOS), "{arch}", runtime.GOARCH) endpoint := fmt.Sprintf("%s/runners/agentflow-gate-mcp?os=%s&arch=%s", d.client.base, targetOS, runtime.GOARCH) - if err := d.checkGateMCPUpdate(ctx, endpoint, path); err != nil { + if err := d.checkCompanionBinaryUpdate(ctx, "gate MCP", endpoint, path); err != nil { return fmt.Errorf("%s/%s: %w", targetOS, runtime.GOARCH, err) } } return nil } -func (d *Daemon) checkGateMCPUpdate(ctx context.Context, endpoint, path string) error { +// Sync at startup after Runner updates, and retry missing artifacts during +// rescans. Conversation workspace requests do not go through the SOP claim loop. +func (d *Daemon) refreshDockerRunnerHelper(ctx context.Context, onlyMissing bool) { + if runtime.GOOS != "darwin" || d.cfg.DisableAutoUpdate || d.runnerWorkActive() { + return + } + updateCtx, cancel := context.WithTimeout(ctx, 30*time.Second) + defer cancel() + if err := d.checkDockerRunnerHelperUpdate(updateCtx, onlyMissing); err != nil && ctx.Err() == nil { + log.Printf("Docker Git/MCP helper update: %v", err) + } +} + +func (d *Daemon) checkDockerRunnerHelperUpdate(ctx context.Context, onlyMissing bool) error { + path, err := flowruntime.DockerRunnerHelperPath() + if err != nil { + return err + } + if onlyMissing { + if _, err := os.Stat(path); !os.IsNotExist(err) { + return err + } + } + return d.checkCompanionBinaryUpdate(ctx, "Docker Git/MCP helper", d.runnerUpdateEndpoint("linux"), path) +} + +func (d *Daemon) checkCompanionBinaryUpdate(ctx context.Context, name, endpoint, path string) error { metadata, err := runnerBinaryMetadata(ctx, endpoint) if err != nil { return err @@ -75,9 +103,11 @@ func (d *Daemon) checkGateMCPUpdate(ctx context.Context, endpoint, path string) return err } defer os.Remove(tmp) - d.updateMu.Lock() + if !d.updateMu.TryLock() { + return nil + } defer d.updateMu.Unlock() - if d.updateReady.Load() || atomic.LoadInt32(&d.running) != 0 || ctx.Err() != nil { + if d.updateReady.Load() || d.runnerExecutionActive() || ctx.Err() != nil { return nil } current, err := hashFile(path) @@ -85,12 +115,12 @@ func (d *Daemon) checkGateMCPUpdate(ctx context.Context, endpoint, path string) return err } if current != localHash { - return errors.New("gate MCP executable changed during update") + return fmt.Errorf("%s executable changed during update", name) } if err := os.Rename(tmp, path); err != nil { - return fmt.Errorf("replace gate MCP executable: %w", err) + return fmt.Errorf("replace %s executable: %w", name, err) } - log.Printf("gate MCP update installed (%s) at %s", metadata.SHA256[:12], path) + log.Printf("%s update installed (%s) at %s", name, metadata.SHA256[:12], path) return nil } @@ -107,8 +137,8 @@ func currentRunnerExecutable() (string, error) { var errRunnerUpdateBusy = errors.New("runner is busy") -func (d *Daemon) runnerUpdateEndpoint() string { - return fmt.Sprintf("%s/runners/agentflow-runner?os=%s&arch=%s", d.client.base, runtime.GOOS, runtime.GOARCH) +func (d *Daemon) runnerUpdateEndpoint(targetOS string) string { + return fmt.Sprintf("%s/runners/agentflow-runner?os=%s&arch=%s", d.client.base, targetOS, runtime.GOARCH) } func (d *Daemon) runnerUpdateHashes(ctx context.Context, binary string) (local, expected string, err error) { @@ -116,7 +146,7 @@ func (d *Daemon) runnerUpdateHashes(ctx context.Context, binary string) (local, if err != nil { return "", "", err } - remote, err := runnerBinaryMetadata(ctx, d.runnerUpdateEndpoint()) + remote, err := runnerBinaryMetadata(ctx, d.runnerUpdateEndpoint(runtime.GOOS)) return local, remote.SHA256, err } @@ -157,7 +187,7 @@ func (d *Daemon) installRunnerUpdate(ctx context.Context, binary string) (bool, if strings.EqualFold(localHash, expectedHash) { return false, nil } - tmp, err := downloadRunnerBinary(ctx, d.runnerUpdateEndpoint(), binary, expectedHash) + tmp, err := downloadRunnerBinary(ctx, d.runnerUpdateEndpoint(runtime.GOOS), binary, expectedHash) if err != nil { return false, err } diff --git a/internal/runner/update_test.go b/internal/runner/update_test.go index 6fe88879d..7a37a1a94 100644 --- a/internal/runner/update_test.go +++ b/internal/runner/update_test.go @@ -163,6 +163,70 @@ func TestGateMCPHelperUpdatesWhileRunnerIdle(t *testing.T) { } } +func TestDockerRunnerHelperUpdateRepairsMissingBinary(t *testing.T) { + const payload = "Linux runner for the Docker Git/MCP helper" + var downloads atomic.Int32 + var damaged atomic.Bool + server := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, req *http.Request) { + query := req.URL.Query() + if req.URL.Path != "/runners/agentflow-runner" || query.Get("os") != "linux" || query.Get("arch") != runtime.GOARCH { + http.NotFound(w, req) + return + } + if query.Get("metadata") == "1" { + expected := payload + if damaged.Load() { + expected = "new companion" + } + hash := sha256.Sum256([]byte(expected)) + fmt.Fprintf(w, `{"sha256":%q}`, hex.EncodeToString(hash[:])) + return + } + downloads.Add(1) + if damaged.Load() { + fmt.Fprint(w, "partial data") + return + } + fmt.Fprint(w, payload) + })) + defer server.Close() + d, err := New(Config{ServerURL: server.URL, BootstrapToken: "fixture"}) + if err != nil { + t.Fatal(err) + } + bin := t.TempDir() + t.Setenv("AGENTFLOW_RUNNER_BINARY", filepath.Join(bin, "agentflow-runner-{os}-{arch}")) + helper := filepath.Join(bin, "agentflow-runner-linux-"+runtime.GOARCH) + ctx := context.Background() + if err := d.checkDockerRunnerHelperUpdate(ctx, true); err != nil { + t.Fatal(err) + } + assertHelper := func() { + t.Helper() + if got, err := os.ReadFile(helper); err != nil || string(got) != payload { + t.Fatalf("Docker helper = %q, %v", got, err) + } + if info, err := os.Stat(helper); err != nil || info.Mode().Perm()&0o100 == 0 { + t.Fatalf("helper is not executable: %v", err) + } + if d.updateReady.Load() { + t.Fatal("updating the companion must not restart the runner") + } + } + assertHelper() + if err := d.checkDockerRunnerHelperUpdate(ctx, false); err != nil { + t.Fatal(err) + } + if n := downloads.Load(); n != 1 { + t.Fatalf("already-current helper was re-downloaded, requests = %d", n) + } + damaged.Store(true) + if err := d.checkDockerRunnerHelperUpdate(ctx, false); err == nil || !strings.Contains(err.Error(), "checksum mismatch") { + t.Fatalf("replacement was not rejected: %v", err) + } + assertHelper() +} + func TestRunnerUpdateDefersWhileWorkspaceRequestIsActive(t *testing.T) { const updated = "new runner" hash := sha256.Sum256([]byte(updated)) diff --git a/internal/runtime/mcp_call.go b/internal/runtime/mcp_call.go index 788151704..a6b92e8e9 100644 --- a/internal/runtime/mcp_call.go +++ b/internal/runtime/mcp_call.go @@ -172,21 +172,30 @@ func installMCPCallHelperForSandbox(sandbox Sandbox, workspace, dest string) err if sandboxDriver(sandbox) != "docker" || goruntime.GOOS == "linux" { return installMCPCallHelper(workspace, dest) } - self, err := os.Executable() + src, err := DockerRunnerHelperPath() if err != nil { return err } - pattern := strings.TrimSpace(os.Getenv("AGENTFLOW_RUNNER_BINARY")) - if !strings.Contains(pattern, "{os}") { - pattern = filepath.Join(filepath.Dir(self), "agentflow-runner-{os}-{arch}") - } - src := strings.NewReplacer("{os}", "linux", "{arch}", goruntime.GOARCH).Replace(pattern) if _, err := os.Stat(src); err != nil { return fmt.Errorf("Docker Git/MCP helper requires a Linux runner binary: set AGENTFLOW_RUNNER_BINARY with {os} and {arch}: %w", err) } return installMCPCallHelperFrom(workspace, src, dest) } +// DockerRunnerHelperPath is the Linux runner artifact used for Git and MCP +// inside Docker on a non-Linux runner. Keep installation and lookup in sync. +func DockerRunnerHelperPath() (string, error) { + pattern := strings.TrimSpace(os.Getenv("AGENTFLOW_RUNNER_BINARY")) + if !strings.Contains(pattern, "{os}") { + self, err := os.Executable() + if err != nil { + return "", err + } + pattern = filepath.Join(filepath.Dir(self), "agentflow-runner-{os}-{arch}") + } + return strings.NewReplacer("{os}", "linux", "{arch}", goruntime.GOARCH).Replace(pattern), nil +} + func installMCPCallHelperFrom(workspace, src, dest string) error { srcInfo, err := os.Stat(src) if err != nil { From 4148580c80049c74b8ef5c519fb48f5eef26cddc Mon Sep 17 00:00:00 2001 From: crispinhu Date: Thu, 19 Nov 2026 23:32:10 +0800 Subject: [PATCH 02/13] fix(runner): safeguard macOS Docker helper updates --- deploy/bind-cli.sh | 28 +++- deploy/bind_cli_docker_runner_test.go | 75 ++++++++-- docs/deployment.md | 4 +- internal/runner/daemon.go | 12 +- internal/runner/run_sandbox.go | 5 + internal/runner/update.go | 99 +++++++++++--- internal/runner/update_test.go | 190 +++++++++++++++++++++++++- 7 files changed, 376 insertions(+), 37 deletions(-) diff --git a/deploy/bind-cli.sh b/deploy/bind-cli.sh index d3bf6b696..4f373e1d4 100755 --- a/deploy/bind-cli.sh +++ b/deploy/bind-cli.sh @@ -596,18 +596,40 @@ install_binary() { publish_runner_binary "$BINARY" } +is_linux_runner_binary() { + local header machine + case "$ARCH" in + amd64) machine="3e00" ;; + arm64) machine="b700" ;; + esac + # Read the ELF64 little-endian header. e_type and e_machine start at bytes 16 and 18. + header="$(LC_ALL=C od -An -v -t x1 -N 64 "$1" | tr -d '[:space:]')" || return 1 + [[ ${#header} -eq 128 && "${header:0:14}" == "7f454c46020101" && + ( "${header:14:2}" == "00" || "${header:14:2}" == "03" ) && + ( "${header:32:4}" == "0200" || "${header:32:4}" == "0300" ) && + "${header:36:4}" == "$machine" ]] +} + install_docker_runner_binary() { local source="${SOURCE_DIR:-$PWD}" + # A custom host runner may have a matching helper managed by its installer. + # A per-OS download URL can replace the helper when it is the selected source. + if [[ -x "$DOCKER_RUNNER_BINARY" && -f "$DOCKER_RUNNER_BINARY" && + ( -n "$LOCAL_BINARY" || + ( "$DOWNLOAD_URL" != *"{os}"* && ( -n "$DOWNLOAD_URL" || -n "$SOURCE_DIR" ) ) ) ]]; then + info "保留自定义 Runner 的 Linux Git/MCP helper:${DOCKER_RUNNER_BINARY}" + return + fi TEMP_BINARY=$(mktemp "${BIN_DIR}/.agentflow-runner.XXXXXX") - if download_runner_binary linux || + if { download_runner_binary linux && is_linux_runner_binary "$TEMP_BINARY"; } || { [[ -d "$source/cmd/agentflow-runner" ]] && command -v go >/dev/null 2>&1 && - build_runner_binary linux "$source" && [[ -s "$TEMP_BINARY" ]]; }; then + build_runner_binary linux "$source" && is_linux_runner_binary "$TEMP_BINARY"; }; then publish_runner_binary "$DOCKER_RUNNER_BINARY" return fi rm -f "$TEMP_BINARY" TEMP_BINARY="" - warn "无法获取 Linux/${ARCH} Git/MCP helper,Docker 工作区需要该文件:${DOCKER_RUNNER_BINARY}" + warn "无法获取有效的 Linux/${ARCH} Git/MCP helper,Docker 工作区需要该文件:${DOCKER_RUNNER_BINARY}" } TEMP_BINARY="" diff --git a/deploy/bind_cli_docker_runner_test.go b/deploy/bind_cli_docker_runner_test.go index 9c3899a1b..6629b2b61 100644 --- a/deploy/bind_cli_docker_runner_test.go +++ b/deploy/bind_cli_docker_runner_test.go @@ -1,6 +1,8 @@ package deploy import ( + "debug/elf" + "encoding/binary" "fmt" "net/http" "net/http/httptest" @@ -17,12 +19,19 @@ func TestBindCLIInstallsDockerRunnerHelper(t *testing.T) { } for _, tc := range []struct { name, hostOS, arch, unameArch string - upgrade, missingArtifact bool + upgrade bool + helperArtifact, source string + preserveHelper bool }{ {name: "macOS_install", hostOS: "darwin", arch: "arm64", unameArch: "arm64"}, {name: "macOS_upgrade", hostOS: "darwin", arch: "amd64", unameArch: "x86_64", upgrade: true}, {name: "Linux_install", hostOS: "linux", arch: "arm64", unameArch: "aarch64"}, - {name: "macOS_preserves_existing_helper_on_failed_download", hostOS: "darwin", arch: "arm64", unameArch: "arm64", missingArtifact: true}, + {name: "macOS_preserves_helper_on_failed_download", hostOS: "darwin", arch: "arm64", unameArch: "arm64", helperArtifact: "unavailable", preserveHelper: true}, + {name: "macOS_preserves_helper_when_server_serves_macOS_binary_for_Linux", hostOS: "darwin", arch: "arm64", unameArch: "arm64", upgrade: true, helperArtifact: "mach-o", preserveHelper: true}, + {name: "macOS_preserves_helper_when_server_serves_wrong_architecture", hostOS: "darwin", arch: "amd64", unameArch: "x86_64", upgrade: true, helperArtifact: "wrong-arch", preserveHelper: true}, + {name: "macOS_preserves_helper_with_local_runner", hostOS: "darwin", arch: "arm64", unameArch: "arm64", source: "from", preserveHelper: true}, + {name: "macOS_preserves_helper_with_host_only_URL", hostOS: "darwin", arch: "arm64", unameArch: "arm64", source: "host-url", preserveHelper: true}, + {name: "macOS_updates_helper_with_explicit_Linux_URL", hostOS: "darwin", arch: "arm64", unameArch: "arm64", source: "template"}, } { t.Run(tc.name, func(t *testing.T) { fixtureHome := t.TempDir() @@ -34,6 +43,15 @@ func TestBindCLIInstallsDockerRunnerHelper(t *testing.T) { if err := os.WriteFile(filepath.Join(bin, "uname"), []byte(uname), 0o755); err != nil { t.Fatal(err) } + linuxRunner := bindFixtureLinuxRunner(tc.arch, "new helper") + oldHelper := bindFixtureLinuxRunner(tc.arch, "old helper") + hostRunner := linuxRunner + if tc.hostOS == "darwin" { + hostRunner = "\xcf\xfa\xed\xfe" + tc.arch + " macOS runner" + } + if tc.source == "from" { + hostRunner = "custom " + hostRunner + } server := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, req *http.Request) { targetOS, arch := req.URL.Query().Get("os"), req.URL.Query().Get("arch") if arch != tc.arch || (targetOS != tc.hostOS && targetOS != "linux") { @@ -42,11 +60,20 @@ func TestBindCLIInstallsDockerRunnerHelper(t *testing.T) { } switch req.URL.Path { case "/runners/agentflow-runner": - if tc.missingArtifact && targetOS == "linux" { - http.NotFound(w, req) + if targetOS == tc.hostOS { + fmt.Fprint(w, hostRunner) return } - fmt.Fprintf(w, "runner %s/%s", targetOS, arch) + switch tc.helperArtifact { + case "unavailable": + http.NotFound(w, req) + case "mach-o": + fmt.Fprint(w, hostRunner) + case "wrong-arch": + fmt.Fprint(w, bindFixtureLinuxRunner("arm64", "new helper")) + default: + fmt.Fprint(w, linuxRunner) + } case "/runners/agentflow-gate-mcp": fmt.Fprintf(w, "gate %s/%s", targetOS, arch) default: @@ -75,8 +102,20 @@ func TestBindCLIInstallsDockerRunnerHelper(t *testing.T) { } else { args = append(args, "--server", server.URL, "--token", "fixture") } - if tc.missingArtifact { - if err := os.WriteFile(helper, []byte("old Linux helper"), 0o755); err != nil { + switch tc.source { + case "from": + custom := filepath.Join(fixtureHome, "custom-runner") + if err := os.WriteFile(custom, []byte(hostRunner), 0o755); err != nil { + t.Fatal(err) + } + args = append(args, "--from", custom) + case "host-url": + args = append(args, "--download-url", server.URL+"/runners/agentflow-runner?os=darwin&arch={arch}") + case "template": + args = append(args, "--download-url", server.URL+"/runners/agentflow-runner?os={os}&arch={arch}") + } + if tc.upgrade || tc.source != "" || tc.preserveHelper { + if err := os.WriteFile(helper, []byte(oldHelper), 0o755); err != nil { t.Fatal(err) } } @@ -95,16 +134,16 @@ func TestBindCLIInstallsDockerRunnerHelper(t *testing.T) { t.Fatalf("%s is not executable: %v", path, err) } } - assertArtifact(filepath.Join(bin, "agentflow-runner"), "runner "+tc.hostOS+"/"+tc.arch) + assertArtifact(filepath.Join(bin, "agentflow-runner"), hostRunner) switch { case tc.hostOS == "linux": if _, err := os.Stat(helper); !os.IsNotExist(err) { t.Fatalf("Linux install wrote a duplicate runner: %v", err) } - case tc.missingArtifact: - assertArtifact(helper, "old Linux helper") + case tc.preserveHelper: + assertArtifact(helper, oldHelper) default: - assertArtifact(helper, "runner linux/"+tc.arch) + assertArtifact(helper, linuxRunner) assertArtifact(filepath.Join(bin, "agentflow-gate-mcp-linux-"+tc.arch), "gate linux/"+tc.arch) } if tc.upgrade { @@ -115,3 +154,17 @@ func TestBindCLIInstallsDockerRunnerHelper(t *testing.T) { }) } } + +func bindFixtureLinuxRunner(arch, payload string) string { + header := make([]byte, 64) + copy(header, "\x7fELF\x02\x01\x01\x00") + machine := elf.EM_X86_64 + if arch == "arm64" { + machine = elf.EM_AARCH64 + } + binary.LittleEndian.PutUint16(header[16:], uint16(elf.ET_EXEC)) + binary.LittleEndian.PutUint16(header[18:], uint16(machine)) + binary.LittleEndian.PutUint32(header[20:], uint32(elf.EV_CURRENT)) + binary.LittleEndian.PutUint16(header[52:], uint16(len(header))) + return string(header) + payload +} diff --git a/docs/deployment.md b/docs/deployment.md index 218893119..65657d3ee 100644 --- a/docs/deployment.md +++ b/docs/deployment.md @@ -133,7 +133,9 @@ The upstream process roles remain `-role api`, `-role worker` and `-role all`. A Personal runners are connected from the execution-machine page with a short-lived binding code. The installer is served at `/runners/install.sh`. `AGENTFLOW_RUNNER_BINARY` can point to binaries with `{os}` and `{arch}` substitutions. Container images bundle Linux/macOS amd64/arm64 runner and gate binaries. Native source installations can build on demand with Go. -The macOS installer places the matching Linux runner next to the macOS executable. Docker workspaces use it for Git credentials and MCP calls. When platform updates are enabled, macOS runners also synchronize this helper at startup and retry if it is missing. +The macOS installer places the matching Linux runner next to the macOS executable. Docker workspaces use it for Git credentials and MCP calls. The installer and updater verify the helper's executable format and CPU architecture before replacing it. Custom host installs keep an existing helper. A download URL with an `{os}` placeholder can supply a replacement when used as the runner's download source. + +When platform updates are enabled, macOS runners synchronize the helper in the background at startup and retry if it is missing or incompatible. The runner can report online and accept work during this check. A Docker workspace that needs a missing helper waits for the initial download attempt. A platform administrator can share one CodeBuddy API Key under **Platform administration → Shared CodeBuddy Key** (平台共享 CodeBuddy Key): pick the network environment that issued it and the models members may use (the first is the default). Members without a key of their own then chat and run SOPs on it, limited to those models; a role configured with another model runs on the default and the run says so. Members with their own key keep using it with any model. Scheduled tasks, clarification, reports, bots and run evaluation still need the runner's own key. A scheduled task uses the key for its selected CLI and does not borrow the shared CodeBuddy key. The key is stored in the database like personal keys and is never shown again after saving. `AGENTFLOW_ASSISTANT_SPONSOR_LOGIN`, which lent one account's key limited to `deepseek-v4.1-flash`, still applies while no shared key is configured. diff --git a/internal/runner/daemon.go b/internal/runner/daemon.go index c1c035288..d25db5ce5 100644 --- a/internal/runner/daemon.go +++ b/internal/runner/daemon.go @@ -48,6 +48,7 @@ type Daemon struct { updateMu sync.RWMutex updateReady atomic.Bool updateDownloadMu sync.Mutex + dockerHelperSyncDone chan struct{} // closed after the initial macOS helper sync cancelClaimLoop context.CancelFunc heartbeatWake chan struct{} maintenance runnerMaintenanceState @@ -153,11 +154,13 @@ func (d *Daemon) Run(ctx context.Context) error { if err := d.ensureRegistered(ctx); err != nil { return err } - d.refreshDockerRunnerHelper(ctx, false) d.refreshRuntimes(ctx) claimCtx, cancelClaim := context.WithCancel(ctx) defer cancelClaim() d.cancelClaimLoop = cancelClaim + if goruntime.GOOS == "darwin" && !d.cfg.DisableAutoUpdate { + d.dockerHelperSyncDone = make(chan struct{}) + } go d.rescanLoop(ctx) heartbeatDone := make(chan struct{}) go func() { defer close(heartbeatDone); d.heartbeatLoop(ctx) }() @@ -173,6 +176,9 @@ func (d *Daemon) Run(ctx context.Context) error { <-controlDone d.maintenance.jobs.Wait() <-heartbeatDone + if d.dockerHelperSyncDone != nil { + <-d.dockerHelperSyncDone + } closeCtx, cancel := context.WithTimeout(context.Background(), 30*time.Second) d.closeAllRunSandboxes(closeCtx) cancel() @@ -373,6 +379,10 @@ func (d *Daemon) availableProviders() []string { } func (d *Daemon) rescanLoop(ctx context.Context) { + if d.dockerHelperSyncDone != nil { + d.refreshDockerRunnerHelper(ctx, false) + close(d.dockerHelperSyncDone) + } ticker := time.NewTicker(5 * time.Minute) defer ticker.Stop() for { diff --git a/internal/runner/run_sandbox.go b/internal/runner/run_sandbox.go index 9cd04f29a..0013ad52b 100644 --- a/internal/runner/run_sandbox.go +++ b/internal/runner/run_sandbox.go @@ -38,6 +38,11 @@ func (d *Daemon) acquireTaskSandbox(ctx context.Context, task domain.RunnerTask) if task.Sandbox == nil { return nil, nil, fmt.Errorf("frozen run sandbox definition is required") } + if strings.TrimSpace(task.Sandbox.Profile.Driver) == domain.SandboxDriverDocker { + if err := d.waitForDockerRunnerHelper(ctx); err != nil { + return nil, nil, err + } + } requirements, resources := taskSandboxSpec(task) key, id, shared := runSandboxKey(task, requirements, resources) if !shared || d.cfg.DisableRunSandboxReuse { diff --git a/internal/runner/update.go b/internal/runner/update.go index d14784bfb..f4f87d9c7 100644 --- a/internal/runner/update.go +++ b/internal/runner/update.go @@ -3,6 +3,7 @@ package runner import ( "context" "crypto/sha256" + "debug/elf" "encoding/hex" "encoding/json" "errors" @@ -53,40 +54,91 @@ func (d *Daemon) checkGateMCPUpdates(ctx context.Context) error { for _, targetOS := range targetOSes { path := strings.ReplaceAll(strings.ReplaceAll(pattern, "{os}", targetOS), "{arch}", runtime.GOARCH) endpoint := fmt.Sprintf("%s/runners/agentflow-gate-mcp?os=%s&arch=%s", d.client.base, targetOS, runtime.GOARCH) - if err := d.checkCompanionBinaryUpdate(ctx, "gate MCP", endpoint, path); err != nil { + if err := d.checkCompanionBinaryUpdate(ctx, "gate MCP", endpoint, path, nil, true); err != nil { return fmt.Errorf("%s/%s: %w", targetOS, runtime.GOARCH, err) } } return nil } -// Sync at startup after Runner updates, and retry missing artifacts during -// rescans. Conversation workspace requests do not go through the SOP claim loop. -func (d *Daemon) refreshDockerRunnerHelper(ctx context.Context, onlyMissing bool) { - if runtime.GOOS != "darwin" || d.cfg.DisableAutoUpdate || d.runnerWorkActive() { +// Sync in the background on startup, then retry missing or incompatible +// helpers during rescans. Conversation requests bypass the SOP claim loop. +func (d *Daemon) refreshDockerRunnerHelper(ctx context.Context, repairOnly bool) { + if runtime.GOOS != "darwin" || d.cfg.DisableAutoUpdate { return } updateCtx, cancel := context.WithTimeout(ctx, 30*time.Second) defer cancel() - if err := d.checkDockerRunnerHelperUpdate(updateCtx, onlyMissing); err != nil && ctx.Err() == nil { + if err := d.checkDockerRunnerHelperUpdate(updateCtx, repairOnly); err != nil && ctx.Err() == nil { log.Printf("Docker Git/MCP helper update: %v", err) } } -func (d *Daemon) checkDockerRunnerHelperUpdate(ctx context.Context, onlyMissing bool) error { +func (d *Daemon) checkDockerRunnerHelperUpdate(ctx context.Context, repairOnly bool) error { path, err := flowruntime.DockerRunnerHelperPath() if err != nil { return err } - if onlyMissing { - if _, err := os.Stat(path); !os.IsNotExist(err) { - return err - } + if repairOnly && validateDockerRunnerHelper(path) == nil { + return nil + } + // Sandboxes copy this executable into the workspace, so an atomic replacement + // can run alongside active tasks and requests waiting for the first download. + return d.checkCompanionBinaryUpdate(ctx, "Docker Git/MCP helper", d.runnerUpdateEndpoint("linux"), path, validateDockerRunnerHelper, false) +} + +func (d *Daemon) waitForDockerRunnerHelper(ctx context.Context) error { + if d.dockerHelperSyncDone == nil { + return nil + } + select { + case <-d.dockerHelperSyncDone: + return nil + default: + } + if path, err := flowruntime.DockerRunnerHelperPath(); err == nil && validateDockerRunnerHelper(path) == nil { + return nil + } + select { + case <-d.dockerHelperSyncDone: + return nil + case <-ctx.Done(): + return ctx.Err() } - return d.checkCompanionBinaryUpdate(ctx, "Docker Git/MCP helper", d.runnerUpdateEndpoint("linux"), path) } -func (d *Daemon) checkCompanionBinaryUpdate(ctx context.Context, name, endpoint, path string) error { +func validateDockerRunnerHelper(path string) error { + var machine elf.Machine + switch runtime.GOARCH { + case "arm64": + machine = elf.EM_AARCH64 + case "amd64": + machine = elf.EM_X86_64 + default: + return fmt.Errorf("unsupported Linux helper architecture %s", runtime.GOARCH) + } + info, err := os.Stat(path) + if err != nil { + return err + } + if !info.Mode().IsRegular() || info.Mode().Perm()&0o111 == 0 { + return fmt.Errorf("expected executable Linux/%s helper", runtime.GOARCH) + } + file, err := elf.Open(path) + if err != nil { + return fmt.Errorf("expected Linux/%s ELF helper: %w", runtime.GOARCH, err) + } + defer file.Close() + if file.Class != elf.ELFCLASS64 || file.Data != elf.ELFDATA2LSB || file.Machine != machine || + (file.OSABI != elf.ELFOSABI_NONE && file.OSABI != elf.ELFOSABI_LINUX) || + (file.Type != elf.ET_EXEC && file.Type != elf.ET_DYN) { + return fmt.Errorf("expected Linux/%s executable, got ELF %s %s %s %s %s", runtime.GOARCH, + file.Class, file.Data, file.Machine, file.OSABI, file.Type) + } + return nil +} + +func (d *Daemon) checkCompanionBinaryUpdate(ctx context.Context, name, endpoint, path string, validate func(string) error, requireIdle bool) error { metadata, err := runnerBinaryMetadata(ctx, endpoint) if err != nil { return err @@ -96,6 +148,9 @@ func (d *Daemon) checkCompanionBinaryUpdate(ctx context.Context, name, endpoint, return err } if localHash == metadata.SHA256 { + if validate != nil { + return validate(path) + } return nil } tmp, err := downloadRunnerBinary(ctx, endpoint, path, metadata.SHA256) @@ -103,11 +158,21 @@ func (d *Daemon) checkCompanionBinaryUpdate(ctx context.Context, name, endpoint, return err } defer os.Remove(tmp) - if !d.updateMu.TryLock() { - return nil + if validate != nil { + if err := validate(tmp); err != nil { + return fmt.Errorf("validate %s: %w", name, err) + } } - defer d.updateMu.Unlock() - if d.updateReady.Load() || d.runnerExecutionActive() || ctx.Err() != nil { + if requireIdle { + if !d.updateMu.TryLock() { + return nil + } + defer d.updateMu.Unlock() + if d.runnerExecutionActive() { + return nil + } + } + if d.updateReady.Load() || ctx.Err() != nil { return nil } current, err := hashFile(path) diff --git a/internal/runner/update_test.go b/internal/runner/update_test.go index 7a37a1a94..2df6b7683 100644 --- a/internal/runner/update_test.go +++ b/internal/runner/update_test.go @@ -3,6 +3,8 @@ package runner import ( "context" "crypto/sha256" + "debug/elf" + "encoding/binary" "encoding/hex" "encoding/json" "errors" @@ -16,6 +18,8 @@ import ( "sync/atomic" "testing" "time" + + "github.com/gorilla/websocket" ) func TestRunnerUpdateReplacesBinaryOnlyAfterVerification(t *testing.T) { @@ -164,7 +168,7 @@ func TestGateMCPHelperUpdatesWhileRunnerIdle(t *testing.T) { } func TestDockerRunnerHelperUpdateRepairsMissingBinary(t *testing.T) { - const payload = "Linux runner for the Docker Git/MCP helper" + payload := dockerRunnerFixtureLinuxBinary(runtime.GOARCH, "Docker helper") var downloads atomic.Int32 var damaged atomic.Bool server := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, req *http.Request) { @@ -198,9 +202,6 @@ func TestDockerRunnerHelperUpdateRepairsMissingBinary(t *testing.T) { t.Setenv("AGENTFLOW_RUNNER_BINARY", filepath.Join(bin, "agentflow-runner-{os}-{arch}")) helper := filepath.Join(bin, "agentflow-runner-linux-"+runtime.GOARCH) ctx := context.Background() - if err := d.checkDockerRunnerHelperUpdate(ctx, true); err != nil { - t.Fatal(err) - } assertHelper := func() { t.Helper() if got, err := os.ReadFile(helper); err != nil || string(got) != payload { @@ -213,6 +214,15 @@ func TestDockerRunnerHelperUpdateRepairsMissingBinary(t *testing.T) { t.Fatal("updating the companion must not restart the runner") } } + // A Docker workspace can already be waiting for the helper under the update fence. + d.updateMu.RLock() + atomic.StoreInt32(&d.running, 1) + err = d.checkDockerRunnerHelperUpdate(ctx, true) + atomic.StoreInt32(&d.running, 0) + d.updateMu.RUnlock() + if err != nil { + t.Fatal(err) + } assertHelper() if err := d.checkDockerRunnerHelperUpdate(ctx, false); err != nil { t.Fatal(err) @@ -225,6 +235,178 @@ func TestDockerRunnerHelperUpdateRepairsMissingBinary(t *testing.T) { t.Fatalf("replacement was not rejected: %v", err) } assertHelper() + damaged.Store(false) + if err := os.WriteFile(helper, []byte("invalid existing helper"), 0o755); err != nil { + t.Fatal(err) + } + if err := d.checkDockerRunnerHelperUpdate(ctx, true); err != nil { + t.Fatal(err) + } + assertHelper() +} + +func TestDockerRunnerHelperUpdateRejectsWrongOSOrArchitecture(t *testing.T) { + otherArch := "arm64" + if runtime.GOARCH == otherArch { + otherArch = "amd64" + } + for _, tc := range []struct{ name, payload string }{ + {name: "macOS_binary", payload: "\xcf\xfa\xed\xfemacOS runner"}, + {name: "wrong_Linux_architecture", payload: dockerRunnerFixtureLinuxBinary(otherArch, "wrong architecture")}, + } { + t.Run(tc.name, func(t *testing.T) { + hash := sha256.Sum256([]byte(tc.payload)) + server := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, req *http.Request) { + if req.URL.Query().Get("metadata") == "1" { + fmt.Fprintf(w, `{"sha256":%q}`, hex.EncodeToString(hash[:])) + return + } + fmt.Fprint(w, tc.payload) + })) + defer server.Close() + d, err := New(Config{ServerURL: server.URL, BootstrapToken: "fixture"}) + if err != nil { + t.Fatal(err) + } + bin := t.TempDir() + t.Setenv("AGENTFLOW_RUNNER_BINARY", filepath.Join(bin, "agentflow-runner-{os}-{arch}")) + helper := filepath.Join(bin, "agentflow-runner-linux-"+runtime.GOARCH) + original := dockerRunnerFixtureLinuxBinary(runtime.GOARCH, "working helper") + if err := os.WriteFile(helper, []byte(original), 0o755); err != nil { + t.Fatal(err) + } + updateErr := d.checkDockerRunnerHelperUpdate(t.Context(), false) + got, err := os.ReadFile(helper) + if err != nil || string(got) != original { + t.Fatalf("incompatible download replaced the helper: %q, read error %v, update error %v", got, err, updateErr) + } + if updateErr == nil || !strings.Contains(updateErr.Error(), "Linux/"+runtime.GOARCH) { + t.Fatalf("expected a platform validation error, got %v", updateErr) + } + }) + } +} + +func TestDockerRunnerHelperDownloadDoesNotBlockMacOSStartup(t *testing.T) { + if runtime.GOOS != "darwin" { + t.Skip("macOS Runner downloads the Linux helper at startup") + } + root := t.TempDir() + t.Setenv("HOME", root) + t.Setenv("PATH", "/usr/bin:/bin") + t.Setenv("AGENTFLOW_RUNNER_BINARY", filepath.Join(root, "agentflow-runner-{os}-{arch}")) + helper := filepath.Join(root, "agentflow-runner-linux-"+runtime.GOARCH) + original := dockerRunnerFixtureLinuxBinary(runtime.GOARCH, "working helper") + if err := os.WriteFile(helper, []byte(original), 0o755); err != nil { + t.Fatal(err) + } + updated := dockerRunnerFixtureLinuxBinary(runtime.GOARCH, "updated helper") + hash := sha256.Sum256([]byte(updated)) + helperRequested := make(chan struct{}, 1) + allowMetadata := make(chan struct{}) + heartbeat := make(chan struct{}, 1) + controlHello := make(chan struct{}, 1) + claim := make(chan struct{}, 1) + signal := func(ch chan struct{}) { + select { + case ch <- struct{}{}: + default: + } + } + upgrader := websocket.Upgrader{} + ctx, cancel := context.WithCancel(t.Context()) + server := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, req *http.Request) { + switch req.URL.Path { + case "/runners/agentflow-runner": + if req.URL.Query().Get("os") != "linux" || req.URL.Query().Get("arch") != runtime.GOARCH { + http.NotFound(w, req) + return + } + if req.URL.Query().Get("metadata") == "1" { + signal(helperRequested) + select { + case <-allowMetadata: + fmt.Fprintf(w, `{"sha256":%q}`, hex.EncodeToString(hash[:])) + case <-req.Context().Done(): + } + return + } + fmt.Fprint(w, updated) + case "/runners/heartbeat": + signal(heartbeat) + fmt.Fprint(w, `{}`) + case "/runners/connect": + conn, err := upgrader.Upgrade(w, req, nil) + if err != nil { + return + } + defer conn.Close() + var hello controlMessage + if conn.ReadJSON(&hello) == nil && hello.Type == "hello" { + signal(controlHello) + _, _, _ = conn.NextReader() + } + case "/runners/tasks/claim": + signal(claim) + <-ctx.Done() + case "/runners/disconnect": + w.WriteHeader(http.StatusNoContent) + default: + http.NotFound(w, req) + } + })) + defer func() { cancel(); server.Close() }() + d, err := New(Config{ServerURL: server.URL, BootstrapToken: "fixture", StatePath: filepath.Join(root, "state.json")}) + if err != nil { + t.Fatal(err) + } + if err := d.saveState(daemonState{RunnerID: "runner", SessionToken: "session", ExpiresAt: time.Now().Add(24 * time.Hour)}); err != nil { + t.Fatal(err) + } + done := make(chan error, 1) + go func() { done <- d.Run(ctx) }() + defer func() { + cancel() + if err := <-done; err != nil { + t.Errorf("run: %v", err) + } + }() + wait := func(ch <-chan struct{}, event string) { + t.Helper() + select { + case <-ch: + case <-time.After(5 * time.Second): + t.Fatalf("did not observe %s before the Linux helper download completed", event) + } + } + wait(helperRequested, "Linux helper metadata request") + wait(heartbeat, "heartbeat") + wait(controlHello, "control hello") + wait(claim, "task polling") + workspaceCtx, cancelWorkspace := context.WithTimeout(ctx, time.Second) + defer cancelWorkspace() + if err := d.waitForDockerRunnerHelper(workspaceCtx); err != nil { + t.Fatalf("existing helper should be available during the download: %v", err) + } + close(allowMetadata) + waitFor(t, 5*time.Second, "helper update", func() bool { + got, err := os.ReadFile(helper) + return err == nil && string(got) == updated + }) +} + +func dockerRunnerFixtureLinuxBinary(arch, payload string) string { + header := make([]byte, 64) + copy(header, "\x7fELF\x02\x01\x01\x00") + machine := elf.EM_X86_64 + if arch == "arm64" { + machine = elf.EM_AARCH64 + } + binary.LittleEndian.PutUint16(header[16:], uint16(elf.ET_EXEC)) + binary.LittleEndian.PutUint16(header[18:], uint16(machine)) + binary.LittleEndian.PutUint32(header[20:], uint32(elf.EV_CURRENT)) + binary.LittleEndian.PutUint16(header[52:], uint16(len(header))) + return string(header) + payload } func TestRunnerUpdateDefersWhileWorkspaceRequestIsActive(t *testing.T) { From b85ed4bb5cbce5f21e4d1dbd1a3e8231c837b428 Mon Sep 17 00:00:00 2001 From: crispinhu Date: Fri, 20 Nov 2026 00:17:05 +0800 Subject: [PATCH 03/13] fix(runner): complete Docker helper install and recovery --- deploy/bind-cli.sh | 163 +++++++++++++++--- deploy/bind_cli_docker_runner_test.go | 148 ++++++++++++++-- docs/deployment.md | 6 +- internal/runner/daemon.go | 18 +- internal/runner/run_sandbox.go | 5 - internal/runner/update.go | 62 +++++-- internal/runner/update_test.go | 132 +++++++++++++- internal/runner/workspace.go | 1 + internal/runner/workspace_browser_test.go | 102 +++++++++++ .../runtime/agent_cli_integration_test.go | 2 +- internal/runtime/agent_cli_test.go | 4 +- internal/runtime/agent_cli_zcode_test.go | 2 +- internal/runtime/cli_live_test.go | 2 +- internal/runtime/command_binding.go | 13 +- .../runtime/command_binding_telemetry_test.go | 4 +- .../command_binding_workspace_git_test.go | 4 +- internal/runtime/conversation_process.go | 2 +- internal/runtime/docker_cases_test.go | 2 +- internal/runtime/managed_files_test.go | 2 +- internal/runtime/mcp_call.go | 27 ++- internal/runtime/mcp_call_test.go | 47 ++++- internal/runtime/mcp_stdio_test.go | 2 +- internal/runtime/provider_credentials_test.go | 6 +- .../provider_gateway_integration_test.go | 2 +- .../runtime/run_credentials_extra_test.go | 8 +- internal/runtime/run_git_credentials.go | 2 +- internal/runtime/runtime_test.go | 2 +- internal/runtime/sandbox_local.go | 2 +- internal/runtime/sandbox_manager.go | 2 +- .../runtime/workspace_terminal_sandbox.go | 2 +- 30 files changed, 651 insertions(+), 125 deletions(-) diff --git a/deploy/bind-cli.sh b/deploy/bind-cli.sh index 4f373e1d4..48d0fa3b3 100755 --- a/deploy/bind-cli.sh +++ b/deploy/bind-cli.sh @@ -38,6 +38,7 @@ BIN_DIR="${HOME}/.local/bin" LOCAL_BINARY="" DOWNLOAD_URL="" SOURCE_DIR="" +RUNNER_BUILD_SOURCE="" INSTALL_SERVICE=0 NO_START=0 UNINSTALL=0 @@ -339,11 +340,24 @@ case "$ARCH" in esac [[ "$OS" == "darwin" || "$OS" == "linux" ]] || fail "不支持的系统: ${OS}(Windows 请使用 PowerShell 安装方式)" +# A thin macOS Runner can execute under Rosetta. Its own GOARCH, instead of +# the installer's uname, determines which Linux companion it looks up. +macos_runner_arch() { + local header="" + if [[ -f "$1" ]]; then + header="$(LC_ALL=C od -An -v -t x1 -N 8 "$1" | tr -d '[:space:]')" + fi + case "$header" in + cffaedfe07000001) printf '%s\n' amd64 ;; + cffaedfe0c000001) printf '%s\n' arm64 ;; + *) printf '%s\n' "$ARCH" ;; + esac +} + RUNNER_HOME="${HOME}/.agentflow-runner" ENV_FILE="${RUNNER_HOME}/env" STATE_FILE="${RUNNER_HOME}/state.json" BINARY="${BIN_DIR}/agentflow-runner" -DOCKER_RUNNER_BINARY="${BIN_DIR}/agentflow-runner-linux-${ARCH}" GATE_BINARY_PATTERN="${BIN_DIR}/agentflow-gate-mcp-{os}-{arch}" PLIST="${HOME}/Library/LaunchAgents/com.agentflow.runner.plist" UNIT="${HOME}/.config/systemd/user/agentflow-runner.service" @@ -421,10 +435,11 @@ if [[ "$UNINSTALL" == "1" ]]; then done < <(docker images --format '{{.Repository}}' 2>/dev/null | awk '/^agentflow-tmp-rt-/' || true) info "已清理 runner Docker 沙箱和临时镜像" fi - rm -f "$BINARY" if [[ "$OS" == "darwin" ]]; then - rm -f "$DOCKER_RUNNER_BINARY" + runner_arch=$(macos_runner_arch "$BINARY") + rm -f "${BIN_DIR}/agentflow-runner-linux-${runner_arch}" fi + rm -f "$BINARY" rm -f "${BIN_DIR}"/agentflow-gate-mcp-darwin-amd64 \ "${BIN_DIR}"/agentflow-gate-mcp-darwin-arm64 \ "${BIN_DIR}"/agentflow-gate-mcp-linux-amd64 \ @@ -554,9 +569,10 @@ download_runner_binary() { } build_runner_binary() { - local target_os="$1" source="$2" + local target_os="$1" source="$2" output="$TEMP_BINARY" + [[ "$output" == /* ]] || output="$PWD/$output" info "从源码 ${source} 构建 agentflow-runner(${target_os}/${ARCH})..." - (cd "$source" && CGO_ENABLED=0 GOOS="$target_os" GOARCH="$ARCH" go build -o "$TEMP_BINARY" ./cmd/agentflow-runner) + (cd "$source" && CGO_ENABLED=0 GOOS="$target_os" GOARCH="$ARCH" go build -o "$output" ./cmd/agentflow-runner) } publish_runner_binary() { @@ -581,15 +597,15 @@ install_binary() { else # 平台未配置分发:回退到本地源码构建(--source 或当前目录为源码 checkout)。 AUTO_UPDATE=0 - SRC="${SOURCE_DIR:-$PWD}" - if [[ ! -d "$SRC/cmd/agentflow-runner" ]]; then + RUNNER_BUILD_SOURCE="${SOURCE_DIR:-$PWD}" + if [[ ! -d "$RUNNER_BUILD_SOURCE/cmd/agentflow-runner" ]]; then fail "平台未提供二进制且未找到源码。解决方式任选其一: 1) 平台管理员设置 AGENTFLOW_SOURCE_ROOT(源码目录)或 AGENTFLOW_RUNNER_BINARY(预编译产物)后重启服务 2) 本命令追加 --source (需要本机安装 Go) 3) 本命令追加 --from <已编译的 agentflow-runner 二进制路径>" fi command -v go >/dev/null 2>&1 || fail "本机未安装 Go,无法从源码构建;请使用 --from 提供二进制" - build_runner_binary "$OS" "$SRC" \ + build_runner_binary "$OS" "$RUNNER_BUILD_SOURCE" \ || fail "源码构建失败;请检查 Go 版本(需 1.22+)或改用 --from" fi fi @@ -597,33 +613,90 @@ install_binary() { } is_linux_runner_binary() { - local header machine + local binary="$1" machine size layout offset table_size case "$ARCH" in - amd64) machine="3e00" ;; - arm64) machine="b700" ;; + amd64) machine=62 ;; + arm64) machine=183 ;; esac - # Read the ELF64 little-endian header. e_type and e_machine start at bytes 16 and 18. - header="$(LC_ALL=C od -An -v -t x1 -N 64 "$1" | tr -d '[:space:]')" || return 1 - [[ ${#header} -eq 128 && "${header:0:14}" == "7f454c46020101" && - ( "${header:14:2}" == "00" || "${header:14:2}" == "03" ) && - ( "${header:32:4}" == "0200" || "${header:32:4}" == "0300" ) && - "${header:36:4}" == "$machine" ]] + size=$(wc -c < "$binary") || return 1 + local decode_bytes=' + { for (i = 1; i <= NF; i++) bytes[count++] = $i } + function little_endian(offset, width, i, value) { + for (i = width - 1; i >= 0; i--) value = 256 * value + bytes[offset + i] + return value + }' + # ELF64 starts with 64 bytes, followed by a table of 56-byte program headers. + layout=$(LC_ALL=C od -An -v -t u1 -N 64 "$binary" | + awk -v machine="$machine" -v size="$size" "$decode_bytes"' + END { + if (count != 64 || bytes[0] != 127 || bytes[1] != 69 || + bytes[2] != 76 || bytes[3] != 70 || bytes[4] != 2 || + bytes[5] != 1 || bytes[6] != 1 || (bytes[7] != 0 && bytes[7] != 3)) exit 1 + type = little_endian(16, 2) + offset = little_endian(32, 8) + num = little_endian(56, 2) + if ((type != 2 && type != 3) || little_endian(18, 2) != machine || + little_endian(54, 2) != 56 || num == 0 || num * 56 > 65536 || + offset < 64 || num * 56 > size - offset) exit 1 + printf "%.0f %d\n", offset, num * 56 + }') || return 1 + read -r offset table_size <<< "$layout" + # The header can be valid even when the server only has part of the file. + LC_ALL=C od -An -v -t u1 -j "$offset" -N "$table_size" "$binary" | + awk -v size="$size" -v table_size="$table_size" "$decode_bytes"' + END { + if (count != table_size) exit 1 + for (header = 0; header < count; header += 56) { + type = little_endian(header, 4) + flags = little_endian(header + 4, 4) + offset = little_endian(header + 8, 8) + file_size = little_endian(header + 32, 8) + if (type != 0 && file_size > 0 && (offset > size || file_size > size - offset)) exit 1 + if (type != 1) continue + if (file_size > little_endian(header + 40, 8)) exit 1 + if (file_size > 0 && flags % 2 == 1) executable = 1 + } + if (!executable) exit 1 + }' } -install_docker_runner_binary() { +is_custom_docker_runner_helper() { + [[ -x "$1" && -f "$1" ]] || return 1 + # A custom installer may also provide an executable script wrapper. + [[ "$(LC_ALL=C od -An -v -t x1 -N 2 "$1" | tr -d '[:space:]')" == 2321 ]] || + is_linux_runner_binary "$1" +} + +stage_docker_runner_binary() { local source="${SOURCE_DIR:-$PWD}" + if [[ -n "$RUNNER_BUILD_SOURCE" ]]; then + build_runner_binary linux "$RUNNER_BUILD_SOURCE" && is_linux_runner_binary "$TEMP_BINARY" + return + fi + if download_runner_binary linux && is_linux_runner_binary "$TEMP_BINARY"; then + return 0 + fi + [[ -d "$source/cmd/agentflow-runner" ]] && command -v go >/dev/null 2>&1 && + build_runner_binary linux "$source" && is_linux_runner_binary "$TEMP_BINARY" +} + +install_docker_runner_binary() { # A custom host runner may have a matching helper managed by its installer. # A per-OS download URL can replace the helper when it is the selected source. - if [[ -x "$DOCKER_RUNNER_BINARY" && -f "$DOCKER_RUNNER_BINARY" && - ( -n "$LOCAL_BINARY" || - ( "$DOWNLOAD_URL" != *"{os}"* && ( -n "$DOWNLOAD_URL" || -n "$SOURCE_DIR" ) ) ) ]]; then + if [[ -n "$LOCAL_BINARY" || -n "$RUNNER_BUILD_SOURCE" || + ( "$DOWNLOAD_URL" != *"{os}"* && ( -n "$DOWNLOAD_URL" || -n "$SOURCE_DIR" ) ) ]] && + is_custom_docker_runner_helper "$DOCKER_RUNNER_BINARY"; then info "保留自定义 Runner 的 Linux Git/MCP helper:${DOCKER_RUNNER_BINARY}" return fi - TEMP_BINARY=$(mktemp "${BIN_DIR}/.agentflow-runner.XXXXXX") - if { download_runner_binary linux && is_linux_runner_binary "$TEMP_BINARY"; } || - { [[ -d "$source/cmd/agentflow-runner" ]] && command -v go >/dev/null 2>&1 && - build_runner_binary linux "$source" && is_linux_runner_binary "$TEMP_BINARY"; }; then + local helper_dir + helper_dir=$(dirname "$DOCKER_RUNNER_BINARY") + if [[ -d "$DOCKER_RUNNER_BINARY" || "$DOCKER_RUNNER_BINARY" -ef "$BINARY" ]] || + ! mkdir -p "$helper_dir" || ! TEMP_BINARY=$(mktemp "${helper_dir}/.agentflow-runner.XXXXXX"); then + warn "无法准备 Linux Git/MCP helper 的安装位置:${DOCKER_RUNNER_BINARY}" + return + fi + if stage_docker_runner_binary; then publish_runner_binary "$DOCKER_RUNNER_BINARY" return fi @@ -636,6 +709,28 @@ TEMP_BINARY="" trap '[[ -z "$TEMP_BINARY" ]] || rm -f "$TEMP_BINARY"' EXIT install_binary +configure_macos_docker_runner_helper() { + local pattern="${AGENTFLOW_RUNNER_BINARY:-}" + if [[ "$UPGRADE" == "1" && -f "$PLIST" && -z "${AGENTFLOW_RUNNER_BINARY+x}" ]]; then + pattern=$(/usr/bin/plutil -extract EnvironmentVariables.AGENTFLOW_RUNNER_BINARY raw "$PLIST" 2>/dev/null || true) + fi + # Keep the template expansion in sync with runtime.DockerRunnerHelperPath. + pattern="${pattern#"${pattern%%[![:space:]]*}"}" + pattern="${pattern%"${pattern##*[![:space:]]}"}" + DOCKER_RUNNER_BINARY="${BIN_DIR}/agentflow-runner-linux-${ARCH}" + if [[ "$pattern" == *"{os}"* ]]; then + [[ "$pattern" == /* ]] || pattern="$PWD/$pattern" + DOCKER_RUNNER_BINARY="${pattern//\{os\}/linux}" + DOCKER_RUNNER_BINARY="${DOCKER_RUNNER_BINARY//\{arch\}/$ARCH}" + fi + export AGENTFLOW_RUNNER_BINARY="$pattern" +} + +if [[ "$OS" == "darwin" ]]; then + ARCH=$(macos_runner_arch "$BINARY") + configure_macos_docker_runner_helper +fi + install_gate_binary() { local target_os="$1" target_arch="$2" target target="${GATE_BINARY_PATTERN//\{os\}/$target_os}" @@ -663,6 +758,21 @@ fi if [[ "$UPGRADE" == "1" ]]; then if [[ "$OS" == "darwin" && -f "$PLIST" ]]; then + if [[ "$AUTO_UPDATE" == "0" ]]; then + arg_count=$(/usr/bin/plutil -extract ProgramArguments raw -expect array "$PLIST") + if [[ "$arg_count" -eq 0 ]] || + [[ "$(/usr/bin/plutil -extract "ProgramArguments.$((arg_count - 1))" raw "$PLIST")" != "-auto-update=false" ]]; then + /usr/bin/plutil -insert ProgramArguments -string -auto-update=false -append "$PLIST" + fi + fi + if [[ "$AGENTFLOW_RUNNER_BINARY" == *"{os}"* ]]; then + if ! /usr/bin/plutil -type EnvironmentVariables "$PLIST" >/dev/null 2>&1; then + /usr/bin/plutil -insert EnvironmentVariables -dictionary "$PLIST" + fi + /usr/bin/plutil -replace EnvironmentVariables.AGENTFLOW_RUNNER_BINARY -string "$AGENTFLOW_RUNNER_BINARY" "$PLIST" + elif /usr/bin/plutil -type EnvironmentVariables.AGENTFLOW_RUNNER_BINARY "$PLIST" >/dev/null 2>&1; then + /usr/bin/plutil -remove EnvironmentVariables.AGENTFLOW_RUNNER_BINARY "$PLIST" + fi launchctl unload "$PLIST" launchctl load "$PLIST" info "已原地升级并重启 launchd 服务;机器绑定和工作区保持不变" @@ -687,6 +797,7 @@ AGENTFLOW_RUNNER_BOOTSTRAP_TOKEN=${TOKEN} AGENTFLOW_RUNNER_NAME=${NAME:-$(hostname)} AGENTFLOW_RUNNER_CONCURRENCY=${CONCURRENCY} AGENTFLOW_GATE_MCP_BINARY=${GATE_BINARY_PATTERN} +AGENTFLOW_RUNNER_BINARY=${AGENTFLOW_RUNNER_BINARY:-} EOF chmod 600 "$ENV_FILE" info "配置已写入 ${ENV_FILE}(权限 600)" @@ -720,11 +831,13 @@ EOF # plist 值需要 XML 转义(& 等) ESCAPED_PATH=$(printf '%s' "$USER_PATH" | sed 's/&/\&/g; s//\>/g') ESCAPED_GATE_PATTERN=$(printf '%s' "$GATE_BINARY_PATTERN" | sed 's/&/\&/g; s//\>/g') + ESCAPED_RUNNER_PATTERN=$(printf '%s' "$AGENTFLOW_RUNNER_BINARY" | sed 's/&/\&/g; s//\>/g') cat >> "$PLIST" < EnvironmentVariables PATH${ESCAPED_PATH} AGENTFLOW_GATE_MCP_BINARY${ESCAPED_GATE_PATTERN} + AGENTFLOW_RUNNER_BINARY${ESCAPED_RUNNER_PATTERN} RunAtLoad KeepAlive diff --git a/deploy/bind_cli_docker_runner_test.go b/deploy/bind_cli_docker_runner_test.go index 6629b2b61..7409025c5 100644 --- a/deploy/bind_cli_docker_runner_test.go +++ b/deploy/bind_cli_docker_runner_test.go @@ -3,12 +3,16 @@ package deploy import ( "debug/elf" "encoding/binary" + "encoding/json" "fmt" "net/http" "net/http/httptest" "os" "os/exec" "path/filepath" + "runtime" + "slices" + "strings" "testing" ) @@ -17,23 +21,40 @@ func TestBindCLIInstallsDockerRunnerHelper(t *testing.T) { if err != nil { t.Skip("curl is required for the runner installer") } + script, err := filepath.Abs("bind-cli.sh") + if err != nil { + t.Fatal(err) + } for _, tc := range []struct { - name, hostOS, arch, unameArch string - upgrade bool - helperArtifact, source string - preserveHelper bool + name, hostOS, arch, unameArch string + upgrade, launchd bool + helperArtifact, source, existing string + preserveHelper bool + templatePath bool }{ {name: "macOS_install", hostOS: "darwin", arch: "arm64", unameArch: "arm64"}, + {name: "macOS_creates_nested_runtime_helper_path", hostOS: "darwin", arch: "arm64", unameArch: "arm64", templatePath: true}, {name: "macOS_upgrade", hostOS: "darwin", arch: "amd64", unameArch: "x86_64", upgrade: true}, {name: "Linux_install", hostOS: "linux", arch: "arm64", unameArch: "aarch64"}, {name: "macOS_preserves_helper_on_failed_download", hostOS: "darwin", arch: "arm64", unameArch: "arm64", helperArtifact: "unavailable", preserveHelper: true}, {name: "macOS_preserves_helper_when_server_serves_macOS_binary_for_Linux", hostOS: "darwin", arch: "arm64", unameArch: "arm64", upgrade: true, helperArtifact: "mach-o", preserveHelper: true}, {name: "macOS_preserves_helper_when_server_serves_wrong_architecture", hostOS: "darwin", arch: "amd64", unameArch: "x86_64", upgrade: true, helperArtifact: "wrong-arch", preserveHelper: true}, + {name: "macOS_preserves_helper_when_only_ELF_header_is_served", hostOS: "darwin", arch: "arm64", unameArch: "arm64", upgrade: true, helperArtifact: "truncated-header", preserveHelper: true}, + {name: "macOS_preserves_helper_when_ELF_segment_is_truncated", hostOS: "darwin", arch: "arm64", unameArch: "arm64", upgrade: true, helperArtifact: "truncated-segment", preserveHelper: true}, {name: "macOS_preserves_helper_with_local_runner", hostOS: "darwin", arch: "arm64", unameArch: "arm64", source: "from", preserveHelper: true}, + {name: "macOS_preserves_helper_with_implicit_source_build", hostOS: "darwin", arch: "arm64", unameArch: "arm64", source: "checkout", preserveHelper: true}, + {name: "macOS_upgrades_launchd_with_custom_runner", hostOS: "darwin", arch: "arm64", unameArch: "arm64", source: "from", launchd: true, upgrade: true, preserveHelper: true}, + {name: "macOS_upgrades_launchd_on_template_path", hostOS: "darwin", arch: "arm64", unameArch: "arm64", source: "from", launchd: true, upgrade: true, templatePath: true}, + {name: "macOS_installs_companion_for_Intel_runner_on_arm64", hostOS: "darwin", arch: "amd64", unameArch: "arm64", source: "from"}, + {name: "macOS_repairs_incompatible_local_helper", hostOS: "darwin", arch: "arm64", unameArch: "arm64", source: "from", existing: "mach-o", upgrade: true}, + {name: "macOS_preserves_custom_helper_script", hostOS: "darwin", arch: "arm64", unameArch: "arm64", source: "from", existing: "script", preserveHelper: true}, {name: "macOS_preserves_helper_with_host_only_URL", hostOS: "darwin", arch: "arm64", unameArch: "arm64", source: "host-url", preserveHelper: true}, {name: "macOS_updates_helper_with_explicit_Linux_URL", hostOS: "darwin", arch: "arm64", unameArch: "arm64", source: "template"}, } { t.Run(tc.name, func(t *testing.T) { + if tc.launchd && runtime.GOOS != "darwin" { + t.Skip("requires macOS plutil") + } fixtureHome := t.TempDir() bin := filepath.Join(fixtureHome, "bin") if err := os.Mkdir(bin, 0o755); err != nil { @@ -47,20 +68,34 @@ func TestBindCLIInstallsDockerRunnerHelper(t *testing.T) { oldHelper := bindFixtureLinuxRunner(tc.arch, "old helper") hostRunner := linuxRunner if tc.hostOS == "darwin" { - hostRunner = "\xcf\xfa\xed\xfe" + tc.arch + " macOS runner" + cpu := "\x0c\x00\x00\x01" + if tc.arch == "amd64" { + cpu = "\x07\x00\x00\x01" + } + hostRunner = "\xcf\xfa\xed\xfe" + cpu + " macOS runner" } if tc.source == "from" { - hostRunner = "custom " + hostRunner + hostRunner += " custom" + } + switch tc.existing { + case "mach-o": + oldHelper = "\xcf\xfa\xed\xfe wrong OS" + case "script": + oldHelper = "#!/bin/sh\nexec /opt/runner \"$@\"\n" } server := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, req *http.Request) { targetOS, arch := req.URL.Query().Get("os"), req.URL.Query().Get("arch") - if arch != tc.arch || (targetOS != tc.hostOS && targetOS != "linux") { + if (arch != tc.arch && arch != tc.unameArch) || (targetOS != tc.hostOS && targetOS != "linux") { http.NotFound(w, req) return } switch req.URL.Path { case "/runners/agentflow-runner": if targetOS == tc.hostOS { + if tc.source == "checkout" { + http.NotFound(w, req) + return + } fmt.Fprint(w, hostRunner) return } @@ -71,8 +106,12 @@ func TestBindCLIInstallsDockerRunnerHelper(t *testing.T) { fmt.Fprint(w, hostRunner) case "wrong-arch": fmt.Fprint(w, bindFixtureLinuxRunner("arm64", "new helper")) + case "truncated-header": + fmt.Fprint(w, linuxRunner[:64]) + case "truncated-segment": + fmt.Fprint(w, linuxRunner[:len(linuxRunner)-1]) default: - fmt.Fprint(w, linuxRunner) + fmt.Fprint(w, bindFixtureLinuxRunner(arch, "new helper")) } case "/runners/agentflow-gate-mcp": fmt.Fprintf(w, "gate %s/%s", targetOS, arch) @@ -81,8 +120,13 @@ func TestBindCLIInstallsDockerRunnerHelper(t *testing.T) { } })) defer server.Close() - args := []string{"bind-cli.sh", "--bin-dir", bin, "--no-start"} + args := []string{script, "--bin-dir", bin, "--no-start"} helper := filepath.Join(bin, "agentflow-runner-linux-"+tc.arch) + patternEnv := "" + if tc.templatePath { + patternEnv = filepath.Join(fixtureHome, "bundle", "{os}", "{arch}", "agentflow-runner") + helper = filepath.Join(fixtureHome, "bundle", "linux", tc.arch, "agentflow-runner") + } statePath := filepath.Join(fixtureHome, ".agentflow-runner", "state.json") const state = `{"runnerId":"fixture"}` if tc.upgrade { @@ -114,15 +158,72 @@ func TestBindCLIInstallsDockerRunnerHelper(t *testing.T) { case "template": args = append(args, "--download-url", server.URL+"/runners/agentflow-runner?os={os}&arch={arch}") } - if tc.upgrade || tc.source != "" || tc.preserveHelper { + plist := filepath.Join(fixtureHome, "Library", "LaunchAgents", "com.agentflow.runner.plist") + oldServiceArgs := []string{filepath.Join(bin, "agentflow-runner"), "-labels", "fixture", "-auto-update=true"} + if tc.launchd { + if err := os.MkdirAll(filepath.Dir(plist), 0o700); err != nil { + t.Fatal(err) + } + data := fmt.Sprintf("KeepAliveProgramArguments%s", strings.Join(oldServiceArgs, "")) + if err := os.WriteFile(plist, []byte(data), 0o600); err != nil { + t.Fatal(err) + } + launchctl := "#!/bin/sh\nif [ \"$1\" = load ]; then cp \"$2\" \"$HOME/reloaded.plist\"; fi\n" + if err := os.WriteFile(filepath.Join(bin, "launchctl"), []byte(launchctl), 0o755); err != nil { + t.Fatal(err) + } + } + if (tc.upgrade && !tc.templatePath) || tc.source == "template" || tc.preserveHelper { if err := os.WriteFile(helper, []byte(oldHelper), 0o755); err != nil { t.Fatal(err) } } - cmd := exec.Command("/bin/bash", args...) - cmd.Env = []string{"HOME=" + fixtureHome, "PATH=" + bin + ":" + filepath.Dir(curl) + ":/usr/bin:/bin", "AGENTFLOW_BROWSER=off"} - if out, err := cmd.CombinedOutput(); err != nil { - t.Fatalf("install: %v\n%s", err, out) + if tc.source == "checkout" { + if err := os.MkdirAll(filepath.Join(fixtureHome, "cmd", "agentflow-runner"), 0o700); err != nil { + t.Fatal(err) + } + if err := os.WriteFile(filepath.Join(fixtureHome, "source-host"), []byte(hostRunner), 0o755); err != nil { + t.Fatal(err) + } + goBuild := "#!/bin/sh\n[ \"$GOOS\" = darwin ] && cp \"$HOME/source-host\" \"$3\"\n" + if err := os.WriteFile(filepath.Join(bin, "go"), []byte(goBuild), 0o755); err != nil { + t.Fatal(err) + } + } + install := func() string { + t.Helper() + cmd := exec.Command("/bin/bash", args...) + cmd.Dir = fixtureHome + cmd.Env = []string{"HOME=" + fixtureHome, "PATH=" + bin + ":" + filepath.Dir(curl) + ":/usr/bin:/bin", "AGENTFLOW_BROWSER=off"} + if patternEnv != "" { + cmd.Env = append(cmd.Env, "AGENTFLOW_RUNNER_BINARY="+patternEnv) + } + out, err := cmd.CombinedOutput() + if err != nil { + t.Fatalf("install: %v\n%s", err, out) + } + return string(out) + } + if output := install(); tc.source == "checkout" && !strings.Contains(output, "-auto-update=false") { + t.Fatalf("local source fallback did not disable automatic updates: %s", output) + } + if tc.launchd { + if tc.templatePath { + // Use the saved service path during another upgrade without a shell override. + if err := os.Remove(helper); err != nil { + t.Fatal(err) + } + patternEnv = "" + } + install() // The same upgrade must keep only one disabling argument. + out, err := exec.Command("/usr/bin/plutil", "-extract", "ProgramArguments", "json", "-o", "-", filepath.Join(fixtureHome, "reloaded.plist")).CombinedOutput() + if err != nil { + t.Fatalf("read reloaded launchd arguments: %v %s", err, out) + } + var got []string + if err := json.Unmarshal(out, &got); err != nil || !slices.Equal(got, append(oldServiceArgs, "-auto-update=false")) { + t.Fatalf("launchd started with %q: %v", got, err) + } } assertArtifact := func(path, want string) { t.Helper() @@ -146,6 +247,11 @@ func TestBindCLIInstallsDockerRunnerHelper(t *testing.T) { assertArtifact(helper, linuxRunner) assertArtifact(filepath.Join(bin, "agentflow-gate-mcp-linux-"+tc.arch), "gate linux/"+tc.arch) } + if tc.templatePath { + if _, err := os.Stat(filepath.Join(bin, "agentflow-runner-linux-"+tc.arch)); !os.IsNotExist(err) { + t.Fatalf("the installer also wrote the fallback helper path: %v", err) + } + } if tc.upgrade { if got, err := os.ReadFile(statePath); err != nil || string(got) != state { t.Fatalf("upgrade changed runner state: %q, %v", got, err) @@ -156,7 +262,8 @@ func TestBindCLIInstallsDockerRunnerHelper(t *testing.T) { } func bindFixtureLinuxRunner(arch, payload string) string { - header := make([]byte, 64) + const elfHeaderSize, programHeaderSize = 64, 56 + header := make([]byte, elfHeaderSize+programHeaderSize) copy(header, "\x7fELF\x02\x01\x01\x00") machine := elf.EM_X86_64 if arch == "arm64" { @@ -165,6 +272,15 @@ func bindFixtureLinuxRunner(arch, payload string) string { binary.LittleEndian.PutUint16(header[16:], uint16(elf.ET_EXEC)) binary.LittleEndian.PutUint16(header[18:], uint16(machine)) binary.LittleEndian.PutUint32(header[20:], uint32(elf.EV_CURRENT)) - binary.LittleEndian.PutUint16(header[52:], uint16(len(header))) + binary.LittleEndian.PutUint64(header[32:], elfHeaderSize) + binary.LittleEndian.PutUint16(header[52:], elfHeaderSize) + binary.LittleEndian.PutUint16(header[54:], programHeaderSize) + binary.LittleEndian.PutUint16(header[56:], 1) + program := header[elfHeaderSize:] + binary.LittleEndian.PutUint32(program, uint32(elf.PT_LOAD)) + binary.LittleEndian.PutUint32(program[4:], uint32(elf.PF_R|elf.PF_X)) + size := uint64(len(header) + len(payload)) + binary.LittleEndian.PutUint64(program[32:], size) + binary.LittleEndian.PutUint64(program[40:], size) return string(header) + payload } diff --git a/docs/deployment.md b/docs/deployment.md index 65657d3ee..c2027a6b9 100644 --- a/docs/deployment.md +++ b/docs/deployment.md @@ -133,9 +133,11 @@ The upstream process roles remain `-role api`, `-role worker` and `-role all`. A Personal runners are connected from the execution-machine page with a short-lived binding code. The installer is served at `/runners/install.sh`. `AGENTFLOW_RUNNER_BINARY` can point to binaries with `{os}` and `{arch}` substitutions. Container images bundle Linux/macOS amd64/arm64 runner and gate binaries. Native source installations can build on demand with Go. -The macOS installer places the matching Linux runner next to the macOS executable. Docker workspaces use it for Git credentials and MCP calls. The installer and updater verify the helper's executable format and CPU architecture before replacing it. Custom host installs keep an existing helper. A download URL with an `{os}` placeholder can supply a replacement when used as the runner's download source. +Docker workspaces on macOS use a Linux Runner executable for Git credentials and MCP calls. The installer chooses the architecture of the installed macOS Runner, including Intel binaries running under Rosetta. It places the helper next to the host binary by default. A Runner-side `AGENTFLOW_RUNNER_BINARY` template with `{os}` selects the installation and runtime path, and the installer carries the template into launchd. -When platform updates are enabled, macOS runners synchronize the helper in the background at startup and retry if it is missing or incompatible. The runner can report online and accept work during this check. A Docker workspace that needs a missing helper waits for the initial download attempt. +The installer and updater validate the Linux executable's format, architecture, and load segments before replacing it. Custom installs keep a compatible existing helper. A Runner built from a local checkout can build its companion from that checkout. A download URL with an `{os}` placeholder can supply both binaries when used as the Runner's download source. + +When platform updates are enabled, macOS runners synchronize the helper in the background at startup. A failed version check is retried during rescans, including when an older helper remains usable. Operations that need a missing helper for Git or MCP can wait up to five seconds for the initial sync. The background download continues within its own transfer timeout. A platform administrator can share one CodeBuddy API Key under **Platform administration → Shared CodeBuddy Key** (平台共享 CodeBuddy Key): pick the network environment that issued it and the models members may use (the first is the default). Members without a key of their own then chat and run SOPs on it, limited to those models; a role configured with another model runs on the default and the run says so. Members with their own key keep using it with any model. Scheduled tasks, clarification, reports, bots and run evaluation still need the runner's own key. A scheduled task uses the key for its selected CLI and does not borrow the shared CodeBuddy key. The key is stored in the database like personal keys and is never shown again after saving. `AGENTFLOW_ASSISTANT_SPONSOR_LOGIN`, which lent one account's key limited to `deepseek-v4.1-flash`, still applies while no shared key is configured. diff --git a/internal/runner/daemon.go b/internal/runner/daemon.go index d25db5ce5..a81144fa9 100644 --- a/internal/runner/daemon.go +++ b/internal/runner/daemon.go @@ -161,7 +161,7 @@ func (d *Daemon) Run(ctx context.Context) error { if goruntime.GOOS == "darwin" && !d.cfg.DisableAutoUpdate { d.dockerHelperSyncDone = make(chan struct{}) } - go d.rescanLoop(ctx) + go d.rescanLoop(ctx, 5*time.Minute) heartbeatDone := make(chan struct{}) go func() { defer close(heartbeatDone); d.heartbeatLoop(ctx) }() controlDone := make(chan struct{}) @@ -378,12 +378,13 @@ func (d *Daemon) availableProviders() []string { return providers } -func (d *Daemon) rescanLoop(ctx context.Context) { +func (d *Daemon) rescanLoop(ctx context.Context, interval time.Duration) { + helperSynced := false if d.dockerHelperSyncDone != nil { - d.refreshDockerRunnerHelper(ctx, false) + helperSynced = d.refreshDockerRunnerHelper(ctx, false) close(d.dockerHelperSyncDone) } - ticker := time.NewTicker(5 * time.Minute) + ticker := time.NewTicker(interval) defer ticker.Stop() for { select { @@ -391,7 +392,9 @@ func (d *Daemon) rescanLoop(ctx context.Context) { return case <-ticker.C: d.refreshRuntimes(ctx) - d.refreshDockerRunnerHelper(ctx, true) + if d.dockerHelperSyncDone != nil { + helperSynced = d.refreshDockerRunnerHelper(ctx, helperSynced) + } d.reapIdleRunSandboxes(ctx, runSandboxIdleTTL) } } @@ -543,6 +546,7 @@ func (d *Daemon) executeTask(ctx context.Context, task domain.RunnerTask) { // locks, cloning repositories, creating sandboxes and collecting outputs too. ctx, stopLease := d.keepTaskLease(ctx, task, leaseRenewInterval) defer stopLease() + ctx = d.withDockerRunnerHelperWait(ctx) // The read fence ends before the completion report: once the control plane // sees this task terminal (and lets a paused run continue), a follow-up // preparation or snapshot must not still find the gate held. @@ -773,7 +777,7 @@ func (d *Daemon) executeTerminal(ctx context.Context, task domain.RunnerTask) ex if err := runtime.ProvisionMCPAssets(ctx, sandbox, workspace, bound, nil); err != nil { return execResult{status: domain.RunnerTaskFailed, errMsg: fmt.Sprintf("provision MCP: %v", err)} } - env, err := runtime.ScriptMCPEnvironment(sandbox, workspace, bound.MCPServers) + env, err := runtime.ScriptMCPEnvironment(ctx, sandbox, workspace, bound.MCPServers) if err != nil { return execResult{status: domain.RunnerTaskFailed, errMsg: fmt.Sprintf("prepare mcp call: %v", err)} } @@ -976,7 +980,7 @@ func (d *Daemon) executeInvocation(ctx context.Context, task domain.RunnerTask) gateAssets, _, _ := runtime.PrepareMCPServers(domain.AgentAssetBundle{MCPServers: servers}, d.mcpTarget(false, inv.GitHTTPCredentials)) servers = gateAssets.MCPServers } - mcpEnv, mcpErr := runtime.ScriptMCPEnvironment(sandbox, workspace, servers) + mcpEnv, mcpErr := runtime.ScriptMCPEnvironment(ctx, sandbox, workspace, servers) if mcpErr != nil { return execResult{status: domain.RunnerTaskFailed, errMsg: fmt.Sprintf("prepare mcp call: %v", mcpErr)}, nil } diff --git a/internal/runner/run_sandbox.go b/internal/runner/run_sandbox.go index 0013ad52b..9cd04f29a 100644 --- a/internal/runner/run_sandbox.go +++ b/internal/runner/run_sandbox.go @@ -38,11 +38,6 @@ func (d *Daemon) acquireTaskSandbox(ctx context.Context, task domain.RunnerTask) if task.Sandbox == nil { return nil, nil, fmt.Errorf("frozen run sandbox definition is required") } - if strings.TrimSpace(task.Sandbox.Profile.Driver) == domain.SandboxDriverDocker { - if err := d.waitForDockerRunnerHelper(ctx); err != nil { - return nil, nil, err - } - } requirements, resources := taskSandboxSpec(task) key, id, shared := runSandboxKey(task, requirements, resources) if !shared || d.cfg.DisableRunSandboxReuse { diff --git a/internal/runner/update.go b/internal/runner/update.go index f4f87d9c7..07e582462 100644 --- a/internal/runner/update.go +++ b/internal/runner/update.go @@ -61,17 +61,16 @@ func (d *Daemon) checkGateMCPUpdates(ctx context.Context) error { return nil } -// Sync in the background on startup, then retry missing or incompatible -// helpers during rescans. Conversation requests bypass the SOP claim loop. -func (d *Daemon) refreshDockerRunnerHelper(ctx context.Context, repairOnly bool) { - if runtime.GOOS != "darwin" || d.cfg.DisableAutoUpdate { - return - } - updateCtx, cancel := context.WithTimeout(ctx, 30*time.Second) - defer cancel() - if err := d.checkDockerRunnerHelperUpdate(updateCtx, repairOnly); err != nil && ctx.Err() == nil { - log.Printf("Docker Git/MCP helper update: %v", err) +// Until the first successful sync, a rescan must retry the version check even +// when an older helper is usable. Downloads use the normal updater's timeout. +func (d *Daemon) refreshDockerRunnerHelper(ctx context.Context, repairOnly bool) bool { + if err := d.checkDockerRunnerHelperUpdate(ctx, repairOnly); err != nil { + if ctx.Err() == nil { + log.Printf("Docker Git/MCP helper update: %v", err) + } + return false } + return true } func (d *Daemon) checkDockerRunnerHelperUpdate(ctx context.Context, repairOnly bool) error { @@ -82,28 +81,39 @@ func (d *Daemon) checkDockerRunnerHelperUpdate(ctx context.Context, repairOnly b if repairOnly && validateDockerRunnerHelper(path) == nil { return nil } + if err := os.MkdirAll(filepath.Dir(path), 0o755); err != nil { + return fmt.Errorf("create Docker Git/MCP helper directory: %w", err) + } // Sandboxes copy this executable into the workspace, so an atomic replacement // can run alongside active tasks and requests waiting for the first download. return d.checkCompanionBinaryUpdate(ctx, "Docker Git/MCP helper", d.runnerUpdateEndpoint("linux"), path, validateDockerRunnerHelper, false) } -func (d *Daemon) waitForDockerRunnerHelper(ctx context.Context) error { +func (d *Daemon) withDockerRunnerHelperWait(ctx context.Context) context.Context { if d.dockerHelperSyncDone == nil { - return nil + return ctx } + return flowruntime.WithDockerRunnerHelperWait(ctx, d.waitForDockerRunnerHelper) +} + +func (d *Daemon) waitForDockerRunnerHelper(ctx context.Context, path string) error { select { case <-d.dockerHelperSyncDone: return nil default: } - if path, err := flowruntime.DockerRunnerHelperPath(); err == nil && validateDockerRunnerHelper(path) == nil { + if validateDockerRunnerHelper(path) == nil { return nil } + // A workspace request can give up while the download continues. It never + // controls the downloader's deadline. + waitCtx, cancel := context.WithTimeout(ctx, 5*time.Second) + defer cancel() select { case <-d.dockerHelperSyncDone: return nil - case <-ctx.Done(): - return ctx.Err() + case <-waitCtx.Done(): + return fmt.Errorf("Docker Git/MCP helper is still syncing: %w", waitCtx.Err()) } } @@ -135,6 +145,23 @@ func validateDockerRunnerHelper(path string) error { return fmt.Errorf("expected Linux/%s executable, got ELF %s %s %s %s %s", runtime.GOARCH, file.Class, file.Data, file.Machine, file.OSABI, file.Type) } + size := uint64(info.Size()) + hasExecutableSegment := false + for _, segment := range file.Progs { + if segment.Type != elf.PT_NULL && segment.Filesz > 0 && + (segment.Off > size || segment.Filesz > size-segment.Off) { + return fmt.Errorf("incomplete Linux/%s ELF helper segment", runtime.GOARCH) + } + if segment.Type == elf.PT_LOAD { + if segment.Filesz > segment.Memsz { + return fmt.Errorf("invalid Linux/%s ELF helper load segment", runtime.GOARCH) + } + hasExecutableSegment = hasExecutableSegment || segment.Filesz > 0 && segment.Flags&elf.PF_X != 0 + } + } + if !hasExecutableSegment { + return fmt.Errorf("Linux/%s ELF helper has no executable load segment", runtime.GOARCH) + } return nil } @@ -147,10 +174,7 @@ func (d *Daemon) checkCompanionBinaryUpdate(ctx context.Context, name, endpoint, if err != nil && !os.IsNotExist(err) { return err } - if localHash == metadata.SHA256 { - if validate != nil { - return validate(path) - } + if strings.EqualFold(localHash, metadata.SHA256) && (validate == nil || validate(path) == nil) { return nil } tmp, err := downloadRunnerBinary(ctx, endpoint, path, metadata.SHA256) diff --git a/internal/runner/update_test.go b/internal/runner/update_test.go index 2df6b7683..ed3f898b3 100644 --- a/internal/runner/update_test.go +++ b/internal/runner/update_test.go @@ -199,8 +199,8 @@ func TestDockerRunnerHelperUpdateRepairsMissingBinary(t *testing.T) { t.Fatal(err) } bin := t.TempDir() - t.Setenv("AGENTFLOW_RUNNER_BINARY", filepath.Join(bin, "agentflow-runner-{os}-{arch}")) - helper := filepath.Join(bin, "agentflow-runner-linux-"+runtime.GOARCH) + t.Setenv("AGENTFLOW_RUNNER_BINARY", filepath.Join(bin, "{os}", "{arch}", "agentflow-runner")) + helper := filepath.Join(bin, "linux", runtime.GOARCH, "agentflow-runner") ctx := context.Background() assertHelper := func() { t.Helper() @@ -243,16 +243,26 @@ func TestDockerRunnerHelperUpdateRepairsMissingBinary(t *testing.T) { t.Fatal(err) } assertHelper() + if err := os.Chmod(helper, 0o644); err != nil { + t.Fatal(err) + } + if err := d.checkDockerRunnerHelperUpdate(ctx, true); err != nil { + t.Fatal(err) + } + assertHelper() } -func TestDockerRunnerHelperUpdateRejectsWrongOSOrArchitecture(t *testing.T) { +func TestDockerRunnerHelperUpdateRejectsIncompatibleBinary(t *testing.T) { otherArch := "arm64" if runtime.GOARCH == otherArch { otherArch = "amd64" } + complete := dockerRunnerFixtureLinuxBinary(runtime.GOARCH, "full program") for _, tc := range []struct{ name, payload string }{ {name: "macOS_binary", payload: "\xcf\xfa\xed\xfemacOS runner"}, {name: "wrong_Linux_architecture", payload: dockerRunnerFixtureLinuxBinary(otherArch, "wrong architecture")}, + {name: "only_ELF_header", payload: complete[:64]}, + {name: "truncated_load_segment", payload: complete[:len(complete)-1]}, } { t.Run(tc.name, func(t *testing.T) { hash := sha256.Sum256([]byte(tc.payload)) @@ -385,7 +395,7 @@ func TestDockerRunnerHelperDownloadDoesNotBlockMacOSStartup(t *testing.T) { wait(claim, "task polling") workspaceCtx, cancelWorkspace := context.WithTimeout(ctx, time.Second) defer cancelWorkspace() - if err := d.waitForDockerRunnerHelper(workspaceCtx); err != nil { + if err := d.waitForDockerRunnerHelper(workspaceCtx, helper); err != nil { t.Fatalf("existing helper should be available during the download: %v", err) } close(allowMetadata) @@ -395,8 +405,109 @@ func TestDockerRunnerHelperDownloadDoesNotBlockMacOSStartup(t *testing.T) { }) } +func TestDockerRunnerHelperRescanRetriesFailedVersionCheck(t *testing.T) { + root := t.TempDir() + t.Setenv("HOME", root) + t.Setenv("PATH", "/usr/bin:/bin") + t.Setenv("AGENTFLOW_RUNNER_BINARY", filepath.Join(root, "agentflow-runner-{os}-{arch}")) + helper := filepath.Join(root, "agentflow-runner-linux-"+runtime.GOARCH) + if err := os.WriteFile(helper, []byte(dockerRunnerFixtureLinuxBinary(runtime.GOARCH, "old version")), 0o755); err != nil { + t.Fatal(err) + } + updated := dockerRunnerFixtureLinuxBinary(runtime.GOARCH, "updated version") + hash := sha256.Sum256([]byte(updated)) + var metadataRequests atomic.Int32 + server := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, req *http.Request) { + if req.URL.Query().Get("metadata") == "1" { + if metadataRequests.Add(1) == 1 { + w.WriteHeader(http.StatusServiceUnavailable) + return + } + fmt.Fprintf(w, `{"sha256":%q}`, hex.EncodeToString(hash[:])) + return + } + fmt.Fprint(w, updated) + })) + defer server.Close() + d, err := New(Config{ServerURL: server.URL, BootstrapToken: "fixture"}) + if err != nil { + t.Fatal(err) + } + d.dockerHelperSyncDone = make(chan struct{}) + ctx, cancel := context.WithCancel(t.Context()) + done := make(chan struct{}) + go func() { + defer close(done) + d.rescanLoop(ctx, 50*time.Millisecond) + }() + defer func() { cancel(); <-done }() + waitFor(t, 5*time.Second, "rescan to replace the old helper after a failed startup sync", func() bool { + data, err := os.ReadFile(helper) + return err == nil && string(data) == updated + }) + if got := metadataRequests.Load(); got != 2 { + t.Fatalf("metadata requests = %d, want a failed check and one retry", got) + } +} + +func TestDockerRunnerHelperSlowDownloadOutlivesWorkspaceWait(t *testing.T) { + root := t.TempDir() + t.Setenv("AGENTFLOW_RUNNER_BINARY", filepath.Join(root, "agentflow-runner-{os}-{arch}")) + helper := filepath.Join(root, "agentflow-runner-linux-"+runtime.GOARCH) + binary := dockerRunnerFixtureLinuxBinary(runtime.GOARCH, "complete slow download") + hash := sha256.Sum256([]byte(binary)) + downloading := make(chan struct{}) + server := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, req *http.Request) { + if req.URL.Query().Get("metadata") == "1" { + fmt.Fprintf(w, `{"sha256":%q}`, hex.EncodeToString(hash[:])) + return + } + fmt.Fprint(w, binary[:64]) + w.(http.Flusher).Flush() + close(downloading) + // Keep the transfer active beyond the old shared 30-second deadline. + timer := time.NewTimer(31 * time.Second) + defer timer.Stop() + select { + case <-timer.C: + fmt.Fprint(w, binary[64:]) + case <-req.Context().Done(): + } + })) + defer server.Close() + d, err := New(Config{ServerURL: server.URL, BootstrapToken: "fixture"}) + if err != nil { + t.Fatal(err) + } + d.dockerHelperSyncDone = make(chan struct{}) + ctx, cancel := context.WithCancel(t.Context()) + done := make(chan struct{}) + go func() { + defer close(done) + d.rescanLoop(ctx, time.Hour) + }() + defer func() { cancel(); <-done }() + select { + case <-downloading: + case <-time.After(5 * time.Second): + t.Fatal("helper download did not start") + } + if err := d.waitForDockerRunnerHelper(ctx, helper); !errors.Is(err, context.DeadlineExceeded) { + t.Fatalf("workspace wait = %v, want its own deadline", err) + } + select { + case <-d.dockerHelperSyncDone: + case <-time.After(40 * time.Second): + t.Fatal("helper sync did not complete") + } + if data, err := os.ReadFile(helper); err != nil || string(data) != binary { + t.Fatalf("slow transfer did not publish the verified helper: %q, %v", data, err) + } +} + func dockerRunnerFixtureLinuxBinary(arch, payload string) string { - header := make([]byte, 64) + const elfHeaderSize, programHeaderSize = 64, 56 + header := make([]byte, elfHeaderSize+programHeaderSize) copy(header, "\x7fELF\x02\x01\x01\x00") machine := elf.EM_X86_64 if arch == "arm64" { @@ -405,7 +516,16 @@ func dockerRunnerFixtureLinuxBinary(arch, payload string) string { binary.LittleEndian.PutUint16(header[16:], uint16(elf.ET_EXEC)) binary.LittleEndian.PutUint16(header[18:], uint16(machine)) binary.LittleEndian.PutUint32(header[20:], uint32(elf.EV_CURRENT)) - binary.LittleEndian.PutUint16(header[52:], uint16(len(header))) + binary.LittleEndian.PutUint64(header[32:], elfHeaderSize) + binary.LittleEndian.PutUint16(header[52:], elfHeaderSize) + binary.LittleEndian.PutUint16(header[54:], programHeaderSize) + binary.LittleEndian.PutUint16(header[56:], 1) + program := header[elfHeaderSize:] + binary.LittleEndian.PutUint32(program, uint32(elf.PT_LOAD)) + binary.LittleEndian.PutUint32(program[4:], uint32(elf.PF_R|elf.PF_X)) + size := uint64(len(header) + len(payload)) + binary.LittleEndian.PutUint64(program[32:], size) + binary.LittleEndian.PutUint64(program[40:], size) return string(header) + payload } diff --git a/internal/runner/workspace.go b/internal/runner/workspace.go index 57842f0b2..4889c0fdd 100644 --- a/internal/runner/workspace.go +++ b/internal/runner/workspace.go @@ -120,6 +120,7 @@ func (d *Daemon) readRunnerWorkspace(ctx context.Context, request domain.RunnerW if d.updateReady.Load() { return domain.RunnerWorkspaceResponse{Status: http.StatusConflict, Error: "Runner 即将重启,请稍后重试"} } + ctx = d.withDockerRunnerHelperWait(ctx) if request.Operation == "conversation_process" { return d.conversationProcess(ctx, request) } diff --git a/internal/runner/workspace_browser_test.go b/internal/runner/workspace_browser_test.go index 15b146402..44611c6f6 100644 --- a/internal/runner/workspace_browser_test.go +++ b/internal/runner/workspace_browser_test.go @@ -3,11 +3,17 @@ package runner import ( "context" "encoding/json" + "fmt" "net/http" + "net/http/httptest" + "os" + "path/filepath" "testing" "time" "agentflow/internal/domain" + + "github.com/gorilla/websocket" ) func TestHandleRunnerWorkspaceBrowserRejectsMissingBrowser(t *testing.T) { @@ -52,6 +58,102 @@ func TestHandleRunnerWorkspaceBrowserReportsEnsureFailure(t *testing.T) { } } +func TestDockerBrowserRequestsDoNotWaitForRunnerHelper(t *testing.T) { + root := t.TempDir() + t.Setenv("AGENTFLOW_BROWSER", "always") + t.Setenv("AGENTFLOW_RUNNER_BINARY", filepath.Join(root, "{os}", "{arch}", "agentflow-runner")) + // Exercise the Docker browser path without launching a real browser. + if err := os.WriteFile(filepath.Join(root, "docker"), []byte("#!/bin/sh\nexit 1\n"), 0o755); err != nil { + t.Fatal(err) + } + t.Setenv("PATH", root+":/usr/bin:/bin") + + const runID = "browser-helper-sync" + if err := os.MkdirAll(filepath.Join(root, "runs", runID, "workspace"), 0o700); err != nil { + t.Fatal(err) + } + request := domain.RunnerWorkspaceRequest{ + RunID: runID, WorkspaceLayout: domain.RunnerWorkspaceLayoutShared, + Operation: domain.RunnerWorkspaceOperationBrowser, Browser: &domain.BrowserRequest{Ensure: true}, + Sandbox: &domain.RunnerSandboxSpec{ + Profile: domain.SandboxProfile{Driver: domain.SandboxDriverDocker}, + Dockerfile: &domain.DockerfileDefinition{Content: "FROM fixture"}, + }, + Workflow: &domain.WorkflowDefinition{}, + } + upgrader := websocket.Upgrader{} + result := make(chan error, 1) + probe := func(conn *websocket.Conn) error { + if err := conn.SetReadDeadline(time.Now().Add(4 * time.Second)); err != nil { + return err + } + var hello controlMessage + if err := conn.ReadJSON(&hello); err != nil { + return err + } + const slots = 8 + for index := range slots { + if err := conn.WriteJSON(controlMessage{ + Type: "workspace.request", RequestID: fmt.Sprint(index), WorkspaceRequest: &request, + }); err != nil { + return err + } + } + for range slots { + var response controlMessage + if err := conn.ReadJSON(&response); err != nil { + return fmt.Errorf("browser requests waited for the helper: %w", err) + } + if response.WorkspaceResponse == nil || response.WorkspaceResponse.Status != http.StatusOK { + return fmt.Errorf("unexpected browser response: %+v", response.WorkspaceResponse) + } + } + info := domain.RunnerWorkspaceRequest{RunID: runID, WorkspaceLayout: domain.RunnerWorkspaceLayoutShared, Operation: domain.RunnerWorkspaceOperationInfo} + if err := conn.WriteJSON(controlMessage{Type: "workspace.request", RequestID: "info", WorkspaceRequest: &info}); err != nil { + return err + } + var response controlMessage + if err := conn.ReadJSON(&response); err != nil { + return err + } + if response.WorkspaceResponse == nil || response.WorkspaceResponse.Status != http.StatusOK { + return fmt.Errorf("workspace info did not have a free slot: %+v", response.WorkspaceResponse) + } + return nil + } + server := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, req *http.Request) { + conn, err := upgrader.Upgrade(w, req, nil) + if err != nil { + result <- err + return + } + defer conn.Close() + result <- probe(conn) + })) + defer server.Close() + d, err := New(Config{ServerURL: server.URL, BootstrapToken: "fixture", DefaultWorkspaceRoot: root}) + if err != nil { + t.Fatal(err) + } + // Model a cold start whose first helper download is still in flight. + d.dockerHelperSyncDone = make(chan struct{}) + ctx, cancel := context.WithCancel(t.Context()) + done := make(chan struct{}) + go func() { + defer close(done) + d.controlLoop(ctx) + }() + defer func() { cancel(); <-done }() + select { + case err := <-result: + if err != nil { + t.Fatal(err) + } + case <-time.After(5 * time.Second): + t.Fatal("control loop did not complete the browser and workspace requests") + } +} + // 只读操作(status/frame)不续期沙箱,写操作续期;HandleBrowser 报错映射为 409。 func TestHandleRunnerWorkspaceBrowserTouchesSandboxOnlyForWrites(t *testing.T) { const runID = "run-browser-touch" diff --git a/internal/runtime/agent_cli_integration_test.go b/internal/runtime/agent_cli_integration_test.go index fb5eb0aff..bd00189c7 100644 --- a/internal/runtime/agent_cli_integration_test.go +++ b/internal/runtime/agent_cli_integration_test.go @@ -23,7 +23,7 @@ type credentialSandbox struct { } func (s credentialSandbox) Exec(ctx context.Context, command CommandSpec, sink EventSink) (string, error) { - bound, err := bindCommand(s.localSandbox, s.workspace, command, s.credentials) + bound, err := bindCommand(ctx, s.localSandbox, s.workspace, command, s.credentials) if err != nil { return "", err } diff --git a/internal/runtime/agent_cli_test.go b/internal/runtime/agent_cli_test.go index c518421da..ff6a1cbb6 100644 --- a/internal/runtime/agent_cli_test.go +++ b/internal/runtime/agent_cli_test.go @@ -396,7 +396,7 @@ func TestBindCommandRejectsSymlinkedParentsBeforeWritingCredentials(t *testing.T credentials := RunCredentials{AgentCLI: map[string]ProviderCredential{ kind: {APIKey: "fake-test-key", BaseURL: "https://example.test"}, }} - if _, err := bindCommand(sb, workspace, command, credentials); err == nil { + if _, err := bindCommand(t.Context(), sb, workspace, command, credentials); err == nil { t.Fatal("symlinked private-home component was accepted") } entries, err := os.ReadDir(outside) @@ -428,7 +428,7 @@ func TestBindAgentCLICommandRejectsSymlinkedPrivateHome(t *testing.T) { if _, _, err := BindAgentCLICommand(sb, workspace, command, ProviderCredential{APIKey: "secret-key", BaseURL: "https://example.test"}, command.Argv); err == nil { t.Fatal("symlinked private home was accepted") } - if _, err := bindCommand(sb, workspace, command, RunCredentials{}); err == nil { + if _, err := bindCommand(t.Context(), sb, workspace, command, RunCredentials{}); err == nil { t.Fatal("bindCommand accepted a symlinked private home") } if entries, _ := os.ReadDir(outside); len(entries) != 0 { diff --git a/internal/runtime/agent_cli_zcode_test.go b/internal/runtime/agent_cli_zcode_test.go index e9c8ace03..49f6e5bea 100644 --- a/internal/runtime/agent_cli_zcode_test.go +++ b/internal/runtime/agent_cli_zcode_test.go @@ -290,7 +290,7 @@ func TestZCodeBindCommandComposition(t *testing.T) { command.CredentialBindings = []CredentialBinding{BindAgentCLI, BindGit, BindMCP} command.PrivateHome = true command.PrivateHomeKey = "zcode-a" - bound, err := bindCommand(sb, workspace, command, RunCredentials{AgentCLI: map[string]ProviderCredential{AgentCLIZCode: {APIKey: "k"}}}) + bound, err := bindCommand(t.Context(), sb, workspace, command, RunCredentials{AgentCLI: map[string]ProviderCredential{AgentCLIZCode: {APIKey: "k"}}}) if err != nil { t.Fatal(err) } diff --git a/internal/runtime/cli_live_test.go b/internal/runtime/cli_live_test.go index b2b6e12c5..c545ab29f 100644 --- a/internal/runtime/cli_live_test.go +++ b/internal/runtime/cli_live_test.go @@ -93,7 +93,7 @@ func runLiveSOP(t *testing.T, root, kind, driver string, item liveCLIConfig) { out = redactLive(out) if err != nil { shown := command.Argv - if bound, berr := bindCommand(sb, workspace, command, creds); berr == nil { + if bound, berr := bindCommand(t.Context(), sb, workspace, command, creds); berr == nil { shown = bound.Argv } t.Fatalf("执行失败: %s\nargv=%q\n%s", redactLive(err.Error()), shown, clipLive(out)) diff --git a/internal/runtime/command_binding.go b/internal/runtime/command_binding.go index fa4f155d3..c67768887 100644 --- a/internal/runtime/command_binding.go +++ b/internal/runtime/command_binding.go @@ -4,6 +4,7 @@ import ( "agentflow/internal/domain" "agentflow/internal/gitwork" "agentflow/internal/observability" + "context" "fmt" "os" "path/filepath" @@ -32,7 +33,7 @@ func upsertEnv(env []string, key, value string) []string { return out } -func bindCommand(sandbox Sandbox, workspace string, command CommandSpec, credentials RunCredentials) (CommandSpec, error) { +func bindCommand(ctx context.Context, sandbox Sandbox, workspace string, command CommandSpec, credentials RunCredentials) (CommandSpec, error) { if command.bindingsPrepared { return command, nil } @@ -114,11 +115,11 @@ func bindCommand(sandbox Sandbox, workspace string, command CommandSpec, credent } bound.environment["CODEBUDDY_INTERNET_ENVIRONMENT"] = strings.TrimSpace(credentials.CodeBuddy.InternetEnvironment) case BindGit: - if err := bindWorkspaceGitEnvironment(sandbox, workspace, bound.environment, credentials); err != nil { + if err := bindWorkspaceGitEnvironment(ctx, sandbox, workspace, bound.environment, credentials); err != nil { return CommandSpec{}, err } case BindGitWorkspace: - if err := bindWorkspaceGitEnvironment(sandbox, workspace, bound.environment, credentials); err != nil { + if err := bindWorkspaceGitEnvironment(ctx, sandbox, workspace, bound.environment, credentials); err != nil { return CommandSpec{}, err } case BindExtra: @@ -130,7 +131,7 @@ func bindCommand(sandbox Sandbox, workspace string, command CommandSpec, credent bound.credentialEnvKeys = append(bound.credentialEnvKeys, envName) } case BindMCP: - if err := bindMCPCallEnvironment(sandbox, workspace, bound.environment, credentials.MCPServers); err != nil { + if err := bindMCPCallEnvironment(ctx, sandbox, workspace, bound.environment, credentials.MCPServers); err != nil { return CommandSpec{}, err } bound.Argv = BindMCPCallArgv(sandbox, bound.Argv) @@ -302,7 +303,7 @@ func privateHomePaths(sandbox Sandbox, workspace string, command CommandSpec) (h // bindWorkspaceGitEnvironment installs the standard host-scoped helper. // It requests credentials through a live relay rather than writing tokens. -func bindWorkspaceGitEnvironment(sandbox Sandbox, workspace string, environment map[string]string, credentials RunCredentials) error { +func bindWorkspaceGitEnvironment(ctx context.Context, sandbox Sandbox, workspace string, environment map[string]string, credentials RunCredentials) error { environment["GIT_TERMINAL_PROMPT"] = "0" if _, err := EnsureControlDirectory(workspace, "runtime"); err != nil { return fmt.Errorf("create git runtime dir: %w", err) @@ -346,7 +347,7 @@ func bindWorkspaceGitEnvironment(sandbox Sandbox, workspace string, environment if _, err := EnsureControlDirectory(workspace, "runtime", "bin"); err != nil { return fmt.Errorf("create git helper dir: %w", err) } - if err := installMCPCallHelperForSandbox(sandbox, workspace, filepath.Join(hostBin, "agentflow-helper")); err != nil { + if err := installMCPCallHelperForSandbox(ctx, sandbox, workspace, filepath.Join(hostBin, "agentflow-helper")); err != nil { return fmt.Errorf("install git credential helper: %w", err) } helper := runtimePath("bin/agentflow-helper") diff --git a/internal/runtime/command_binding_telemetry_test.go b/internal/runtime/command_binding_telemetry_test.go index 48add7aea..bddc9ec27 100644 --- a/internal/runtime/command_binding_telemetry_test.go +++ b/internal/runtime/command_binding_telemetry_test.go @@ -38,14 +38,14 @@ func TestBindTelemetryEnvironmentSetsCollectorAndRunTags(t *testing.T) { func TestBindCommandAppliesTelemetryEnvironment(t *testing.T) { t.Setenv("AGENTFLOW_OTEL_TRACES_ENDPOINT", "http://collector.test/v1/traces") workspace := t.TempDir() - plain, err := bindCommand(&localSandbox{workspace: workspace}, workspace, CommandSpec{Argv: []string{"true"}}, RunCredentials{}) + plain, err := bindCommand(t.Context(), &localSandbox{workspace: workspace}, workspace, CommandSpec{Argv: []string{"true"}}, RunCredentials{}) if err != nil { t.Fatal(err) } if _, ok := plain.environment["AGENTFLOW_RUN_ID"]; ok { t.Fatalf("command without telemetry got telemetry env: %#v", plain.environment) } - traced, err := bindCommand(&localSandbox{workspace: workspace}, workspace, CommandSpec{Argv: []string{"true"}, Telemetry: &InvocationOptions{RunID: "run-2", NodeID: "node-b"}}, RunCredentials{}) + traced, err := bindCommand(t.Context(), &localSandbox{workspace: workspace}, workspace, CommandSpec{Argv: []string{"true"}, Telemetry: &InvocationOptions{RunID: "run-2", NodeID: "node-b"}}, RunCredentials{}) if err != nil { t.Fatal(err) } diff --git a/internal/runtime/command_binding_workspace_git_test.go b/internal/runtime/command_binding_workspace_git_test.go index e1799fd7b..ff62acd35 100644 --- a/internal/runtime/command_binding_workspace_git_test.go +++ b/internal/runtime/command_binding_workspace_git_test.go @@ -129,7 +129,7 @@ func TestBindGitWorkspaceResetsCLIConfig(t *testing.T) { workspace := t.TempDir() sb := &localSandbox{workspace: workspace, driver: "docker"} env := map[string]string{SessionGatewayEnv: "http://relay.invalid/mcp"} - if err := bindWorkspaceGitEnvironment(sb, workspace, env, RunCredentials{GitHTTPHosts: map[string]string{"github.com": "github"}}); err != nil { + if err := bindWorkspaceGitEnvironment(t.Context(), sb, workspace, env, RunCredentials{GitHTTPHosts: map[string]string{"github.com": "github"}}); err != nil { t.Fatal(err) } stale := filepath.Join(workspace, ".agentflow", "runtime", "gh-config", "hosts.yml") @@ -137,7 +137,7 @@ func TestBindGitWorkspaceResetsCLIConfig(t *testing.T) { t.Fatal(err) } env = map[string]string{SessionGatewayEnv: "http://relay.invalid/mcp"} - if err := bindWorkspaceGitEnvironment(sb, workspace, env, RunCredentials{GitHTTPHosts: map[string]string{"github.com": "github"}}); err != nil { + if err := bindWorkspaceGitEnvironment(t.Context(), sb, workspace, env, RunCredentials{GitHTTPHosts: map[string]string{"github.com": "github"}}); err != nil { t.Fatal(err) } if _, err := os.Stat(stale); !os.IsNotExist(err) { diff --git a/internal/runtime/conversation_process.go b/internal/runtime/conversation_process.go index c85c02fdc..53d61ea0f 100644 --- a/internal/runtime/conversation_process.go +++ b/internal/runtime/conversation_process.go @@ -643,7 +643,7 @@ func (p *ConversationProcessPool) start(ctx context.Context, root, workspace str } } nativeArgv := append([]string(nil), command.Argv...) - command, err = bindCommand(bindSandbox, bindWorkspace, command, req.Command.Credentials) + command, err = bindCommand(procCtx, bindSandbox, bindWorkspace, command, req.Command.Credentials) if err != nil { return ConversationProcessResult{}, err } diff --git a/internal/runtime/docker_cases_test.go b/internal/runtime/docker_cases_test.go index fb2ad5643..f390d1a24 100644 --- a/internal/runtime/docker_cases_test.go +++ b/internal/runtime/docker_cases_test.go @@ -44,7 +44,7 @@ func TestDockerSandboxLifecycleWithFakeCLI(t *testing.T) { t.Fatalf("sandbox=%+v", sb) } const extraValue = "test-extra-credential" - command, err := bindCommand(sb, workspace, CommandSpec{ + command, err := bindCommand(t.Context(), sb, workspace, CommandSpec{ Argv: []string{"sh", "-lc", "echo ok"}, CredentialBindings: []CredentialBinding{BindExtra}, ExtraCredentialEnv: map[string]string{"DEPLOYMENT_VALUE": "registry"}, diff --git a/internal/runtime/managed_files_test.go b/internal/runtime/managed_files_test.go index 3a7a63ac0..4ad0ddd9d 100644 --- a/internal/runtime/managed_files_test.go +++ b/internal/runtime/managed_files_test.go @@ -169,7 +169,7 @@ func TestPrepareMCPCallRejectsSymlinks(t *testing.T) { if err := os.Symlink(victim, target); err != nil { t.Fatal(err) } - if _, err := PrepareMCPCall(nil, workspace, nil); err == nil { + if _, err := PrepareMCPCall(t.Context(), nil, workspace, nil); err == nil { t.Fatal("symlink accepted") } if victim != outside { diff --git a/internal/runtime/mcp_call.go b/internal/runtime/mcp_call.go index a6b92e8e9..6483ece31 100644 --- a/internal/runtime/mcp_call.go +++ b/internal/runtime/mcp_call.go @@ -57,7 +57,7 @@ func mcpCallGuestPath(rel string) string { // PrepareMCPCall writes the script-node helper (`agentflow mcp call`) and bound // MCP server list into the workspace. Tokens stay in a 0600 file; they are not // exported as environment variables. -func PrepareMCPCall(sandbox Sandbox, workspace string, servers []domain.MCPServerDefinition) (map[string]string, error) { +func PrepareMCPCall(ctx context.Context, sandbox Sandbox, workspace string, servers []domain.MCPServerDefinition) (map[string]string, error) { hostRoot := mcpCallHostDir(workspace) hostBin := filepath.Join(hostRoot, "bin") if _, err := EnsureControlDirectory(workspace, "runtime", "bin"); err != nil { @@ -80,7 +80,7 @@ func PrepareMCPCall(sandbox Sandbox, workspace string, servers []domain.MCPServe return nil, fmt.Errorf("write mcp call config: %w", err) } helperHost := filepath.Join(hostBin, "agentflow-helper") - if err := installMCPCallHelperForSandbox(sandbox, workspace, helperHost); err != nil { + if err := installMCPCallHelperForSandbox(ctx, sandbox, workspace, helperHost); err != nil { return nil, err } wrapperHost := filepath.Join(hostBin, "agentflow") @@ -168,7 +168,15 @@ func installMCPCallHelper(workspace, dest string) error { return installMCPCallHelperFrom(workspace, src, dest) } -func installMCPCallHelperForSandbox(sandbox Sandbox, workspace, dest string) error { +type dockerRunnerHelperWaitKey struct{} + +// WithDockerRunnerHelperWait lets a personal Runner wait for its background +// download when a command actually needs the Linux Git/MCP executable. +func WithDockerRunnerHelperWait(ctx context.Context, wait func(context.Context, string) error) context.Context { + return context.WithValue(ctx, dockerRunnerHelperWaitKey{}, wait) +} + +func installMCPCallHelperForSandbox(ctx context.Context, sandbox Sandbox, workspace, dest string) error { if sandboxDriver(sandbox) != "docker" || goruntime.GOOS == "linux" { return installMCPCallHelper(workspace, dest) } @@ -176,6 +184,11 @@ func installMCPCallHelperForSandbox(sandbox Sandbox, workspace, dest string) err if err != nil { return err } + if wait, ok := ctx.Value(dockerRunnerHelperWaitKey{}).(func(context.Context, string) error); ok { + if err := wait(ctx, src); err != nil { + return err + } + } if _, err := os.Stat(src); err != nil { return fmt.Errorf("Docker Git/MCP helper requires a Linux runner binary: set AGENTFLOW_RUNNER_BINARY with {os} and {arch}: %w", err) } @@ -254,8 +267,8 @@ func mcpCallAliases(server domain.MCPServerDefinition) []string { return out } -func bindMCPCallEnvironment(sandbox Sandbox, workspace string, environment map[string]string, servers []domain.MCPServerDefinition) error { - prepared, err := PrepareMCPCall(sandbox, workspace, servers) +func bindMCPCallEnvironment(ctx context.Context, sandbox Sandbox, workspace string, environment map[string]string, servers []domain.MCPServerDefinition) error { + prepared, err := PrepareMCPCall(ctx, sandbox, workspace, servers) if err != nil { return err } @@ -344,9 +357,9 @@ func wrapIsolatedMCPCallExec(argv []string) []string { // ScriptMCPEnvironment materializes agentflow mcp call and returns AGENTFLOW_BIN // plus the config path. It does not rewrite PATH for local/unisolated processes. -func ScriptMCPEnvironment(sandbox Sandbox, workspace string, servers []domain.MCPServerDefinition) (map[string]string, error) { +func ScriptMCPEnvironment(ctx context.Context, sandbox Sandbox, workspace string, servers []domain.MCPServerDefinition) (map[string]string, error) { env := map[string]string{} - if err := bindMCPCallEnvironment(sandbox, workspace, env, servers); err != nil { + if err := bindMCPCallEnvironment(ctx, sandbox, workspace, env, servers); err != nil { return nil, err } return env, nil diff --git a/internal/runtime/mcp_call_test.go b/internal/runtime/mcp_call_test.go index 9676c9e6f..42e9b7818 100644 --- a/internal/runtime/mcp_call_test.go +++ b/internal/runtime/mcp_call_test.go @@ -75,7 +75,7 @@ func TestMCPCallCLIInvokesBoundHTTPServer(t *testing.T) { ID: "mcp-2214-project-dns", Name: "Config Center MCP", MarketID: "2214", Transport: "http", URL: gateway.URL, Headers: map[string]string{"Authorization": "Bearer mcp-token"}, }}} - env, err := ScriptMCPEnvironment(sb, workspace, assets.MCPServers) + env, err := ScriptMCPEnvironment(t.Context(), sb, workspace, assets.MCPServers) if err != nil { t.Fatal(err) } @@ -100,7 +100,7 @@ func TestMCPCallRequiresPersonalCredentialAtCallTime(t *testing.T) { if err != nil { t.Fatal(err) } - env, err := ScriptMCPEnvironment(sb, workspace, assets.MCPServers) + env, err := ScriptMCPEnvironment(t.Context(), sb, workspace, assets.MCPServers) if err != nil { t.Fatal(err) } @@ -117,7 +117,7 @@ func TestBindMCPWritesWorkspaceBinWithoutPATH(t *testing.T) { workspace := t.TempDir() sb := &localSandbox{workspace: workspace, environment: map[string]string{"PATH": "/usr/bin"}} command := CommandSpec{Argv: []string{"sh", "-lc", "agentflow mcp list"}, CredentialBindings: []CredentialBinding{BindMCP}} - bound, err := bindCommand(sb, workspace, command, RunCredentials{MCPServers: []domain.MCPServerDefinition{{ + bound, err := bindCommand(t.Context(), sb, workspace, command, RunCredentials{MCPServers: []domain.MCPServerDefinition{{ ID: "tapd", Name: "TAPD", Transport: "http", URL: "https://example.com/tapd", }}}) if err != nil { @@ -152,7 +152,7 @@ func TestDockerMCPCallPointsAtWorkspaceBin(t *testing.T) { provideDockerHelperFixture(t) workspace := t.TempDir() sb := &localSandbox{workspace: workspace, driver: "docker"} - env, err := ScriptMCPEnvironment(sb, workspace, []domain.MCPServerDefinition{{ + env, err := ScriptMCPEnvironment(t.Context(), sb, workspace, []domain.MCPServerDefinition{{ ID: "tapd", Name: "TAPD", Transport: "http", URL: "https://example.com/tapd", }}) if err != nil { @@ -198,10 +198,45 @@ func provideDockerHelperFixture(t *testing.T) { t.Setenv("AGENTFLOW_RUNNER_BINARY", pattern) } +func TestDockerHelperBindingWaitsForTheRunnerArtifact(t *testing.T) { + if goruntime.GOOS == "linux" { + t.Skip("a Linux Runner uses its own executable") + } + for _, use := range []string{"git", "mcp"} { + t.Run(use, func(t *testing.T) { + root := t.TempDir() + t.Setenv("AGENTFLOW_RUNNER_BINARY", filepath.Join(root, "runner-{os}-{arch}")) + helper := filepath.Join(root, "runner-linux-"+goruntime.GOARCH) + workspace := t.TempDir() + sb := &localSandbox{workspace: workspace, driver: "docker"} + const payload = "#!/bin/sh\nexit 0\n" + ctx := WithDockerRunnerHelperWait(t.Context(), func(ctx context.Context, path string) error { + if path != helper { + t.Fatalf("waited for %q, want %q", path, helper) + } + return os.WriteFile(path, []byte(payload), 0o755) + }) + var err error + if use == "git" { + env := map[string]string{SessionGatewayEnv: "http://fixture.invalid"} + err = bindWorkspaceGitEnvironment(ctx, sb, workspace, env, RunCredentials{GitHTTPHosts: map[string]string{"git.fixture.invalid": "other"}}) + } else { + _, err = PrepareMCPCall(ctx, sb, workspace, nil) + } + if err != nil { + t.Fatal(err) + } + if got, err := os.ReadFile(filepath.Join(mcpCallHostDir(workspace), "bin", "agentflow-helper")); err != nil || string(got) != payload { + t.Fatalf("workspace helper = %q, %v", got, err) + } + }) + } +} + func TestProcessSandboxMCPCallUsesAbsoluteManagedLauncher(t *testing.T) { workspace := t.TempDir() sb := &localSandbox{workspace: workspace, driver: "bwrap"} - env, err := PrepareMCPCall(sb, workspace, []domain.MCPServerDefinition{{ + env, err := PrepareMCPCall(t.Context(), sb, workspace, []domain.MCPServerDefinition{{ ID: "replace-batch", Name: "Replace Batch", Transport: "stdio", Command: "python3", Args: []string{"server.py"}, FileRefs: []domain.MCPFileRef{{Path: "server.py"}}, }}) if err != nil { @@ -263,7 +298,7 @@ func TestHookScriptCanCallMCP(t *testing.T) { } sb := &localSandbox{workspace: workspace} command := CommandSpec{Argv: []string{"sh", "-lc", compiled[0].Command}, CredentialBindings: []CredentialBinding{BindMCP}} - bound, err := bindCommand(sb, workspace, command, RunCredentials{MCPServers: []domain.MCPServerDefinition{{ + bound, err := bindCommand(t.Context(), sb, workspace, command, RunCredentials{MCPServers: []domain.MCPServerDefinition{{ ID: "tapd", Name: "TAPD", MarketID: "70", Transport: "http", URL: "https://example.com/tapd", }}}) if err != nil { diff --git a/internal/runtime/mcp_stdio_test.go b/internal/runtime/mcp_stdio_test.go index b6db2c8ab..cefef34cc 100644 --- a/internal/runtime/mcp_stdio_test.go +++ b/internal/runtime/mcp_stdio_test.go @@ -20,7 +20,7 @@ read initialized read request printf '%s\n' '{"jsonrpc":"2.0","id":2,"result":{"content":[{"type":"text","text":"stdio-ok"}]}}'` servers := []domain.MCPServerDefinition{{ID: "local", Name: "Local", Transport: "stdio", Command: "sh", Args: []string{"-c", serverScript}, TimeoutSec: 5}} - env, err := ScriptMCPEnvironment(sb, workspace, servers) + env, err := ScriptMCPEnvironment(t.Context(), sb, workspace, servers) if err != nil { t.Fatal(err) } diff --git a/internal/runtime/provider_credentials_test.go b/internal/runtime/provider_credentials_test.go index 08de2ce6a..25896c649 100644 --- a/internal/runtime/provider_credentials_test.go +++ b/internal/runtime/provider_credentials_test.go @@ -25,7 +25,7 @@ func TestProviderCredentialBindingIsolation(t *testing.T) { if err != nil { t.Fatal(err) } - bound, err := bindCommand(sb, workspace, command, creds) + bound, err := bindCommand(t.Context(), sb, workspace, command, creds) if err != nil { t.Fatal(err) } @@ -66,13 +66,13 @@ func TestProviderCredentialBindingIsolation(t *testing.T) { t.Fatalf("subprocess environment failed: %v", err) } // Without a responsible user's key, no host credential may be reused. - _, err = bindCommand(sb, workspace, command, RunCredentials{}) + _, err = bindCommand(t.Context(), sb, workspace, command, RunCredentials{}) if err == nil || !strings.Contains(err.Error(), "未配置") { t.Fatal("missing user key must fail before any CLI can reuse host login") } }) } - plain, err := bindCommand(&localSandbox{workspace: t.TempDir()}, t.TempDir(), CommandSpec{Argv: []string{"true"}}, creds) + plain, err := bindCommand(t.Context(), &localSandbox{workspace: t.TempDir()}, t.TempDir(), CommandSpec{Argv: []string{"true"}}, creds) if err != nil { t.Fatal(err) } diff --git a/internal/runtime/provider_gateway_integration_test.go b/internal/runtime/provider_gateway_integration_test.go index 22f579090..6930a5432 100644 --- a/internal/runtime/provider_gateway_integration_test.go +++ b/internal/runtime/provider_gateway_integration_test.go @@ -107,7 +107,7 @@ func TestNativeProviderCustomGateway(t *testing.T) { } creds := RunCredentials{Codex: ProviderCredential{APIKey: "local-gateway-test-key", BaseURL: server.URL + "/v1"}, ClaudeCode: ProviderCredential{APIKey: "local-gateway-test-key", BaseURL: server.URL}} sb := &localSandbox{workspace: workspace} - bound, err := bindCommand(sb, workspace, command, creds) + bound, err := bindCommand(t.Context(), sb, workspace, command, creds) if err != nil { t.Fatal(err) } diff --git a/internal/runtime/run_credentials_extra_test.go b/internal/runtime/run_credentials_extra_test.go index 8c065ed68..31d8f0102 100644 --- a/internal/runtime/run_credentials_extra_test.go +++ b/internal/runtime/run_credentials_extra_test.go @@ -50,7 +50,7 @@ func TestBindExtraCredentialEnv(t *testing.T) { } credentials := RunCredentials{Extra: map[string]string{"gateway": "tok-1"}} - bound, err := bindCommand(sb, sb.workspace, command, credentials) + bound, err := bindCommand(t.Context(), sb, sb.workspace, command, credentials) if err != nil { t.Fatalf("bindCommand: %v", err) } @@ -66,7 +66,7 @@ func TestBindExtraCredentialEnv(t *testing.T) { // Without the binding the mapping is inert. plain := command plain.CredentialBindings = nil - bound, err = bindCommand(sb, sb.workspace, plain, credentials) + bound, err = bindCommand(t.Context(), sb, sb.workspace, plain, credentials) if err != nil { t.Fatalf("bindCommand without binding: %v", err) } @@ -110,7 +110,7 @@ func TestBindExtraMarksCredentialEnvKeysForRedaction(t *testing.T) { CredentialBindings: []CredentialBinding{BindExtra}, ExtraCredentialEnv: map[string]string{"AWS_SECRET_ACCESS_KEY": "gateway"}, } - bound, err := bindCommand(sb, sb.workspace, command, RunCredentials{Extra: map[string]string{"gateway": "tok-1"}}) + bound, err := bindCommand(t.Context(), sb, sb.workspace, command, RunCredentials{Extra: map[string]string{"gateway": "tok-1"}}) if err != nil { t.Fatalf("bindCommand: %v", err) } @@ -152,7 +152,7 @@ func TestConversationPathBindsExtraCredentialEnv(t *testing.T) { CredentialBindings: wire.Bindings, ExtraCredentialEnv: wire.ExtraCredentialEnv, } - bound, err := bindCommand(sb, sb.workspace, rebuilt, wire.Credentials) + bound, err := bindCommand(t.Context(), sb, sb.workspace, rebuilt, wire.Credentials) if err != nil { t.Fatalf("bindCommand: %v", err) } diff --git a/internal/runtime/run_git_credentials.go b/internal/runtime/run_git_credentials.go index 8de21e476..305afa1a0 100644 --- a/internal/runtime/run_git_credentials.go +++ b/internal/runtime/run_git_credentials.go @@ -89,7 +89,7 @@ func RunGitEnvironment(ctx context.Context, sandbox Sandbox, workspace string, c for _, key := range workspaceGitSecretEnvironment { env[key] = "" } - if err := bindWorkspaceGitEnvironment(sandbox, workspace, env, credentials); err != nil { + if err := bindWorkspaceGitEnvironment(ctx, sandbox, workspace, env, credentials); err != nil { closeRelay() return nil, func() {}, err } diff --git a/internal/runtime/runtime_test.go b/internal/runtime/runtime_test.go index c07265979..fa7fe334d 100644 --- a/internal/runtime/runtime_test.go +++ b/internal/runtime/runtime_test.go @@ -819,7 +819,7 @@ func TestLightweightSandboxSmoke(t *testing.T) { t.Fatal(createErr) } allowed := `test "$HOME" != "` + stateHome + `" && test -w "$HOME" && f=$(mktemp) && printf ok > "$f" && printf ok > /dev/null && printf ok > workspace-write.txt` - command, err := bindCommand(sb, workspace, CommandSpec{Argv: []string{fakeCodeBuddy, "-lc", allowed}, Provider: "codebuddy", PrivateHome: true}, RunCredentials{}) + command, err := bindCommand(t.Context(), sb, workspace, CommandSpec{Argv: []string{fakeCodeBuddy, "-lc", allowed}, Provider: "codebuddy", PrivateHome: true}, RunCredentials{}) if err != nil { t.Fatal(err) } diff --git a/internal/runtime/sandbox_local.go b/internal/runtime/sandbox_local.go index aad2bd386..87106831b 100644 --- a/internal/runtime/sandbox_local.go +++ b/internal/runtime/sandbox_local.go @@ -106,7 +106,7 @@ func ExecuteLocalCommand(ctx context.Context, workspace string, command CommandS if cleanup != nil { defer cleanup() } - bound, err := bindCommand(sandbox, workspace, command, credentials) + bound, err := bindCommand(ctx, sandbox, workspace, command, credentials) if err != nil { return "", err } diff --git a/internal/runtime/sandbox_manager.go b/internal/runtime/sandbox_manager.go index b2991d016..65fe2d101 100644 --- a/internal/runtime/sandbox_manager.go +++ b/internal/runtime/sandbox_manager.go @@ -439,7 +439,7 @@ func (s *managedSandbox) Exec(ctx context.Context, command CommandSpec, sink Eve // Binding writes the credential helpers into the workspace; parallel // branches then run their commands concurrently. s.execMu.Lock() - bound, err := bindCommand(s.Sandbox, s.workspace, command, credentials) + bound, err := bindCommand(ctx, s.Sandbox, s.workspace, command, credentials) s.execMu.Unlock() if err != nil { return "", err diff --git a/internal/runtime/workspace_terminal_sandbox.go b/internal/runtime/workspace_terminal_sandbox.go index 1f123fb4d..3c687f821 100644 --- a/internal/runtime/workspace_terminal_sandbox.go +++ b/internal/runtime/workspace_terminal_sandbox.go @@ -117,7 +117,7 @@ func sandboxTerminalCommandBound(ctx context.Context, sandbox Sandbox, command C return nil, err } credentials.GitHTTPHosts = runGitHosts(credentials) - command, err = bindCommand(sandbox, sandbox.Workspace(), prepared, credentials) + command, err = bindCommand(ctx, sandbox, sandbox.Workspace(), prepared, credentials) if err != nil { closeGit() return nil, err From b5b9eafd4650953d7d45f7c9b8843c06164414e0 Mon Sep 17 00:00:00 2001 From: crispinhu Date: Fri, 20 Nov 2026 00:42:07 +0800 Subject: [PATCH 04/13] fix(runner): guard and persist Docker helper templates --- deploy/bind-cli.sh | 41 +++++++++++++++++-- deploy/bind_cli_docker_runner_test.go | 57 ++++++++++++++++++++++++--- docs/deployment.md | 2 +- internal/runner/update_test.go | 28 +++++++++++++ internal/runtime/mcp_call.go | 16 +++++--- 5 files changed, 129 insertions(+), 15 deletions(-) diff --git a/deploy/bind-cli.sh b/deploy/bind-cli.sh index 48d0fa3b3..620363636 100755 --- a/deploy/bind-cli.sh +++ b/deploy/bind-cli.sh @@ -709,10 +709,19 @@ TEMP_BINARY="" trap '[[ -z "$TEMP_BINARY" ]] || rm -f "$TEMP_BINARY"' EXIT install_binary +saved_runner_binary_pattern() { + awk 'sub(/^AGENTFLOW_RUNNER_BINARY=/, "") { print; exit }' "$ENV_FILE" +} + configure_macos_docker_runner_helper() { local pattern="${AGENTFLOW_RUNNER_BINARY:-}" - if [[ "$UPGRADE" == "1" && -f "$PLIST" && -z "${AGENTFLOW_RUNNER_BINARY+x}" ]]; then - pattern=$(/usr/bin/plutil -extract EnvironmentVariables.AGENTFLOW_RUNNER_BINARY raw "$PLIST" 2>/dev/null || true) + if [[ "$UPGRADE" == "1" && -z "${AGENTFLOW_RUNNER_BINARY+x}" ]]; then + if [[ -f "$PLIST" ]]; then + pattern=$(/usr/bin/plutil -extract EnvironmentVariables.AGENTFLOW_RUNNER_BINARY raw "$PLIST" 2>/dev/null) || + pattern=$(saved_runner_binary_pattern) + else + pattern=$(saved_runner_binary_pattern) + fi fi # Keep the template expansion in sync with runtime.DockerRunnerHelperPath. pattern="${pattern#"${pattern%%[![:space:]]*}"}" @@ -723,9 +732,24 @@ configure_macos_docker_runner_helper() { DOCKER_RUNNER_BINARY="${pattern//\{os\}/linux}" DOCKER_RUNNER_BINARY="${DOCKER_RUNNER_BINARY//\{arch\}/$ARCH}" fi + if [[ "$DOCKER_RUNNER_BINARY" -ef "$BINARY" ]]; then + fail "Linux Git/MCP helper 路径与 macOS Runner 相同:${DOCKER_RUNNER_BINARY}" + fi export AGENTFLOW_RUNNER_BINARY="$pattern" } +save_runner_binary_pattern() { + [[ "$(saved_runner_binary_pattern)" != "$AGENTFLOW_RUNNER_BINARY" ]] || return 0 + local tmp + tmp=$(mktemp "${RUNNER_HOME}/.env.XXXXXX") + if ! { sed '/^AGENTFLOW_RUNNER_BINARY=/d' "$ENV_FILE" && + printf 'AGENTFLOW_RUNNER_BINARY=%s\n' "$AGENTFLOW_RUNNER_BINARY"; } > "$tmp" || + ! mv -f "$tmp" "$ENV_FILE"; then + rm -f "$tmp" + fail "无法保存 Git/MCP helper 路径配置" + fi +} + if [[ "$OS" == "darwin" ]]; then ARCH=$(macos_runner_arch "$BINARY") configure_macos_docker_runner_helper @@ -757,6 +781,9 @@ if [[ "$OS" != "linux" ]]; then fi if [[ "$UPGRADE" == "1" ]]; then + if [[ "$OS" == "darwin" ]]; then + save_runner_binary_pattern + fi if [[ "$OS" == "darwin" && -f "$PLIST" ]]; then if [[ "$AUTO_UPDATE" == "0" ]]; then arg_count=$(/usr/bin/plutil -extract ProgramArguments raw -expect array "$PLIST") @@ -815,7 +842,15 @@ USER_PATH="${PATH}" if [[ "$NO_START" == "1" ]]; then info "已完成安装与配置(--no-start,未启动)。手动启动:" - info " $BINARY ${RUN_ARGS[*]}" + runner_command="" + if [[ "${AGENTFLOW_RUNNER_BINARY:-}" == *"{os}"* ]]; then + runner_command="AGENTFLOW_RUNNER_BINARY=$(shell_quote "$AGENTFLOW_RUNNER_BINARY") " + fi + runner_command+="$(shell_quote "$BINARY")" + for arg in "${RUN_ARGS[@]}"; do + runner_command+=" $(shell_quote "$arg")" + done + info " $runner_command" info "常驻方式:追加 --service 重新执行本脚本;卸载:追加 --uninstall(--purge 删除全部配置)" elif [[ "$INSTALL_SERVICE" == "1" ]]; then if [[ "$OS" == "darwin" ]]; then diff --git a/deploy/bind_cli_docker_runner_test.go b/deploy/bind_cli_docker_runner_test.go index 7409025c5..e79bb2e3e 100644 --- a/deploy/bind_cli_docker_runner_test.go +++ b/deploy/bind_cli_docker_runner_test.go @@ -31,9 +31,11 @@ func TestBindCLIInstallsDockerRunnerHelper(t *testing.T) { helperArtifact, source, existing string preserveHelper bool templatePath bool + helperAliasesRunner bool }{ {name: "macOS_install", hostOS: "darwin", arch: "arm64", unameArch: "arm64"}, - {name: "macOS_creates_nested_runtime_helper_path", hostOS: "darwin", arch: "arm64", unameArch: "arm64", templatePath: true}, + {name: "macOS_uses_template_in_manual_start_and_upgrade", hostOS: "darwin", arch: "arm64", unameArch: "arm64", templatePath: true, source: "from"}, + {name: "macOS_rejects_template_aliasing_the_runner", hostOS: "darwin", arch: "arm64", unameArch: "arm64", templatePath: true, helperAliasesRunner: true}, {name: "macOS_upgrade", hostOS: "darwin", arch: "amd64", unameArch: "x86_64", upgrade: true}, {name: "Linux_install", hostOS: "linux", arch: "arm64", unameArch: "aarch64"}, {name: "macOS_preserves_helper_on_failed_download", hostOS: "darwin", arch: "arm64", unameArch: "arm64", helperArtifact: "unavailable", preserveHelper: true}, @@ -56,8 +58,12 @@ func TestBindCLIInstallsDockerRunnerHelper(t *testing.T) { t.Skip("requires macOS plutil") } fixtureHome := t.TempDir() + bundle := filepath.Join(fixtureHome, "artifact bundle") bin := filepath.Join(fixtureHome, "bin") - if err := os.Mkdir(bin, 0o755); err != nil { + if tc.helperAliasesRunner { + bin = filepath.Join(bundle, "linux", tc.arch) + } + if err := os.MkdirAll(bin, 0o755); err != nil { t.Fatal(err) } uname := fmt.Sprintf("#!/bin/sh\ncase \"$1\" in -s) echo %s ;; -m) echo %s ;; esac\n", tc.hostOS, tc.unameArch) @@ -124,8 +130,8 @@ func TestBindCLIInstallsDockerRunnerHelper(t *testing.T) { helper := filepath.Join(bin, "agentflow-runner-linux-"+tc.arch) patternEnv := "" if tc.templatePath { - patternEnv = filepath.Join(fixtureHome, "bundle", "{os}", "{arch}", "agentflow-runner") - helper = filepath.Join(fixtureHome, "bundle", "linux", tc.arch, "agentflow-runner") + patternEnv = filepath.Join(bundle, "{os}", "{arch}", "agentflow-runner") + helper = filepath.Join(bundle, "linux", tc.arch, "agentflow-runner") } statePath := filepath.Join(fixtureHome, ".agentflow-runner", "state.json") const state = `{"runnerId":"fixture"}` @@ -199,14 +205,53 @@ func TestBindCLIInstallsDockerRunnerHelper(t *testing.T) { cmd.Env = append(cmd.Env, "AGENTFLOW_RUNNER_BINARY="+patternEnv) } out, err := cmd.CombinedOutput() - if err != nil { + if tc.helperAliasesRunner { + if err == nil || !strings.Contains(string(out), "helper 路径与 macOS Runner 相同") { + t.Fatalf("installer did not reject the conflicting path: %v\n%s", err, out) + } + } else if err != nil { t.Fatalf("install: %v\n%s", err, out) } return string(out) } - if output := install(); tc.source == "checkout" && !strings.Contains(output, "-auto-update=false") { + output := install() + if tc.helperAliasesRunner { + if got, err := os.ReadFile(helper); err != nil || string(got) != hostRunner { + t.Fatalf("macOS Runner was changed by the helper install: %q, %v", got, err) + } + return + } + if tc.source == "checkout" && !strings.Contains(output, "-auto-update=false") { t.Fatalf("local source fallback did not disable automatic updates: %s", output) } + if tc.templatePath && !tc.upgrade { + var start string + for line := range strings.SplitSeq(output, "\n") { + if command, ok := strings.CutPrefix(line, "[bind-cli] "); ok && strings.Contains(command, " -state ") { + start = command + } + } + if start == "" { + t.Fatalf("manual launch command missing: %s", output) + } + if err := os.WriteFile(filepath.Join(bin, "agentflow-runner"), []byte("#!/bin/sh\nprintf '%s' \"$AGENTFLOW_RUNNER_BINARY\"\n"), 0o755); err != nil { + t.Fatal(err) + } + cmd := exec.Command("/bin/bash", "-c", start) + cmd.Env = []string{"HOME=" + fixtureHome, "PATH=/usr/bin:/bin"} + if out, err := cmd.CombinedOutput(); err != nil || string(out) != patternEnv { + t.Fatalf("manual launch got helper template %q, %v, want %q", out, err, patternEnv) + } + if err := os.WriteFile(statePath, []byte(state), 0o600); err != nil { + t.Fatal(err) + } + if err := os.Remove(helper); err != nil { + t.Fatal(err) + } + args = append(args, "--upgrade") + patternEnv = "" + install() + } if tc.launchd { if tc.templatePath { // Use the saved service path during another upgrade without a shell override. diff --git a/docs/deployment.md b/docs/deployment.md index c2027a6b9..662ea289e 100644 --- a/docs/deployment.md +++ b/docs/deployment.md @@ -133,7 +133,7 @@ The upstream process roles remain `-role api`, `-role worker` and `-role all`. A Personal runners are connected from the execution-machine page with a short-lived binding code. The installer is served at `/runners/install.sh`. `AGENTFLOW_RUNNER_BINARY` can point to binaries with `{os}` and `{arch}` substitutions. Container images bundle Linux/macOS amd64/arm64 runner and gate binaries. Native source installations can build on demand with Go. -Docker workspaces on macOS use a Linux Runner executable for Git credentials and MCP calls. The installer chooses the architecture of the installed macOS Runner, including Intel binaries running under Rosetta. It places the helper next to the host binary by default. A Runner-side `AGENTFLOW_RUNNER_BINARY` template with `{os}` selects the installation and runtime path, and the installer carries the template into launchd. +Docker workspaces on macOS use a Linux Runner executable for Git credentials and MCP calls. The installer chooses the architecture of the installed macOS Runner, including Intel binaries running under Rosetta. It places the helper next to the host binary by default. A Runner-side `AGENTFLOW_RUNNER_BINARY` template with `{os}` selects the installation and runtime path. The installer saves it for upgrades and includes it in launchd and in the startup command printed by `--no-start`. The helper path must resolve to a separate file from the macOS Runner. The installer and updater validate the Linux executable's format, architecture, and load segments before replacing it. Custom installs keep a compatible existing helper. A Runner built from a local checkout can build its companion from that checkout. A download URL with an `{os}` placeholder can supply both binaries when used as the Runner's download source. diff --git a/internal/runner/update_test.go b/internal/runner/update_test.go index ed3f898b3..0a17dd177 100644 --- a/internal/runner/update_test.go +++ b/internal/runner/update_test.go @@ -252,6 +252,34 @@ func TestDockerRunnerHelperUpdateRepairsMissingBinary(t *testing.T) { assertHelper() } +func TestDockerRunnerHelperUpdateRejectsRunningExecutablePath(t *testing.T) { + self, err := os.Executable() + if err != nil { + t.Fatal(err) + } + root := t.TempDir() + if err := os.Symlink(filepath.Dir(self), filepath.Join(root, "linux")); err != nil { + t.Fatal(err) + } + t.Setenv("AGENTFLOW_RUNNER_BINARY", filepath.Join(root, "{os}", filepath.Base(self))) + var requests atomic.Int32 + server := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, req *http.Request) { + requests.Add(1) + w.WriteHeader(http.StatusServiceUnavailable) + })) + defer server.Close() + d, err := New(Config{ServerURL: server.URL, BootstrapToken: "fixture"}) + if err != nil { + t.Fatal(err) + } + if err := d.checkDockerRunnerHelperUpdate(t.Context(), false); err == nil || !strings.Contains(err.Error(), "aliases the host Runner") { + t.Fatalf("conflicting helper path was not rejected: %v", err) + } + if got := requests.Load(); got != 0 { + t.Fatalf("updater requested an artifact for a conflicting path, requests = %d", got) + } +} + func TestDockerRunnerHelperUpdateRejectsIncompatibleBinary(t *testing.T) { otherArch := "arm64" if runtime.GOARCH == otherArch { diff --git a/internal/runtime/mcp_call.go b/internal/runtime/mcp_call.go index 6483ece31..80c86f8dd 100644 --- a/internal/runtime/mcp_call.go +++ b/internal/runtime/mcp_call.go @@ -198,15 +198,21 @@ func installMCPCallHelperForSandbox(ctx context.Context, sandbox Sandbox, worksp // DockerRunnerHelperPath is the Linux runner artifact used for Git and MCP // inside Docker on a non-Linux runner. Keep installation and lookup in sync. func DockerRunnerHelperPath() (string, error) { + self, err := os.Executable() + if err != nil { + return "", err + } pattern := strings.TrimSpace(os.Getenv("AGENTFLOW_RUNNER_BINARY")) if !strings.Contains(pattern, "{os}") { - self, err := os.Executable() - if err != nil { - return "", err - } pattern = filepath.Join(filepath.Dir(self), "agentflow-runner-{os}-{arch}") } - return strings.NewReplacer("{os}", "linux", "{arch}", goruntime.GOARCH).Replace(pattern), nil + path := strings.NewReplacer("{os}", "linux", "{arch}", goruntime.GOARCH).Replace(pattern) + if helper, err := os.Stat(path); err == nil { + if host, err := os.Stat(self); err == nil && os.SameFile(helper, host) { + return "", fmt.Errorf("Docker Git/MCP helper path aliases the host Runner: %s", path) + } + } + return path, nil } func installMCPCallHelperFrom(workspace, src, dest string) error { From 7872a47e9fa845ef6c9b7da8d09e4d188a7eaf69 Mon Sep 17 00:00:00 2001 From: crispinhu Date: Fri, 20 Nov 2026 01:04:41 +0800 Subject: [PATCH 05/13] fix(runner): install helpers for universal macOS runners --- deploy/bind-cli.sh | 77 ++++++++++++++++++++------- deploy/bind_cli_docker_runner_test.go | 19 ++++++- docs/deployment.md | 2 +- 3 files changed, 78 insertions(+), 20 deletions(-) diff --git a/deploy/bind-cli.sh b/deploy/bind-cli.sh index 620363636..26602a936 100755 --- a/deploy/bind-cli.sh +++ b/deploy/bind-cli.sh @@ -340,18 +340,44 @@ case "$ARCH" in esac [[ "$OS" == "darwin" || "$OS" == "linux" ]] || fail "不支持的系统: ${OS}(Windows 请使用 PowerShell 安装方式)" -# A thin macOS Runner can execute under Rosetta. Its own GOARCH, instead of -# the installer's uname, determines which Linux companion it looks up. -macos_runner_arch() { - local header="" +# Use the Mach-O slices instead of uname. A universal Runner installed under +# Rosetta can later be launched natively by launchd. +macos_runner_arches() { + local header="" entry_size little=0 arches if [[ -f "$1" ]]; then header="$(LC_ALL=C od -An -v -t x1 -N 8 "$1" | tr -d '[:space:]')" fi case "$header" in - cffaedfe07000001) printf '%s\n' amd64 ;; - cffaedfe0c000001) printf '%s\n' arm64 ;; - *) printf '%s\n' "$ARCH" ;; + cffaedfe07000001) printf '%s\n' amd64; return ;; + cffaedfe0c000001) printf '%s\n' arm64; return ;; + cafebabe*) entry_size=20 ;; + cafebabf*) entry_size=32 ;; + bebafeca*) entry_size=20; little=1 ;; + bfbafeca*) entry_size=32; little=1 ;; + *) printf '%s\n' "$ARCH"; return ;; esac + # A fat header is eight bytes. Bound the read to the architecture table + # and accept only the CPU types for which we distribute Linux companions. + arches=$(LC_ALL=C od -An -v -t u1 -N 4104 "$1" | + awk -v stride="$entry_size" -v little="$little" ' + { for (i = 1; i <= NF; i++) bytes[count++] = $i } + function word(offset, i, value) { + for (i = 0; i < 4; i++) value = 256 * value + bytes[offset + (little ? 3-i : i)] + return value + } + END { + slices = word(4) + if (slices < 1 || 8 + slices * stride > count) exit 1 + for (slice = 0; slice < slices; slice++) { + cpu = word(8 + slice * stride) + if (cpu == 16777223) amd64 = 1 + if (cpu == 16777228) arm64 = 1 + } + if (amd64 && arm64) print "amd64 arm64" + else if (amd64) print "amd64" + else if (arm64) print "arm64" + }') || arches="" + printf '%s\n' "${arches:-$ARCH}" } RUNNER_HOME="${HOME}/.agentflow-runner" @@ -436,8 +462,10 @@ if [[ "$UNINSTALL" == "1" ]]; then info "已清理 runner Docker 沙箱和临时镜像" fi if [[ "$OS" == "darwin" ]]; then - runner_arch=$(macos_runner_arch "$BINARY") - rm -f "${BIN_DIR}/agentflow-runner-linux-${runner_arch}" + read -r -a runner_arches <<< "$(macos_runner_arches "$BINARY")" + for runner_arch in "${runner_arches[@]}"; do + rm -f "${BIN_DIR}/agentflow-runner-linux-${runner_arch}" + done fi rm -f "$BINARY" rm -f "${BIN_DIR}"/agentflow-gate-mcp-darwin-amd64 \ @@ -726,16 +754,24 @@ configure_macos_docker_runner_helper() { # Keep the template expansion in sync with runtime.DockerRunnerHelperPath. pattern="${pattern#"${pattern%%[![:space:]]*}"}" pattern="${pattern%"${pattern##*[![:space:]]}"}" - DOCKER_RUNNER_BINARY="${BIN_DIR}/agentflow-runner-linux-${ARCH}" if [[ "$pattern" == *"{os}"* ]]; then + if [[ "${#runner_arches[@]}" -gt 1 && "$pattern" != *"{arch}"* ]]; then + fail "通用 macOS Runner 需要为每种架构安装 Linux Git/MCP helper,请在 AGENTFLOW_RUNNER_BINARY 中添加 {arch}" + fi [[ "$pattern" == /* ]] || pattern="$PWD/$pattern" - DOCKER_RUNNER_BINARY="${pattern//\{os\}/linux}" + fi + export AGENTFLOW_RUNNER_BINARY="$pattern" +} + +select_macos_docker_runner_helper() { + DOCKER_RUNNER_BINARY="${BIN_DIR}/agentflow-runner-linux-${ARCH}" + if [[ "$AGENTFLOW_RUNNER_BINARY" == *"{os}"* ]]; then + DOCKER_RUNNER_BINARY="${AGENTFLOW_RUNNER_BINARY//\{os\}/linux}" DOCKER_RUNNER_BINARY="${DOCKER_RUNNER_BINARY//\{arch\}/$ARCH}" fi if [[ "$DOCKER_RUNNER_BINARY" -ef "$BINARY" ]]; then fail "Linux Git/MCP helper 路径与 macOS Runner 相同:${DOCKER_RUNNER_BINARY}" fi - export AGENTFLOW_RUNNER_BINARY="$pattern" } save_runner_binary_pattern() { @@ -751,7 +787,7 @@ save_runner_binary_pattern() { } if [[ "$OS" == "darwin" ]]; then - ARCH=$(macos_runner_arch "$BINARY") + read -r -a runner_arches <<< "$(macos_runner_arches "$BINARY")" configure_macos_docker_runner_helper fi @@ -773,11 +809,16 @@ install_gate_binary() { chmod +x "$target" } -# Docker on macOS needs Linux versions of both the Gate MCP and Git/MCP helpers. -install_gate_binary "$OS" "$ARCH" -if [[ "$OS" != "linux" ]]; then - install_gate_binary linux "$ARCH" - install_docker_runner_binary +# A universal Runner needs both companions whichever slice gets launched. +if [[ "$OS" == "darwin" ]]; then + for ARCH in "${runner_arches[@]}"; do + select_macos_docker_runner_helper + install_gate_binary darwin "$ARCH" + install_gate_binary linux "$ARCH" + install_docker_runner_binary + done +else + install_gate_binary "$OS" "$ARCH" fi if [[ "$UPGRADE" == "1" ]]; then diff --git a/deploy/bind_cli_docker_runner_test.go b/deploy/bind_cli_docker_runner_test.go index e79bb2e3e..69746447a 100644 --- a/deploy/bind_cli_docker_runner_test.go +++ b/deploy/bind_cli_docker_runner_test.go @@ -32,6 +32,7 @@ func TestBindCLIInstallsDockerRunnerHelper(t *testing.T) { preserveHelper bool templatePath bool helperAliasesRunner bool + universal bool }{ {name: "macOS_install", hostOS: "darwin", arch: "arm64", unameArch: "arm64"}, {name: "macOS_uses_template_in_manual_start_and_upgrade", hostOS: "darwin", arch: "arm64", unameArch: "arm64", templatePath: true, source: "from"}, @@ -48,6 +49,7 @@ func TestBindCLIInstallsDockerRunnerHelper(t *testing.T) { {name: "macOS_upgrades_launchd_with_custom_runner", hostOS: "darwin", arch: "arm64", unameArch: "arm64", source: "from", launchd: true, upgrade: true, preserveHelper: true}, {name: "macOS_upgrades_launchd_on_template_path", hostOS: "darwin", arch: "arm64", unameArch: "arm64", source: "from", launchd: true, upgrade: true, templatePath: true}, {name: "macOS_installs_companion_for_Intel_runner_on_arm64", hostOS: "darwin", arch: "amd64", unameArch: "arm64", source: "from"}, + {name: "macOS_under_Rosetta_installs_both_companions_for_universal_Runner", hostOS: "darwin", arch: "arm64", unameArch: "x86_64", source: "from", universal: true}, {name: "macOS_repairs_incompatible_local_helper", hostOS: "darwin", arch: "arm64", unameArch: "arm64", source: "from", existing: "mach-o", upgrade: true}, {name: "macOS_preserves_custom_helper_script", hostOS: "darwin", arch: "arm64", unameArch: "arm64", source: "from", existing: "script", preserveHelper: true}, {name: "macOS_preserves_helper_with_host_only_URL", hostOS: "darwin", arch: "arm64", unameArch: "arm64", source: "host-url", preserveHelper: true}, @@ -83,6 +85,15 @@ func TestBindCLIInstallsDockerRunnerHelper(t *testing.T) { if tc.source == "from" { hostRunner += " custom" } + if tc.universal { + const x8664, arm64 = 0x01000007, 0x0100000c + header := make([]byte, 8+2*20) + binary.BigEndian.PutUint32(header[:], 0xcafebabe) + binary.BigEndian.PutUint32(header[4:], 2) + binary.BigEndian.PutUint32(header[8:], x8664) + binary.BigEndian.PutUint32(header[28:], arm64) + hostRunner = string(header) + "universal runner" + } switch tc.existing { case "mach-o": oldHelper = "\xcf\xfa\xed\xfe wrong OS" @@ -91,7 +102,8 @@ func TestBindCLIInstallsDockerRunnerHelper(t *testing.T) { } server := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, req *http.Request) { targetOS, arch := req.URL.Query().Get("os"), req.URL.Query().Get("arch") - if (arch != tc.arch && arch != tc.unameArch) || (targetOS != tc.hostOS && targetOS != "linux") { + if (arch != tc.arch && arch != tc.unameArch && !(tc.universal && arch == "amd64")) || + (targetOS != tc.hostOS && targetOS != "linux") { http.NotFound(w, req) return } @@ -281,6 +293,11 @@ func TestBindCLIInstallsDockerRunnerHelper(t *testing.T) { } } assertArtifact(filepath.Join(bin, "agentflow-runner"), hostRunner) + if tc.universal { + assertArtifact(filepath.Join(bin, "agentflow-runner-linux-amd64"), bindFixtureLinuxRunner("amd64", "new helper")) + assertArtifact(filepath.Join(bin, "agentflow-gate-mcp-darwin-amd64"), "gate darwin/amd64") + assertArtifact(filepath.Join(bin, "agentflow-gate-mcp-darwin-arm64"), "gate darwin/arm64") + } switch { case tc.hostOS == "linux": if _, err := os.Stat(helper); !os.IsNotExist(err) { diff --git a/docs/deployment.md b/docs/deployment.md index 662ea289e..00ee8ec46 100644 --- a/docs/deployment.md +++ b/docs/deployment.md @@ -133,7 +133,7 @@ The upstream process roles remain `-role api`, `-role worker` and `-role all`. A Personal runners are connected from the execution-machine page with a short-lived binding code. The installer is served at `/runners/install.sh`. `AGENTFLOW_RUNNER_BINARY` can point to binaries with `{os}` and `{arch}` substitutions. Container images bundle Linux/macOS amd64/arm64 runner and gate binaries. Native source installations can build on demand with Go. -Docker workspaces on macOS use a Linux Runner executable for Git credentials and MCP calls. The installer chooses the architecture of the installed macOS Runner, including Intel binaries running under Rosetta. It places the helper next to the host binary by default. A Runner-side `AGENTFLOW_RUNNER_BINARY` template with `{os}` selects the installation and runtime path. The installer saves it for upgrades and includes it in launchd and in the startup command printed by `--no-start`. The helper path must resolve to a separate file from the macOS Runner. +Docker workspaces on macOS use a Linux Runner executable for Git credentials and MCP calls. The installer chooses the architecture of the installed macOS Runner, including Intel binaries running under Rosetta. Universal Runners receive helpers for both supported slices. It places the helper next to the host binary by default. A Runner-side `AGENTFLOW_RUNNER_BINARY` template with `{os}` selects the installation and runtime path. Use `{arch}` in the template for a universal Runner. The installer saves it for upgrades and includes it in launchd and in the startup command printed by `--no-start`. The helper path must resolve to a separate file from the macOS Runner. The installer and updater validate the Linux executable's format, architecture, and load segments before replacing it. Custom installs keep a compatible existing helper. A Runner built from a local checkout can build its companion from that checkout. A download URL with an `{os}` placeholder can supply both binaries when used as the Runner's download source. From 417f88b52440d01cf9fc8b303c9e688ac86dc054 Mon Sep 17 00:00:00 2001 From: crispinhu Date: Fri, 20 Nov 2026 01:12:37 +0800 Subject: [PATCH 06/13] fix(runner): preserve native installs for universal binaries --- deploy/bind-cli.sh | 96 ++++++++++++++++++++------- deploy/bind_cli_docker_runner_test.go | 46 ++++++++++++- docs/deployment.md | 2 +- 3 files changed, 118 insertions(+), 26 deletions(-) diff --git a/deploy/bind-cli.sh b/deploy/bind-cli.sh index 26602a936..dcd542a2e 100755 --- a/deploy/bind-cli.sh +++ b/deploy/bind-cli.sh @@ -597,10 +597,10 @@ download_runner_binary() { } build_runner_binary() { - local target_os="$1" source="$2" output="$TEMP_BINARY" + local target_os="$1" source="$2" command="${3:-agentflow-runner}" output="$TEMP_BINARY" [[ "$output" == /* ]] || output="$PWD/$output" - info "从源码 ${source} 构建 agentflow-runner(${target_os}/${ARCH})..." - (cd "$source" && CGO_ENABLED=0 GOOS="$target_os" GOARCH="$ARCH" go build -o "$output" ./cmd/agentflow-runner) + info "从源码 ${source} 构建 ${command}(${target_os}/${ARCH})..." + (cd "$source" && CGO_ENABLED=0 GOOS="$target_os" GOARCH="$ARCH" go build -o "$output" "./cmd/$command") } publish_runner_binary() { @@ -763,14 +763,38 @@ configure_macos_docker_runner_helper() { export AGENTFLOW_RUNNER_BINARY="$pattern" } -select_macos_docker_runner_helper() { - DOCKER_RUNNER_BINARY="${BIN_DIR}/agentflow-runner-linux-${ARCH}" +macos_docker_runner_helper_path() { + local target_arch="$1" target="${BIN_DIR}/agentflow-runner-linux-${1}" if [[ "$AGENTFLOW_RUNNER_BINARY" == *"{os}"* ]]; then - DOCKER_RUNNER_BINARY="${AGENTFLOW_RUNNER_BINARY//\{os\}/linux}" - DOCKER_RUNNER_BINARY="${DOCKER_RUNNER_BINARY//\{arch\}/$ARCH}" + target="${AGENTFLOW_RUNNER_BINARY//\{os\}/linux}" + target="${target//\{arch\}/$target_arch}" fi - if [[ "$DOCKER_RUNNER_BINARY" -ef "$BINARY" ]]; then - fail "Linux Git/MCP helper 路径与 macOS Runner 相同:${DOCKER_RUNNER_BINARY}" + if [[ "$target" -ef "$BINARY" ]]; then + fail "Linux Git/MCP helper 路径与 macOS Runner 相同:${target}" + fi + printf '%s\n' "$target" +} + +canonical_helper_target() { + local target="$1" dir + dir=$(dirname "$target") + (mkdir -p "$dir" && cd -P "$dir" && printf '%s/%s\n' "$PWD" "${target##*/}") +} + +check_universal_helper_paths() { + [[ "${#runner_arches[@]}" -gt 1 && "$AGENTFLOW_RUNNER_BINARY" == *"{os}"* ]] || return 0 + local amd64 arm64 resolved_amd64 resolved_arm64 + amd64=$(macos_docker_runner_helper_path amd64) + arm64=$(macos_docker_runner_helper_path arm64) + if [[ "$amd64" -ef "$arm64" ]]; then + fail "两种架构的 Linux Git/MCP helper 路径相同,请使用独立的架构目录" + fi + # The installer can still warn and skip a target whose directory is + # unavailable. For writable paths, check the physical parent directories. + resolved_amd64=$(canonical_helper_target "$amd64" 2>/dev/null) || return 0 + resolved_arm64=$(canonical_helper_target "$arm64" 2>/dev/null) || return 0 + if [[ "$resolved_amd64" == "$resolved_arm64" ]]; then + fail "两种架构的 Linux Git/MCP helper 路径相同,请使用独立的架构目录" fi } @@ -788,37 +812,63 @@ save_runner_binary_pattern() { if [[ "$OS" == "darwin" ]]; then read -r -a runner_arches <<< "$(macos_runner_arches "$BINARY")" + # uname reports x86_64 under Rosetta too. Intel Macs can use only the + # amd64 slice and may be connected to a platform that publishes only amd64. + if [[ "${#runner_arches[@]}" -gt 1 && "$ARCH" == "amd64" && + "$(PATH="$PATH:/usr/sbin" sysctl -n hw.optional.arm64 2>/dev/null || true)" != "1" ]]; then + runner_arches=(amd64) + fi configure_macos_docker_runner_helper + check_universal_helper_paths fi install_gate_binary() { - local target_os="$1" target_arch="$2" target + local target_os="$1" target_arch="$ARCH" optional="${2:-0}" target + local src="${SOURCE_DIR:-$PWD}" error target="${GATE_BINARY_PATTERN//\{os\}/$target_os}" target="${target//\{arch\}/$target_arch}" info "从 ${SERVER} 下载 Gate MCP(${target_os}/${target_arch})..." - if curl -fsSL "${SERVER}/runners/agentflow-gate-mcp?os=${target_os}&arch=${target_arch}" -o "$target"; then - chmod +x "$target" + TEMP_BINARY=$(mktemp "${BIN_DIR}/.agentflow-gate-mcp.XXXXXX") + if curl -fsSL "${SERVER}/runners/agentflow-gate-mcp?os=${target_os}&arch=${target_arch}" -o "$TEMP_BINARY" && + [[ -s "$TEMP_BINARY" ]]; then + publish_runner_binary "$target" + return + fi + if [[ ! -d "$src/cmd/agentflow-gate-mcp" ]]; then + error="平台未提供 Gate MCP ${target_os}/${target_arch} 二进制,且未找到本地源码" + elif ! command -v go >/dev/null 2>&1; then + error="本机未安装 Go,无法构建 Gate MCP;请让平台配置 AGENTFLOW_GATE_MCP_BINARY" + elif build_runner_binary "$target_os" "$src" agentflow-gate-mcp && [[ -s "$TEMP_BINARY" ]]; then + publish_runner_binary "$target" return + else + error="Gate MCP ${target_os}/${target_arch} 源码构建失败" + fi + rm -f "$TEMP_BINARY" + TEMP_BINARY="" + if [[ "$optional" == "1" ]]; then + warn "$error" + else + fail "$error" fi - local src="${SOURCE_DIR:-$PWD}" - [[ -d "$src/cmd/agentflow-gate-mcp" ]] || fail "平台未提供 Gate MCP ${target_os}/${target_arch} 二进制,且未找到本地源码" - command -v go >/dev/null 2>&1 || fail "本机未安装 Go,无法构建 Gate MCP;请让平台配置 AGENTFLOW_GATE_MCP_BINARY" - info "从源码 ${src} 构建 Gate MCP(${target_os}/${target_arch})..." - (cd "$src" && CGO_ENABLED=0 GOOS="$target_os" GOARCH="$target_arch" go build -o "$target" ./cmd/agentflow-gate-mcp) \ - || fail "Gate MCP 源码构建失败" - chmod +x "$target" } # A universal Runner needs both companions whichever slice gets launched. if [[ "$OS" == "darwin" ]]; then + required_arch="${runner_arches[0]}" + if [[ "${#runner_arches[@]}" -gt 1 ]]; then + required_arch="arm64" + fi for ARCH in "${runner_arches[@]}"; do - select_macos_docker_runner_helper - install_gate_binary darwin "$ARCH" - install_gate_binary linux "$ARCH" + DOCKER_RUNNER_BINARY=$(macos_docker_runner_helper_path "$ARCH") + optional_gate=0 + [[ "$ARCH" == "$required_arch" ]] || optional_gate=1 + install_gate_binary darwin "$optional_gate" + install_gate_binary linux "$optional_gate" install_docker_runner_binary done else - install_gate_binary "$OS" "$ARCH" + install_gate_binary "$OS" fi if [[ "$UPGRADE" == "1" ]]; then diff --git a/deploy/bind_cli_docker_runner_test.go b/deploy/bind_cli_docker_runner_test.go index 69746447a..7f973c710 100644 --- a/deploy/bind_cli_docker_runner_test.go +++ b/deploy/bind_cli_docker_runner_test.go @@ -33,6 +33,8 @@ func TestBindCLIInstallsDockerRunnerHelper(t *testing.T) { templatePath bool helperAliasesRunner bool universal bool + intelHardware, sharedTemplateDir bool + arm64OnlyArtifacts bool }{ {name: "macOS_install", hostOS: "darwin", arch: "arm64", unameArch: "arm64"}, {name: "macOS_uses_template_in_manual_start_and_upgrade", hostOS: "darwin", arch: "arm64", unameArch: "arm64", templatePath: true, source: "from"}, @@ -50,6 +52,9 @@ func TestBindCLIInstallsDockerRunnerHelper(t *testing.T) { {name: "macOS_upgrades_launchd_on_template_path", hostOS: "darwin", arch: "arm64", unameArch: "arm64", source: "from", launchd: true, upgrade: true, templatePath: true}, {name: "macOS_installs_companion_for_Intel_runner_on_arm64", hostOS: "darwin", arch: "amd64", unameArch: "arm64", source: "from"}, {name: "macOS_under_Rosetta_installs_both_companions_for_universal_Runner", hostOS: "darwin", arch: "arm64", unameArch: "x86_64", source: "from", universal: true}, + {name: "macOS_Intel_installs_universal_Runner_from_amd64_only_platform", hostOS: "darwin", arch: "amd64", unameArch: "x86_64", source: "from", universal: true, intelHardware: true}, + {name: "macOS_Apple_Silicon_installs_universal_Runner_from_arm64_only_platform", hostOS: "darwin", arch: "arm64", unameArch: "arm64", source: "from", universal: true, arm64OnlyArtifacts: true}, + {name: "macOS_rejects_universal_companions_with_a_shared_template_directory", hostOS: "darwin", arch: "arm64", unameArch: "x86_64", source: "from", universal: true, templatePath: true, sharedTemplateDir: true}, {name: "macOS_repairs_incompatible_local_helper", hostOS: "darwin", arch: "arm64", unameArch: "arm64", source: "from", existing: "mach-o", upgrade: true}, {name: "macOS_preserves_custom_helper_script", hostOS: "darwin", arch: "arm64", unameArch: "arm64", source: "from", existing: "script", preserveHelper: true}, {name: "macOS_preserves_helper_with_host_only_URL", hostOS: "darwin", arch: "arm64", unameArch: "arm64", source: "host-url", preserveHelper: true}, @@ -93,6 +98,14 @@ func TestBindCLIInstallsDockerRunnerHelper(t *testing.T) { binary.BigEndian.PutUint32(header[8:], x8664) binary.BigEndian.PutUint32(header[28:], arm64) hostRunner = string(header) + "universal runner" + arm64Hardware := 1 + if tc.intelHardware { + arm64Hardware = 0 + } + sysctl := fmt.Sprintf("#!/bin/sh\nprintf '%%s\\n' %d\n", arm64Hardware) + if err := os.WriteFile(filepath.Join(bin, "sysctl"), []byte(sysctl), 0o755); err != nil { + t.Fatal(err) + } } switch tc.existing { case "mach-o": @@ -102,7 +115,7 @@ func TestBindCLIInstallsDockerRunnerHelper(t *testing.T) { } server := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, req *http.Request) { targetOS, arch := req.URL.Query().Get("os"), req.URL.Query().Get("arch") - if (arch != tc.arch && arch != tc.unameArch && !(tc.universal && arch == "amd64")) || + if (arch != tc.arch && arch != tc.unameArch && !(tc.universal && arch == "amd64" && !tc.arm64OnlyArtifacts)) || (targetOS != tc.hostOS && targetOS != "linux") { http.NotFound(w, req) return @@ -145,6 +158,15 @@ func TestBindCLIInstallsDockerRunnerHelper(t *testing.T) { patternEnv = filepath.Join(bundle, "{os}", "{arch}", "agentflow-runner") helper = filepath.Join(bundle, "linux", tc.arch, "agentflow-runner") } + if tc.sharedTemplateDir { + amd64 := filepath.Join(bundle, "linux", "amd64") + if err := os.MkdirAll(amd64, 0o755); err != nil { + t.Fatal(err) + } + if err := os.Symlink(amd64, filepath.Join(bundle, "linux", "arm64")); err != nil { + t.Fatal(err) + } + } statePath := filepath.Join(fixtureHome, ".agentflow-runner", "state.json") const state = `{"runnerId":"fixture"}` if tc.upgrade { @@ -221,12 +243,22 @@ func TestBindCLIInstallsDockerRunnerHelper(t *testing.T) { if err == nil || !strings.Contains(string(out), "helper 路径与 macOS Runner 相同") { t.Fatalf("installer did not reject the conflicting path: %v\n%s", err, out) } + } else if tc.sharedTemplateDir { + if err == nil || !strings.Contains(string(out), "两种架构的 Linux Git/MCP helper 路径相同") { + t.Fatalf("installer did not reject the shared template path: %v\n%s", err, out) + } } else if err != nil { t.Fatalf("install: %v\n%s", err, out) } return string(out) } output := install() + if tc.sharedTemplateDir { + if _, err := os.Stat(helper); !os.IsNotExist(err) { + t.Fatalf("the installer wrote a helper before rejecting the conflicting template: %v", err) + } + return + } if tc.helperAliasesRunner { if got, err := os.ReadFile(helper); err != nil || string(got) != hostRunner { t.Fatalf("macOS Runner was changed by the helper install: %q, %v", got, err) @@ -293,11 +325,21 @@ func TestBindCLIInstallsDockerRunnerHelper(t *testing.T) { } } assertArtifact(filepath.Join(bin, "agentflow-runner"), hostRunner) - if tc.universal { + if tc.universal && !tc.intelHardware && !tc.arm64OnlyArtifacts { assertArtifact(filepath.Join(bin, "agentflow-runner-linux-amd64"), bindFixtureLinuxRunner("amd64", "new helper")) assertArtifact(filepath.Join(bin, "agentflow-gate-mcp-darwin-amd64"), "gate darwin/amd64") assertArtifact(filepath.Join(bin, "agentflow-gate-mcp-darwin-arm64"), "gate darwin/arm64") } + if tc.intelHardware { + if _, err := os.Stat(filepath.Join(bin, "agentflow-runner-linux-arm64")); !os.IsNotExist(err) { + t.Fatalf("Intel install wrote an arm64 helper: %v", err) + } + } + if tc.arm64OnlyArtifacts { + if _, err := os.Stat(filepath.Join(bin, "agentflow-gate-mcp-linux-amd64")); !os.IsNotExist(err) { + t.Fatalf("missing optional artifact changed the amd64 Gate helper: %v", err) + } + } switch { case tc.hostOS == "linux": if _, err := os.Stat(helper); !os.IsNotExist(err) { diff --git a/docs/deployment.md b/docs/deployment.md index 00ee8ec46..6480ead63 100644 --- a/docs/deployment.md +++ b/docs/deployment.md @@ -133,7 +133,7 @@ The upstream process roles remain `-role api`, `-role worker` and `-role all`. A Personal runners are connected from the execution-machine page with a short-lived binding code. The installer is served at `/runners/install.sh`. `AGENTFLOW_RUNNER_BINARY` can point to binaries with `{os}` and `{arch}` substitutions. Container images bundle Linux/macOS amd64/arm64 runner and gate binaries. Native source installations can build on demand with Go. -Docker workspaces on macOS use a Linux Runner executable for Git credentials and MCP calls. The installer chooses the architecture of the installed macOS Runner, including Intel binaries running under Rosetta. Universal Runners receive helpers for both supported slices. It places the helper next to the host binary by default. A Runner-side `AGENTFLOW_RUNNER_BINARY` template with `{os}` selects the installation and runtime path. Use `{arch}` in the template for a universal Runner. The installer saves it for upgrades and includes it in launchd and in the startup command printed by `--no-start`. The helper path must resolve to a separate file from the macOS Runner. +Docker workspaces on macOS use a Linux Runner executable for Git credentials and MCP calls. The installer chooses the architecture of the installed macOS Runner, including Intel binaries running under Rosetta. For a universal Runner on Apple Silicon it installs the arm64 helpers and adds the amd64 helpers when available. On Intel Macs it installs the amd64 helpers. By default, the installer places the helpers next to the host binary. A Runner-side `AGENTFLOW_RUNNER_BINARY` template with `{os}` selects the installation and runtime path. To install both helpers, use `{arch}` and give each architecture a distinct destination. The installer saves the template for upgrades and includes it in launchd and in the startup command printed by `--no-start`. Helper paths must resolve to files separate from the macOS Runner. The installer and updater validate the Linux executable's format, architecture, and load segments before replacing it. Custom installs keep a compatible existing helper. A Runner built from a local checkout can build its companion from that checkout. A download URL with an `{os}` placeholder can supply both binaries when used as the Runner's download source. From ede101a40477de0f48ccd2bd055fd0222f4b33c1 Mon Sep 17 00:00:00 2001 From: crispinhu Date: Fri, 20 Nov 2026 01:17:43 +0800 Subject: [PATCH 07/13] fix(runner): launch universal macOS runners natively --- deploy/bind-cli.sh | 15 ++++++++++----- deploy/bind_cli_docker_runner_test.go | 4 ++++ docs/deployment.md | 2 +- 3 files changed, 15 insertions(+), 6 deletions(-) diff --git a/deploy/bind-cli.sh b/deploy/bind-cli.sh index dcd542a2e..3ef0ae2af 100755 --- a/deploy/bind-cli.sh +++ b/deploy/bind-cli.sh @@ -926,6 +926,12 @@ RUN_ARGS=(-server "$SERVER" -token "$TOKEN" -name "${NAME:-$(hostname)}" -concur if [[ "$AUTO_UPDATE" == "0" ]]; then RUN_ARGS+=(-auto-update=false) fi +RUNNER_LAUNCH=("$BINARY") +if [[ "$OS" == "darwin" && "${#runner_arches[@]}" -gt 1 ]]; then + # Use the required native slice for foreground and manual starts, even + # when the shell runs under Rosetta and the optional amd64 files are absent. + RUNNER_LAUNCH=(/usr/bin/arch -arm64 "$BINARY") +fi # 用户当前 PATH:launchd/systemd 的服务环境只有 /usr/bin:/bin,不含 # ~/.local/bin、Homebrew、nvm 等 CLI 安装目录,必须显式带入。 @@ -937,11 +943,10 @@ if [[ "$NO_START" == "1" ]]; then if [[ "${AGENTFLOW_RUNNER_BINARY:-}" == *"{os}"* ]]; then runner_command="AGENTFLOW_RUNNER_BINARY=$(shell_quote "$AGENTFLOW_RUNNER_BINARY") " fi - runner_command+="$(shell_quote "$BINARY")" - for arg in "${RUN_ARGS[@]}"; do - runner_command+=" $(shell_quote "$arg")" + for arg in "${RUNNER_LAUNCH[@]}" "${RUN_ARGS[@]}"; do + runner_command+="$(shell_quote "$arg") " done - info " $runner_command" + info " ${runner_command% }" info "常驻方式:追加 --service 重新执行本脚本;卸载:追加 --uninstall(--purge 删除全部配置)" elif [[ "$INSTALL_SERVICE" == "1" ]]; then if [[ "$OS" == "darwin" ]]; then @@ -1004,5 +1009,5 @@ EOF info "卸载方式:curl -fsSL ${SERVER}/runners/install.sh | bash -s -- --uninstall" else info "前台启动 agentflow-runner(Ctrl+C 停止;常驻请加 --service)..." - exec "$BINARY" "${RUN_ARGS[@]}" + exec "${RUNNER_LAUNCH[@]}" "${RUN_ARGS[@]}" fi diff --git a/deploy/bind_cli_docker_runner_test.go b/deploy/bind_cli_docker_runner_test.go index 7f973c710..754265768 100644 --- a/deploy/bind_cli_docker_runner_test.go +++ b/deploy/bind_cli_docker_runner_test.go @@ -253,6 +253,10 @@ func TestBindCLIInstallsDockerRunnerHelper(t *testing.T) { return string(out) } output := install() + if tc.universal && !tc.intelHardware && !tc.sharedTemplateDir && + !strings.Contains(output, "/usr/bin/arch -arm64 ") { + t.Fatalf("the manual launch command can inherit Rosetta: %s", output) + } if tc.sharedTemplateDir { if _, err := os.Stat(helper); !os.IsNotExist(err) { t.Fatalf("the installer wrote a helper before rejecting the conflicting template: %v", err) diff --git a/docs/deployment.md b/docs/deployment.md index 6480ead63..c89e9b7d0 100644 --- a/docs/deployment.md +++ b/docs/deployment.md @@ -133,7 +133,7 @@ The upstream process roles remain `-role api`, `-role worker` and `-role all`. A Personal runners are connected from the execution-machine page with a short-lived binding code. The installer is served at `/runners/install.sh`. `AGENTFLOW_RUNNER_BINARY` can point to binaries with `{os}` and `{arch}` substitutions. Container images bundle Linux/macOS amd64/arm64 runner and gate binaries. Native source installations can build on demand with Go. -Docker workspaces on macOS use a Linux Runner executable for Git credentials and MCP calls. The installer chooses the architecture of the installed macOS Runner, including Intel binaries running under Rosetta. For a universal Runner on Apple Silicon it installs the arm64 helpers and adds the amd64 helpers when available. On Intel Macs it installs the amd64 helpers. By default, the installer places the helpers next to the host binary. A Runner-side `AGENTFLOW_RUNNER_BINARY` template with `{os}` selects the installation and runtime path. To install both helpers, use `{arch}` and give each architecture a distinct destination. The installer saves the template for upgrades and includes it in launchd and in the startup command printed by `--no-start`. Helper paths must resolve to files separate from the macOS Runner. +Docker workspaces on macOS use a Linux Runner executable for Git credentials and MCP calls. The installer chooses the architecture of the installed macOS Runner, including Intel binaries running under Rosetta. For a universal Runner on Apple Silicon it installs the arm64 helpers and adds the amd64 helpers when available. Foreground starts and the command printed by `--no-start` select the native arm64 slice, including from a Rosetta shell. On Intel Macs the installer installs the amd64 helpers. By default, it places the helpers next to the host binary. A Runner-side `AGENTFLOW_RUNNER_BINARY` template with `{os}` selects the installation and runtime path. To install both helpers, use `{arch}` and give each architecture a distinct destination. The installer saves the template for upgrades and includes it in launchd and in the startup command printed by `--no-start`. Helper paths must resolve to files separate from the macOS Runner. The installer and updater validate the Linux executable's format, architecture, and load segments before replacing it. Custom installs keep a compatible existing helper. A Runner built from a local checkout can build its companion from that checkout. A download URL with an `{os}` placeholder can supply both binaries when used as the Runner's download source. From 79ae312bdb9dc93ab39e949baa5ef7dbaf1abce7 Mon Sep 17 00:00:00 2001 From: crispinhu Date: Fri, 20 Nov 2026 01:35:12 +0800 Subject: [PATCH 08/13] fix(runner): validate helper destinations before publishing upgrades --- deploy/bind-cli.sh | 53 ++++++++++++++---------- deploy/bind_cli_docker_runner_test.go | 59 ++++++++++++++++++++++++--- docs/deployment.md | 2 +- 3 files changed, 86 insertions(+), 28 deletions(-) diff --git a/deploy/bind-cli.sh b/deploy/bind-cli.sh index 3ef0ae2af..56e7de5dc 100755 --- a/deploy/bind-cli.sh +++ b/deploy/bind-cli.sh @@ -610,7 +610,7 @@ publish_runner_binary() { TEMP_BINARY="" } -install_binary() { +stage_runner_binary() { mkdir -p "$BIN_DIR" TEMP_BINARY=$(mktemp "${BIN_DIR}/.agentflow-runner.XXXXXX") if [[ -n "$LOCAL_BINARY" ]]; then @@ -637,7 +637,7 @@ install_binary() { || fail "源码构建失败;请检查 Go 版本(需 1.22+)或改用 --from" fi fi - publish_runner_binary "$BINARY" + [[ -s "$TEMP_BINARY" ]] || fail "下载或构建的 runner 二进制为空" } is_linux_runner_binary() { @@ -734,8 +734,11 @@ install_docker_runner_binary() { } TEMP_BINARY="" -trap '[[ -z "$TEMP_BINARY" ]] || rm -f "$TEMP_BINARY"' EXIT -install_binary +STAGED_RUNNER="" +trap '[[ -z "$TEMP_BINARY" ]] || rm -f "$TEMP_BINARY"; [[ -z "$STAGED_RUNNER" ]] || rm -f "$STAGED_RUNNER"' EXIT +stage_runner_binary +STAGED_RUNNER="$TEMP_BINARY" +TEMP_BINARY="" saved_runner_binary_pattern() { awk 'sub(/^AGENTFLOW_RUNNER_BINARY=/, "") { print; exit }' "$ENV_FILE" @@ -781,21 +784,25 @@ canonical_helper_target() { (mkdir -p "$dir" && cd -P "$dir" && printf '%s/%s\n' "$PWD" "${target##*/}") } -check_universal_helper_paths() { - [[ "${#runner_arches[@]}" -gt 1 && "$AGENTFLOW_RUNNER_BINARY" == *"{os}"* ]] || return 0 - local amd64 arm64 resolved_amd64 resolved_arm64 - amd64=$(macos_docker_runner_helper_path amd64) - arm64=$(macos_docker_runner_helper_path arm64) - if [[ "$amd64" -ef "$arm64" ]]; then - fail "两种架构的 Linux Git/MCP helper 路径相同,请使用独立的架构目录" - fi - # The installer can still warn and skip a target whose directory is - # unavailable. For writable paths, check the physical parent directories. - resolved_amd64=$(canonical_helper_target "$amd64" 2>/dev/null) || return 0 - resolved_arm64=$(canonical_helper_target "$arm64" 2>/dev/null) || return 0 - if [[ "$resolved_amd64" == "$resolved_arm64" ]]; then - fail "两种架构的 Linux Git/MCP helper 路径相同,请使用独立的架构目录" - fi +check_macos_helper_paths() { + local host_target target resolved runner_arch previous_target="" previous_resolved="" + host_target=$(canonical_helper_target "$BINARY") + for runner_arch in "${runner_arches[@]}"; do + target=$(macos_docker_runner_helper_path "$runner_arch") + # Compare physical parents even on fresh installs, where -ef cannot + # compare inodes yet. Unavailable helper destinations are warned about + # by the installer when it tries to stage the companion. + resolved=$(canonical_helper_target "$target" 2>/dev/null) || resolved="" + if [[ -n "$resolved" && "$resolved" == "$host_target" ]]; then + fail "Linux Git/MCP helper 路径与 macOS Runner 相同:${target}" + fi + if [[ -n "$previous_target" && "$target" -ef "$previous_target" ]] || + [[ -n "$resolved" && "$resolved" == "$previous_resolved" ]]; then + fail "两种架构的 Linux Git/MCP helper 路径相同,请使用独立的架构目录" + fi + previous_target="$target" + previous_resolved="$resolved" + done } save_runner_binary_pattern() { @@ -811,7 +818,7 @@ save_runner_binary_pattern() { } if [[ "$OS" == "darwin" ]]; then - read -r -a runner_arches <<< "$(macos_runner_arches "$BINARY")" + read -r -a runner_arches <<< "$(macos_runner_arches "$STAGED_RUNNER")" # uname reports x86_64 under Rosetta too. Intel Macs can use only the # amd64 slice and may be connected to a platform that publishes only amd64. if [[ "${#runner_arches[@]}" -gt 1 && "$ARCH" == "amd64" && @@ -819,7 +826,7 @@ if [[ "$OS" == "darwin" ]]; then runner_arches=(amd64) fi configure_macos_docker_runner_helper - check_universal_helper_paths + check_macos_helper_paths fi install_gate_binary() { @@ -871,6 +878,10 @@ else install_gate_binary "$OS" fi +TEMP_BINARY="$STAGED_RUNNER" +STAGED_RUNNER="" +publish_runner_binary "$BINARY" + if [[ "$UPGRADE" == "1" ]]; then if [[ "$OS" == "darwin" ]]; then save_runner_binary_pattern diff --git a/deploy/bind_cli_docker_runner_test.go b/deploy/bind_cli_docker_runner_test.go index 754265768..f08fddb72 100644 --- a/deploy/bind_cli_docker_runner_test.go +++ b/deploy/bind_cli_docker_runner_test.go @@ -35,6 +35,8 @@ func TestBindCLIInstallsDockerRunnerHelper(t *testing.T) { universal bool intelHardware, sharedTemplateDir bool arm64OnlyArtifacts bool + templateMissingArch bool + missingRequiredGate bool }{ {name: "macOS_install", hostOS: "darwin", arch: "arm64", unameArch: "arm64"}, {name: "macOS_uses_template_in_manual_start_and_upgrade", hostOS: "darwin", arch: "arm64", unameArch: "arm64", templatePath: true, source: "from"}, @@ -55,6 +57,8 @@ func TestBindCLIInstallsDockerRunnerHelper(t *testing.T) { {name: "macOS_Intel_installs_universal_Runner_from_amd64_only_platform", hostOS: "darwin", arch: "amd64", unameArch: "x86_64", source: "from", universal: true, intelHardware: true}, {name: "macOS_Apple_Silicon_installs_universal_Runner_from_arm64_only_platform", hostOS: "darwin", arch: "arm64", unameArch: "arm64", source: "from", universal: true, arm64OnlyArtifacts: true}, {name: "macOS_rejects_universal_companions_with_a_shared_template_directory", hostOS: "darwin", arch: "arm64", unameArch: "x86_64", source: "from", universal: true, templatePath: true, sharedTemplateDir: true}, + {name: "macOS_rejected_universal_upgrade_preserves_installed_runner", hostOS: "darwin", arch: "arm64", unameArch: "arm64", source: "from", universal: true, upgrade: true, launchd: true, templatePath: true, templateMissingArch: true}, + {name: "macOS_preserves_installed_runner_if_required_gate_is_unavailable", hostOS: "darwin", arch: "arm64", unameArch: "arm64", source: "from", universal: true, upgrade: true, missingRequiredGate: true}, {name: "macOS_repairs_incompatible_local_helper", hostOS: "darwin", arch: "arm64", unameArch: "arm64", source: "from", existing: "mach-o", upgrade: true}, {name: "macOS_preserves_custom_helper_script", hostOS: "darwin", arch: "arm64", unameArch: "arm64", source: "from", existing: "script", preserveHelper: true}, {name: "macOS_preserves_helper_with_host_only_URL", hostOS: "darwin", arch: "arm64", unameArch: "arm64", source: "host-url", preserveHelper: true}, @@ -145,6 +149,10 @@ func TestBindCLIInstallsDockerRunnerHelper(t *testing.T) { fmt.Fprint(w, bindFixtureLinuxRunner(arch, "new helper")) } case "/runners/agentflow-gate-mcp": + if tc.missingRequiredGate && targetOS == "darwin" && arch == "arm64" { + http.NotFound(w, req) + return + } fmt.Fprintf(w, "gate %s/%s", targetOS, arch) default: http.NotFound(w, req) @@ -158,6 +166,11 @@ func TestBindCLIInstallsDockerRunnerHelper(t *testing.T) { patternEnv = filepath.Join(bundle, "{os}", "{arch}", "agentflow-runner") helper = filepath.Join(bundle, "linux", tc.arch, "agentflow-runner") } + if tc.templateMissingArch { + patternEnv = filepath.Join(bundle, "{os}", "agentflow-runner") + helper = filepath.Join(bundle, "linux", "agentflow-runner") + oldHelper = bindFixtureLinuxRunner("amd64", "original Intel helper") + } if tc.sharedTemplateDir { amd64 := filepath.Join(bundle, "linux", "amd64") if err := os.MkdirAll(amd64, 0o755); err != nil { @@ -169,14 +182,21 @@ func TestBindCLIInstallsDockerRunnerHelper(t *testing.T) { } statePath := filepath.Join(fixtureHome, ".agentflow-runner", "state.json") const state = `{"runnerId":"fixture"}` + const oldHost = "\xcf\xfa\xed\xfe\x07\x00\x00\x01 old Intel Runner" + envPath := filepath.Join(filepath.Dir(statePath), "env") + initialEnv := "AGENTFLOW_SERVER_URL=" + server.URL + "\n" if tc.upgrade { if err := os.Mkdir(filepath.Dir(statePath), 0o700); err != nil { t.Fatal(err) } + if tc.templateMissingArch { + initialEnv += "AGENTFLOW_RUNNER_BINARY=" + patternEnv + "\n" + patternEnv = "" // Use the saved configuration, with no process override. + } for path, data := range map[string]string{ - statePath: state, - filepath.Join(filepath.Dir(statePath), "env"): "AGENTFLOW_SERVER_URL=" + server.URL + "\n", - filepath.Join(bin, "agentflow-runner"): "old host runner", + statePath: state, + envPath: initialEnv, + filepath.Join(bin, "agentflow-runner"): oldHost, } { if err := os.WriteFile(path, []byte(data), 0o700); err != nil { t.Fatal(err) @@ -213,7 +233,10 @@ func TestBindCLIInstallsDockerRunnerHelper(t *testing.T) { t.Fatal(err) } } - if (tc.upgrade && !tc.templatePath) || tc.source == "template" || tc.preserveHelper { + if (tc.upgrade && !tc.templatePath) || tc.source == "template" || tc.preserveHelper || tc.templateMissingArch { + if err := os.MkdirAll(filepath.Dir(helper), 0o755); err != nil { + t.Fatal(err) + } if err := os.WriteFile(helper, []byte(oldHelper), 0o755); err != nil { t.Fatal(err) } @@ -247,12 +270,36 @@ func TestBindCLIInstallsDockerRunnerHelper(t *testing.T) { if err == nil || !strings.Contains(string(out), "两种架构的 Linux Git/MCP helper 路径相同") { t.Fatalf("installer did not reject the shared template path: %v\n%s", err, out) } + } else if tc.templateMissingArch { + if err == nil || !strings.Contains(string(out), "请在 AGENTFLOW_RUNNER_BINARY 中添加 {arch}") { + t.Fatalf("installer did not reject the old single-architecture template: %v\n%s", err, out) + } + } else if tc.missingRequiredGate { + if err == nil || !strings.Contains(string(out), "平台未提供 Gate MCP darwin/arm64") { + t.Fatalf("installer did not report the missing required Gate helper: %v\n%s", err, out) + } } else if err != nil { t.Fatalf("install: %v\n%s", err, out) } return string(out) } output := install() + if tc.templateMissingArch || tc.missingRequiredGate { + for path, want := range map[string]string{ + filepath.Join(bin, "agentflow-runner"): oldHost, + helper: oldHelper, + envPath: initialEnv, + statePath: state, + } { + if got, err := os.ReadFile(path); err != nil || string(got) != want { + t.Fatalf("rejected upgrade changed %s: %q, %v", filepath.Base(path), got, err) + } + } + if _, err := os.Stat(filepath.Join(fixtureHome, "reloaded.plist")); !os.IsNotExist(err) { + t.Fatalf("rejected upgrade restarted the service: %v", err) + } + return + } if tc.universal && !tc.intelHardware && !tc.sharedTemplateDir && !strings.Contains(output, "/usr/bin/arch -arm64 ") { t.Fatalf("the manual launch command can inherit Rosetta: %s", output) @@ -264,8 +311,8 @@ func TestBindCLIInstallsDockerRunnerHelper(t *testing.T) { return } if tc.helperAliasesRunner { - if got, err := os.ReadFile(helper); err != nil || string(got) != hostRunner { - t.Fatalf("macOS Runner was changed by the helper install: %q, %v", got, err) + if _, err := os.Stat(helper); !os.IsNotExist(err) { + t.Fatalf("installer published the runner before rejecting its conflicting helper path: %v", err) } return } diff --git a/docs/deployment.md b/docs/deployment.md index c89e9b7d0..a1012b145 100644 --- a/docs/deployment.md +++ b/docs/deployment.md @@ -135,7 +135,7 @@ Personal runners are connected from the execution-machine page with a short-live Docker workspaces on macOS use a Linux Runner executable for Git credentials and MCP calls. The installer chooses the architecture of the installed macOS Runner, including Intel binaries running under Rosetta. For a universal Runner on Apple Silicon it installs the arm64 helpers and adds the amd64 helpers when available. Foreground starts and the command printed by `--no-start` select the native arm64 slice, including from a Rosetta shell. On Intel Macs the installer installs the amd64 helpers. By default, it places the helpers next to the host binary. A Runner-side `AGENTFLOW_RUNNER_BINARY` template with `{os}` selects the installation and runtime path. To install both helpers, use `{arch}` and give each architecture a distinct destination. The installer saves the template for upgrades and includes it in launchd and in the startup command printed by `--no-start`. Helper paths must resolve to files separate from the macOS Runner. -The installer and updater validate the Linux executable's format, architecture, and load segments before replacing it. Custom installs keep a compatible existing helper. A Runner built from a local checkout can build its companion from that checkout. A download URL with an `{os}` placeholder can supply both binaries when used as the Runner's download source. +The installer checks the helper destinations against the staged macOS binary and installs the required Gate MCP helpers before replacing an installed Runner. The installer and updater validate the Linux executable's format, architecture, and load segments before replacing it. Custom installs keep a compatible existing helper. A Runner built from a local checkout can build its companion from that checkout. A download URL with an `{os}` placeholder can supply both binaries when used as the Runner's download source. When platform updates are enabled, macOS runners synchronize the helper in the background at startup. A failed version check is retried during rescans, including when an older helper remains usable. Operations that need a missing helper for Git or MCP can wait up to five seconds for the initial sync. The background download continues within its own transfer timeout. From c9664f09e2b0ad12288fb30a4461f7c30ffcd568 Mon Sep 17 00:00:00 2001 From: crispinhu Date: Fri, 20 Nov 2026 02:00:39 +0800 Subject: [PATCH 09/13] fix(runner): preserve Docker support across macOS architecture upgrades --- deploy/bind-cli.sh | 82 +++++++++++++++------------ deploy/bind_cli_docker_runner_test.go | 47 ++++++++++++--- docs/deployment.md | 2 +- 3 files changed, 87 insertions(+), 44 deletions(-) diff --git a/deploy/bind-cli.sh b/deploy/bind-cli.sh index 56e7de5dc..20241c57a 100755 --- a/deploy/bind-cli.sh +++ b/deploy/bind-cli.sh @@ -341,7 +341,7 @@ esac [[ "$OS" == "darwin" || "$OS" == "linux" ]] || fail "不支持的系统: ${OS}(Windows 请使用 PowerShell 安装方式)" # Use the Mach-O slices instead of uname. A universal Runner installed under -# Rosetta can later be launched natively by launchd. +# Rosetta can later be launched natively by launchd. List the native slice first. macos_runner_arches() { local header="" entry_size little=0 arches if [[ -f "$1" ]]; then @@ -373,10 +373,15 @@ macos_runner_arches() { if (cpu == 16777223) amd64 = 1 if (cpu == 16777228) arm64 = 1 } - if (amd64 && arm64) print "amd64 arm64" + if (amd64 && arm64) print "arm64 amd64" else if (amd64) print "amd64" else if (arm64) print "arm64" }') || arches="" + # uname reports x86_64 under Rosetta too. Intel Macs can use only amd64. + if [[ "$arches" == "arm64 amd64" && "$ARCH" == "amd64" && + "$(PATH="$PATH:/usr/sbin" sysctl -n hw.optional.arm64 2>/dev/null || true)" != "1" ]]; then + arches="amd64" + fi printf '%s\n' "${arches:-$ARCH}" } @@ -642,9 +647,10 @@ stage_runner_binary() { is_linux_runner_binary() { local binary="$1" machine size layout offset table_size - case "$ARCH" in + case "${2:-$ARCH}" in amd64) machine=62 ;; arm64) machine=183 ;; + *) return 1 ;; esac size=$(wc -c < "$binary") || return 1 local decode_bytes=' @@ -688,11 +694,11 @@ is_linux_runner_binary() { }' } -is_custom_docker_runner_helper() { +is_usable_docker_runner_helper() { [[ -x "$1" && -f "$1" ]] || return 1 # A custom installer may also provide an executable script wrapper. [[ "$(LC_ALL=C od -An -v -t x1 -N 2 "$1" | tr -d '[:space:]')" == 2321 ]] || - is_linux_runner_binary "$1" + is_linux_runner_binary "$1" "${2:-$ARCH}" } stage_docker_runner_binary() { @@ -713,7 +719,7 @@ install_docker_runner_binary() { # A per-OS download URL can replace the helper when it is the selected source. if [[ -n "$LOCAL_BINARY" || -n "$RUNNER_BUILD_SOURCE" || ( "$DOWNLOAD_URL" != *"{os}"* && ( -n "$DOWNLOAD_URL" || -n "$SOURCE_DIR" ) ) ]] && - is_custom_docker_runner_helper "$DOCKER_RUNNER_BINARY"; then + is_usable_docker_runner_helper "$DOCKER_RUNNER_BINARY"; then info "保留自定义 Runner 的 Linux Git/MCP helper:${DOCKER_RUNNER_BINARY}" return fi @@ -744,16 +750,16 @@ saved_runner_binary_pattern() { awk 'sub(/^AGENTFLOW_RUNNER_BINARY=/, "") { print; exit }' "$ENV_FILE" } -configure_macos_docker_runner_helper() { - local pattern="${AGENTFLOW_RUNNER_BINARY:-}" - if [[ "$UPGRADE" == "1" && -z "${AGENTFLOW_RUNNER_BINARY+x}" ]]; then - if [[ -f "$PLIST" ]]; then - pattern=$(/usr/bin/plutil -extract EnvironmentVariables.AGENTFLOW_RUNNER_BINARY raw "$PLIST" 2>/dev/null) || - pattern=$(saved_runner_binary_pattern) - else - pattern=$(saved_runner_binary_pattern) - fi +installed_macos_runner_binary_pattern() { + if [[ -f "$PLIST" ]] && + /usr/bin/plutil -extract EnvironmentVariables.AGENTFLOW_RUNNER_BINARY raw "$PLIST" 2>/dev/null; then + return fi + saved_runner_binary_pattern +} + +configure_macos_docker_runner_helper() { + local pattern="${AGENTFLOW_RUNNER_BINARY-$1}" # Keep the template expansion in sync with runtime.DockerRunnerHelperPath. pattern="${pattern#"${pattern%%[![:space:]]*}"}" pattern="${pattern%"${pattern##*[![:space:]]}"}" @@ -767,14 +773,11 @@ configure_macos_docker_runner_helper() { } macos_docker_runner_helper_path() { - local target_arch="$1" target="${BIN_DIR}/agentflow-runner-linux-${1}" - if [[ "$AGENTFLOW_RUNNER_BINARY" == *"{os}"* ]]; then - target="${AGENTFLOW_RUNNER_BINARY//\{os\}/linux}" + local target_arch="$1" pattern="$2" target="${BIN_DIR}/agentflow-runner-linux-${1}" + if [[ "$pattern" == *"{os}"* ]]; then + target="${pattern//\{os\}/linux}" target="${target//\{arch\}/$target_arch}" fi - if [[ "$target" -ef "$BINARY" ]]; then - fail "Linux Git/MCP helper 路径与 macOS Runner 相同:${target}" - fi printf '%s\n' "$target" } @@ -788,12 +791,12 @@ check_macos_helper_paths() { local host_target target resolved runner_arch previous_target="" previous_resolved="" host_target=$(canonical_helper_target "$BINARY") for runner_arch in "${runner_arches[@]}"; do - target=$(macos_docker_runner_helper_path "$runner_arch") + target=$(macos_docker_runner_helper_path "$runner_arch" "$AGENTFLOW_RUNNER_BINARY") # Compare physical parents even on fresh installs, where -ef cannot # compare inodes yet. Unavailable helper destinations are warned about # by the installer when it tries to stage the companion. resolved=$(canonical_helper_target "$target" 2>/dev/null) || resolved="" - if [[ -n "$resolved" && "$resolved" == "$host_target" ]]; then + if [[ "$target" -ef "$BINARY" ]] || [[ -n "$resolved" && "$resolved" == "$host_target" ]]; then fail "Linux Git/MCP helper 路径与 macOS Runner 相同:${target}" fi if [[ -n "$previous_target" && "$target" -ef "$previous_target" ]] || @@ -819,13 +822,22 @@ save_runner_binary_pattern() { if [[ "$OS" == "darwin" ]]; then read -r -a runner_arches <<< "$(macos_runner_arches "$STAGED_RUNNER")" - # uname reports x86_64 under Rosetta too. Intel Macs can use only the - # amd64 slice and may be connected to a platform that publishes only amd64. - if [[ "${#runner_arches[@]}" -gt 1 && "$ARCH" == "amd64" && - "$(PATH="$PATH:/usr/sbin" sysctl -n hw.optional.arm64 2>/dev/null || true)" != "1" ]]; then - runner_arches=(amd64) + required_arch="${runner_arches[0]}" + previous_pattern="" + require_replacement_helper=0 + if [[ "$UPGRADE" == "1" ]]; then + previous_pattern=$(installed_macos_runner_binary_pattern) + read -r -a previous_arches <<< "$(macos_runner_arches "$BINARY")" + previous_arch="${previous_arches[0]}" + if [[ "$previous_arch" != "$required_arch" ]]; then + previous_helper=$(macos_docker_runner_helper_path "$previous_arch" "$previous_pattern") + if [[ ! "$previous_helper" -ef "$BINARY" ]] && + is_usable_docker_runner_helper "$previous_helper" "$previous_arch"; then + require_replacement_helper=1 + fi + fi fi - configure_macos_docker_runner_helper + configure_macos_docker_runner_helper "$previous_pattern" check_macos_helper_paths fi @@ -860,19 +872,19 @@ install_gate_binary() { fi } -# A universal Runner needs both companions whichever slice gets launched. +# Install the primary slice's companions before touching the optional slice. if [[ "$OS" == "darwin" ]]; then - required_arch="${runner_arches[0]}" - if [[ "${#runner_arches[@]}" -gt 1 ]]; then - required_arch="arm64" - fi for ARCH in "${runner_arches[@]}"; do - DOCKER_RUNNER_BINARY=$(macos_docker_runner_helper_path "$ARCH") + DOCKER_RUNNER_BINARY=$(macos_docker_runner_helper_path "$ARCH" "$AGENTFLOW_RUNNER_BINARY") optional_gate=0 [[ "$ARCH" == "$required_arch" ]] || optional_gate=1 install_gate_binary darwin "$optional_gate" install_gate_binary linux "$optional_gate" install_docker_runner_binary + if [[ "$ARCH" == "$required_arch" && "$require_replacement_helper" == "1" ]] && + ! is_usable_docker_runner_helper "$DOCKER_RUNNER_BINARY"; then + fail "缺少切换架构所需的 Linux/${ARCH} Git/MCP helper,已保留当前 Runner 和服务:${DOCKER_RUNNER_BINARY}" + fi done else install_gate_binary "$OS" diff --git a/deploy/bind_cli_docker_runner_test.go b/deploy/bind_cli_docker_runner_test.go index f08fddb72..076783654 100644 --- a/deploy/bind_cli_docker_runner_test.go +++ b/deploy/bind_cli_docker_runner_test.go @@ -37,6 +37,7 @@ func TestBindCLIInstallsDockerRunnerHelper(t *testing.T) { arm64OnlyArtifacts bool templateMissingArch bool missingRequiredGate bool + missingReplacementHelper bool }{ {name: "macOS_install", hostOS: "darwin", arch: "arm64", unameArch: "arm64"}, {name: "macOS_uses_template_in_manual_start_and_upgrade", hostOS: "darwin", arch: "arm64", unameArch: "arm64", templatePath: true, source: "from"}, @@ -59,13 +60,14 @@ func TestBindCLIInstallsDockerRunnerHelper(t *testing.T) { {name: "macOS_rejects_universal_companions_with_a_shared_template_directory", hostOS: "darwin", arch: "arm64", unameArch: "x86_64", source: "from", universal: true, templatePath: true, sharedTemplateDir: true}, {name: "macOS_rejected_universal_upgrade_preserves_installed_runner", hostOS: "darwin", arch: "arm64", unameArch: "arm64", source: "from", universal: true, upgrade: true, launchd: true, templatePath: true, templateMissingArch: true}, {name: "macOS_preserves_installed_runner_if_required_gate_is_unavailable", hostOS: "darwin", arch: "arm64", unameArch: "arm64", source: "from", universal: true, upgrade: true, missingRequiredGate: true}, + {name: "macOS_architecture_upgrade_keeps_working_runner_when_new_helper_is_unavailable", hostOS: "darwin", arch: "arm64", unameArch: "arm64", source: "from", universal: true, upgrade: true, launchd: true, missingReplacementHelper: true}, {name: "macOS_repairs_incompatible_local_helper", hostOS: "darwin", arch: "arm64", unameArch: "arm64", source: "from", existing: "mach-o", upgrade: true}, {name: "macOS_preserves_custom_helper_script", hostOS: "darwin", arch: "arm64", unameArch: "arm64", source: "from", existing: "script", preserveHelper: true}, {name: "macOS_preserves_helper_with_host_only_URL", hostOS: "darwin", arch: "arm64", unameArch: "arm64", source: "host-url", preserveHelper: true}, {name: "macOS_updates_helper_with_explicit_Linux_URL", hostOS: "darwin", arch: "arm64", unameArch: "arm64", source: "template"}, } { t.Run(tc.name, func(t *testing.T) { - if tc.launchd && runtime.GOOS != "darwin" { + if tc.launchd && !tc.missingReplacementHelper && runtime.GOOS != "darwin" { t.Skip("requires macOS plutil") } fixtureHome := t.TempDir() @@ -134,6 +136,10 @@ func TestBindCLIInstallsDockerRunnerHelper(t *testing.T) { fmt.Fprint(w, hostRunner) return } + if tc.missingReplacementHelper && arch == "arm64" { + w.WriteHeader(http.StatusServiceUnavailable) + return + } switch tc.helperArtifact { case "unavailable": http.NotFound(w, req) @@ -171,6 +177,10 @@ func TestBindCLIInstallsDockerRunnerHelper(t *testing.T) { helper = filepath.Join(bundle, "linux", "agentflow-runner") oldHelper = bindFixtureLinuxRunner("amd64", "original Intel helper") } + if tc.missingReplacementHelper { + oldHelper = bindFixtureLinuxRunner("amd64", "existing Intel helper") + helper = filepath.Join(bin, "agentflow-runner-linux-amd64") + } if tc.sharedTemplateDir { amd64 := filepath.Join(bundle, "linux", "amd64") if err := os.MkdirAll(amd64, 0o755); err != nil { @@ -220,19 +230,29 @@ func TestBindCLIInstallsDockerRunnerHelper(t *testing.T) { } plist := filepath.Join(fixtureHome, "Library", "LaunchAgents", "com.agentflow.runner.plist") oldServiceArgs := []string{filepath.Join(bin, "agentflow-runner"), "-labels", "fixture", "-auto-update=true"} + if tc.missingReplacementHelper { + oldServiceArgs[len(oldServiceArgs)-1] = "-auto-update=false" + } + initialPlist := "" if tc.launchd { if err := os.MkdirAll(filepath.Dir(plist), 0o700); err != nil { t.Fatal(err) } - data := fmt.Sprintf("KeepAliveProgramArguments%s", strings.Join(oldServiceArgs, "")) - if err := os.WriteFile(plist, []byte(data), 0o600); err != nil { + initialPlist = fmt.Sprintf("KeepAliveProgramArguments%s", strings.Join(oldServiceArgs, "")) + if err := os.WriteFile(plist, []byte(initialPlist), 0o600); err != nil { t.Fatal(err) } - launchctl := "#!/bin/sh\nif [ \"$1\" = load ]; then cp \"$2\" \"$HOME/reloaded.plist\"; fi\n" + launchctl := "#!/bin/sh\nprintf '%s\\n' \"$1\" >> \"$HOME/launchctl.log\"\nif [ \"$1\" = load ]; then cp \"$2\" \"$HOME/reloaded.plist\"; fi\n" if err := os.WriteFile(filepath.Join(bin, "launchctl"), []byte(launchctl), 0o755); err != nil { t.Fatal(err) } } + oldGate := filepath.Join(bin, "agentflow-gate-mcp-linux-amd64") + if tc.missingReplacementHelper { + if err := os.WriteFile(oldGate, []byte("original Intel Gate"), 0o755); err != nil { + t.Fatal(err) + } + } if (tc.upgrade && !tc.templatePath) || tc.source == "template" || tc.preserveHelper || tc.templateMissingArch { if err := os.MkdirAll(filepath.Dir(helper), 0o755); err != nil { t.Fatal(err) @@ -278,24 +298,35 @@ func TestBindCLIInstallsDockerRunnerHelper(t *testing.T) { if err == nil || !strings.Contains(string(out), "平台未提供 Gate MCP darwin/arm64") { t.Fatalf("installer did not report the missing required Gate helper: %v\n%s", err, out) } + } else if tc.missingReplacementHelper { + if err == nil || !strings.Contains(string(out), "缺少切换架构所需的 Linux/arm64 Git/MCP helper") { + t.Fatalf("installer did not abort the architecture switch: %v\n%s", err, out) + } } else if err != nil { t.Fatalf("install: %v\n%s", err, out) } return string(out) } output := install() - if tc.templateMissingArch || tc.missingRequiredGate { - for path, want := range map[string]string{ + if tc.templateMissingArch || tc.missingRequiredGate || tc.missingReplacementHelper { + preserved := map[string]string{ filepath.Join(bin, "agentflow-runner"): oldHost, helper: oldHelper, envPath: initialEnv, statePath: state, - } { + } + if tc.launchd { + preserved[plist] = initialPlist + } + if tc.missingReplacementHelper { + preserved[oldGate] = "original Intel Gate" + } + for path, want := range preserved { if got, err := os.ReadFile(path); err != nil || string(got) != want { t.Fatalf("rejected upgrade changed %s: %q, %v", filepath.Base(path), got, err) } } - if _, err := os.Stat(filepath.Join(fixtureHome, "reloaded.plist")); !os.IsNotExist(err) { + if _, err := os.Stat(filepath.Join(fixtureHome, "launchctl.log")); !os.IsNotExist(err) { t.Fatalf("rejected upgrade restarted the service: %v", err) } return diff --git a/docs/deployment.md b/docs/deployment.md index a1012b145..d76ca4b76 100644 --- a/docs/deployment.md +++ b/docs/deployment.md @@ -135,7 +135,7 @@ Personal runners are connected from the execution-machine page with a short-live Docker workspaces on macOS use a Linux Runner executable for Git credentials and MCP calls. The installer chooses the architecture of the installed macOS Runner, including Intel binaries running under Rosetta. For a universal Runner on Apple Silicon it installs the arm64 helpers and adds the amd64 helpers when available. Foreground starts and the command printed by `--no-start` select the native arm64 slice, including from a Rosetta shell. On Intel Macs the installer installs the amd64 helpers. By default, it places the helpers next to the host binary. A Runner-side `AGENTFLOW_RUNNER_BINARY` template with `{os}` selects the installation and runtime path. To install both helpers, use `{arch}` and give each architecture a distinct destination. The installer saves the template for upgrades and includes it in launchd and in the startup command printed by `--no-start`. Helper paths must resolve to files separate from the macOS Runner. -The installer checks the helper destinations against the staged macOS binary and installs the required Gate MCP helpers before replacing an installed Runner. The installer and updater validate the Linux executable's format, architecture, and load segments before replacing it. Custom installs keep a compatible existing helper. A Runner built from a local checkout can build its companion from that checkout. A download URL with an `{os}` placeholder can supply both binaries when used as the Runner's download source. +The installer checks the helper destinations against the staged macOS binary and installs the required Gate MCP helpers before replacing an installed Runner. When an upgrade changes architecture on a Runner with a working Docker helper, the installer requires a compatible helper for the new architecture before replacing the Runner and restarting its service. The installer and updater validate the Linux executable's format, architecture, and load segments before replacing it. Custom installs keep a compatible existing helper. A Runner built from a local checkout can build its companion from that checkout. A download URL with an `{os}` placeholder can supply both binaries when used as the Runner's download source. When platform updates are enabled, macOS runners synchronize the helper in the background at startup. A failed version check is retried during rescans, including when an older helper remains usable. Operations that need a missing helper for Git or MCP can wait up to five seconds for the initial sync. The background download continues within its own transfer timeout. From 9df09569da6abbe98d7eb84d39ed885bac22e625 Mon Sep 17 00:00:00 2001 From: crispinhu Date: Fri, 20 Nov 2026 02:06:39 +0800 Subject: [PATCH 10/13] fix(runner): recognize prior Docker helpers during macOS upgrades --- deploy/bind-cli.sh | 20 ++++++++++++------ deploy/bind_cli_docker_runner_test.go | 29 ++++++++++++++++++++------- docs/deployment.md | 2 +- 3 files changed, 37 insertions(+), 14 deletions(-) diff --git a/deploy/bind-cli.sh b/deploy/bind-cli.sh index 20241c57a..2e5ac4eb2 100755 --- a/deploy/bind-cli.sh +++ b/deploy/bind-cli.sh @@ -758,11 +758,17 @@ installed_macos_runner_binary_pattern() { saved_runner_binary_pattern } -configure_macos_docker_runner_helper() { - local pattern="${AGENTFLOW_RUNNER_BINARY-$1}" +trim_runner_binary_pattern() { + local pattern="$1" # Keep the template expansion in sync with runtime.DockerRunnerHelperPath. pattern="${pattern#"${pattern%%[![:space:]]*}"}" pattern="${pattern%"${pattern##*[![:space:]]}"}" + printf '%s\n' "$pattern" +} + +configure_macos_docker_runner_helper() { + local pattern + pattern=$(trim_runner_binary_pattern "${AGENTFLOW_RUNNER_BINARY-$1}") if [[ "$pattern" == *"{os}"* ]]; then if [[ "${#runner_arches[@]}" -gt 1 && "$pattern" != *"{arch}"* ]]; then fail "通用 macOS Runner 需要为每种架构安装 Linux Git/MCP helper,请在 AGENTFLOW_RUNNER_BINARY 中添加 {arch}" @@ -827,15 +833,17 @@ if [[ "$OS" == "darwin" ]]; then require_replacement_helper=0 if [[ "$UPGRADE" == "1" ]]; then previous_pattern=$(installed_macos_runner_binary_pattern) + previous_pattern=$(trim_runner_binary_pattern "$previous_pattern") read -r -a previous_arches <<< "$(macos_runner_arches "$BINARY")" - previous_arch="${previous_arches[0]}" - if [[ "$previous_arch" != "$required_arch" ]]; then + # The old universal binary may be running its Intel slice under Rosetta. + for previous_arch in "${previous_arches[@]}"; do previous_helper=$(macos_docker_runner_helper_path "$previous_arch" "$previous_pattern") if [[ ! "$previous_helper" -ef "$BINARY" ]] && is_usable_docker_runner_helper "$previous_helper" "$previous_arch"; then require_replacement_helper=1 + break fi - fi + done fi configure_macos_docker_runner_helper "$previous_pattern" check_macos_helper_paths @@ -883,7 +891,7 @@ if [[ "$OS" == "darwin" ]]; then install_docker_runner_binary if [[ "$ARCH" == "$required_arch" && "$require_replacement_helper" == "1" ]] && ! is_usable_docker_runner_helper "$DOCKER_RUNNER_BINARY"; then - fail "缺少切换架构所需的 Linux/${ARCH} Git/MCP helper,已保留当前 Runner 和服务:${DOCKER_RUNNER_BINARY}" + fail "缺少升级所需的 Linux/${ARCH} Git/MCP helper(${DOCKER_RUNNER_BINARY}),已保留当前 Runner 和服务" fi done else diff --git a/deploy/bind_cli_docker_runner_test.go b/deploy/bind_cli_docker_runner_test.go index 076783654..14dadb915 100644 --- a/deploy/bind_cli_docker_runner_test.go +++ b/deploy/bind_cli_docker_runner_test.go @@ -32,10 +32,11 @@ func TestBindCLIInstallsDockerRunnerHelper(t *testing.T) { preserveHelper bool templatePath bool helperAliasesRunner bool - universal bool + universal, previousUniversal bool intelHardware, sharedTemplateDir bool arm64OnlyArtifacts bool templateMissingArch bool + trimSavedTemplate bool missingRequiredGate bool missingReplacementHelper bool }{ @@ -61,6 +62,8 @@ func TestBindCLIInstallsDockerRunnerHelper(t *testing.T) { {name: "macOS_rejected_universal_upgrade_preserves_installed_runner", hostOS: "darwin", arch: "arm64", unameArch: "arm64", source: "from", universal: true, upgrade: true, launchd: true, templatePath: true, templateMissingArch: true}, {name: "macOS_preserves_installed_runner_if_required_gate_is_unavailable", hostOS: "darwin", arch: "arm64", unameArch: "arm64", source: "from", universal: true, upgrade: true, missingRequiredGate: true}, {name: "macOS_architecture_upgrade_keeps_working_runner_when_new_helper_is_unavailable", hostOS: "darwin", arch: "arm64", unameArch: "arm64", source: "from", universal: true, upgrade: true, launchd: true, missingReplacementHelper: true}, + {name: "macOS_keeps_working_Rosetta_slice_when_native_helper_is_unavailable", hostOS: "darwin", arch: "arm64", unameArch: "x86_64", source: "from", previousUniversal: true, upgrade: true, launchd: true, missingReplacementHelper: true}, + {name: "macOS_preserves_working_helper_with_whitespace_in_saved_template", hostOS: "darwin", arch: "arm64", unameArch: "arm64", source: "from", upgrade: true, templatePath: true, trimSavedTemplate: true, missingReplacementHelper: true}, {name: "macOS_repairs_incompatible_local_helper", hostOS: "darwin", arch: "arm64", unameArch: "arm64", source: "from", existing: "mach-o", upgrade: true}, {name: "macOS_preserves_custom_helper_script", hostOS: "darwin", arch: "arm64", unameArch: "arm64", source: "from", existing: "script", preserveHelper: true}, {name: "macOS_preserves_helper_with_host_only_URL", hostOS: "darwin", arch: "arm64", unameArch: "arm64", source: "host-url", preserveHelper: true}, @@ -96,14 +99,20 @@ func TestBindCLIInstallsDockerRunnerHelper(t *testing.T) { if tc.source == "from" { hostRunner += " custom" } - if tc.universal { + oldHost := "\xcf\xfa\xed\xfe\x07\x00\x00\x01 old Intel Runner" + if tc.universal || tc.previousUniversal { const x8664, arm64 = 0x01000007, 0x0100000c header := make([]byte, 8+2*20) binary.BigEndian.PutUint32(header[:], 0xcafebabe) binary.BigEndian.PutUint32(header[4:], 2) binary.BigEndian.PutUint32(header[8:], x8664) binary.BigEndian.PutUint32(header[28:], arm64) - hostRunner = string(header) + "universal runner" + if tc.previousUniversal { + oldHost = string(header) + "old universal runner" + } + if tc.universal { + hostRunner = string(header) + "universal runner" + } arm64Hardware := 1 if tc.intelHardware { arm64Hardware = 0 @@ -180,6 +189,9 @@ func TestBindCLIInstallsDockerRunnerHelper(t *testing.T) { if tc.missingReplacementHelper { oldHelper = bindFixtureLinuxRunner("amd64", "existing Intel helper") helper = filepath.Join(bin, "agentflow-runner-linux-amd64") + if tc.templatePath { + helper = filepath.Join(bundle, "linux", "amd64", "agentflow-runner") + } } if tc.sharedTemplateDir { amd64 := filepath.Join(bundle, "linux", "amd64") @@ -192,7 +204,6 @@ func TestBindCLIInstallsDockerRunnerHelper(t *testing.T) { } statePath := filepath.Join(fixtureHome, ".agentflow-runner", "state.json") const state = `{"runnerId":"fixture"}` - const oldHost = "\xcf\xfa\xed\xfe\x07\x00\x00\x01 old Intel Runner" envPath := filepath.Join(filepath.Dir(statePath), "env") initialEnv := "AGENTFLOW_SERVER_URL=" + server.URL + "\n" if tc.upgrade { @@ -203,6 +214,10 @@ func TestBindCLIInstallsDockerRunnerHelper(t *testing.T) { initialEnv += "AGENTFLOW_RUNNER_BINARY=" + patternEnv + "\n" patternEnv = "" // Use the saved configuration, with no process override. } + if tc.trimSavedTemplate { + initialEnv += "AGENTFLOW_RUNNER_BINARY= " + patternEnv + " \n" + patternEnv = "" + } for path, data := range map[string]string{ statePath: state, envPath: initialEnv, @@ -253,7 +268,7 @@ func TestBindCLIInstallsDockerRunnerHelper(t *testing.T) { t.Fatal(err) } } - if (tc.upgrade && !tc.templatePath) || tc.source == "template" || tc.preserveHelper || tc.templateMissingArch { + if (tc.upgrade && !tc.templatePath) || tc.source == "template" || tc.preserveHelper || tc.templateMissingArch || tc.missingReplacementHelper { if err := os.MkdirAll(filepath.Dir(helper), 0o755); err != nil { t.Fatal(err) } @@ -299,8 +314,8 @@ func TestBindCLIInstallsDockerRunnerHelper(t *testing.T) { t.Fatalf("installer did not report the missing required Gate helper: %v\n%s", err, out) } } else if tc.missingReplacementHelper { - if err == nil || !strings.Contains(string(out), "缺少切换架构所需的 Linux/arm64 Git/MCP helper") { - t.Fatalf("installer did not abort the architecture switch: %v\n%s", err, out) + if err == nil || !strings.Contains(string(out), "缺少升级所需的 Linux/arm64 Git/MCP helper") { + t.Fatalf("installer did not preserve the working runner: %v\n%s", err, out) } } else if err != nil { t.Fatalf("install: %v\n%s", err, out) diff --git a/docs/deployment.md b/docs/deployment.md index d76ca4b76..a9d4072e6 100644 --- a/docs/deployment.md +++ b/docs/deployment.md @@ -135,7 +135,7 @@ Personal runners are connected from the execution-machine page with a short-live Docker workspaces on macOS use a Linux Runner executable for Git credentials and MCP calls. The installer chooses the architecture of the installed macOS Runner, including Intel binaries running under Rosetta. For a universal Runner on Apple Silicon it installs the arm64 helpers and adds the amd64 helpers when available. Foreground starts and the command printed by `--no-start` select the native arm64 slice, including from a Rosetta shell. On Intel Macs the installer installs the amd64 helpers. By default, it places the helpers next to the host binary. A Runner-side `AGENTFLOW_RUNNER_BINARY` template with `{os}` selects the installation and runtime path. To install both helpers, use `{arch}` and give each architecture a distinct destination. The installer saves the template for upgrades and includes it in launchd and in the startup command printed by `--no-start`. Helper paths must resolve to files separate from the macOS Runner. -The installer checks the helper destinations against the staged macOS binary and installs the required Gate MCP helpers before replacing an installed Runner. When an upgrade changes architecture on a Runner with a working Docker helper, the installer requires a compatible helper for the new architecture before replacing the Runner and restarting its service. The installer and updater validate the Linux executable's format, architecture, and load segments before replacing it. Custom installs keep a compatible existing helper. A Runner built from a local checkout can build its companion from that checkout. A download URL with an `{os}` placeholder can supply both binaries when used as the Runner's download source. +The installer checks the helper destinations against the staged macOS binary and installs the required Gate MCP helpers before replacing an installed Runner. When the existing Runner has a working Docker helper, an upgrade requires a compatible helper at the new Runner's configured path before replacing the binary and restarting the service. The installer and updater validate the Linux executable's format, architecture, and load segments before replacing it. Custom installs keep a compatible existing helper. A Runner built from a local checkout can build its companion from that checkout. A download URL with an `{os}` placeholder can supply both binaries when used as the Runner's download source. When platform updates are enabled, macOS runners synchronize the helper in the background at startup. A failed version check is retried during rescans, including when an older helper remains usable. Operations that need a missing helper for Git or MCP can wait up to five seconds for the initial sync. The background download continues within its own transfer timeout. From d584b3f517681ef7abbd6cf0409d0b7bc93f77de Mon Sep 17 00:00:00 2001 From: crispinhu Date: Fri, 20 Nov 2026 02:12:11 +0800 Subject: [PATCH 11/13] fix(runner): resolve installed Docker helpers as the runtime does --- deploy/bind-cli.sh | 40 +++++++++++++++------------ deploy/bind_cli_docker_runner_test.go | 20 ++++++++++++-- docs/deployment.md | 2 +- 3 files changed, 40 insertions(+), 22 deletions(-) diff --git a/deploy/bind-cli.sh b/deploy/bind-cli.sh index 2e5ac4eb2..19bb489cc 100755 --- a/deploy/bind-cli.sh +++ b/deploy/bind-cli.sh @@ -695,7 +695,8 @@ is_linux_runner_binary() { } is_usable_docker_runner_helper() { - [[ -x "$1" && -f "$1" ]] || return 1 + # The runtime copies the source into the sandbox with executable mode. + [[ -r "$1" && -f "$1" ]] || return 1 # A custom installer may also provide an executable script wrapper. [[ "$(LC_ALL=C od -An -v -t x1 -N 2 "$1" | tr -d '[:space:]')" == 2321 ]] || is_linux_runner_binary "$1" "${2:-$ARCH}" @@ -750,30 +751,34 @@ saved_runner_binary_pattern() { awk 'sub(/^AGENTFLOW_RUNNER_BINARY=/, "") { print; exit }' "$ENV_FILE" } -installed_macos_runner_binary_pattern() { - if [[ -f "$PLIST" ]] && - /usr/bin/plutil -extract EnvironmentVariables.AGENTFLOW_RUNNER_BINARY raw "$PLIST" 2>/dev/null; then - return - fi - saved_runner_binary_pattern -} - -trim_runner_binary_pattern() { - local pattern="$1" +normalize_runner_binary_pattern() { + local pattern="$1" working_dir="$2" # Keep the template expansion in sync with runtime.DockerRunnerHelperPath. pattern="${pattern#"${pattern%%[![:space:]]*}"}" pattern="${pattern%"${pattern##*[![:space:]]}"}" + if [[ "$pattern" == *"{os}"* && "$pattern" != /* ]]; then + pattern="${working_dir%/}/$pattern" + fi printf '%s\n' "$pattern" } +installed_macos_runner_binary_pattern() { + local pattern working_dir + if [[ -f "$PLIST" ]] && + pattern=$(/usr/bin/plutil -extract EnvironmentVariables.AGENTFLOW_RUNNER_BINARY raw "$PLIST" 2>/dev/null); then + working_dir=$(/usr/bin/plutil -extract WorkingDirectory raw "$PLIST" 2>/dev/null) || working_dir="/" + normalize_runner_binary_pattern "$pattern" "${working_dir:-/}" + else + pattern=$(saved_runner_binary_pattern) + normalize_runner_binary_pattern "$pattern" "$PWD" + fi +} + configure_macos_docker_runner_helper() { local pattern - pattern=$(trim_runner_binary_pattern "${AGENTFLOW_RUNNER_BINARY-$1}") - if [[ "$pattern" == *"{os}"* ]]; then - if [[ "${#runner_arches[@]}" -gt 1 && "$pattern" != *"{arch}"* ]]; then - fail "通用 macOS Runner 需要为每种架构安装 Linux Git/MCP helper,请在 AGENTFLOW_RUNNER_BINARY 中添加 {arch}" - fi - [[ "$pattern" == /* ]] || pattern="$PWD/$pattern" + pattern=$(normalize_runner_binary_pattern "${AGENTFLOW_RUNNER_BINARY-$1}" "$PWD") + if [[ "${#runner_arches[@]}" -gt 1 && "$pattern" == *"{os}"* && "$pattern" != *"{arch}"* ]]; then + fail "通用 macOS Runner 需要为每种架构安装 Linux Git/MCP helper,请在 AGENTFLOW_RUNNER_BINARY 中添加 {arch}" fi export AGENTFLOW_RUNNER_BINARY="$pattern" } @@ -833,7 +838,6 @@ if [[ "$OS" == "darwin" ]]; then require_replacement_helper=0 if [[ "$UPGRADE" == "1" ]]; then previous_pattern=$(installed_macos_runner_binary_pattern) - previous_pattern=$(trim_runner_binary_pattern "$previous_pattern") read -r -a previous_arches <<< "$(macos_runner_arches "$BINARY")" # The old universal binary may be running its Intel slice under Rosetta. for previous_arch in "${previous_arches[@]}"; do diff --git a/deploy/bind_cli_docker_runner_test.go b/deploy/bind_cli_docker_runner_test.go index 14dadb915..5baf85d3b 100644 --- a/deploy/bind_cli_docker_runner_test.go +++ b/deploy/bind_cli_docker_runner_test.go @@ -37,6 +37,7 @@ func TestBindCLIInstallsDockerRunnerHelper(t *testing.T) { arm64OnlyArtifacts bool templateMissingArch bool trimSavedTemplate bool + relativeServiceTemplate bool missingRequiredGate bool missingReplacementHelper bool }{ @@ -64,13 +65,15 @@ func TestBindCLIInstallsDockerRunnerHelper(t *testing.T) { {name: "macOS_architecture_upgrade_keeps_working_runner_when_new_helper_is_unavailable", hostOS: "darwin", arch: "arm64", unameArch: "arm64", source: "from", universal: true, upgrade: true, launchd: true, missingReplacementHelper: true}, {name: "macOS_keeps_working_Rosetta_slice_when_native_helper_is_unavailable", hostOS: "darwin", arch: "arm64", unameArch: "x86_64", source: "from", previousUniversal: true, upgrade: true, launchd: true, missingReplacementHelper: true}, {name: "macOS_preserves_working_helper_with_whitespace_in_saved_template", hostOS: "darwin", arch: "arm64", unameArch: "arm64", source: "from", upgrade: true, templatePath: true, trimSavedTemplate: true, missingReplacementHelper: true}, + {name: "macOS_preserves_readable_old_helper_without_execute_permission", hostOS: "darwin", arch: "arm64", unameArch: "arm64", source: "from", existing: "non-executable", upgrade: true, launchd: true, missingReplacementHelper: true}, + {name: "macOS_preserves_helper_relative_to_launchd_working_directory", hostOS: "darwin", arch: "arm64", unameArch: "arm64", source: "from", upgrade: true, launchd: true, relativeServiceTemplate: true, missingReplacementHelper: true}, {name: "macOS_repairs_incompatible_local_helper", hostOS: "darwin", arch: "arm64", unameArch: "arm64", source: "from", existing: "mach-o", upgrade: true}, {name: "macOS_preserves_custom_helper_script", hostOS: "darwin", arch: "arm64", unameArch: "arm64", source: "from", existing: "script", preserveHelper: true}, {name: "macOS_preserves_helper_with_host_only_URL", hostOS: "darwin", arch: "arm64", unameArch: "arm64", source: "host-url", preserveHelper: true}, {name: "macOS_updates_helper_with_explicit_Linux_URL", hostOS: "darwin", arch: "arm64", unameArch: "arm64", source: "template"}, } { t.Run(tc.name, func(t *testing.T) { - if tc.launchd && !tc.missingReplacementHelper && runtime.GOOS != "darwin" { + if tc.launchd && (!tc.missingReplacementHelper || tc.relativeServiceTemplate) && runtime.GOOS != "darwin" { t.Skip("requires macOS plutil") } fixtureHome := t.TempDir() @@ -122,11 +125,14 @@ func TestBindCLIInstallsDockerRunnerHelper(t *testing.T) { t.Fatal(err) } } + oldHelperMode := os.FileMode(0o755) switch tc.existing { case "mach-o": oldHelper = "\xcf\xfa\xed\xfe wrong OS" case "script": oldHelper = "#!/bin/sh\nexec /opt/runner \"$@\"\n" + case "non-executable": + oldHelperMode = 0o644 } server := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, req *http.Request) { targetOS, arch := req.URL.Query().Get("os"), req.URL.Query().Get("arch") @@ -193,6 +199,10 @@ func TestBindCLIInstallsDockerRunnerHelper(t *testing.T) { helper = filepath.Join(bundle, "linux", "amd64", "agentflow-runner") } } + workingDir := filepath.Join(fixtureHome, "service directory") + if tc.relativeServiceTemplate { + helper = filepath.Join(workingDir, "relative helpers", "linux", "amd64", "agentflow-runner") + } if tc.sharedTemplateDir { amd64 := filepath.Join(bundle, "linux", "amd64") if err := os.MkdirAll(amd64, 0o755); err != nil { @@ -253,7 +263,11 @@ func TestBindCLIInstallsDockerRunnerHelper(t *testing.T) { if err := os.MkdirAll(filepath.Dir(plist), 0o700); err != nil { t.Fatal(err) } - initialPlist = fmt.Sprintf("KeepAliveProgramArguments%s", strings.Join(oldServiceArgs, "")) + serviceConfig := "" + if tc.relativeServiceTemplate { + serviceConfig = fmt.Sprintf("WorkingDirectory%sEnvironmentVariablesAGENTFLOW_RUNNER_BINARYrelative helpers/{os}/{arch}/agentflow-runner", workingDir) + } + initialPlist = fmt.Sprintf("KeepAliveProgramArguments%s%s", strings.Join(oldServiceArgs, ""), serviceConfig) if err := os.WriteFile(plist, []byte(initialPlist), 0o600); err != nil { t.Fatal(err) } @@ -272,7 +286,7 @@ func TestBindCLIInstallsDockerRunnerHelper(t *testing.T) { if err := os.MkdirAll(filepath.Dir(helper), 0o755); err != nil { t.Fatal(err) } - if err := os.WriteFile(helper, []byte(oldHelper), 0o755); err != nil { + if err := os.WriteFile(helper, []byte(oldHelper), oldHelperMode); err != nil { t.Fatal(err) } } diff --git a/docs/deployment.md b/docs/deployment.md index a9d4072e6..dec563d46 100644 --- a/docs/deployment.md +++ b/docs/deployment.md @@ -135,7 +135,7 @@ Personal runners are connected from the execution-machine page with a short-live Docker workspaces on macOS use a Linux Runner executable for Git credentials and MCP calls. The installer chooses the architecture of the installed macOS Runner, including Intel binaries running under Rosetta. For a universal Runner on Apple Silicon it installs the arm64 helpers and adds the amd64 helpers when available. Foreground starts and the command printed by `--no-start` select the native arm64 slice, including from a Rosetta shell. On Intel Macs the installer installs the amd64 helpers. By default, it places the helpers next to the host binary. A Runner-side `AGENTFLOW_RUNNER_BINARY` template with `{os}` selects the installation and runtime path. To install both helpers, use `{arch}` and give each architecture a distinct destination. The installer saves the template for upgrades and includes it in launchd and in the startup command printed by `--no-start`. Helper paths must resolve to files separate from the macOS Runner. -The installer checks the helper destinations against the staged macOS binary and installs the required Gate MCP helpers before replacing an installed Runner. When the existing Runner has a working Docker helper, an upgrade requires a compatible helper at the new Runner's configured path before replacing the binary and restarting the service. The installer and updater validate the Linux executable's format, architecture, and load segments before replacing it. Custom installs keep a compatible existing helper. A Runner built from a local checkout can build its companion from that checkout. A download URL with an `{os}` placeholder can supply both binaries when used as the Runner's download source. +The installer checks the helper destinations against the staged macOS binary and installs the required Gate MCP helpers before replacing an installed Runner. When the existing Runner has a working Docker helper, an upgrade requires a compatible helper at the new Runner's configured path before replacing the binary and restarting the service. Relative templates in the installed launchd configuration use the job's working directory. The installer and updater validate the Linux executable's format, architecture, and load segments before replacing it. Custom installs keep a compatible existing helper. A Runner built from a local checkout can build its companion from that checkout. A download URL with an `{os}` placeholder can supply both binaries when used as the Runner's download source. When platform updates are enabled, macOS runners synchronize the helper in the background at startup. A failed version check is retried during rescans, including when an older helper remains usable. Operations that need a missing helper for Git or MCP can wait up to five seconds for the initial sync. The background download continues within its own transfer timeout. From a62c88856fc07a8648dff178e938ce680a3fed4e Mon Sep 17 00:00:00 2001 From: crispinhu Date: Fri, 20 Nov 2026 02:24:33 +0800 Subject: [PATCH 12/13] fix(runner): let Docker reuse readable helpers during startup sync --- docs/deployment.md | 2 +- internal/runner/update.go | 17 ++++++++++++----- internal/runner/update_test.go | 20 +++++++++++++++++--- 3 files changed, 30 insertions(+), 9 deletions(-) diff --git a/docs/deployment.md b/docs/deployment.md index dec563d46..bc915a054 100644 --- a/docs/deployment.md +++ b/docs/deployment.md @@ -137,7 +137,7 @@ Docker workspaces on macOS use a Linux Runner executable for Git credentials and The installer checks the helper destinations against the staged macOS binary and installs the required Gate MCP helpers before replacing an installed Runner. When the existing Runner has a working Docker helper, an upgrade requires a compatible helper at the new Runner's configured path before replacing the binary and restarting the service. Relative templates in the installed launchd configuration use the job's working directory. The installer and updater validate the Linux executable's format, architecture, and load segments before replacing it. Custom installs keep a compatible existing helper. A Runner built from a local checkout can build its companion from that checkout. A download URL with an `{os}` placeholder can supply both binaries when used as the Runner's download source. -When platform updates are enabled, macOS runners synchronize the helper in the background at startup. A failed version check is retried during rescans, including when an older helper remains usable. Operations that need a missing helper for Git or MCP can wait up to five seconds for the initial sync. The background download continues within its own transfer timeout. +When platform updates are enabled, macOS runners synchronize the helper in the background at startup. A failed version check is retried during rescans, including when an older helper remains usable. A readable, compatible helper can be copied into a Docker workspace with executable permissions while the sync runs. Operations that need a missing helper for Git or MCP can wait up to five seconds for the initial sync. The background download continues within its own transfer timeout. A platform administrator can share one CodeBuddy API Key under **Platform administration → Shared CodeBuddy Key** (平台共享 CodeBuddy Key): pick the network environment that issued it and the models members may use (the first is the default). Members without a key of their own then chat and run SOPs on it, limited to those models; a role configured with another model runs on the default and the run says so. Members with their own key keep using it with any model. Scheduled tasks, clarification, reports, bots and run evaluation still need the runner's own key. A scheduled task uses the key for its selected CLI and does not borrow the shared CodeBuddy key. The key is stored in the database like personal keys and is never shown again after saving. `AGENTFLOW_ASSISTANT_SPONSOR_LOGIN`, which lent one account's key limited to `deepseek-v4.1-flash`, still applies while no shared key is configured. diff --git a/internal/runner/update.go b/internal/runner/update.go index 07e582462..081bf95da 100644 --- a/internal/runner/update.go +++ b/internal/runner/update.go @@ -78,7 +78,10 @@ func (d *Daemon) checkDockerRunnerHelperUpdate(ctx context.Context, repairOnly b if err != nil { return err } - if repairOnly && validateDockerRunnerHelper(path) == nil { + validateInstalled := func(path string) error { + return validateDockerRunnerHelper(path, true) + } + if repairOnly && validateInstalled(path) == nil { return nil } if err := os.MkdirAll(filepath.Dir(path), 0o755); err != nil { @@ -86,7 +89,7 @@ func (d *Daemon) checkDockerRunnerHelperUpdate(ctx context.Context, repairOnly b } // Sandboxes copy this executable into the workspace, so an atomic replacement // can run alongside active tasks and requests waiting for the first download. - return d.checkCompanionBinaryUpdate(ctx, "Docker Git/MCP helper", d.runnerUpdateEndpoint("linux"), path, validateDockerRunnerHelper, false) + return d.checkCompanionBinaryUpdate(ctx, "Docker Git/MCP helper", d.runnerUpdateEndpoint("linux"), path, validateInstalled, false) } func (d *Daemon) withDockerRunnerHelperWait(ctx context.Context) context.Context { @@ -102,7 +105,8 @@ func (d *Daemon) waitForDockerRunnerHelper(ctx context.Context, path string) err return nil default: } - if validateDockerRunnerHelper(path) == nil { + // A workspace copy gets its own executable permissions. + if validateDockerRunnerHelper(path, false) == nil { return nil } // A workspace request can give up while the download continues. It never @@ -117,7 +121,7 @@ func (d *Daemon) waitForDockerRunnerHelper(ctx context.Context, path string) err } } -func validateDockerRunnerHelper(path string) error { +func validateDockerRunnerHelper(path string, requireExecutable bool) error { var machine elf.Machine switch runtime.GOARCH { case "arm64": @@ -131,7 +135,10 @@ func validateDockerRunnerHelper(path string) error { if err != nil { return err } - if !info.Mode().IsRegular() || info.Mode().Perm()&0o111 == 0 { + if !info.Mode().IsRegular() { + return fmt.Errorf("expected regular Linux/%s helper file", runtime.GOARCH) + } + if requireExecutable && info.Mode().Perm()&0o111 == 0 { return fmt.Errorf("expected executable Linux/%s helper", runtime.GOARCH) } file, err := elf.Open(path) diff --git a/internal/runner/update_test.go b/internal/runner/update_test.go index 0a17dd177..e0ebc7f3c 100644 --- a/internal/runner/update_test.go +++ b/internal/runner/update_test.go @@ -19,6 +19,8 @@ import ( "testing" "time" + flowruntime "agentflow/internal/runtime" + "github.com/gorilla/websocket" ) @@ -335,7 +337,7 @@ func TestDockerRunnerHelperDownloadDoesNotBlockMacOSStartup(t *testing.T) { t.Setenv("AGENTFLOW_RUNNER_BINARY", filepath.Join(root, "agentflow-runner-{os}-{arch}")) helper := filepath.Join(root, "agentflow-runner-linux-"+runtime.GOARCH) original := dockerRunnerFixtureLinuxBinary(runtime.GOARCH, "working helper") - if err := os.WriteFile(helper, []byte(original), 0o755); err != nil { + if err := os.WriteFile(helper, []byte(original), 0o644); err != nil { t.Fatal(err) } updated := dockerRunnerFixtureLinuxBinary(runtime.GOARCH, "updated helper") @@ -423,8 +425,16 @@ func TestDockerRunnerHelperDownloadDoesNotBlockMacOSStartup(t *testing.T) { wait(claim, "task polling") workspaceCtx, cancelWorkspace := context.WithTimeout(ctx, time.Second) defer cancelWorkspace() - if err := d.waitForDockerRunnerHelper(workspaceCtx, helper); err != nil { - t.Fatalf("existing helper should be available during the download: %v", err) + workspace := t.TempDir() + if _, err := flowruntime.PrepareMCPCall(d.withDockerRunnerHelperWait(workspaceCtx), dockerHelperFixtureSandbox{}, workspace, nil); err != nil { + t.Fatalf("existing readable helper should be available while metadata is pending: %v", err) + } + workspaceHelper := filepath.Join(workspace, ".agentflow", "runtime", "bin", "agentflow-helper") + if got, err := os.ReadFile(workspaceHelper); err != nil || string(got) != original { + t.Fatalf("workspace helper = %q, %v", got, err) + } + if info, err := os.Stat(workspaceHelper); err != nil || info.Mode().Perm()&0o100 == 0 { + t.Fatalf("workspace helper did not receive executable permissions: %v", err) } close(allowMetadata) waitFor(t, 5*time.Second, "helper update", func() bool { @@ -433,6 +443,10 @@ func TestDockerRunnerHelperDownloadDoesNotBlockMacOSStartup(t *testing.T) { }) } +type dockerHelperFixtureSandbox struct{ flowruntime.Sandbox } + +func (dockerHelperFixtureSandbox) Driver() string { return "docker" } + func TestDockerRunnerHelperRescanRetriesFailedVersionCheck(t *testing.T) { root := t.TempDir() t.Setenv("HOME", root) From 552cae293cbafbd398f9fa0dbdfbbb7e2693e5e4 Mon Sep 17 00:00:00 2001 From: crispinhu Date: Fri, 20 Nov 2026 10:49:50 +0800 Subject: [PATCH 13/13] fix(runner): reuse local Docker helper wrappers during sync --- docs/deployment.md | 2 +- internal/runner/update.go | 23 +++++++++++++++++------ internal/runner/update_test.go | 14 ++++++++++++-- 3 files changed, 30 insertions(+), 9 deletions(-) diff --git a/docs/deployment.md b/docs/deployment.md index bc915a054..ed1819455 100644 --- a/docs/deployment.md +++ b/docs/deployment.md @@ -137,7 +137,7 @@ Docker workspaces on macOS use a Linux Runner executable for Git credentials and The installer checks the helper destinations against the staged macOS binary and installs the required Gate MCP helpers before replacing an installed Runner. When the existing Runner has a working Docker helper, an upgrade requires a compatible helper at the new Runner's configured path before replacing the binary and restarting the service. Relative templates in the installed launchd configuration use the job's working directory. The installer and updater validate the Linux executable's format, architecture, and load segments before replacing it. Custom installs keep a compatible existing helper. A Runner built from a local checkout can build its companion from that checkout. A download URL with an `{os}` placeholder can supply both binaries when used as the Runner's download source. -When platform updates are enabled, macOS runners synchronize the helper in the background at startup. A failed version check is retried during rescans, including when an older helper remains usable. A readable, compatible helper can be copied into a Docker workspace with executable permissions while the sync runs. Operations that need a missing helper for Git or MCP can wait up to five seconds for the initial sync. The background download continues within its own transfer timeout. +When platform updates are enabled, macOS runners synchronize the helper in the background at startup. A failed version check is retried during rescans, including when an older helper remains usable. A readable, compatible local ELF or a locally configured script wrapper can be copied into a Docker workspace with executable permissions while the sync runs. Operations that need a missing helper for Git or MCP can wait up to five seconds for the initial sync. The background download continues within its own transfer timeout. A platform administrator can share one CodeBuddy API Key under **Platform administration → Shared CodeBuddy Key** (平台共享 CodeBuddy Key): pick the network environment that issued it and the models members may use (the first is the default). Members without a key of their own then chat and run SOPs on it, limited to those models; a role configured with another model runs on the default and the run says so. Members with their own key keep using it with any model. Scheduled tasks, clarification, reports, bots and run evaluation still need the runner's own key. A scheduled task uses the key for its selected CLI and does not borrow the shared CodeBuddy key. The key is stored in the database like personal keys and is never shown again after saving. `AGENTFLOW_ASSISTANT_SPONSOR_LOGIN`, which lent one account's key limited to `deepseek-v4.1-flash`, still applies while no shared key is configured. diff --git a/internal/runner/update.go b/internal/runner/update.go index 081bf95da..afaf0772a 100644 --- a/internal/runner/update.go +++ b/internal/runner/update.go @@ -79,7 +79,7 @@ func (d *Daemon) checkDockerRunnerHelperUpdate(ctx context.Context, repairOnly b return err } validateInstalled := func(path string) error { - return validateDockerRunnerHelper(path, true) + return validateDockerRunnerHelper(path, false) } if repairOnly && validateInstalled(path) == nil { return nil @@ -106,7 +106,7 @@ func (d *Daemon) waitForDockerRunnerHelper(ctx context.Context, path string) err default: } // A workspace copy gets its own executable permissions. - if validateDockerRunnerHelper(path, false) == nil { + if validateDockerRunnerHelper(path, true) == nil { return nil } // A workspace request can give up while the download continues. It never @@ -121,7 +121,7 @@ func (d *Daemon) waitForDockerRunnerHelper(ctx context.Context, path string) err } } -func validateDockerRunnerHelper(path string, requireExecutable bool) error { +func validateDockerRunnerHelper(path string, forWorkspace bool) error { var machine elf.Machine switch runtime.GOARCH { case "arm64": @@ -138,14 +138,25 @@ func validateDockerRunnerHelper(path string, requireExecutable bool) error { if !info.Mode().IsRegular() { return fmt.Errorf("expected regular Linux/%s helper file", runtime.GOARCH) } - if requireExecutable && info.Mode().Perm()&0o111 == 0 { + if !forWorkspace && info.Mode().Perm()&0o111 == 0 { return fmt.Errorf("expected executable Linux/%s helper", runtime.GOARCH) } - file, err := elf.Open(path) + source, err := os.Open(path) + if err != nil { + return err + } + defer source.Close() + if forWorkspace { + // Match the installer for local custom wrappers. Platform artifacts must be ELF. + var header [2]byte + if _, err := source.ReadAt(header[:], 0); err == nil && header == [2]byte{'#', '!'} { + return nil + } + } + file, err := elf.NewFile(source) if err != nil { return fmt.Errorf("expected Linux/%s ELF helper: %w", runtime.GOARCH, err) } - defer file.Close() if file.Class != elf.ELFCLASS64 || file.Data != elf.ELFDATA2LSB || file.Machine != machine || (file.OSABI != elf.ELFOSABI_NONE && file.OSABI != elf.ELFOSABI_LINUX) || (file.Type != elf.ET_EXEC && file.Type != elf.ET_DYN) { diff --git a/internal/runner/update_test.go b/internal/runner/update_test.go index e0ebc7f3c..6a68307a2 100644 --- a/internal/runner/update_test.go +++ b/internal/runner/update_test.go @@ -291,6 +291,7 @@ func TestDockerRunnerHelperUpdateRejectsIncompatibleBinary(t *testing.T) { for _, tc := range []struct{ name, payload string }{ {name: "macOS_binary", payload: "\xcf\xfa\xed\xfemacOS runner"}, {name: "wrong_Linux_architecture", payload: dockerRunnerFixtureLinuxBinary(otherArch, "wrong architecture")}, + {name: "script_wrapper", payload: "#!/bin/sh\nexit 0\n"}, {name: "only_ELF_header", payload: complete[:64]}, {name: "truncated_load_segment", payload: complete[:len(complete)-1]}, } { @@ -331,13 +332,22 @@ func TestDockerRunnerHelperDownloadDoesNotBlockMacOSStartup(t *testing.T) { if runtime.GOOS != "darwin" { t.Skip("macOS Runner downloads the Linux helper at startup") } + t.Run("readable_ELF", func(t *testing.T) { + testDockerRunnerHelperDuringStartup(t, dockerRunnerFixtureLinuxBinary(runtime.GOARCH, "working helper"), 0o644) + }) + t.Run("local_script_wrapper", func(t *testing.T) { + testDockerRunnerHelperDuringStartup(t, "#!/bin/sh\nexec /usr/local/bin/agentflow-runner \"$@\"\n", 0o755) + }) +} + +func testDockerRunnerHelperDuringStartup(t *testing.T, original string, mode os.FileMode) { + t.Helper() root := t.TempDir() t.Setenv("HOME", root) t.Setenv("PATH", "/usr/bin:/bin") t.Setenv("AGENTFLOW_RUNNER_BINARY", filepath.Join(root, "agentflow-runner-{os}-{arch}")) helper := filepath.Join(root, "agentflow-runner-linux-"+runtime.GOARCH) - original := dockerRunnerFixtureLinuxBinary(runtime.GOARCH, "working helper") - if err := os.WriteFile(helper, []byte(original), 0o644); err != nil { + if err := os.WriteFile(helper, []byte(original), mode); err != nil { t.Fatal(err) } updated := dockerRunnerFixtureLinuxBinary(runtime.GOARCH, "updated helper")