Skip to content

Self-hosted workflows for coding-agent delivery. Orchestrate CodeBuddy, Codex and Claude Code with scripts and human approval gates. Includes Local workflows for coding assistants.

fix(runtime): provision missing CLIs in Docker SOPs (#1077)

crispinhu27684e79d966ce
diff --git a/docs/deployment.md b/docs/deployment.md
index e441ba49..0d1c7999 100644
--- a/docs/deployment.md
+++ b/docs/deployment.md
@@ -79,6 +79,8 @@ For native services running as an ordinary host user, default/root Docker images
The Compose deployment mounts the host Docker socket into the platform container so built-in AI SOPs run out of the box. `AGENTFLOW_ISOLATED_IMAGE` points to the installed platform image: default sandboxes start separate sibling containers from that same image, with no second CLI download or image build. They do not mount the Docker socket. Custom Dockerfiles still build and cache their own images. The run workspace is mounted at `/workspace` on the Compose network. Because bind mounts are resolved by the host Docker daemon, `LOOPFORGE_DATA_DIR` (written to `.env` by `scripts/configure.sh`, default `./.data`) is mounted into the platform container at the same absolute path; workspaces and CLI state live under it. Native conversation workspaces bind-mount their conversation roots the same way, so `compose.yaml` sets `AGENTFLOW_CONVERSATION_DIR` to `${LOOPFORGE_DATA_DIR}/conversations`. Conversation workspaces in a Compose deployment use Docker sandboxes: the native (bwrap) sandbox needs user and PID namespaces, which the unprivileged platform container cannot create, and the image does not ship bubblewrap. Use a native installation or a connected execution machine for native sandboxes. Attachments and other per-user assistant state stay in `AGENTFLOW_ASSISTANT_SESSION_DIR` (`/data/assistant` in the `platform-data` volume), which is never mounted into a workspace. A platform container whose `AGENTFLOW_CONVERSATION_DIR` is unset keeps conversation roots there too, and opening a conversation workspace then fails with `mkdirat ... read-only file system`.
+Docker SOP nodes using a standard CLI executor first look for the CLI on the sandbox user's PATH. When it is missing, LoopForge uses a shared installation for the platform image where available or runs the same installer as conversation workspaces in the container. The install uses the sandbox's configured proxy, and later nodes in that container reuse the CLI. In-container installation requires a writable filesystem and access to the official package source. Read-only sandboxes can use a CLI from the image or the mounted toolchain. ZCode uses the official executable supplied by the image.
+
Access to the Docker socket is equivalent to root on the host. Two safeguards follow from that: the platform runs every task in a sandbox container, including SOPs configured for the `local` driver (`AGENTFLOW_LOCAL_SANDBOX=docker`), and only platform administrators can point a repository at a host source path. Even so, anyone who can run SOPs can execute code in containers on this host, so only give accounts to people you trust and do not expose the service to untrusted networks. Agent CLIs also apply a bound repository's own configuration as their native rules define, including unattended SOP runs: `AGENTS.md`/`CLAUDE.md` instructions, `.codebuddy/`, `.claude/settings.json` (hooks and environment) and `.mcp.json` can start commands or MCP servers inside the sandbox. Bind only repositories whose contents you trust. To run without the socket, remove the `docker.sock` volume and the `AGENTFLOW_LOCAL_SANDBOX` setting from `compose.yaml`, then connect a separate Docker-capable worker or execution machine for AI SOPs; the script-only welcome SOP then runs inside the platform container.
### Slow networks: clone and image build limits
diff --git a/internal/runtime/cli_ondemand.go b/internal/runtime/cli_ondemand.go
index b6b18fcb..c96694e5 100644
--- a/internal/runtime/cli_ondemand.go
+++ b/internal/runtime/cli_ondemand.go
@@ -16,8 +16,10 @@ import (
// a person asks from a failed conversation. Package names and installer URLs are fixed:
// the request may choose an engine, never a URL or a package.
const (
- cursorInstallScript = "curl -fsSL --proto '=https' --tlsv1.2 https://cursor.com/install | bash"
- agyInstallScript = "curl -fsSL --proto '=https' --tlsv1.2 https://antigravity.google/cli/install.sh | bash"
+ cursorInstallerURL = "https://cursor.com/install"
+ agyInstallerURL = "https://antigravity.google/cli/install.sh"
+ cursorInstallScript = "curl -fsSL --proto '=https' --tlsv1.2 " + cursorInstallerURL + " | bash"
+ agyInstallScript = "curl -fsSL --proto '=https' --tlsv1.2 " + agyInstallerURL + " | bash"
)
// DeepSeekHarnessVersion is the dsh release the Dockerfile bundles and an
@@ -43,7 +45,7 @@ func onDemandCLICatalog() map[string]onDemandCLI {
return map[string]onDemandCLI{
"codex": {Engine: "codex", Binary: "codex", Package: "@openai/codex", Bundled: true},
"codebuddy": {Engine: "codebuddy", Binary: "codebuddy", Package: "@tencent-ai/codebuddy-code", Bundled: true},
- "claude-code": {Engine: "claude-code", Binary: "claude"},
+ "claude-code": {Engine: "claude-code", Binary: "claude", Package: "@anthropic-ai/claude-code"},
"opencode": {Engine: "opencode", Binary: "opencode", Package: "opencode-ai"},
"cursor": {Engine: "cursor", Binary: "cursor-agent", Script: cursorInstallScript},
"agy": {Engine: "agy", Binary: "agy", Script: agyInstallScript},
diff --git a/internal/runtime/cli_ondemand_sandbox_test.go b/internal/runtime/cli_ondemand_sandbox_test.go
index 90cd42b5..d3f02e4a 100644
--- a/internal/runtime/cli_ondemand_sandbox_test.go
+++ b/internal/runtime/cli_ondemand_sandbox_test.go
@@ -3,12 +3,122 @@ package runtime
import (
"context"
"os"
+ "os/exec"
"path/filepath"
+ "strings"
"testing"
+ "time"
"agentflow/internal/domain"
)
+func TestDockerSOPExecInstallsMissingCLIOnce(t *testing.T) {
+ t.Setenv("AGENTFLOW_RUNTIME_CLI_DIR", "")
+ setupMarker := filepath.Join(t.TempDir(), "installed")
+ t.Setenv("LOOPFORGE_TEST_CLI_SETUP", setupMarker)
+ probes := filepath.Join(t.TempDir(), "probes")
+ t.Setenv("LOOPFORGE_TEST_CLI_PROBES", probes)
+ useFakeCommands(t, map[string]string{"docker": `#!/bin/sh
+set -eu
+case "$*" in
+ *loopforge-cli-probe*)
+ printf 'probe\n' >> "$LOOPFORGE_TEST_CLI_PROBES"
+ test -s "$LOOPFORGE_TEST_CLI_SETUP" || exit 127 ;;
+ *"id -u; id -g"*) printf '1000\n1000\n' ;;
+ *loopforge-cli-available*) test -s "$LOOPFORGE_TEST_CLI_SETUP" || exit 127 ;;
+ *loopforge-cli-setup*)
+ for mode do :; done
+ test "$mode" = install
+ printf 'install\n' >> "$LOOPFORGE_TEST_CLI_SETUP" ;;
+ *loopforge-cli-verify*) printf '/opt/loopforge/conversation-cli/.local/bin/agy\n' ;;
+ *) for arg do last=$arg; done
+ printf '%s\n' "$last" ;;
+esac
+`})
+ sandbox := &dockerSandbox{name: "workspace", started: true}
+ for _, command := range []CommandSpec{
+ {Provider: AgentCLIAntigravity, Argv: []string{"agy", "first"}},
+ {Provider: AgentCLIAntigravity, Argv: []string{"agy", "second"}},
+ {Provider: AgentCLIAntigravity, Argv: []string{"/custom/agy", "explicit"}},
+ {Provider: "script", Argv: []string{"sh", "-c", "script"}},
+ } {
+ want := command.Argv[len(command.Argv)-1]
+ out, err := sandbox.Exec(context.Background(), command, nil)
+ if err != nil || strings.TrimSpace(out) != want {
+ t.Fatalf("exec %v: %q %v", command.Argv, out, err)
+ }
+ }
+ if got, err := os.ReadFile(setupMarker); err != nil || string(got) != "install\n" {
+ t.Fatalf("expected exactly one setup, got %q: %v", got, err)
+ }
+ if got, err := os.ReadFile(probes); err != nil || string(got) != "probe\nprobe\n" {
+ t.Fatalf("expected probes only for standard CLI invocations, got %q: %v", got, err)
+ }
+}
+
+// A CLI visible only to the image's root account must not prevent preparation
+// of a copy that the task user can execute.
+func TestDockerSOPUsesCLIExecutableByTaskUser(t *testing.T) {
+ if os.Getenv("AGENTFLOW_TEST_DOCKER") != "1" {
+ t.Skip("set AGENTFLOW_TEST_DOCKER=1 with the python:3.13-alpine image")
+ }
+ t.Setenv("AGENTFLOW_RUNTIME_CLI_DIR", "")
+ ctx, cancel := context.WithTimeout(context.Background(), time.Minute)
+ defer cancel()
+ docker := func(input string, args ...string) string {
+ t.Helper()
+ cmd := exec.CommandContext(ctx, "docker", args...)
+ cmd.Stdin = strings.NewReader(input)
+ out, err := cmd.CombinedOutput()
+ if err != nil {
+ t.Fatalf("docker %s: %v: %s", args[0], err, out)
+ }
+ return strings.TrimSpace(string(out))
+ }
+ container := docker("", "run", "--pull=never", "-d", "--network", "none", "--user", "1000:1000",
+ "--workdir", "/", "--cap-drop=ALL", "--security-opt", "no-new-privileges",
+ "python:3.13-alpine", "sleep", "120")
+ t.Cleanup(func() { _ = exec.Command("docker", "rm", "-f", container).Run() })
+ docker(`set -eu
+mkdir -p /workspace /root/private/bin
+chmod 700 /root
+printf '#!/bin/sh\necho root-only\n' > /root/private/bin/agy
+printf '[ "$(id -u)" != 0 ] || export PATH=/root/private/bin:$PATH\n' > /etc/profile.d/root-cli.sh
+cat > /usr/local/bin/curl <<'CURL'
+#!/bin/sh
+set -eu
+while [ "$1" != -o ]; do shift; done
+cat > "$2" <<'INSTALL'
+#!/bin/sh
+set -eu
+mkdir -p "$HOME/.local/bin"
+printf '#!/bin/sh\nid -u\n' > "$HOME/.local/bin/agy"
+chmod 755 "$HOME/.local/bin/agy"
+echo install >> /opt/loopforge/conversation-cli/installs
+INSTALL
+CURL
+printf '#!/bin/sh\nexec /bin/sh "$@"\n' > /usr/local/bin/bash
+chmod 755 /root/private/bin/agy /usr/local/bin/curl /usr/local/bin/bash
+`, "exec", "-i", "--user", "0:0", container, "sh", "-s")
+ if got := docker("", "exec", "--user", "0:0", container, "sh", "-lc", "command -v agy"); got != "/root/private/bin/agy" {
+ t.Fatalf("root CLI fixture: %q", got)
+ }
+ sandbox := &dockerSandbox{name: container, started: true}
+ for range 2 {
+ out, err := sandbox.Exec(ctx, CommandSpec{Provider: AgentCLIAntigravity, Argv: []string{"agy", "--version"}}, nil)
+ if err != nil || strings.TrimSpace(out) != "1000" {
+ t.Fatalf("task CLI: %q: %v", out, err)
+ }
+ }
+ path, err := ensureConversationCLI(ctx, sandbox, AgentCLIAntigravity, "/workspace/home")
+ if err != nil || path != "/opt/loopforge/conversation-cli/.local/bin/agy" {
+ t.Fatalf("reusing installed CLI for a conversation: %q: %v", path, err)
+ }
+ if got := docker("", "exec", container, "cat", "/opt/loopforge/conversation-cli/installs"); got != "install" {
+ t.Fatalf("expected CLI to be installed once, got %q", got)
+ }
+}
+
// A failed on-demand install must stop the sandbox exec instead of silently
// running without the CLI on PATH.
func TestDockerSandboxOnDemandCLIPathReturnsInstallErrors(t *testing.T) {
diff --git a/internal/runtime/conversation_approval_test.go b/internal/runtime/conversation_approval_test.go
index f4d9104f..48cdb62e 100644
--- a/internal/runtime/conversation_approval_test.go
+++ b/internal/runtime/conversation_approval_test.go
@@ -69,7 +69,7 @@ func TestConversationSupportsEveryRegisteredCLI(t *testing.T) {
if _, err := InstallConversationApproval(root, kind, command); err != nil {
t.Fatal(err)
}
- if _, err := conversationCLISetup(kind, conversationBinary(kind)); err != nil {
+ if _, err := dockerCLISetup(kind, conversationBinary(kind)); err != nil {
t.Fatal(err)
}
})
@@ -77,7 +77,7 @@ func TestConversationSupportsEveryRegisteredCLI(t *testing.T) {
}
func TestZCodeConversationSetupRequiresOfficialPreinstallation(t *testing.T) {
- setup, err := conversationCLISetup(AgentCLIZCode, conversationBinary(AgentCLIZCode))
+ setup, err := dockerCLISetup(AgentCLIZCode, conversationBinary(AgentCLIZCode))
if err != nil || strings.Contains(setup, "npm install") || !strings.Contains(setup, "预装官方 ZCode CLI") {
t.Fatalf("ZCode must use its official preinstalled binary: %s: %v", setup, err)
}
diff --git a/internal/runtime/conversation_sandbox.go b/internal/runtime/conversation_sandbox.go
index c6ecf56a..3dd1ff91 100644
--- a/internal/runtime/conversation_sandbox.go
+++ b/internal/runtime/conversation_sandbox.go
@@ -166,13 +166,38 @@ func ensureConversationCLI(ctx context.Context, sandbox Sandbox, provider, home
if !ok {
return "", fmt.Errorf("对话工作区只支持 Docker 或 native 沙箱")
}
+ s.execGate.RLock()
+ defer s.execGate.RUnlock()
+ return s.ensureDockerCLI(ctx, provider, home)
+}
+
+const dockerCLISharedPath = "/opt/loopforge/conversation-cli/bin:/opt/loopforge/conversation-cli/.local/bin"
+const dockerCLISharedPathSetup = "PATH=" + dockerCLISharedPath + ":$PATH\nexport PATH\n"
+
+const dockerCLIProbe = `cli_path=$(command -v "$1") || exit 127
+[ -f "$cli_path" ] && [ -x "$cli_path" ] || exit 127
+printf '%s\n' "$cli_path"
+`
+
+// ensureDockerCLI prepares a provider in an existing container. SOP and chat
+// callers hold the execution gate so preparation cannot race recreation.
+func (s *dockerSandbox) ensureDockerCLI(ctx context.Context, provider, home string) (string, error) {
binary := conversationBinary(provider)
- setup, err := conversationCLISetup(provider, binary)
+ setup, err := dockerCLISetup(provider, binary)
if err != nil {
return "", err
}
ctx, cancel := context.WithTimeout(ctx, 10*time.Minute)
defer cancel()
+ // npm providers share the same install prefix. Serialize preparation even
+ // when different SOP nodes start different CLIs in the same container.
+ s.cliSetupOnce.Do(func() { s.cliSetupGate = make(chan struct{}, 1) })
+ select {
+ case s.cliSetupGate <- struct{}{}:
+ defer func() { <-s.cliSetupGate }()
+ case <-ctx.Done():
+ return "", ctx.Err()
+ }
// Probe the actual execution user, including numeric Docker USER values.
// Root preparation must preserve that identity when the native CLI starts.
identity, err := exec.CommandContext(ctx, "docker", "exec", "--workdir", "/", s.name, "sh", "-c", "id -u; id -g").CombinedOutput()
@@ -194,35 +219,55 @@ func ensureConversationCLI(ctx context.Context, sandbox Sandbox, provider, home
if err != nil {
return "", err
}
- setupArgs := append(append([]string{"exec", "--user", "0:0", "--workdir", "/"}, toolchain...), s.name, "sh", "-lc", setup, "loopforge-cli-setup", ids[0], ids[1], home)
+ // Only the task user's PATH and permissions determine whether to install.
+ // The root login shell may see a private copy the task cannot execute.
+ taskArgs := append(append([]string{"exec", "--workdir", "/"}, toolchain...), s.name, "sh", "-lc")
+ taskPathSetup := dockerCLISharedPathSetup + toolchainPathSetup
+ probe, err := exec.CommandContext(ctx, "docker", append(taskArgs, taskPathSetup+dockerCLIProbe, "loopforge-cli-available", binary)...).CombinedOutput()
+ installMode := "reuse"
+ if err != nil {
+ if !isDockerCLIMissing(err) {
+ return "", fmt.Errorf("探测工作区 CLI %s 失败:%w: %s", binary, err, conversationSetupOutput(probe))
+ }
+ installMode = "install"
+ }
+
+ setupArgs := []string{"exec", "--user", "0:0", "--workdir", "/"}
+ // Preparation uses a separate Docker exec as root. Carry the sandbox's
+ // configured network settings into that exec as well as normal CLI turns.
+ for _, key := range []string{"HTTP_PROXY", "HTTPS_PROXY", "ALL_PROXY", "NO_PROXY", "http_proxy", "https_proxy", "all_proxy", "no_proxy"} {
+ if value, ok := s.profile.Environment[key]; ok {
+ setupArgs = append(setupArgs, "-e", key+"="+value)
+ }
+ }
+ setupArgs = append(append(setupArgs, toolchain...), s.name, "sh", "-lc", setup, "loopforge-cli-setup", ids[0], ids[1], home, installMode)
output, err := exec.CommandContext(ctx, "docker", setupArgs...).CombinedOutput()
if err != nil {
return "", fmt.Errorf("准备 %s 原生CLI失败(工作区镜像需支持 Node.js/npm 和 Python3):%w: %s", provider, err, conversationSetupOutput(output))
}
- checkArgs := append(append(append([]string{"exec", "--workdir", "/"}, toolchain...), s.name), withToolchainPath([]string{"python3", "-c", "import os,pwd; pwd.getpwuid(os.geteuid())"})...)
- if check, err := exec.CommandContext(ctx, "docker", checkArgs...).CombinedOutput(); err != nil {
- return "", fmt.Errorf("验证工作区 CLI 用户失败: %w: %s", err, conversationSetupOutput(check))
+ check := taskPathSetup + "python3 -c 'import os,pwd; pwd.getpwuid(os.geteuid())' || exit\n" + dockerCLIProbe
+ checkArgs := append(taskArgs, check, "loopforge-cli-verify", binary)
+ output, err = exec.CommandContext(ctx, "docker", checkArgs...).CombinedOutput()
+ if err != nil {
+ return "", fmt.Errorf("验证工作区执行用户可使用 CLI %s 失败:%w: %s", binary, err, conversationSetupOutput(output))
}
lines := strings.Split(strings.TrimSpace(string(output)), "\n")
path := strings.TrimSpace(lines[len(lines)-1])
if !strings.HasPrefix(path, "/") || strings.ContainsAny(path, "\r\n\x00") {
- return "", fmt.Errorf("CLI安装未返回可执行文件路径")
+ return "", fmt.Errorf("工作区执行用户未返回 CLI %s 的可执行文件路径", binary)
}
return path, nil
}
-func conversationCLISetup(provider, binary string) (string, error) {
- packages := map[string]string{
- "codebuddy": "@tencent-ai/codebuddy-code", "codex": "@openai/codex", "claude-code": "@anthropic-ai/claude-code",
- AgentCLIOpenCode: "opencode-ai", AgentCLIKimi: "@moonshot-ai/kimi-code", AgentCLIPi: "@earendil-works/pi-coding-agent", AgentCLIDeepSeek: "@deepseek-ai/dsh@" + DeepSeekHarnessVersion,
- }
+func dockerCLISetup(provider, binary string) (string, error) {
+ spec := onDemandCLICatalog()[provider]
installer := ""
- if pkg := packages[provider]; pkg != "" {
+ if spec.Package != "" {
flags := ""
- if provider == AgentCLIDeepSeek {
+ if spec.RelaxEngines {
flags = "--engine-strict=false "
}
- installer = "npm install --no-audit --no-fund " + flags + "--prefix /opt/loopforge/conversation-cli " + shellSingleQuote(pkg) + " >&2\nln -sf ../node_modules/.bin/" + shellSingleQuote(binary) + " /opt/loopforge/conversation-cli/bin/" + shellSingleQuote(binary)
+ installer = "npm install --no-audit --no-fund " + flags + "--prefix /opt/loopforge/conversation-cli " + shellSingleQuote(spec.Package) + " >&2\nln -sf ../node_modules/.bin/" + shellSingleQuote(binary) + " /opt/loopforge/conversation-cli/bin/" + shellSingleQuote(binary)
} else {
switch provider {
case AgentCLIZCode:
@@ -230,26 +275,38 @@ func conversationCLISetup(provider, binary string) (string, error) {
// it has no standalone npm package. Never install a namesake.
installer = "echo 'ZCode CLI 未安装;请在工作区镜像中预装官方 ZCode CLI 并将 zcode 加入 PATH' >&2; exit 1"
case AgentCLICursor:
- installer = "curl -fsSL https://cursor.com/install | HOME=/opt/loopforge/conversation-cli bash >&2"
+ installer = conversationScriptInstaller(cursorInstallerURL)
case AgentCLIAntigravity:
- installer = "curl -fsSL https://antigravity.google/cli/install.sh | HOME=/opt/loopforge/conversation-cli bash >&2"
+ installer = conversationScriptInstaller(agyInstallerURL)
default:
return "", fmt.Errorf("不支持的会话CLI %s", provider)
}
}
// Setup runs as root in a --cap-drop=ALL container, where GNU tar's default
// of restoring archive owners fails with EPERM.
- return "set -eu\n" +
- `PATH=/opt/loopforge/conversation-cli/bin:/opt/loopforge/conversation-cli/.local/bin:$PATH
-TAR_OPTIONS=--no-same-owner
-export PATH TAR_OPTIONS
-` + toolchainPathSetup + `if ! command -v python3 >/dev/null 2>&1; then
+ return "set -eu\n" + dockerCLISharedPathSetup + toolchainPathSetup + `export TAR_OPTIONS=--no-same-owner
+if ! command -v python3 >/dev/null 2>&1; then
if command -v apt-get >/dev/null 2>&1; then apt-get update >&2 && apt-get install -y python3 >&2
elif command -v apk >/dev/null 2>&1; then apk add --no-cache python3 >&2
else echo 'Python3 is required for native CLI hooks and process supervision' >&2; exit 1; fi
fi
-` + conversationCLIIdentitySetup + "if ! command -v " + shellSingleQuote(binary) + " >/dev/null 2>&1; then\nmkdir -p /opt/loopforge/conversation-cli/bin\n" + installer + "\nfi\n" +
- "python3 -c 'import json,urllib.request'\ncommand -v " + shellSingleQuote(binary) + "\n", nil
+` + conversationCLIIdentitySetup + "if [ \"$4\" = install ]; then\nmkdir -p /opt/loopforge/conversation-cli/bin\n" + installer + "\nfi\n" +
+ "python3 -c 'import json,urllib.request'\n", nil
+}
+
+// Download the complete HTTPS installer before executing it. Retry the transfer
+// once because a TLS connection failure can be transient.
+func conversationScriptInstaller(url string) string {
+ return "installer_url=" + shellSingleQuote(url) + "\n" + `installer_file=$(mktemp)
+trap 'rm -f "$installer_file"' EXIT
+download_installer() {
+ curl -fsSL --proto '=https' --tlsv1.2 --connect-timeout 10 --max-time 45 -o "$installer_file" "$installer_url"
+}
+if ! download_installer; then
+ sleep 1
+ download_installer
+fi
+HOME=/opt/loopforge/conversation-cli bash "$installer_file" >&2`
}
// Node-based CLIs call getpwuid even when HOME is already set. Numeric
diff --git a/internal/runtime/conversation_sandbox_test.go b/internal/runtime/conversation_sandbox_test.go
new file mode 100644
index 00000000..1d01d843
--- /dev/null
+++ b/internal/runtime/conversation_sandbox_test.go
@@ -0,0 +1,108 @@
+package runtime
+
+import (
+ "context"
+ "os"
+ "os/exec"
+ "path/filepath"
+ "strings"
+ "testing"
+
+ "agentflow/internal/domain"
+)
+
+func TestConversationCLISetupUsesSandboxProxy(t *testing.T) {
+ bin := t.TempDir()
+ t.Setenv("PATH", bin+string(os.PathListSeparator)+os.Getenv("PATH"))
+ t.Setenv("AGENTFLOW_RUNTIME_CLI_DIR", "")
+ argsPath := filepath.Join(t.TempDir(), "setup-args")
+ t.Setenv("LOOPFORGE_TEST_SETUP_ARGS", argsPath)
+ docker := writeScript(t, `#!/bin/sh
+set -eu
+case "$*" in
+ *"id -u; id -g"*) printf '1000\n1000\n' ;;
+ *loopforge-cli-available*) exit 127 ;;
+ *"loopforge-cli-setup"*)
+ printf '%s\n' "$@" > "$LOOPFORGE_TEST_SETUP_ARGS" ;;
+ *loopforge-cli-verify*) printf '/opt/loopforge/conversation-cli/.local/bin/agy\n' ;;
+esac
+`)
+ if err := os.Symlink(docker, filepath.Join(bin, "docker")); err != nil {
+ t.Fatal(err)
+ }
+ sb := &dockerSandbox{name: "workspace", profile: domain.SandboxProfile{Environment: map[string]string{
+ "HTTPS_PROXY": "http://proxy.example.test:3128",
+ "no_proxy": "localhost",
+ "BASH_ENV": "/workspace/profile.sh",
+ }}}
+ if _, err := ensureConversationCLI(context.Background(), sb, AgentCLIAntigravity, "/workspace/home"); err != nil {
+ t.Fatal(err)
+ }
+ args, err := os.ReadFile(argsPath)
+ if err != nil {
+ t.Fatal(err)
+ }
+ for _, option := range []string{"HTTPS_PROXY=http://proxy.example.test:3128", "no_proxy=localhost"} {
+ if !strings.Contains(string(args), "\n-e\n"+option+"\n") {
+ t.Errorf("installer missing proxy option %s", option)
+ }
+ }
+ if strings.Contains(string(args), "BASH_ENV=") {
+ t.Error("installer inherited unrelated workspace shell configuration")
+ }
+}
+
+func TestConversationScriptInstallerRetriesDownload(t *testing.T) {
+ for _, tc := range []struct {
+ name string
+ fail string
+ }{
+ {name: "recovers after TLS error", fail: "once"},
+ {name: "returns persistent TLS error", fail: "always"},
+ } {
+ t.Run(tc.name, func(t *testing.T) {
+ bin := t.TempDir()
+ t.Setenv("PATH", bin+string(os.PathListSeparator)+os.Getenv("PATH"))
+ t.Setenv("LOOPFORGE_TEST_DOWNLOAD_MARKER", filepath.Join(t.TempDir(), "first-attempt"))
+ t.Setenv("LOOPFORGE_TEST_DOWNLOAD_FAILURE", tc.fail)
+ curl := writeScript(t, `#!/bin/sh
+set -eu
+while [ "$#" -gt 0 ]; do
+ case "$1" in -o) output=$2; shift ;; esac
+ shift
+done
+echo "download attempted" >&2
+if [ -e "$LOOPFORGE_TEST_DOWNLOAD_MARKER" ] && [ "$LOOPFORGE_TEST_DOWNLOAD_FAILURE" = once ]; then
+ printf '%s' complete > "$output"
+ exit 0
+fi
+touch "$LOOPFORGE_TEST_DOWNLOAD_MARKER"
+printf '%s' incomplete > "$output"
+echo "curl: (35) SSL routines::wrong version number" >&2
+exit 35
+`)
+ bash := writeScript(t, `#!/bin/sh
+echo "installer invoked"
+test "$(cat "$1")" = complete
+`)
+ for name, script := range map[string]string{"curl": curl, "bash": bash} {
+ if err := os.Symlink(script, filepath.Join(bin, name)); err != nil {
+ t.Fatal(err)
+ }
+ }
+
+ output, err := exec.Command("sh", "-ec", conversationScriptInstaller(agyInstallerURL)).CombinedOutput()
+ if strings.Count(string(output), "download attempted") != 2 {
+ t.Fatalf("installer download did not retry once: %s", output)
+ }
+ ran := strings.Count(string(output), "installer invoked")
+ if tc.fail == "once" {
+ if err != nil || ran != 1 {
+ t.Fatalf("verified download did not install: %v\n%s", err, output)
+ }
+ } else if stop, ok := err.(*exec.ExitError); !ok || stop.ExitCode() != 35 || ran != 0 {
+ t.Fatalf("failed transfer ran the installer or lost curl's exit code: %v\n%s", err, output)
+ }
+ })
+ }
+}
diff --git a/internal/runtime/sandbox_docker.go b/internal/runtime/sandbox_docker.go
index 408bd66c..c4fb30fa 100644
--- a/internal/runtime/sandbox_docker.go
+++ b/internal/runtime/sandbox_docker.go
@@ -28,6 +28,8 @@ type dockerSandbox struct {
mu sync.Mutex
browserMu sync.Mutex
started bool
+ cliSetupOnce sync.Once
+ cliSetupGate chan struct{}
// execGate lets parallel branches exec concurrently (read side) while a
// cwd-recovery Recreate (write side) waits for them instead of docker
// rm-ing the container under a sibling's running command.
@@ -164,6 +166,10 @@ func (s *dockerSandbox) Exec(ctx context.Context, command CommandSpec, sink Even
}
func (s *dockerSandbox) execOnce(ctx context.Context, command CommandSpec, sink EventSink) (out string, err error) {
+ command, cliPath, err := s.prepareSOPCLI(ctx, command)
+ if err != nil {
+ return "", err
+ }
args := []string{"exec"}
if command.Stdin != nil || isManagedClaude(command) {
args = append(args, "-i")
@@ -171,10 +177,6 @@ func (s *dockerSandbox) execOnce(ctx context.Context, command CommandSpec, sink
for _, environment := range appendEnvironment(nil, s.profile.Environment, command.environment) {
args = append(args, "-e", environment)
}
- cliPath, err := s.onDemandCLIPath(ctx, command)
- if err != nil {
- return "", err
- }
if cliPath != "" {
args = append(args, "-e", "AGENTFLOW_RUNTIME_CLI_PATH="+cliPath)
}
@@ -183,8 +185,8 @@ func (s *dockerSandbox) execOnce(ctx context.Context, command CommandSpec, sink
args = append(args, s.name)
argv := dockerWorkspaceExecArgv(command.Argv)
if command.WorkingDir != "" {
- argv = append([]string{"sh", "-lc", dockerMCPCallLaunch + `PATH=/opt/loopforge/conversation-cli/bin:/opt/loopforge/conversation-cli/.local/bin:$PATH; export PATH
-cd "$1" && shift && exec "$@"`, "conversation", command.WorkingDir}, dropShellLoginFlag(command.Argv)...)
+ argv = append([]string{"sh", "-lc", dockerMCPCallLaunch + dockerCLISharedPathSetup +
+ `cd "$1" && shift && exec "$@"`, "conversation", command.WorkingDir}, dropShellLoginFlag(command.Argv)...)
}
processFile := ""
if command.OwnProcessGroup {
@@ -211,7 +213,7 @@ cd "$1" && shift && exec "$@"`, "conversation", command.WorkingDir}, dropShellLo
// PATH; helper bin is prepended after that, and an inner `sh -lc` is demoted
// to `sh -c` so a second login does not wipe the workspace bin.
func dockerWorkspaceExecArgv(argv []string) []string {
- launch := dockerMCPCallLaunch
+ launch := dockerMCPCallLaunch + "PATH=$PATH:" + dockerCLISharedPath + "\nexport PATH\n"
if len(argv) == 0 {
return []string{"sh", "-lc", launch + "pwd"}
}
@@ -229,6 +231,52 @@ if [ -n "${AGENTFLOW_RUNTIME_CLI_PATH:-}" ] && [ -d "$AGENTFLOW_RUNTIME_CLI_PATH
fi
` + toolchainPathSetup
+// prepareSOPCLI is limited to the default binaries of registered providers.
+// Explicit executable paths, shell tasks and already prepared chat commands
+// retain their original argv.
+func (s *dockerSandbox) prepareSOPCLI(ctx context.Context, command CommandSpec) (CommandSpec, string, error) {
+ spec, ok := onDemandCLICatalog()[command.Provider]
+ if !ok || len(command.Argv) == 0 || command.Argv[0] != spec.Binary {
+ return command, "", nil
+ }
+ // Probe with the normal command user's PATH. This also finds installs
+ // from earlier nodes without running the privileged preparation again.
+ args := []string{"exec"}
+ path, hasPath := command.environment["PATH"]
+ if !hasPath {
+ path, hasPath = s.profile.Environment["PATH"]
+ }
+ if hasPath {
+ args = append(args, "-e", "PATH="+path)
+ }
+ args = append(append(args, s.toolchainExecEnv()...), s.name)
+ args = append(args, dockerWorkspaceExecArgv([]string{"sh", "-c", dockerCLIProbe, "loopforge-cli-probe", spec.Binary})...)
+ output, err := exec.CommandContext(ctx, "docker", args...).CombinedOutput()
+ if err == nil {
+ return command, "", nil
+ }
+ if !isDockerCLIMissing(err) {
+ return command, "", fmt.Errorf("探测沙箱 CLI %s 失败:%w: %s", spec.Binary, err, conversationSetupOutput(output))
+ }
+ // The published image can use the existing, shared host installations.
+ // Other sandboxes prepare the official CLI in the current container.
+ cliPath, err := s.onDemandCLIPath(ctx, command)
+ if err != nil || cliPath != "" {
+ return command, cliPath, err
+ }
+ binary, err := s.ensureDockerCLI(ctx, command.Provider, "/workspace")
+ if err != nil {
+ return command, "", err
+ }
+ command.Argv = append([]string{binary}, command.Argv[1:]...)
+ return command, "", nil
+}
+
+func isDockerCLIMissing(err error) bool {
+ var exit *exec.ExitError
+ return errors.As(err, &exit) && exit.ExitCode() == 127
+}
+
// onDemandCLIPath installs a CLI the published runtime image does not bundle
// (Claude Code and the npm agent CLIs) for sandboxes of that image, and returns
// the mounted bin directory. It is appended to PATH so a CLI shipped by an
diff --git a/web/app/assets-harness.css b/web/app/assets-harness.css
index 89982827..0405244c 100644
--- a/web/app/assets-harness.css
+++ b/web/app/assets-harness.css
@@ -370,7 +370,10 @@
/* Switches: the platform checkboxes (name="global" / name="readOnlyRootFS") drawn as Harness switches. */
#assetsView .rule-global-block { margin: 14px 0 0; padding: 14px 0 0; border: 0; border-top: 1px solid var(--hui-border-soft); border-radius: 0; background: none; }
#assetsView :is(.rule-global-row, .asset-switch-row) { display: flex; align-items: flex-start; justify-content: space-between; gap: 12px; margin: 0; padding: 0; border: 0; background: none; cursor: pointer; }
-#assetsView .asset-switch-row { margin-top: 14px; padding-top: 14px; border-top: 1px solid var(--hui-border-soft); }
+#assetsView .asset-switch-row { margin-top: 14px; padding-top: 14px; border-top: 1px solid var(--hui-border-soft); cursor: default; }
+#assetsView .asset-switch-row label { cursor: pointer; }
+#assetsView .asset-switch-controls { display: inline-flex; flex: none; align-items: center; gap: 8px; }
+#assetsView .asset-switch-controls .field-help { padding: 0; background: transparent; }
#assetsView :is(.rule-global-row, .asset-switch-row) b { display: block; color: var(--hui-text); font: 500 13px/1.4 var(--hui-sans); }
#assetsView :is(.rule-global-row, .asset-switch-row) small { display: block; margin-top: 2px; color: var(--hui-tertiary); font-size: 12px; font-weight: 400; line-height: 1.45; }
#assetsView :is(.rule-global-input, .asset-switch) { margin: 2px 0 0; }
diff --git a/web/app/assets.js b/web/app/assets.js
index 495e08a6..558b7bba 100644
--- a/web/app/assets.js
+++ b/web/app/assets.js
@@ -336,7 +336,17 @@ function assetBasicFieldsHTML(a,{creating}){
const kind=assetKindLabel();
let html=`<label class="asset-field-label" for="assetFieldName">名称</label><input id="assetFieldName" name="name" class="asset-input" value="${escapeHTML(a.name||'')}" required placeholder="给${escapeHTML(kind)}起个名字"><label class="asset-field-label" for="assetFieldId">标识</label><input id="assetFieldId" name="id" class="asset-input is-mono" value="${escapeHTML(a.id||'')}" required ${creating?'placeholder="如 loopforge-core"':'readonly aria-readonly="true"'}><div class="asset-field-hint">${creating?'创建后不可修改,用于资产引用。':'标识用于资产引用,创建后不可修改。'}</div><label class="asset-field-label" for="assetFieldDesc">描述</label><input id="assetFieldDesc" name="description" class="asset-input" value="${escapeHTML(a.description||'')}" placeholder="一句话说明用途">`;
if(state.assetType==='rules')html+=`<label class="asset-field-label" for="assetFieldPriority">优先级</label><input id="assetFieldPriority" name="priority" class="asset-input" type="number" value="${a.priority||100}"><div class="asset-field-hint">数值越大越先注入。</div>${ruleGlobalFields(a)}`;
- if(state.assetType==='sandboxes')html+=`<label class="asset-field-label">隔离方式</label><select name="driver" class="asset-select" aria-label="隔离方式"><option value="local" ${sandboxDriverOption(a.driver)==='local'?'selected':''}>local(本机直接执行)</option><option value="native" ${sandboxDriverOption(a.driver)==='native'?'selected':''}>native(系统轻量隔离)</option><option value="docker" ${sandboxDriverOption(a.driver)==='docker'?'selected':''}>docker(OCI 容器)</option></select><div data-sandbox-drivers="local" class="json-help">直接在本机 workspace 执行,并继承受控的宿主进程环境。</div><div data-sandbox-drivers="native" class="json-help">按执行机器的系统自动选择:macOS 用 seatbelt,Linux 用 bwrap。</div><div data-sandbox-drivers="native"><label class="asset-field-label">执行环境</label><select name="environmentId" class="asset-select" aria-label="执行环境">${environmentOptions(a.environmentId)}</select><div class="json-help">选中后沙箱会执行该环境的 <code>install.sh</code>,把工具装进隔离的 <code>$PREFIX</code>,再用 PATH 切换。未选择时,若 workspace 存在 <code>agentflow-environment/</code> 也会自动启用。</div></div><div data-sandbox-drivers="docker"><label class="asset-field-label">Dockerfile</label><select name="dockerfileId" class="asset-select" aria-label="Dockerfile">${dockerfileOptions(a.dockerfileId)}</select><div class="json-help">沙箱只引用这条目录资产;初始化时用库里的内容构建临时镜像,结束后删除容器和镜像。</div><label class="asset-switch-row"><span><b>容器根文件系统只读</b><small>仅限制镜像自身的 /usr、/etc 等目录;/workspace 仍可写,/tmp 使用临时内存盘。部分工具可能不兼容,默认建议关闭。</small></span><input name="readOnlyRootFS" type="checkbox" class="asset-switch" role="switch" ${a.readOnlyRootFS?'checked':''}></label></div>`;
+ if(state.assetType==='sandboxes')html+=`<label class="asset-field-label">隔离方式</label><select name="driver" class="asset-select" aria-label="隔离方式"><option value="local" ${sandboxDriverOption(a.driver)==='local'?'selected':''}>local(本机直接执行)</option><option value="native" ${sandboxDriverOption(a.driver)==='native'?'selected':''}>native(系统轻量隔离)</option><option value="docker" ${sandboxDriverOption(a.driver)==='docker'?'selected':''}>docker(OCI 容器)</option></select><div data-sandbox-drivers="local" class="json-help">直接在本机 workspace 执行,并继承受控的宿主进程环境。</div><div data-sandbox-drivers="native" class="json-help">按执行机器的系统自动选择:macOS 用 seatbelt,Linux 用 bwrap。</div><div data-sandbox-drivers="native"><label class="asset-field-label">执行环境</label><select name="environmentId" class="asset-select" aria-label="执行环境">${environmentOptions(a.environmentId)}</select><div class="json-help">选中后沙箱会执行该环境的 <code>install.sh</code>,把工具装进隔离的 <code>$PREFIX</code>,再用 PATH 切换。未选择时,若 workspace 存在 <code>agentflow-environment/</code> 也会自动启用。</div></div><div data-sandbox-drivers="docker"><label class="asset-field-label">Dockerfile</label><select name="dockerfileId" class="asset-select" aria-label="Dockerfile">${dockerfileOptions(a.dockerfileId)}</select><div class="json-help">沙箱只引用这条目录资产;初始化时用库里的内容构建临时镜像,结束后删除容器和镜像。</div>
+ <div class="asset-switch-row">
+ <label for="assetReadOnlyRootFS">
+ <b>容器根文件系统只读</b>
+ <small>开启后,/usr、/etc 等系统目录只读,/tmp 使用临时内存盘。默认建议关闭。</small>
+ </label>
+ <span class="asset-switch-controls">
+ <input id="assetReadOnlyRootFS" name="readOnlyRootFS" type="checkbox" class="asset-switch" role="switch" ${a.readOnlyRootFS?'checked':''}>
+ <button id="assetReadOnlyRootFSHelp" type="button" class="field-help" aria-label="容器根文件系统只读说明" title="开启后,缺少的 CLI 无法在容器内自动安装。工作区 /workspace 仍可写。">?</button>
+ </span>
+ </div></div>`;
return html;
}
function assetAsideHTML(a,{creating}){
@@ -360,7 +370,13 @@ function renderAssetForm(a){
f.querySelectorAll('[data-asset-tab]').forEach(b=>b.onclick=()=>setAssetTab(b.dataset.assetTab));
setAssetTab(state.assetTab||tabs[0][0]);
if(state.assetType==='rules')bindRuleGlobalPicker(a);
- if(state.assetType==='sandboxes'){f.elements.driver.onchange=()=>syncSandboxDriverFields(f.elements.driver);syncSandboxDriverFields(f.elements.driver)}
+ if(state.assetType==='sandboxes'){
+ f.elements.driver.onchange=()=>syncSandboxDriverFields(f.elements.driver);
+ syncSandboxDriverFields(f.elements.driver);
+ f.querySelector('#assetReadOnlyRootFSHelp')?.addEventListener('click',event=>{
+ window.HuiTooltip?.show(event.currentTarget);
+ });
+ }
f.querySelectorAll('select.asset-select').forEach(sel=>window.enhanceSelect?.(sel));
if(readonly)f.querySelectorAll('input,textarea,select,.repo-picker-tag').forEach(el=>{if(el.type!=='file')el.disabled=true});
if(state.assetType==='skills'&&!creating){skillUploadButtons(readonly||!!assetSkillSource(a));bindAssetSourceActions(a)}
diff --git a/webtest/tests/assets-agents.test.mjs b/webtest/tests/assets-agents.test.mjs
index 07042836..3a0ed45b 100644
--- a/webtest/tests/assets-agents.test.mjs
+++ b/webtest/tests/assets-agents.test.mjs
@@ -1,6 +1,6 @@
import test from 'node:test';
import assert from 'node:assert/strict';
-import { loadApp, settle } from '../lib/load-app.mjs';
+import { chooseOption, loadApp, settle } from '../lib/load-app.mjs';
test('asset catalog filters, opens, marks dirty, shares, saves, and deletes assets', async (t) => {
const app = await loadApp();
@@ -55,13 +55,28 @@ test('asset forms save environment and sandbox-specific JSON fields', async (t)
app.evaluate(`state.assetType='sandboxes';state.selectedAsset='__new__';state.assetDetailKey='';renderAssets()`);
form = app.document.querySelector('#assetForm');
+ const readOnlyHelp = form.querySelector('#assetReadOnlyRootFSHelp');
+ const dockerFields = readOnlyHelp.closest('[data-sandbox-drivers="docker"]');
+ assert.equal(dockerFields.hidden, true);
+ chooseOption(form.elements.driver, 'docker');
+ assert.equal(dockerFields.hidden, false);
+ readOnlyHelp.click();
+ const tooltip = app.document.querySelector('#huiTooltip:not([hidden])');
+ assert.match(tooltip?.textContent ?? '', /缺少的 CLI 无法在容器内自动安装。工作区 \/workspace 仍可写/);
+ assert.equal(form.elements.readOnlyRootFS.checked, false);
+ assert.equal(app.router.calls.some((c) => c.path === '/api/sandboxes' && c.method === 'PUT'), false);
+
form.elements.id.value = 'sandbox-new';
form.elements.name.value = 'Docker sandbox';
form.elements.environment.value = '{"CI":"1"}';
+ chooseOption(form.elements.dockerfileId, 'docker-1');
+ form.elements.readOnlyRootFS.checked = true;
form.dispatchEvent(new app.window.Event('submit', { bubbles: true, cancelable: true }));
await settle(2);
const sandbox = app.router.calls.find((c) => c.path === '/api/sandboxes' && c.method === 'PUT').body;
- assert.equal(sandbox.driver, 'local');
+ assert.equal(sandbox.driver, 'docker');
+ assert.equal(sandbox.dockerfileId, 'docker-1');
+ assert.equal(sandbox.readOnlyRootFS, true);
assert.deepEqual(sandbox.environment, { CI: '1' });
});