Skip to content
Open
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
2 changes: 1 addition & 1 deletion cmd/agentflow/main.go
Original file line number Diff line number Diff line change
Expand Up @@ -92,7 +92,7 @@ func main() {
mysqlDSN := flag.String("mysql-dsn", "", "MySQL DSN; overrides AGENTFLOW_MYSQL_DSN. MySQL is the only data source.")
roleFlag := flag.String("role", "", "process role: api, worker, or all (default all)")
cliAction := flag.String("cli-action", "", "local managed CLI administration: status, update, or rollback; exits without starting services")
cliProvider := flag.String("cli-provider", "", "provider for CLI rollback: codex, codebuddy, or claude-code")
cliProvider := flag.String("cli-provider", "", "managed CLI provider to roll back")
cliTimeout := flag.Duration("cli-timeout", 80*time.Minute, "total managed CLI operation timeout")
browserImage := flag.Bool("browser-image", false, "build or pull the agent browser sidecar image, print its name and exit")
flag.Parse()
Expand Down
6 changes: 6 additions & 0 deletions docs/deployment.md
Original file line number Diff line number Diff line change
Expand Up @@ -15,6 +15,12 @@ npm install --global @openai/codex@0.162.1 @anthropic-ai/claude-code@2.1.326

Ensure the service can find `codebuddy` and Node.js on its PATH, or set `AGENTFLOW_CODEBUDDY_BIN` to the installed executable. Configure the model key and its network environment in personal settings. The no-key script demo does not need the CLI. The production Docker image includes CodeBuddy, Codex and DeepSeek Harness (`dsh`). Claude Code and the other agent CLIs are not bundled. When a conversation fails because one is missing, the error says it is not installed and offers an install button. That downloads the pinned `@anthropic-ai/claude-code` release, or the public package for OpenCode, Kimi Code and Pi, into `$LOOPFORGE_DATA_DIR/cli`; an installation outside the image gets the pinned `@deepseek-ai/dsh` release the same way. Cursor CLI and Antigravity use their providers' installers and land in the service user's `~/.local/bin`. Closing or reloading the browser does not stop an install that has already started, and the button stays on “自动安装” until it finishes. A finished install replaces the earlier generation failure with a prompt to send the message again. The next message reuses the installation. An SOP sandbox of the published image that selects Claude Code, OpenCode, Kimi Code or Pi installs the same package on first use and shares it with conversations. Cursor CLI and Antigravity are not installed into SOP sandboxes. Connected runners keep their own CLI requirements.

Set `AGENTFLOW_MANAGED_CLI_ROOT` to a persistent absolute directory to enable the daily CLI updater on platform processes that execute runs (`worker` or `all`). The updater uses npm for Claude Code, CodeBuddy, Codex, DeepSeek Harness, Kimi Code, OpenCode, and Pi. Cursor and Antigravity use their official release archives. All candidates pass a 24-hour observation window and a version and CLI argument check before activation. The previous installation remains available for rollback. After a rollback, automatic updates wait for a release newer than the rejected version.

For native execution, the platform prefers explicit binary overrides, then the managed inventory. Platform-owned native workflows pin the inventory within their managed root. A worker that adopts a run can reuse its pin when it accesses the same persistent managed directory at the same absolute path with compatible binaries. Workers with separate roots resolve the CLI from their own inventory.

The updater keeps observations of Cursor and Antigravity releases across daily checks so each release can age even while the vendor keeps publishing. Docker sandboxes use the CLI supplied by their image or sandbox installer. ZCode uses the executable supplied by the deployment.

A conversation workspace on a custom Dockerfile without Node.js, npm or Python 3 uses the platform's own copies. On first use the platform copies its Node.js, npm and a relocatable Python into `$LOOPFORGE_DATA_DIR/cli/toolchain/<build>/`, plus each bundled CLI (CodeBuddy, Codex, DeepSeek Harness) the first time a sandbox needs it, and mounts the directory read-only at the end of the sandbox `PATH`. Tools the image ships take precedence. Only glibc images of the platform's architecture use it; Alpine (musl) images need their own Node.js, npm and Python 3. A new platform build creates a new directory and leaves the previous ones in place: after an upgrade, delete the other `cli/toolchain/<build>/` directories (about 200 MB each plus the CLIs copied into them).

Stop the foreground service with Ctrl-C. Start it again with the same command. MySQL data stays in its Compose volume. `docker compose stop mysql` stops the database without deleting it.
Expand Down
22 changes: 13 additions & 9 deletions internal/httpapi/assistant_agentcli_bin_test.go
Original file line number Diff line number Diff line change
Expand Up @@ -16,32 +16,36 @@ import (
"agentflow/internal/managedcli"
)

func TestResolveUnmanagedCLIPreservesPathAndInstallerFallback(t *testing.T) {
func TestResolveManagedPiBeforePATHAndPreserveOverrides(t *testing.T) {
root, host, home := t.TempDir(), t.TempDir(), t.TempDir()
t.Setenv("HOME", home)
t.Setenv("PATH", host)
t.Setenv("AGENTFLOW_MANAGED_CLI_ROOT", root)
t.Setenv("AGENTFLOW_DSH_BIN", "")
t.Setenv("AGENTFLOW_PI_BIN", "")
t.Setenv("AGENTFLOW_CURSOR_BIN", "")
hostDSH := filepath.Join(host, "dsh")
if err := os.WriteFile(hostDSH, []byte("#!/bin/sh\n"), 0700); err != nil {
hostPi := filepath.Join(host, "pi")
if err := os.WriteFile(hostPi, []byte("#!/bin/sh\n"), 0700); err != nil {
t.Fatal(err)
}
managed := filepath.Join(root, "providers", "dsh", "0.2.2-rc.1", "node_modules", ".bin", "dsh")
managed := filepath.Join(root, "providers", "pi", "1.5.2", "node_modules", ".bin", "pi")
if err := os.MkdirAll(filepath.Dir(managed), 0700); err != nil {
t.Fatal(err)
}
if err := os.WriteFile(managed, []byte("#!/bin/sh\n"), 0700); err != nil {
t.Fatal(err)
}
data, _ := json.Marshal(managedcli.State{Current: managedcli.Inventory{"dsh": {Version: "0.2.2-rc.1", Binary: managed}}})
data, _ := json.Marshal(managedcli.State{Current: managedcli.Inventory{"pi": {Version: "1.5.2", Binary: managed}}})
if err := os.WriteFile(filepath.Join(root, "state.json"), data, 0600); err != nil {
t.Fatal(err)
}
if got, err := resolveAssistantEngineBin("dsh"); err != nil || got != hostDSH {
t.Fatalf("unmanaged dsh did not use PATH: %q %v", got, err)
if got, err := resolveAssistantEngineBin("pi"); err != nil || got != managed {
t.Fatalf("managed Pi did not supersede the host binary: %q %v", got, err)
}
// Cursor has no npm package: the managed root never hides ~/.local/bin.
t.Setenv("AGENTFLOW_PI_BIN", hostPi)
if got, err := resolveAssistantEngineBin("pi"); err != nil || got != hostPi {
t.Fatalf("explicit Pi override was ignored: %q %v", got, err)
}
// An empty Cursor inventory still falls back to its installer location.
found, err := resolveAssistantEngineBin("cursor")
// The integration image also installs Cursor globally. PATH and HOME
// isolation deliberately do not disable the supported global fallback.
Expand Down
4 changes: 2 additions & 2 deletions internal/httpapi/assistant_engine_cli.go
Original file line number Diff line number Diff line change
Expand Up @@ -70,12 +70,12 @@ func resolveAssistantEngineBin(engine string) (string, error) {
if engine == assistantEngineClaude {
binary, override, managed = "claude", "AGENTFLOW_CLAUDE_BIN", "claude-code"
} else if runtime.IsAgentCLI(engine) {
binary, override, managed = runtime.AgentCLIBinary(engine), "AGENTFLOW_"+strings.ToUpper(strings.ReplaceAll(engine, "-", "_"))+"_BIN", ""
binary, override, managed = runtime.AgentCLIBinary(engine), "AGENTFLOW_"+strings.ToUpper(strings.ReplaceAll(engine, "-", "_"))+"_BIN", engine
}
if path := strings.TrimSpace(os.Getenv(override)); path != "" && fileExecutable(path) {
return path, nil
}
if root := strings.TrimSpace(os.Getenv("AGENTFLOW_MANAGED_CLI_ROOT")); root != "" && managed != "" {
if root := strings.TrimSpace(os.Getenv("AGENTFLOW_MANAGED_CLI_ROOT")); root != "" && managedcli.Supports(managed) {
if inventory, err := managedcli.ReadInventory(root); err == nil {
if path, ok := inventory.BinaryFor(managed); ok {
return path, nil
Expand Down
3 changes: 2 additions & 1 deletion internal/managedcli/coordinator_process_test.go
Original file line number Diff line number Diff line change
Expand Up @@ -10,6 +10,7 @@ import (
"os"
"os/exec"
"path/filepath"
"strings"
"testing"
"time"
)
Expand Down Expand Up @@ -156,7 +157,7 @@ func TestDailyClaimAcrossProcessesAndCrash(t *testing.T) {
}
data, err := os.ReadFile(filepath.Join(root, "attempts"))
must(t, err)
want := "attempt\nattempt\nattempt\n" // One check visits all three providers.
want := strings.Repeat("attempt\n", len(providerNames())) // One check visits every provider.
if crash {
want = "attempt\n" // The first request was interrupted after the claim.
}
Expand Down
35 changes: 20 additions & 15 deletions internal/managedcli/manifest.go
Original file line number Diff line number Diff line change
Expand Up @@ -18,13 +18,14 @@ import (

var releaseVersion = regexp.MustCompile(`^(0|[1-9][0-9]*)\.(0|[1-9][0-9]*)\.(0|[1-9][0-9]*)$`)

// Installation points at one immutable, version-specific npm installation.
// Installation points at an immutable version-specific CLI installation.
// Authentication/configuration homes are deliberately not part of this record.
type Installation struct {
Version string `json:"version"`
Binary string `json:"binary"`
Integrity string `json:"integrity,omitempty"`
InstalledAt time.Time `json:"installedAt,omitempty"`
Version string `json:"version"`
Binary string `json:"binary"`
Integrity string `json:"integrity,omitempty"`
PublishedAt *time.Time `json:"publishedAt,omitempty"`
InstalledAt time.Time `json:"installedAt,omitempty"`
}

type Inventory map[string]Installation
Expand All @@ -35,12 +36,13 @@ func (i Inventory) BinaryFor(provider string) (string, bool) {
}

type State struct {
LastCheck time.Time `json:"lastCheck"`
Candidates Inventory `json:"candidates"`
Current Inventory `json:"current"`
Previous Inventory `json:"previous"`
Rejected map[string]string `json:"rejected,omitempty"`
UpdatedAt time.Time `json:"updatedAt,omitempty"`
LastCheck time.Time `json:"lastCheck"`
Candidates Inventory `json:"candidates"`
Current Inventory `json:"current"`
Previous Inventory `json:"previous"`
Rejected map[string]string `json:"rejected,omitempty"`
VendorObservations map[string][]vendorObservation `json:"vendorObservations,omitempty"`
UpdatedAt time.Time `json:"updatedAt,omitempty"`
}

// State and its rollback pointers are committed in one atomic rename.
Expand All @@ -63,6 +65,9 @@ func ReadState(root string) (State, error) {
if state.Rejected == nil {
state.Rejected = map[string]string{}
}
if state.VendorObservations == nil {
state.VendorObservations = map[string][]vendorObservation{}
}
if err := validateInventory(root, state.Current); err != nil {
return State{}, fmt.Errorf("current inventory: %w", err)
}
Expand All @@ -74,8 +79,8 @@ func ReadInventory(root string) (Inventory, error) {
return state.Current, err
}

// PinInventory fixes the complete inventory for a run, including an empty one
// before initial provisioning. Pins live outside agent-controlled workspaces.
// PinInventory fixes the complete inventory for a run in this root, including
// an empty one before provisioning. Pins live outside agent-controlled workspaces.
// Publishing via link makes concurrent first claims observe a complete file.
// Old versions and pins are not automatically deleted: suspended/resumable runs
// may still reference them after the runner or updater restarts.
Expand Down Expand Up @@ -161,10 +166,10 @@ func validateInventory(root string, inventory Inventory) error {
return errors.New("managed CLI inventory must be a JSON object")
}
for provider, installed := range inventory {
if _, ok := providerSpecs[provider]; !ok {
if !Supports(provider) {
return fmt.Errorf("unknown managed CLI provider %q", provider)
}
if !releaseVersion.MatchString(installed.Version) {
if !validProviderVersion(provider, installed.Version) {
return fmt.Errorf("invalid release version for %s", provider)
}
base := filepath.Join(root, "providers", provider)
Expand Down
78 changes: 55 additions & 23 deletions internal/managedcli/npm.go
Original file line number Diff line number Diff line change
Expand Up @@ -54,7 +54,7 @@ func (m *Manager) commandEnvironment() []string {
)
}

func (m *Manager) prepareTools(ctx context.Context) error {
func (m *Manager) prepareCommandDirectories() error {
for _, rel := range []string{"updater-home", "tmp", "npm-cache", "providers"} {
if err := prepareDirectory(m.Root, rel); err != nil {
return err
Expand All @@ -65,6 +65,13 @@ func (m *Manager) prepareTools(ctx context.Context) error {
return err
}
}
return nil
}

func (m *Manager) prepareTools(ctx context.Context) error {
if err := m.prepareCommandDirectories(); err != nil {
return err
}
for name, target := range map[string]*string{"node": &m.nodeBinary, "npm": &m.npmBinary} {
if *target == "" {
path, err := exec.LookPath(name)
Expand Down Expand Up @@ -112,47 +119,72 @@ func (m *Manager) install(ctx context.Context, provider string, candidate releas
}
}
}()
if err := os.WriteFile(filepath.Join(stage, "package.json"), []byte("{\"private\":true}\n"), 0o600); err != nil {
return Installation{}, err
}
args := []string{"install", "--prefix", stage, "--registry", npmRegistry, "--no-audit", "--no-fund", "--engine-strict", "--ignore-scripts", "--include=optional", "--save-exact", spec.Package + "@" + candidate.Version}
if _, err := m.command(ctx, m.npmBinary, args, stage); err != nil {
return Installation{}, fmt.Errorf("install %s: %w", provider, err)
}
if err := verifyPackageLock(stage, spec.Package, candidate); err != nil {
return Installation{}, err
}
// Some native optional dependencies need lifecycle hooks. Defer them until
// npm has fetched the exact candidate and its SRI has been checked. Commands
// use the updater's isolated home and credential-free environment; they run
// with the worker's OS permissions, not in a separate security sandbox.
rebuild := []string{"rebuild", "--prefix", stage, "--registry", npmRegistry, "--no-audit", "--no-fund"}
if _, err := m.command(ctx, m.npmBinary, rebuild, stage); err != nil {
return Installation{}, fmt.Errorf("build verified CLI dependencies: %w", err)
var executable string
if candidate.Artifact != nil {
executable = spec.Binary
err = m.installVendorArtifact(ctx, provider, candidate, stage)
} else {
executable = filepath.Join("node_modules", ".bin", spec.Binary)
err = m.installPackage(ctx, provider, spec, candidate, stage)
}
if err := verifyPackageLock(stage, spec.Package, candidate); err != nil {
if err != nil {
return Installation{}, err
}
staged := Installation{Version: candidate.Version, Binary: filepath.Join(stage, "node_modules", ".bin", spec.Binary)}
staged := Installation{Version: candidate.Version, Binary: filepath.Join(stage, executable)}
if err := validateInventory(m.Root, Inventory{provider: staged}); err != nil {
return Installation{}, err
}
// Rename a unique complete directory, never an existing installation.
// npm's .bin links are relative and remain valid after this rename.
// Executable links and launchers are relative to the installation.
final := filepath.Join(base, candidate.Version+"-"+strings.TrimPrefix(filepath.Base(stage), ".staging-"))
if _, err := os.Lstat(final); err == nil || !os.IsNotExist(err) {
return Installation{}, errors.New("candidate installation target already exists or is inaccessible")
}
if err := os.Rename(stage, final); err != nil {
return Installation{}, err
}
installed := Installation{Version: candidate.Version, Binary: filepath.Join(final, "node_modules", ".bin", spec.Binary), Integrity: candidate.Dist.Integrity, InstalledAt: m.Now().UTC()}
installed := Installation{
Version: candidate.Version, Binary: filepath.Join(final, executable),
Integrity: candidate.identity(), InstalledAt: m.Now().UTC(),
}
if provider == "cursor" {
installed.PublishedAt = &candidate.Published
}
if err := validateInventory(m.Root, Inventory{provider: installed}); err != nil {
return Installation{}, err
}
return installed, nil
}

func (m *Manager) installPackage(ctx context.Context, provider string, spec providerSpec, candidate release, stage string) error {
if err := os.WriteFile(filepath.Join(stage, "package.json"), []byte("{\"private\":true}\n"), 0o600); err != nil {
return err
}
engines := "--engine-strict"
if spec.RelaxEngines {
engines = "--engine-strict=false"
}
args := []string{"install", "--prefix", stage, "--registry", npmRegistry, "--no-audit", "--no-fund", engines, "--ignore-scripts", "--include=optional", "--save-exact", spec.Package + "@" + candidate.Version}
if _, err := m.command(ctx, m.npmBinary, args, stage); err != nil {
return fmt.Errorf("install %s: %w", provider, err)
}
if err := verifyPackageLock(stage, spec.Package, candidate); err != nil {
return err
}
// Some native optional dependencies need lifecycle hooks. Defer them until
// npm has fetched the exact candidate and its SRI has been checked. Commands
// use the updater's isolated home and credential-free environment; they run
// with the worker's OS permissions, not in a separate security sandbox.
rebuild := []string{"rebuild", "--prefix", stage, "--registry", npmRegistry, "--no-audit", "--no-fund"}
if _, err := m.command(ctx, m.npmBinary, rebuild, stage); err != nil {
return fmt.Errorf("build verified CLI dependencies: %w", err)
}
if err := verifyPackageLock(stage, spec.Package, candidate); err != nil {
return err
}
return nil
}

func verifyPackageLock(dir, packageName string, candidate release) error {
var lock struct {
Packages map[string]struct {
Expand Down Expand Up @@ -180,7 +212,7 @@ func verifyPackageLock(dir, packageName string, candidate release) error {
return nil
}

var outputVersion = regexp.MustCompile(`(?:^|[^0-9.])([0-9]+\.[0-9]+\.[0-9]+)(?:$|[^0-9.A-Za-z+-])`)
var outputVersion = regexp.MustCompile(`(?:^|[^0-9.])([0-9]+\.[0-9]+\.[0-9]+(?:-(?:rc\.[0-9]+|[a-f0-9]{7,40}))?)(?:$|[^0-9.A-Za-z+-])`)

func (m *Manager) validate(ctx context.Context, provider string, installed Installation) error {
if err := validateInventory(m.Root, Inventory{provider: installed}); err != nil {
Expand Down
Loading
Loading