fix(agents): add validated managed runtime recovery (#2580)

This commit is contained in:
Carlos Florêncio
2026-08-13 12:14:01 +01:00
committed by GitHub
parent 5dff29d61e
commit 45c9ba5554
72 changed files with 4258 additions and 474 deletions
+1 -1
View File
@@ -7,6 +7,7 @@ require (
github.com/bmatcuk/doublestar/v4 v4.10.0
github.com/coder/acp-go-sdk v0.13.5
github.com/creack/pty v1.1.24
github.com/Masterminds/semver/v3 v3.2.1
github.com/gin-gonic/gin v1.9.1
github.com/godbus/dbus/v5 v5.1.0
github.com/google/uuid v1.6.0
@@ -46,7 +47,6 @@ require (
)
require (
github.com/Masterminds/semver/v3 v3.2.1 // indirect
github.com/Microsoft/go-winio v0.6.2 // indirect
github.com/bahlo/generic-list-go v0.2.0 // indirect
github.com/buger/jsonparser v1.1.2 // indirect
@@ -176,6 +176,9 @@ type CommandOptions struct {
// standalone CLI was found in the execution environment. Such agents emit
// the native binary (e.g. "copilot --acp") instead of "npx -y <pkg>".
PreferNativeBinary bool
// ManagedRuntimeVersion is an internal exact version override for trusted
// managed npm ACP runtimes. Empty preserves the legacy unversioned command.
ManagedRuntimeVersion string
}
// PassthroughOptions are passed to BuildPassthroughCommand.
@@ -107,7 +107,7 @@ func (a *ClaudeACP) IsInstalled(ctx context.Context) (*DiscoveryResult, error) {
}
func (a *ClaudeACP) BuildCommand(opts CommandOptions) Command {
return a.ManagedNPMRuntime().CachedACPCommand()
return a.ManagedNPMRuntime().ACPCommand(opts.ManagedRuntimeVersion)
}
func (a *ClaudeACP) ManagedNPMRuntime() ManagedNPMRuntimeSpec {
@@ -96,7 +96,7 @@ func (a *CodexACP) IsInstalled(ctx context.Context) (*DiscoveryResult, error) {
}
func (a *CodexACP) BuildCommand(opts CommandOptions) Command {
return a.ManagedNPMRuntime().CachedACPCommand()
return a.ManagedNPMRuntime().ACPCommand(opts.ManagedRuntimeVersion)
}
func (a *CodexACP) ManagedNPMRuntime() ManagedNPMRuntimeSpec {
@@ -90,8 +90,8 @@ func (a *CopilotACP) IsInstalled(ctx context.Context) (*DiscoveryResult, error)
// execution environment. See NativeBinaryAgent.
func (a *CopilotACP) NativeBinaryName() string { return copilotNativeBinary }
func (a *CopilotACP) BuildCommand(CommandOptions) Command {
return a.ManagedNPMRuntime().CachedACPCommand()
func (a *CopilotACP) BuildCommand(opts CommandOptions) Command {
return a.ManagedNPMRuntime().ACPCommand(opts.ManagedRuntimeVersion)
}
func (a *CopilotACP) ManagedNPMRuntime() ManagedNPMRuntimeSpec {
+1 -1
View File
@@ -78,7 +78,7 @@ func (a *Gemini) IsInstalled(ctx context.Context) (*DiscoveryResult, error) {
}
func (a *Gemini) BuildCommand(opts CommandOptions) Command {
return a.ManagedNPMRuntime().CachedACPCommand()
return a.ManagedNPMRuntime().ACPCommand(opts.ManagedRuntimeVersion)
}
func (a *Gemini) ManagedNPMRuntime() ManagedNPMRuntimeSpec {
@@ -13,36 +13,56 @@ type ManagedNPMRuntimeSpec struct {
ACPArgs []string
}
// PackageSpec returns the trusted package name or exact package@version spec.
func (s ManagedNPMRuntimeSpec) PackageSpec(version string) string {
if version == "" {
return s.Package
}
return s.Package + "@" + version
}
// ExecutionCacheKey returns npm's deterministic _npx execution-tree key for
// this trusted package spec. npm derives it from the full package string using
// SHA-512 and the first 16 lowercase hexadecimal characters.
func (s ManagedNPMRuntimeSpec) ExecutionCacheKey() string {
digest := sha512.Sum512([]byte(s.Package))
// SHA-512 and the first 16 lowercase hexadecimal characters. The optional
// argument preserves the unversioned legacy key when omitted.
func (s ManagedNPMRuntimeSpec) ExecutionCacheKey(versions ...string) string {
digest := sha512.Sum512([]byte(s.PackageSpec(firstVersion(versions))))
return hex.EncodeToString(digest[:])[:16]
}
// CachedACPCommand returns the normal launch command. The package is
// intentionally unversioned and prefer-offline lets npm reuse a suitable
// execution-cache entry while still fetching when the cache is empty.
func (s ManagedNPMRuntimeSpec) CachedACPCommand() Command {
args := []string{"npx", "--yes", "--prefer-offline", s.Package}
// ACPCommand returns the normal launch command for the exact version when one
// is supplied. An empty version keeps the legacy unversioned behavior.
func (s ManagedNPMRuntimeSpec) ACPCommand(version string) Command {
args := []string{"npx", "--yes", "--prefer-offline", s.PackageSpec(version)}
args = append(args, s.ACPArgs...)
return NewCommand(args...)
}
// CacheUpdateCommand returns the explicit cache-refresh command. npm exec
// installs the built-in unversioned package with online freshness before
// running a no-op under the prepared execution environment.
func (s ManagedNPMRuntimeSpec) CacheUpdateCommand() Command {
// CachedACPCommand returns the legacy unversioned launch command.
func (s ManagedNPMRuntimeSpec) CachedACPCommand() Command {
return s.ACPCommand("")
}
// CacheUpdateCommand returns the explicit cache preparation command. The
// optional version makes npm prepare one deterministic package@version tree.
func (s ManagedNPMRuntimeSpec) CacheUpdateCommand(versions ...string) Command {
packageSpec := s.PackageSpec(firstVersion(versions))
return NewCommand(
"npm",
"exec",
"--yes",
"--prefer-online",
"--package="+s.Package,
"--package="+packageSpec,
"--",
"node",
"-e",
"",
)
}
func firstVersion(versions []string) string {
if len(versions) == 0 {
return ""
}
return versions[0]
}
@@ -59,6 +59,63 @@ func TestManagedNPMRuntimeExecutionCacheKeyMatchesNPM(t *testing.T) {
}
}
func TestManagedNPMRuntimeBuildsExactVersionCommandsAndCacheKey(t *testing.T) {
spec := ManagedNPMRuntimeSpec{
Package: "opencode-ai",
ACPArgs: []string{"acp", "--print-logs"},
}
wantACP := []string{"npx", "--yes", "--prefer-offline", "opencode-ai@1.18.5", "acp", "--print-logs"}
if got := spec.ACPCommand("1.18.5").Args(); !slices.Equal(got, wantACP) {
t.Fatalf("ACPCommand = %#v, want %#v", got, wantACP)
}
wantUpdate := []string{
"npm", "exec", "--yes", "--prefer-online",
"--package=opencode-ai@1.18.5", "--", "node", "-e", "",
}
if got := spec.CacheUpdateCommand("1.18.5").Args(); !slices.Equal(got, wantUpdate) {
t.Fatalf("CacheUpdateCommand = %#v, want %#v", got, wantUpdate)
}
if got := spec.ExecutionCacheKey("1.18.5"); got != "cd439a892fc193b3" {
t.Fatalf("versioned ExecutionCacheKey = %q, want cd439a892fc193b3", got)
}
}
func TestManagedNPMRuntimeExactVersionSupportsScopedPackages(t *testing.T) {
spec := ManagedNPMRuntimeSpec{Package: "@scope/managed-acp", ACPArgs: []string{"--acp"}}
want := []string{"npx", "--yes", "--prefer-offline", "@scope/managed-acp@3.4.5", "--acp"}
if got := spec.ACPCommand("3.4.5").Args(); !slices.Equal(got, want) {
t.Fatalf("scoped ACPCommand = %#v, want %#v", got, want)
}
if spec.ExecutionCacheKey("3.4.5") == spec.ExecutionCacheKey() {
t.Fatal("versioned scoped cache key equals legacy key")
}
}
func TestManagedAgentsHonorExactVersionCommandOption(t *testing.T) {
tests := []struct {
name string
agent ManagedNPMRuntimeAgent
}{
{"claude", NewClaudeACP()},
{"codex", NewCodexACP()},
{"opencode", NewOpenCodeACP()},
{"copilot", NewCopilotACP()},
{"gemini", NewGemini()},
}
for _, tt := range tests {
t.Run(tt.name, func(t *testing.T) {
version := "1.2.3"
want := tt.agent.ManagedNPMRuntime().ACPCommand(version).Args()
got := tt.agent.(interface {
BuildCommand(CommandOptions) Command
}).BuildCommand(CommandOptions{ManagedRuntimeVersion: version}).Args()
if !slices.Equal(got, want) {
t.Fatalf("exact BuildCommand = %#v, want %#v", got, want)
}
})
}
}
func assertUnversionedPackage(t *testing.T, argv []string, wantPackage string) {
t.Helper()
packageArg := argv[3]
@@ -85,7 +85,7 @@ func (a *OpenCodeACP) IsInstalled(ctx context.Context) (*DiscoveryResult, error)
}
func (a *OpenCodeACP) BuildCommand(opts CommandOptions) Command {
return a.ManagedNPMRuntime().CachedACPCommand()
return a.ManagedNPMRuntime().ACPCommand(opts.ManagedRuntimeVersion)
}
func (a *OpenCodeACP) ManagedNPMRuntime() ManagedNPMRuntimeSpec {
@@ -0,0 +1,71 @@
package hostutility
import (
"context"
"errors"
"testing"
"github.com/kandev/kandev/internal/agent/agents"
"github.com/kandev/kandev/internal/agent/managedruntime"
)
type managedRuntimeSelectionReader struct {
selection managedruntime.Selection
found bool
err error
}
func (r managedRuntimeSelectionReader) Get(
context.Context,
string,
string,
) (managedruntime.Selection, bool, error) {
return r.selection, r.found, r.err
}
func TestResolveInferenceCommandUsesActiveExactVersion(t *testing.T) {
manager := &Manager{managedRuntimeSelections: managedRuntimeSelectionReader{
selection: managedruntime.Selection{Package: "opencode-ai", Version: "1.18.5"},
found: true,
}}
agent := agents.NewOpenCodeACP()
command, err := manager.resolveInferenceCommand(context.Background(), agent.ID(), agent, agents.Command{})
if err != nil {
t.Fatalf("resolveInferenceCommand: %v", err)
}
want := agent.ManagedNPMRuntime().ACPCommand("1.18.5").Args()
if got := command.Args(); !equalStrings(got, want) {
t.Fatalf("command = %#v, want %#v", got, want)
}
}
func TestResolveInferenceCommandPreservesLegacyAndReportsSelectionErrors(t *testing.T) {
agent := agents.NewOpenCodeACP()
manager := &Manager{managedRuntimeSelections: managedRuntimeSelectionReader{}}
command, err := manager.resolveInferenceCommand(context.Background(), agent.ID(), agent, agents.Command{})
if err != nil {
t.Fatalf("legacy resolveInferenceCommand: %v", err)
}
if got, want := command.Args(), agent.ManagedNPMRuntime().CachedACPCommand().Args(); !equalStrings(got, want) {
t.Fatalf("legacy command = %#v, want %#v", got, want)
}
wantErr := errors.New("selection read failed")
manager.managedRuntimeSelections = managedRuntimeSelectionReader{err: wantErr}
if _, err := manager.resolveInferenceCommand(context.Background(), agent.ID(), agent, agents.Command{}); !errors.Is(err, wantErr) {
t.Fatalf("selection error = %v, want %v", err, wantErr)
}
}
func equalStrings(left, right []string) bool {
if len(left) != len(right) {
return false
}
for i := range left {
if left[i] != right[i] {
return false
}
}
return true
}
@@ -16,6 +16,7 @@ import (
"golang.org/x/sync/singleflight"
"github.com/kandev/kandev/internal/agent/agents"
"github.com/kandev/kandev/internal/agent/managedruntime"
"github.com/kandev/kandev/internal/agent/registry"
agentctlclient "github.com/kandev/kandev/internal/agent/runtime/agentctl"
settingsmodels "github.com/kandev/kandev/internal/agent/settings/models"
@@ -54,14 +55,15 @@ type Manager struct {
cache *cache
modelCache *modelConfigCache
mu sync.RWMutex
instances map[string]*instance // keyed by agent type
createGroup singleflight.Group
modelGroup singleflight.Group
modelGenerationMu sync.Mutex
modelGenerations map[string]uint64
startCancel context.CancelFunc
stopped bool
mu sync.RWMutex
instances map[string]*instance // keyed by agent type
createGroup singleflight.Group
modelGroup singleflight.Group
modelGenerationMu sync.Mutex
modelGenerations map[string]uint64
managedRuntimeSelections managedruntime.SelectionReader
startCancel context.CancelFunc
stopped bool
}
// SetProfileResolver wires the profile eligibility and launch-policy reader.
@@ -105,6 +107,12 @@ func (m *Manager) SetAuthToken(token string) {
m.authToken = token
}
// SetManagedRuntimeSelectionStore wires the install-wide exact-version
// resolver used by every host-local managed-runtime command path.
func (m *Manager) SetManagedRuntimeSelectionStore(store managedruntime.SelectionReader) {
m.managedRuntimeSelections = store
}
func (m *Manager) SetTemporaryArtifactRegistry(registry *tempartifacts.Registry) {
m.mu.Lock()
defer m.mu.Unlock()
@@ -623,8 +631,12 @@ func (m *Manager) probeWithCommand(
) AgentCapabilities {
probeCtx, cancel := context.WithTimeout(ctx, probeTimeout)
defer cancel()
resolvedCommand, err := m.resolveInferenceCommand(probeCtx, inst.agentType, ia, command)
if err != nil {
return probeFailureCapabilities(inst.agentType, StatusFailed, err.Error(), 0, time.Now())
}
req := buildProbeRequest(inst, ia, refresh, command)
req := buildProbeRequest(inst, ia, refresh, resolvedCommand)
resp, err := inst.client.Probe(probeCtx, req)
now := time.Now()
if err != nil {
@@ -676,6 +688,41 @@ func (m *Manager) probeWithCommand(
return caps
}
// resolveInferenceCommand selects the trusted exact host version for ordinary
// probes and prompts. A non-empty override is reserved for candidate probes.
func (m *Manager) resolveInferenceCommand(
ctx context.Context,
agentType string,
ia agents.InferenceAgent,
override agents.Command,
) (agents.Command, error) {
if !override.IsEmpty() {
return override, nil
}
cfg := ia.InferenceConfig()
if cfg == nil || !cfg.Supported {
return agents.Command{}, errors.New("inference config not available")
}
command := cfg.Command
ag, ok := ia.(agents.Agent)
if !ok || m.managedRuntimeSelections == nil {
return command, nil
}
managed, ok := ag.(agents.ManagedNPMRuntimeAgent)
if !ok {
return command, nil
}
spec := managed.ManagedNPMRuntime()
selection, found, err := m.managedRuntimeSelections.Get(ctx, agentType, spec.Package)
if err != nil {
return agents.Command{}, fmt.Errorf("resolve active managed runtime version for %s: %w", agentType, err)
}
if !found || selection.Package != spec.Package {
return command, nil
}
return spec.ACPCommand(selection.Version), nil
}
const modelConfigResolveTimeout = 60 * time.Second
func buildProbeRequest(
@@ -47,6 +47,10 @@ func (m *Manager) ExecuteProfilePrompt(ctx context.Context, profileID, prompt st
return nil, err
}
cfg := ia.InferenceConfig()
command, err := m.resolveInferenceCommand(ctx, profile.AgentID, ia, agents.Command{})
if err != nil {
return nil, err
}
resolved := m.resolveModel(profile.AgentID, profile.Model, ia)
autoApprove := profile.AutoApprove
req := &agentctlutil.PromptRequest{
@@ -56,7 +60,7 @@ func (m *Manager) ExecuteProfilePrompt(ctx context.Context, profileID, prompt st
Mode: profile.Mode,
AutoApprovePermissions: &autoApprove,
InferenceConfig: &agentctlutil.InferenceConfigDTO{
Command: cfg.Command.Args(), ModelFlag: cfg.ModelFlag.Args(), WorkDir: inst.workDir,
Command: command.Args(), ModelFlag: cfg.ModelFlag.Args(), WorkDir: inst.workDir,
Env: env, StripEnv: agents.StripEnvFor(ia), CLIFlags: cliFlags, CommandPrefix: prefix,
},
}
@@ -171,8 +175,12 @@ func (m *Manager) resolveModelConfigFlight(
if cfg == nil || !cfg.Supported {
return nil, errors.New("inference config not available")
}
command, err := m.resolveInferenceCommand(probeCtx, agentType, ia, agents.Command{})
if err != nil {
return nil, err
}
probeReq := buildProbeRequest(inst, ia, req.Refresh, agents.Command{})
probeReq := buildProbeRequest(inst, ia, req.Refresh, command)
probeReq.Model = req.Model
probeReq.Mode = req.Mode
probeReq.ConfigOptions = cloneStringMap(req.ConfigOptions)
@@ -240,6 +248,23 @@ func (m *Manager) RefreshWithCommand(
ctx context.Context,
agentType string,
command agents.Command,
) (AgentCapabilities, error) {
caps, err := m.ProbeWithCommand(ctx, agentType, command)
if err != nil {
return AgentCapabilities{}, err
}
if caps.Status == StatusOK {
m.PublishCapabilities(agentType, caps)
}
return caps, nil
}
// ProbeWithCommand runs a trusted command override without changing the live
// capability cache. Runtime activation uses this boundary before persistence.
func (m *Manager) ProbeWithCommand(
ctx context.Context,
agentType string,
command agents.Command,
) (AgentCapabilities, error) {
m.invalidateModelConfigCache(agentType)
inst, ia, err := m.getInstance(ctx, agentType)
@@ -247,12 +272,19 @@ func (m *Manager) RefreshWithCommand(
return AgentCapabilities{}, err
}
caps := m.probeWithCommand(ctx, inst, ia, true, command)
if caps.Status == StatusOK {
m.cache.set(caps)
}
return caps, nil
}
// PublishCapabilities makes a successful candidate the live catalogue. The
// caller is responsible for persisting the active selection first.
func (m *Manager) PublishCapabilities(agentType string, caps AgentCapabilities) {
if caps.Status != StatusOK {
return
}
m.invalidateModelConfigCache(agentType)
m.cache.set(caps)
}
// ExecutePrompt runs a sessionless utility prompt against the warm instance
// for the given agent type. Convenience wrapper over ExecutePromptWithMCP
// that opts the call out of MCP tool access — most callers (PR title, commit
@@ -281,6 +313,10 @@ func (m *Manager) ExecutePromptWithMCP(
return nil, err
}
cfg := ia.InferenceConfig()
command, err := m.resolveInferenceCommand(ctx, agentType, ia, agents.Command{})
if err != nil {
return nil, err
}
resolved := m.resolveModel(agentType, model, ia)
@@ -290,7 +326,7 @@ func (m *Manager) ExecutePromptWithMCP(
Model: resolved,
Mode: mode,
InferenceConfig: &agentctlutil.InferenceConfigDTO{
Command: cfg.Command.Args(),
Command: command.Args(),
ModelFlag: cfg.ModelFlag.Args(),
WorkDir: inst.workDir,
Env: agents.RuntimeEnvFor(ia),
@@ -0,0 +1,102 @@
package managedruntime
import (
"context"
"encoding/json"
"errors"
"fmt"
"strings"
)
var (
ErrInvalidSelection = errors.New("invalid managed runtime selection")
errSettingsMissing = errors.New("managed runtime settings store is unavailable")
)
const selectionKeyPrefix = "managed_runtime.active."
// SettingsStore is the small persistence seam required by the install-wide
// managed-runtime selection store.
type SettingsStore interface {
Get(context.Context, string) ([]byte, bool, error)
Save(context.Context, string, []byte) error
}
// SelectionStore is the runtime-facing seam for reading and persisting an
// active managed-runtime selection.
type SelectionStore interface {
Get(context.Context, string, string) (Selection, bool, error)
Save(context.Context, string, string, string) error
}
// SelectionReader is the read-only seam used by runtime command builders.
type SelectionReader interface {
Get(context.Context, string, string) (Selection, bool, error)
}
// Selection is the trusted package identity and exact active version for one
// built-in agent.
type Selection struct {
Package string `json:"package"`
Version string `json:"version"`
}
type Store struct {
settings SettingsStore
}
// NewStore creates the install-wide active-version store.
func NewStore(settings SettingsStore) *Store {
return &Store{settings: settings}
}
// Get returns the selection only when it belongs to the package currently
// trusted for the agent. A package replacement therefore starts unselected.
func (s *Store) Get(ctx context.Context, agentID, packageName string) (Selection, bool, error) {
if s == nil || s.settings == nil {
return Selection{}, false, errSettingsMissing
}
if agentID == "" || packageName == "" {
return Selection{}, false, fmt.Errorf("%w: agent and package are required", ErrInvalidSelection)
}
raw, found, err := s.settings.Get(ctx, selectionKey(agentID))
if err != nil || !found {
return Selection{}, found, err
}
var selection Selection
if err := json.Unmarshal(raw, &selection); err != nil {
return Selection{}, false, fmt.Errorf("%w: decode: %v", ErrInvalidSelection, err)
}
if selection.Package != packageName {
return Selection{}, false, nil
}
if selection.Version == "" {
return Selection{}, false, fmt.Errorf("%w: version is empty", ErrInvalidSelection)
}
if _, err := ParseStableVersion(selection.Version); err != nil {
return Selection{}, false, fmt.Errorf("%w: %v", ErrInvalidSelection, err)
}
return selection, true, nil
}
// Save persists a validated exact version for one trusted package.
func (s *Store) Save(ctx context.Context, agentID, packageName, version string) error {
if s == nil || s.settings == nil {
return errSettingsMissing
}
if agentID == "" || packageName == "" {
return fmt.Errorf("%w: agent and package are required", ErrInvalidSelection)
}
if _, err := ParseStableVersion(version); err != nil {
return fmt.Errorf("%w: %v", ErrInvalidSelection, err)
}
raw, err := json.Marshal(Selection{Package: packageName, Version: version})
if err != nil {
return fmt.Errorf("marshal managed runtime selection: %w", err)
}
return s.settings.Save(ctx, selectionKey(agentID), raw)
}
func selectionKey(agentID string) string {
return selectionKeyPrefix + strings.TrimSpace(agentID)
}
@@ -0,0 +1,82 @@
package managedruntime
import (
"context"
"errors"
"testing"
)
type memorySettings struct {
values map[string][]byte
err error
}
func (s *memorySettings) Get(_ context.Context, key string) ([]byte, bool, error) {
if s.err != nil {
return nil, false, s.err
}
value, ok := s.values[key]
return append([]byte(nil), value...), ok, nil
}
func (s *memorySettings) Save(_ context.Context, key string, value []byte) error {
if s.err != nil {
return s.err
}
if s.values == nil {
s.values = make(map[string][]byte)
}
s.values[key] = append([]byte(nil), value...)
return nil
}
func TestStoreRoundTripAndPerAgentIsolation(t *testing.T) {
settings := &memorySettings{}
store := NewStore(settings)
ctx := context.Background()
if _, found, err := store.Get(ctx, "opencode-acp", "opencode-ai"); err != nil || found {
t.Fatalf("missing selection = found %v, err %v", found, err)
}
if err := store.Save(ctx, "opencode-acp", "opencode-ai", "1.18.5"); err != nil {
t.Fatalf("save opencode: %v", err)
}
if err := store.Save(ctx, "claude-acp", "@example/claude", "2.0.0"); err != nil {
t.Fatalf("save claude: %v", err)
}
got, found, err := store.Get(ctx, "opencode-acp", "opencode-ai")
if err != nil || !found || got.Package != "opencode-ai" || got.Version != "1.18.5" {
t.Fatalf("opencode selection = %#v, found %v, err %v", got, found, err)
}
got, found, err = store.Get(ctx, "claude-acp", "@example/claude")
if err != nil || !found || got.Version != "2.0.0" {
t.Fatalf("claude selection = %#v, found %v, err %v", got, found, err)
}
}
func TestStoreRejectsInvalidStoredValueAndPackageMismatch(t *testing.T) {
settings := &memorySettings{values: map[string][]byte{
selectionKey("opencode-acp"): []byte(`{"package":"opencode-ai","version":"latest"}`),
selectionKey("claude-acp"): []byte(`{"package":"old-claude","version":"1.0.0"}`),
}}
store := NewStore(settings)
if _, _, err := store.Get(context.Background(), "opencode-acp", "opencode-ai"); !errors.Is(err, ErrInvalidSelection) {
t.Fatalf("invalid stored selection error = %v, want %v", err, ErrInvalidSelection)
}
if _, found, err := store.Get(context.Background(), "claude-acp", "@example/claude"); err != nil || found {
t.Fatalf("package mismatch = found %v, err %v; want no selection", found, err)
}
}
func TestStorePropagatesSettingsErrors(t *testing.T) {
wantErr := errors.New("settings unavailable")
store := NewStore(&memorySettings{err: wantErr})
if _, _, err := store.Get(context.Background(), "opencode-acp", "opencode-ai"); !errors.Is(err, wantErr) {
t.Fatalf("get error = %v, want %v", err, wantErr)
}
if err := store.Save(context.Background(), "opencode-acp", "opencode-ai", "1.18.5"); !errors.Is(err, wantErr) {
t.Fatalf("save error = %v, want %v", err, wantErr)
}
}
@@ -0,0 +1,220 @@
package managedruntime
import (
"errors"
"fmt"
"regexp"
"sort"
"strings"
"github.com/Masterminds/semver/v3"
)
var ErrInvalidStableVersion = errors.New("invalid stable semver")
var ErrNoStableVersions = errors.New("no stable runtime versions available")
// Operation is the backend-derived action for a managed runtime target.
type Operation string
const (
OperationUpdate Operation = "update"
OperationRollback Operation = "rollback"
OperationRepair Operation = "repair"
OperationUpToDate Operation = "up_to_date"
)
// VersionOption is one selectable version in the bounded catalogue.
type VersionOption struct {
Version string `json:"version"`
Latest bool `json:"latest"`
}
// Catalogue contains the bounded UI projection and the complete stable set
// used to authorize a submitted target.
type Catalogue struct {
Versions []VersionOption
Latest string
all map[string]struct{}
}
var stableVersionPattern = regexp.MustCompile(
`^(0|[1-9][0-9]*)\.(0|[1-9][0-9]*)\.(0|[1-9][0-9]*)(\+[0-9A-Za-z-]+(\.[0-9A-Za-z-]+)*)?$`,
)
// ParseStableVersion accepts only strict, prerelease-free SemVer values.
func ParseStableVersion(value string) (*semver.Version, error) {
if !stableVersionPattern.MatchString(value) {
return nil, fmt.Errorf("%w: %q", ErrInvalidStableVersion, value)
}
parsed, err := semver.NewVersion(value)
if err != nil {
return nil, fmt.Errorf("%w: %q: %v", ErrInvalidStableVersion, value, err)
}
if parsed.Prerelease() != "" {
return nil, fmt.Errorf("%w: prerelease %q", ErrInvalidStableVersion, value)
}
return parsed, nil
}
// SortStableVersions validates, deduplicates, and sorts versions newest first.
func SortStableVersions(values []string) ([]string, error) {
type parsedVersion struct {
value string
parsed *semver.Version
}
unique := make(map[string]parsedVersion, len(values))
for _, value := range values {
parsed, err := ParseStableVersion(value)
if err != nil {
return nil, err
}
unique[value] = parsedVersion{value: value, parsed: parsed}
}
versions := make([]parsedVersion, 0, len(unique))
for _, version := range unique {
versions = append(versions, version)
}
sort.Slice(versions, func(i, j int) bool {
compare := versions[i].parsed.Compare(versions[j].parsed)
if compare == 0 {
return versions[i].value > versions[j].value
}
return compare > 0
})
out := make([]string, len(versions))
for i, version := range versions {
out[i] = version.value
}
return out, nil
}
// BuildCatalogue filters npm metadata to strict stable versions, orders it
// newest first, and keeps the newest 50 plus any active/current extras. The
// complete stable set remains private so callers can validate targets that
// are outside the bounded UI projection.
func BuildCatalogue(published []string, latest string, extras ...string) (Catalogue, error) {
stable, seen := filterStableVersions(published)
if len(stable) == 0 {
return Catalogue{}, ErrNoStableVersions
}
ordered, err := SortStableVersions(stable)
if err != nil {
return Catalogue{}, err
}
latest = normalizedLatest(latest, ordered, seen)
visibleValues := visibleCatalogueVersions(ordered, seen, extras...)
visibleValues, err = SortStableVersions(visibleValues)
if err != nil {
return Catalogue{}, err
}
options := make([]VersionOption, 0, len(visibleValues))
for _, value := range visibleValues {
options = append(options, VersionOption{Version: value, Latest: value == latest})
}
return Catalogue{Versions: options, Latest: latest, all: seen}, nil
}
func filterStableVersions(values []string) ([]string, map[string]struct{}) {
stable := make([]string, 0, len(values))
seen := make(map[string]struct{}, len(values))
for _, value := range values {
if _, err := ParseStableVersion(value); err != nil {
continue
}
if _, exists := seen[value]; exists {
continue
}
seen[value] = struct{}{}
stable = append(stable, value)
}
return stable, seen
}
func normalizedLatest(latest string, ordered []string, published map[string]struct{}) string {
latest = strings.TrimSpace(latest)
if _, err := ParseStableVersion(latest); err != nil {
return ordered[0]
}
if _, exists := published[latest]; !exists {
return ordered[0]
}
return latest
}
func visibleCatalogueVersions(
ordered []string,
published map[string]struct{},
extras ...string,
) []string {
visible := make(map[string]struct{}, 50+len(extras))
for _, value := range ordered {
if len(visible) >= 50 {
break
}
visible[value] = struct{}{}
}
for _, value := range extras {
if _, err := ParseStableVersion(value); err != nil {
continue
}
if _, exists := published[value]; exists {
visible[value] = struct{}{}
}
}
values := make([]string, 0, len(visible))
for value := range visible {
values = append(values, value)
}
return values
}
// Has reports whether version is one of the published stable versions.
func (c Catalogue) Has(version string) bool {
if _, err := ParseStableVersion(version); err != nil {
return false
}
_, ok := c.all[version]
return ok
}
// ClassifyOperation derives the operator-facing action. Empty or malformed
// observed values are treated as unknown and therefore require repair.
func ClassifyOperation(active, current, target string) (Operation, error) {
targetVersion, err := ParseStableVersion(target)
if err != nil {
return "", err
}
activeVersion, activeOK := parseKnownVersion(active)
currentVersion, currentOK := parseKnownVersion(current)
if activeOK && currentOK && active == target && current == target {
return OperationUpToDate, nil
}
if !currentOK {
return OperationRepair, nil
}
baseValue := current
baseVersion := currentVersion
if activeOK {
baseValue = active
baseVersion = activeVersion
}
if target == baseValue {
return OperationRepair, nil
}
compare := targetVersion.Compare(baseVersion)
if compare > 0 {
return OperationUpdate, nil
}
if compare < 0 {
return OperationRollback, nil
}
return OperationRepair, nil
}
func parseKnownVersion(value string) (*semver.Version, bool) {
if value == "" {
return nil, false
}
parsed, err := ParseStableVersion(value)
return parsed, err == nil
}
@@ -0,0 +1,93 @@
package managedruntime
import (
"fmt"
"slices"
"testing"
)
func TestParseStableVersion(t *testing.T) {
for _, value := range []string{"1.2.3", "0.0.1", "10.20.30+build.7"} {
if _, err := ParseStableVersion(value); err != nil {
t.Errorf("ParseStableVersion(%q) = %v, want nil", value, err)
}
}
for _, value := range []string{
"1.2", "1.2.3-beta.1", "v1.2.3", "latest", "@scope/pkg@1.2.3", "1.2.3 ", "01.2.3",
} {
if _, err := ParseStableVersion(value); err == nil {
t.Errorf("ParseStableVersion(%q) = nil error, want rejection", value)
}
}
}
func TestSortStableVersionsDeduplicatesDescending(t *testing.T) {
got, err := SortStableVersions([]string{"1.2.0", "2.0.0", "1.10.0", "2.0.0", "1.2.0"})
if err != nil {
t.Fatalf("SortStableVersions: %v", err)
}
want := []string{"2.0.0", "1.10.0", "1.2.0"}
if !slices.Equal(got, want) {
t.Fatalf("sorted versions = %#v, want %#v", got, want)
}
}
func TestBuildCatalogueFiltersBoundsAndRetainsExtras(t *testing.T) {
published := make([]string, 0, 54)
for minor := 0; minor < 52; minor++ {
published = append(published, fmt.Sprintf("1.0.%d", minor))
}
published = append(published, "1.0.99-beta.1", "latest", "1.0.1")
catalogue, err := BuildCatalogue(published, "1.0.50", "1.0.0")
if err != nil {
t.Fatalf("BuildCatalogue: %v", err)
}
if len(catalogue.Versions) != 51 {
t.Fatalf("visible versions = %d, want 51", len(catalogue.Versions))
}
if catalogue.Versions[0].Version != "1.0.51" || catalogue.Versions[0].Latest {
t.Fatalf("first option = %#v", catalogue.Versions[0])
}
if catalogue.Latest != "1.0.50" {
t.Fatalf("latest = %q", catalogue.Latest)
}
if !catalogue.Has("1.0.0") || catalogue.Has("1.0.99-beta.1") || catalogue.Has("latest") {
t.Fatal("catalogue target membership is incorrect")
}
latestFound := false
for _, option := range catalogue.Versions {
if option.Version == "1.0.50" {
latestFound = option.Latest
}
}
if !latestFound {
t.Fatal("latest marker missing")
}
}
func TestClassifyOperation(t *testing.T) {
tests := []struct {
name string
active, current, target string
want Operation
}{
{name: "update", active: "1.0.1", current: "1.0.1", target: "1.0.2", want: OperationUpdate},
{name: "rollback", active: "1.0.3", current: "1.0.3", target: "1.0.2", want: OperationRollback},
{name: "repair unknown", active: "", current: "", target: "1.0.2", want: OperationRepair},
{name: "repair inactive current", active: "", current: "1.0.2", target: "1.0.2", want: OperationRepair},
{name: "up to date", active: "1.0.2", current: "1.0.2", target: "1.0.2", want: OperationUpToDate},
{name: "repair active drift", active: "1.0.3", current: "1.0.2", target: "1.0.3", want: OperationRepair},
}
for _, test := range tests {
t.Run(test.name, func(t *testing.T) {
got, err := ClassifyOperation(test.active, test.current, test.target)
if err != nil {
t.Fatalf("ClassifyOperation: %v", err)
}
if got != test.want {
t.Fatalf("operation = %q, want %q", got, test.want)
}
})
}
}
@@ -9,6 +9,7 @@ import (
"github.com/kandev/kandev/internal/agent/agents"
"github.com/kandev/kandev/internal/agent/runtime/routingerr"
agentruntime "github.com/kandev/kandev/internal/agentruntime"
"github.com/kandev/kandev/internal/common/logger"
"go.uber.org/zap"
)
@@ -90,23 +91,8 @@ func validateMockProviders(reg *Registry, raw string, log *logger.Logger) {
// HTTP /routing/retry endpoint can flip a degraded provider back to
// healthy without waiting for the next real launch.
func registerRealProvidersProber(reg *Registry, log *logger.Logger) {
resolver := func(providerID string) ([]string, map[string]string, bool) {
ag, ok := reg.Get(providerID)
if !ok || !ag.Enabled() {
return nil, nil, false
}
cmd := ag.BuildCommand(agents.CommandOptions{})
if cmd.IsEmpty() {
return nil, nil, false
}
var env map[string]string
if rt := ag.Runtime(); rt != nil && len(rt.Env) > 0 {
env = make(map[string]string, len(rt.Env))
for k, v := range rt.Env {
env[k] = v
}
}
return cmd.Args(), env, true
resolver := func(ctx context.Context, providerID string) ([]string, map[string]string, bool) {
return reg.resolveProviderCommand(ctx, providerID)
}
probe := routingerr.NewACPProbe(resolver, log)
for _, id := range RoutableProviderIDs {
@@ -122,6 +108,64 @@ func registerRealProvidersProber(reg *Registry, log *logger.Logger) {
}
}
// resolveProviderCommand builds the host command used by a recovery probe.
// Managed agents must use the same persisted selection as ordinary host
// launches. A selection read failure therefore returns no command instead of
// silently probing the unversioned package.
func (r *Registry) resolveProviderCommand(
ctx context.Context,
providerID string,
) ([]string, map[string]string, bool) {
ag, ok := r.Get(providerID)
if !ok || !ag.Enabled() {
return nil, nil, false
}
managedRuntimeVersion, ok := r.resolveManagedProviderVersion(ctx, providerID, ag)
if !ok {
return nil, nil, false
}
opts := agents.CommandOptions{
Runtime: agentruntime.RuntimeStandalone,
ManagedRuntimeVersion: managedRuntimeVersion,
}
cmd := ag.BuildCommand(opts)
if cmd.IsEmpty() {
return nil, nil, false
}
var env map[string]string
if rt := ag.Runtime(); rt != nil && len(rt.Env) > 0 {
env = make(map[string]string, len(rt.Env))
for k, v := range rt.Env {
env[k] = v
}
}
return cmd.Args(), env, true
}
func (r *Registry) resolveManagedProviderVersion(
ctx context.Context,
providerID string,
ag agents.Agent,
) (string, bool) {
managed, ok := ag.(agents.ManagedNPMRuntimeAgent)
if !ok {
return "", true
}
selectionStore := r.managedRuntimeSelectionReader()
if selectionStore == nil {
return "", false
}
spec := managed.ManagedNPMRuntime()
selection, found, err := selectionStore.Get(ctx, providerID, spec.Package)
if err != nil || !found {
return "", err == nil
}
if selection.Package != spec.Package || selection.Version == "" {
return "", false
}
return selection.Version, true
}
// registerExtraMockProviders parses the supplied comma-separated list
// of provider IDs and registers each accepted entry as a MockAgent
// alias under that canonical provider ID.
@@ -1,12 +1,45 @@
package registry
import (
"context"
"errors"
"os"
"testing"
"github.com/kandev/kandev/internal/agent/agents"
"github.com/kandev/kandev/internal/agent/managedruntime"
agentruntime "github.com/kandev/kandev/internal/agentruntime"
)
type recordingManagedProviderAgent struct {
agents.Agent
selection agents.ManagedNPMRuntimeSpec
opts agents.CommandOptions
}
func (a *recordingManagedProviderAgent) BuildCommand(opts agents.CommandOptions) agents.Command {
a.opts = opts
return a.selection.ACPCommand(opts.ManagedRuntimeVersion)
}
func (a *recordingManagedProviderAgent) ManagedNPMRuntime() agents.ManagedNPMRuntimeSpec {
return a.selection
}
type providerSelectionReader struct {
selection managedruntime.Selection
found bool
err error
}
func (s providerSelectionReader) Get(
context.Context,
string,
string,
) (managedruntime.Selection, bool, error) {
return s.selection, s.found, s.err
}
func TestProvide_MockAgentModes(t *testing.T) {
tests := []struct {
name string
@@ -87,6 +120,52 @@ func TestProvide_MockAgentModes(t *testing.T) {
}
}
func TestResolveProviderCommandUsesActiveManagedRuntimeVersion(t *testing.T) {
log := newTestLogger()
reg := NewRegistry(log)
agent := &recordingManagedProviderAgent{
Agent: agents.NewOpenCodeACP(),
selection: agents.NewOpenCodeACP().ManagedNPMRuntime(),
}
if err := reg.Register(agent); err != nil {
t.Fatalf("Register: %v", err)
}
reg.SetManagedRuntimeSelectionStore(providerSelectionReader{
selection: managedruntime.Selection{Package: "opencode-ai", Version: "1.18.5"},
found: true,
})
args, _, ok := reg.resolveProviderCommand(context.Background(), agent.ID())
if !ok {
t.Fatal("resolveProviderCommand returned !ok")
}
if got := args[3]; got != "opencode-ai@1.18.5" {
t.Fatalf("package arg = %q, want exact active version", got)
}
if agent.opts.Runtime != agentruntime.RuntimeStandalone {
t.Fatalf("runtime = %q, want standalone", agent.opts.Runtime)
}
}
func TestResolveProviderCommandFailsClosedOnSelectionReadError(t *testing.T) {
log := newTestLogger()
reg := NewRegistry(log)
agent := &recordingManagedProviderAgent{
Agent: agents.NewOpenCodeACP(),
selection: agents.NewOpenCodeACP().ManagedNPMRuntime(),
}
if err := reg.Register(agent); err != nil {
t.Fatalf("Register: %v", err)
}
wantErr := errors.New("selection unavailable")
reg.SetManagedRuntimeSelectionStore(providerSelectionReader{err: wantErr})
args, _, ok := reg.resolveProviderCommand(context.Background(), agent.ID())
if ok || args != nil {
t.Fatalf("resolveProviderCommand = (%v, ..., %v), want fail closed", args, ok)
}
}
// TestProvide_MockProviders_RegistersExtraAliases ensures that when
// KANDEV_MOCK_AGENT=only and KANDEV_MOCK_PROVIDERS lists canonical
// routing provider IDs, each accepted ID is registered as an extra
@@ -12,6 +12,7 @@ import (
"go.uber.org/zap"
"github.com/kandev/kandev/internal/agent/agents"
"github.com/kandev/kandev/internal/agent/managedruntime"
"github.com/kandev/kandev/internal/common/logger"
v1 "github.com/kandev/kandev/pkg/api/v1"
)
@@ -33,6 +34,23 @@ type Registry struct {
loaded bool
mu sync.RWMutex
logger *logger.Logger
// managedRuntimeSelections supplies exact versions to host-local provider
// recovery probes. It is wired after the settings store is available.
managedRuntimeSelections managedruntime.SelectionReader
}
// SetManagedRuntimeSelectionStore wires the install-wide exact-version reader
// used by host-local managed-runtime recovery probes.
func (r *Registry) SetManagedRuntimeSelectionStore(store managedruntime.SelectionReader) {
r.mu.Lock()
defer r.mu.Unlock()
r.managedRuntimeSelections = store
}
func (r *Registry) managedRuntimeSelectionReader() managedruntime.SelectionReader {
r.mu.RLock()
defer r.mu.RUnlock()
return r.managedRuntimeSelections
}
// NewRegistry creates a new agent registry
@@ -0,0 +1,145 @@
package lifecycle
import (
"context"
"errors"
"strings"
"testing"
"github.com/kandev/kandev/internal/agent/agents"
"github.com/kandev/kandev/internal/agent/managedruntime"
agentruntime "github.com/kandev/kandev/internal/agentruntime"
"github.com/kandev/kandev/internal/task/models"
)
type managedRuntimeSelectionStore struct {
selection managedruntime.Selection
found bool
err error
}
func (s managedRuntimeSelectionStore) Get(
context.Context,
string,
string,
) (managedruntime.Selection, bool, error) {
return s.selection, s.found, s.err
}
func (s managedRuntimeSelectionStore) Save(context.Context, string, string, string) error {
return nil
}
func TestBuildAgentCommandUsesExactVersionOnlyOnStandalone(t *testing.T) {
log := newTestLogger()
manager := &Manager{commandBuilder: NewCommandBuilder(), logger: log}
manager.SetManagedRuntimeSelectionStore(managedRuntimeSelectionStore{
selection: managedruntime.Selection{Package: "opencode-ai", Version: "1.18.5"},
found: true,
})
agent := agents.NewOpenCodeACP()
tests := []struct {
name string
executorType models.ExecutorType
wantVersion bool
}{
{name: "standalone", executorType: models.ExecutorTypeLocal, wantVersion: true},
{name: "worktree", executorType: models.ExecutorTypeWorktree, wantVersion: true},
{name: "docker", executorType: models.ExecutorTypeLocalDocker},
{name: "ssh", executorType: models.ExecutorTypeSSH},
}
for _, tt := range tests {
t.Run(tt.name, func(t *testing.T) {
cmds, err := manager.buildAgentCommandWithContext(
context.Background(),
&LaunchRequest{ExecutorType: string(tt.executorType)},
nil,
agent,
false,
)
if err != nil {
t.Fatalf("buildAgentCommandWithContext: %v", err)
}
hasVersion := strings.Contains(cmds.initial, "opencode-ai@1.18.5")
if hasVersion != tt.wantVersion {
t.Fatalf("command = %q, version present = %v, want %v", cmds.initial, hasVersion, tt.wantVersion)
}
})
}
}
func TestBuildAgentCommandFailsWhenActiveSelectionCannotBeRead(t *testing.T) {
manager := &Manager{commandBuilder: NewCommandBuilder(), logger: newTestLogger()}
wantErr := errors.New("selection unavailable")
manager.SetManagedRuntimeSelectionStore(managedRuntimeSelectionStore{err: wantErr})
_, err := manager.buildAgentCommandWithContext(
context.Background(),
&LaunchRequest{ExecutorType: string(models.ExecutorTypeLocal)},
nil,
agents.NewOpenCodeACP(),
false,
)
if !errors.Is(err, wantErr) {
t.Fatalf("selection error = %v, want %v", err, wantErr)
}
}
func TestBuildFreshAgentCommandUsesExactVersionForStandaloneRestart(t *testing.T) {
manager := &Manager{commandBuilder: NewCommandBuilder(), logger: newTestLogger()}
manager.SetManagedRuntimeSelectionStore(managedRuntimeSelectionStore{
selection: managedruntime.Selection{Package: "opencode-ai", Version: "1.18.5"},
found: true,
})
commands, err := manager.buildFreshAgentCommand(
context.Background(),
&AgentExecution{RuntimeName: agentruntime.RuntimeStandalone},
agents.NewOpenCodeACP(),
)
if err != nil {
t.Fatalf("buildFreshAgentCommand: %v", err)
}
if !strings.Contains(commands.initial, "opencode-ai@1.18.5") {
t.Fatalf("restart command = %q, want exact selected version", commands.initial)
}
}
func TestBuildFreshAgentCommandFailsWhenStandaloneSelectionCannotBeRead(t *testing.T) {
manager := &Manager{commandBuilder: NewCommandBuilder(), logger: newTestLogger()}
wantErr := errors.New("selection unavailable")
manager.SetManagedRuntimeSelectionStore(managedRuntimeSelectionStore{err: wantErr})
_, err := manager.buildFreshAgentCommand(
context.Background(),
&AgentExecution{RuntimeName: agentruntime.RuntimeStandalone},
agents.NewOpenCodeACP(),
)
if !errors.Is(err, wantErr) {
t.Fatalf("selection error = %v, want %v", err, wantErr)
}
}
func TestBuildFreshAgentCommandLeavesRemoteCommandUnversioned(t *testing.T) {
manager := &Manager{commandBuilder: NewCommandBuilder(), logger: newTestLogger()}
manager.SetManagedRuntimeSelectionStore(managedRuntimeSelectionStore{
selection: managedruntime.Selection{Package: "opencode-ai", Version: "1.18.5"},
found: true,
})
commands, err := manager.buildFreshAgentCommand(
context.Background(),
&AgentExecution{RuntimeName: agentruntime.RuntimeSSH},
agents.NewOpenCodeACP(),
)
if err != nil {
t.Fatalf("buildFreshAgentCommand: %v", err)
}
if strings.Contains(commands.initial, "opencode-ai@1.18.5") {
t.Fatalf("remote restart command = %q, must not use host selection", commands.initial)
}
if !strings.Contains(commands.initial, "opencode-ai") {
t.Fatalf("remote restart command = %q, want managed runtime command", commands.initial)
}
}
@@ -13,6 +13,7 @@ import (
"github.com/kandev/kandev/internal/agent/docker"
"github.com/kandev/kandev/internal/agent/executor"
"github.com/kandev/kandev/internal/agent/managedruntime"
"github.com/kandev/kandev/internal/agent/registry"
"github.com/kandev/kandev/internal/agent/runtime/activity"
agentctl "github.com/kandev/kandev/internal/agent/runtime/agentctl"
@@ -159,6 +160,9 @@ type Manager struct {
// managedGoCache provides the opt-in GOCACHE for host-local executions.
// System storage wiring installs it after settings persistence is ready.
managedGoCache ManagedGoCacheEnvironmentProvider
// managedRuntimeSelections supplies exact versions for host-local managed
// npm runtimes. Remote/container runtimes intentionally do not consult it.
managedRuntimeSelections managedruntime.SelectionReader
activityCoordinator *activity.Coordinator
activityMu sync.Mutex
@@ -179,6 +183,12 @@ func (m *Manager) SetManagedGoCacheEnvironmentProvider(provider ManagedGoCacheEn
m.managedGoCache = provider
}
// SetManagedRuntimeSelectionStore wires the install-wide exact-version
// resolver used by standalone managed-agent launches.
func (m *Manager) SetManagedRuntimeSelectionStore(store managedruntime.SelectionReader) {
m.managedRuntimeSelections = store
}
// SetActivityCoordinator wires the install-wide host-resource activity gate.
// It is optional so embedded and test configurations retain legacy behavior.
func (m *Manager) SetActivityCoordinator(coordinator *activity.Coordinator) {
@@ -1739,6 +1739,10 @@ func (m *Manager) buildFreshAgentCommand(ctx context.Context, execution *AgentEx
if err != nil {
return agentCommands{}, err
}
managedRuntimeVersion, err := m.resolveManagedRuntimeVersion(ctx, execution.RuntimeName, agentConfig)
if err != nil {
return agentCommands{}, err
}
opts := agents.CommandOptions{
Model: model,
@@ -1750,7 +1754,8 @@ func (m *Manager) buildFreshAgentCommand(ctx context.Context, execution *AgentEx
// Runtime is "standalone" / "docker" / "sprites" — MockAgent
// reads this to pick a bare name (container PATH lookup) vs.
// an absolute host path.
Runtime: execution.RuntimeName,
Runtime: execution.RuntimeName,
ManagedRuntimeVersion: managedRuntimeVersion,
}
args := m.commandBuilder.BuildCommandArgs(agentConfig, opts)
continueArgs := m.commandBuilder.BuildContinueCommandArgs(agentConfig, opts)
@@ -17,6 +17,7 @@ import (
"github.com/kandev/kandev/internal/agent/executor"
"github.com/kandev/kandev/internal/agent/runtime/activity"
"github.com/kandev/kandev/internal/agent/settings/cliflags"
"github.com/kandev/kandev/internal/agentruntime"
"github.com/kandev/kandev/internal/common/subproc"
"github.com/kandev/kandev/internal/events"
"github.com/kandev/kandev/internal/gitconfigenv"
@@ -311,11 +312,13 @@ func (m *Manager) resolveProfileLaunchTokens(profileInfo *AgentProfileInfo) (cli
return cliFlagTokens, commandPrefixTokens, nil
}
// buildAgentCommand builds the agent command strings for the execution.
// Returns both the initial command and the continue command (for one-shot agents like Amp).
// Returns an error when a configured command_prefix cannot be resolved, so a
// configured profile fails closed instead of launching unwrapped.
func (m *Manager) buildAgentCommand(req *LaunchRequest, profileInfo *AgentProfileInfo, agentConfig agents.Agent, preferNative bool) (agentCommands, error) {
func (m *Manager) buildAgentCommandWithContext(
ctx context.Context,
req *LaunchRequest,
profileInfo *AgentProfileInfo,
agentConfig agents.Agent,
preferNative bool,
) (agentCommands, error) {
model := ""
autoApprove := false
permissionValues := make(map[string]bool)
@@ -335,6 +338,11 @@ func (m *Manager) buildAgentCommand(req *LaunchRequest, profileInfo *AgentProfil
model = req.ModelOverride
}
cliFlagTokens = appendRouteOverrideFlags(cliFlagTokens, req)
runtime := models.ExecutorType(req.ExecutorType).Runtime()
managedRuntimeVersion, err := m.resolveManagedRuntimeVersion(ctx, runtime, agentConfig)
if err != nil {
return agentCommands{}, err
}
// Only pass SessionID (for --resume flag) if the agent supports recovery.
// Agents with CanRecover=false (e.g. Auggie) use history context injection instead.
sessionID := req.ACPSessionID
@@ -342,14 +350,15 @@ func (m *Manager) buildAgentCommand(req *LaunchRequest, profileInfo *AgentProfil
sessionID = ""
}
cmdOpts := agents.CommandOptions{
Model: model,
SessionID: sessionID,
AutoApprove: autoApprove,
PermissionValues: permissionValues,
CLIFlagTokens: cliFlagTokens,
CommandPrefixTokens: commandPrefixTokens,
Runtime: models.ExecutorType(req.ExecutorType).Runtime(),
PreferNativeBinary: preferNative,
Model: model,
SessionID: sessionID,
AutoApprove: autoApprove,
PermissionValues: permissionValues,
CLIFlagTokens: cliFlagTokens,
CommandPrefixTokens: commandPrefixTokens,
Runtime: runtime,
PreferNativeBinary: preferNative,
ManagedRuntimeVersion: managedRuntimeVersion,
}
args := m.commandBuilder.BuildCommandArgs(agentConfig, cmdOpts)
continueArgs := m.commandBuilder.BuildContinueCommandArgs(agentConfig, cmdOpts)
@@ -359,6 +368,29 @@ func (m *Manager) buildAgentCommand(req *LaunchRequest, profileInfo *AgentProfil
return newAgentCommands(args, continueArgs), nil
}
func (m *Manager) resolveManagedRuntimeVersion(
ctx context.Context,
runtime agentruntime.Runtime,
agentConfig agents.Agent,
) (string, error) {
if runtime != agentruntime.RuntimeStandalone || m.managedRuntimeSelections == nil {
return "", nil
}
managed, ok := agentConfig.(agents.ManagedNPMRuntimeAgent)
if !ok {
return "", nil
}
spec := managed.ManagedNPMRuntime()
selection, found, err := m.managedRuntimeSelections.Get(ctx, agentConfig.ID(), spec.Package)
if err != nil {
return "", fmt.Errorf("resolve active managed runtime version for %s: %w", agentConfig.ID(), err)
}
if !found || selection.Package != spec.Package {
return "", nil
}
return selection.Version, nil
}
func validateBuiltAgentCommands(args, continueArgs []string) error {
if err := cliflags.ValidateCommandArgs(args); err != nil {
return fmt.Errorf("validate agent command: %w", err)
@@ -1054,7 +1086,7 @@ func (m *Manager) promoteWorkspaceExecution(ctx context.Context, execution *Agen
return nil, fmt.Errorf("agent type %q is disabled", agentTypeName)
}
preferNative := m.preferNativeBinary(agentConfig, execution.RuntimeName, execution.MetadataSnapshot())
cmds, err := m.buildAgentCommand(req, profileInfo, agentConfig, preferNative)
cmds, err := m.buildAgentCommandWithContext(sharedCtx, req, profileInfo, agentConfig, preferNative)
if err != nil {
return nil, err
}
@@ -1230,7 +1262,7 @@ func (m *Manager) launchInternal(ctx context.Context, req *LaunchRequest) (*Agen
// Build the in-memory AgentExecution from the runtime instance. Extracted
// to keep launchInternal under the cyclomatic-complexity budget.
execution, err := m.buildExecutionFromInstance(req, execReq, execInstance, rt, profileInfo, agentConfig, prepResult)
execution, err := m.buildExecutionFromInstance(ctx, req, execReq, execInstance, rt, profileInfo, agentConfig, prepResult)
if err != nil {
// Command resolution failed (e.g. a configured command_prefix could not
// be tokenised). The execution isn't built yet, so stop the runtime
@@ -1275,6 +1307,7 @@ func (m *Manager) launchInternal(ctx context.Context, req *LaunchRequest) (*Agen
// into an in-memory *AgentExecution ready for Add. Pulled out of launchInternal
// to keep the orchestration loop's cyclomatic complexity within the linter budget.
func (m *Manager) buildExecutionFromInstance(
ctx context.Context,
req *LaunchRequest,
execReq *ExecutorCreateRequest,
execInstance *ExecutorInstance,
@@ -1297,7 +1330,7 @@ func (m *Manager) buildExecutionFromInstance(
// promoteWorkspaceExecution's call site rather than re-deriving from the
// requested ExecutorType.
preferNative := m.preferNativeBinary(agentConfig, execution.RuntimeName, execReq.Metadata)
cmds, err := m.buildAgentCommand(req, profileInfo, agentConfig, preferNative)
cmds, err := m.buildAgentCommandWithContext(ctx, req, profileInfo, agentConfig, preferNative)
if err != nil {
return nil, err
}
@@ -95,7 +95,7 @@ func TestBuildAgentCommand_ResumeFlag(t *testing.T) {
t.Run("CanRecover=true with ACPSessionID includes --resume", func(t *testing.T) {
ag := &resumeTestAgent{canRecover: &canRecoverTrue}
req := &LaunchRequest{ACPSessionID: "sess-123"}
cmds, err := mgr.buildAgentCommand(req, nil, ag, false)
cmds, err := mgr.buildAgentCommandWithContext(context.Background(), req, nil, ag, false)
require.NoError(t, err)
require.Contains(t, cmds.initial, "--resume")
require.Contains(t, cmds.initial, "sess-123")
@@ -104,7 +104,7 @@ func TestBuildAgentCommand_ResumeFlag(t *testing.T) {
t.Run("CanRecover=false with ACPSessionID omits --resume", func(t *testing.T) {
ag := &resumeTestAgent{canRecover: &canRecoverFalse}
req := &LaunchRequest{ACPSessionID: "sess-123"}
cmds, err := mgr.buildAgentCommand(req, nil, ag, false)
cmds, err := mgr.buildAgentCommandWithContext(context.Background(), req, nil, ag, false)
require.NoError(t, err)
require.False(t, strings.Contains(cmds.initial, "--resume"),
"expected no --resume flag, got: %s", cmds.initial)
@@ -115,7 +115,7 @@ func TestBuildAgentCommand_ResumeFlag(t *testing.T) {
t.Run("CanRecover=true with empty ACPSessionID omits --resume", func(t *testing.T) {
ag := &resumeTestAgent{canRecover: &canRecoverTrue}
req := &LaunchRequest{ACPSessionID: ""}
cmds, err := mgr.buildAgentCommand(req, nil, ag, false)
cmds, err := mgr.buildAgentCommandWithContext(context.Background(), req, nil, ag, false)
require.NoError(t, err)
require.False(t, strings.Contains(cmds.initial, "--resume"),
"expected no --resume flag when ACPSessionID is empty, got: %s", cmds.initial)
@@ -124,7 +124,7 @@ func TestBuildAgentCommand_ResumeFlag(t *testing.T) {
t.Run("CanRecover=nil (default true) with ACPSessionID includes --resume", func(t *testing.T) {
ag := &resumeTestAgent{canRecover: nil}
req := &LaunchRequest{ACPSessionID: "sess-456"}
cmds, err := mgr.buildAgentCommand(req, nil, ag, false)
cmds, err := mgr.buildAgentCommandWithContext(context.Background(), req, nil, ag, false)
require.NoError(t, err)
require.Contains(t, cmds.initial, "--resume")
require.Contains(t, cmds.initial, "sess-456")
@@ -167,7 +167,7 @@ func TestBuildAgentCommand_UsesManagedNPMRuntimes(t *testing.T) {
for _, tt := range tests {
t.Run(tt.name, func(t *testing.T) {
cmds, err := mgr.buildAgentCommand(&LaunchRequest{}, nil, tt.agent, true)
cmds, err := mgr.buildAgentCommandWithContext(context.Background(), &LaunchRequest{}, nil, tt.agent, true)
require.NoError(t, err)
require.Equal(t, tt.want, cmds.initial)
})
@@ -205,7 +205,7 @@ func TestBuildAgentCommand_CLIFlagsAppended(t *testing.T) {
{Flag: "--add-dir /shared", Enabled: true}, // must be split
},
}
cmds, err := mgr.buildAgentCommand(&LaunchRequest{}, profile, ag, false)
cmds, err := mgr.buildAgentCommandWithContext(context.Background(), &LaunchRequest{}, profile, ag, false)
require.NoError(t, err)
require.Contains(t, cmds.initial, "--allow-all-tools")
@@ -223,7 +223,7 @@ func TestBuildAgentCommand_CLIFlagsAppended(t *testing.T) {
{Flag: `--broken "unterminated`, Enabled: true},
},
}
cmds, err := mgr.buildAgentCommand(&LaunchRequest{}, profile, ag, false)
cmds, err := mgr.buildAgentCommandWithContext(context.Background(), &LaunchRequest{}, profile, ag, false)
require.NoError(t, err)
// The bad flag is dropped entirely; the launch still produces the
// agent's base command so a user with a typo still gets their task
@@ -232,7 +232,7 @@ func TestBuildAgentCommand_CLIFlagsAppended(t *testing.T) {
})
t.Run("nil profile produces bare command", func(t *testing.T) {
cmds, err := mgr.buildAgentCommand(&LaunchRequest{}, nil, ag, false)
cmds, err := mgr.buildAgentCommandWithContext(context.Background(), &LaunchRequest{}, nil, ag, false)
require.NoError(t, err)
require.Equal(t, "copilot --acp", cmds.initial)
})
@@ -247,7 +247,7 @@ func TestBuildAgentCommand_CommandPrefix(t *testing.T) {
ProfileID: "p1",
CommandPrefix: "greywall --",
}
cmds, err := mgr.buildAgentCommand(&LaunchRequest{}, profile, ag, false)
cmds, err := mgr.buildAgentCommandWithContext(context.Background(), &LaunchRequest{}, profile, ag, false)
require.NoError(t, err)
require.Equal(t, "greywall -- copilot --acp", cmds.initial)
})
@@ -258,14 +258,14 @@ func TestBuildAgentCommand_CommandPrefix(t *testing.T) {
CommandPrefix: "greywall --",
CLIFlags: []settingsmodels.CLIFlag{{Flag: "--allow-all-tools", Enabled: true}},
}
cmds, err := mgr.buildAgentCommand(&LaunchRequest{}, profile, ag, false)
cmds, err := mgr.buildAgentCommandWithContext(context.Background(), &LaunchRequest{}, profile, ag, false)
require.NoError(t, err)
require.Equal(t, "greywall -- copilot --acp --allow-all-tools", cmds.initial)
})
t.Run("empty prefix leaves the command unwrapped", func(t *testing.T) {
profile := &AgentProfileInfo{ProfileID: "p3"}
cmds, err := mgr.buildAgentCommand(&LaunchRequest{}, profile, ag, false)
cmds, err := mgr.buildAgentCommandWithContext(context.Background(), &LaunchRequest{}, profile, ag, false)
require.NoError(t, err)
require.Equal(t, "copilot --acp", cmds.initial)
})
@@ -275,7 +275,7 @@ func TestBuildAgentCommand_CommandPrefix(t *testing.T) {
ProfileID: "p4",
CommandPrefix: `greywall "unterminated`,
}
_, err := mgr.buildAgentCommand(&LaunchRequest{}, profile, ag, false)
_, err := mgr.buildAgentCommandWithContext(context.Background(), &LaunchRequest{}, profile, ag, false)
require.Error(t, err, "a configured prefix that cannot be resolved must abort the launch")
})
@@ -292,7 +292,7 @@ func TestBuildAgentCommand_CommandPrefix(t *testing.T) {
CommandPrefix: "greywall --",
CLIFlags: []settingsmodels.CLIFlag{{Flag: "--allow-all-tools", Enabled: true}},
}
cmds, err := mgr.buildAgentCommand(&LaunchRequest{}, profile, continueAgent, false)
cmds, err := mgr.buildAgentCommandWithContext(context.Background(), &LaunchRequest{}, profile, continueAgent, false)
require.NoError(t, err)
require.Equal(t, "greywall -- amp threads continue --allow-all-tools", cmds.continue_)
})
@@ -320,7 +320,7 @@ func TestBuildAgentCommand_RejectsInvalidBuiltArgv(t *testing.T) {
}
for _, tt := range tests {
t.Run(tt.name, func(t *testing.T) {
_, err := mgr.buildAgentCommand(&LaunchRequest{}, nil, tt.agent, false)
_, err := mgr.buildAgentCommandWithContext(context.Background(), &LaunchRequest{}, nil, tt.agent, false)
require.Error(t, err)
})
}
@@ -24,7 +24,7 @@ import (
// agent type. Kept as a function seam so this package does not import
// the heavyweight registry/agents packages — the wire-up site (see
// registry.Provide) injects a concrete resolver at boot.
type CommandResolver func(providerID string) (argv []string, env map[string]string, ok bool)
type CommandResolver func(ctx context.Context, providerID string) (argv []string, env map[string]string, ok bool)
// ACPProbe is a cheap availability check that spawns the agent's ACP
// binary, performs a single JSON-RPC `initialize` round-trip, and tears
@@ -76,7 +76,9 @@ func (p *ACPProbe) Probe(ctx context.Context, in ProbeInput) *Error {
Stderr: "acp-probe: no command resolver wired",
})
}
argv, env, ok := p.resolver(in.ProviderID)
pCtx, cancel := context.WithTimeout(ctx, p.timeout)
defer cancel()
argv, env, ok := p.resolver(pCtx, in.ProviderID)
if !ok || len(argv) == 0 {
return Classify(Input{
Phase: PhaseAuthCheck,
@@ -85,9 +87,6 @@ func (p *ACPProbe) Probe(ctx context.Context, in ProbeInput) *Error {
})
}
pCtx, cancel := context.WithTimeout(ctx, p.timeout)
defer cancel()
cmd := exec.CommandContext(pCtx, argv[0], argv[1:]...)
if len(env) > 0 {
cmd.Env = mergeEnv(env)
@@ -27,7 +27,7 @@ func writeShellBin(t *testing.T, dir, name, body string) string {
// every provider id. Used to exercise the probe loop without wiring the
// full agent registry into a unit test.
func staticResolver(argv []string) CommandResolver {
return func(_ string) ([]string, map[string]string, bool) {
return func(_ context.Context, _ string) ([]string, map[string]string, bool) {
return argv, nil, true
}
}
@@ -89,7 +89,7 @@ func TestACPProbe_MissingResolver(t *testing.T) {
}
func TestACPProbe_ResolverReturnsNotOK(t *testing.T) {
probe := NewACPProbe(func(_ string) ([]string, map[string]string, bool) {
probe := NewACPProbe(func(_ context.Context, _ string) ([]string, map[string]string, bool) {
return nil, nil, false
}, nil)
got := probe.Probe(context.Background(), ProbeInput{ProviderID: "unknown"})
@@ -203,11 +203,24 @@ func (c *Controller) PreviewAgentCommand(ctx context.Context, agentName string,
PermissionValues: req.PermissionSettings,
})
} else {
managedRuntimeVersion := ""
var err error
if managed, ok := agentConfig.(agents.ManagedNPMRuntimeAgent); ok {
managedRuntimeVersion, err = c.activeRuntimeVersion(
ctx,
agentName,
managed.ManagedNPMRuntime().Package,
)
if err != nil {
return nil, fmt.Errorf("resolve active managed runtime version: %w", err)
}
}
cmd = agentConfig.BuildCommand(agents.CommandOptions{
Model: req.Model,
PermissionValues: req.PermissionSettings,
CLIFlagTokens: cliFlagTokens,
PreferNativeBinary: previewPrefersNativeBinary(agentConfig),
Model: req.Model,
PermissionValues: req.PermissionSettings,
CLIFlagTokens: cliFlagTokens,
PreferNativeBinary: previewPrefersNativeBinary(agentConfig),
ManagedRuntimeVersion: managedRuntimeVersion,
})
if len(cliFlagTokens) > 0 {
cmd = cmd.With().Flag(cliFlagTokens...).Build()
@@ -93,7 +93,6 @@ func (c *Controller) buildAvailableAgentDTO(ctx context.Context, ag agents.Agent
}
modelConfig := c.buildModelConfigFromHostUtility(ag.ID())
_ = ctx
capabilities := dto.AgentCapabilitiesDTO{
SupportsSessionResume: availability.Capabilities.SupportsSessionResume,
@@ -133,7 +132,7 @@ func (c *Controller) buildAvailableAgentDTO(ctx context.Context, ag agents.Agent
}
loginCommand := buildLoginCommandDTO(ag)
runtimeUpdate := c.buildRuntimeUpdateDTO(ag, availability.Available)
runtimeUpdate := c.buildRuntimeUpdateDTO(ctx, ag, availability.Available)
return dto.AvailableAgentDTO{
Name: ag.ID(),
@@ -155,7 +154,7 @@ func (c *Controller) buildAvailableAgentDTO(ctx context.Context, ag agents.Agent
}
}
func (c *Controller) buildRuntimeUpdateDTO(ag agents.Agent, available bool) *dto.RuntimeUpdateDTO {
func (c *Controller) buildRuntimeUpdateDTO(ctx context.Context, ag agents.Agent, available bool) *dto.RuntimeUpdateDTO {
if !available {
return nil
}
@@ -168,6 +167,11 @@ func (c *Controller) buildRuntimeUpdateDTO(ag agents.Agent, available bool) *dto
return nil
}
item := &dto.RuntimeUpdateDTO{Supported: true, Package: spec.Package}
if c.managedRuntimeSelections != nil {
if selection, found, err := c.managedRuntimeSelections.Get(ctx, ag.ID(), spec.Package); err == nil && found {
item.ActiveVersion = selection.Version
}
}
if c.runtimeUpdater != nil {
if caps, found := c.runtimeUpdater.CurrentCapabilities(ag.ID()); found {
item.CurrentVersion = caps.AgentVersion
@@ -12,16 +12,21 @@ import (
"path/filepath"
"strings"
"sync"
"time"
"github.com/kandev/kandev/internal/agent/agents"
"github.com/kandev/kandev/internal/agent/hostutility"
"github.com/kandev/kandev/internal/agent/managedruntime"
"github.com/kandev/kandev/internal/agent/settings/dto"
)
var (
ErrRuntimeUpdateUnsupported = errors.New("agent runtime update unsupported")
ErrRuntimeUpdaterUnavailable = errors.New("agent runtime updater unavailable")
ErrRuntimeUpdatePreviewFailed = errors.New("agent runtime update preview failed")
ErrRuntimeUpdateUnsupported = errors.New("agent runtime update unsupported")
ErrRuntimeUpdaterUnavailable = errors.New("agent runtime updater unavailable")
ErrRuntimeUpdatePreviewFailed = errors.New("agent runtime update preview failed")
ErrRuntimeUpdateTargetRequired = errors.New("managed runtime target version is required")
ErrRuntimeUpdateTargetInvalid = errors.New("managed runtime target version is invalid")
ErrRuntimeUpdateTargetMissing = errors.New("managed runtime target version is not published")
)
// PreviewAgentUpdate resolves the trusted built-in update recipe without
@@ -29,6 +34,7 @@ var (
func (c *Controller) PreviewAgentUpdate(
ctx context.Context,
name string,
targetVersions ...string,
) (*dto.AgentUpdatePreviewDTO, error) {
if c.runtimeUpdater == nil {
return nil, ErrRuntimeUpdaterUnavailable
@@ -50,21 +56,98 @@ func (c *Controller) PreviewAgentUpdate(
if caps, found := c.runtimeUpdater.CurrentCapabilities(name); found {
current = caps.AgentVersion
}
target, err := c.runtimeUpdater.ResolveTarget(ctx, spec.Package)
active, err := c.activeRuntimeVersion(ctx, name, spec.Package)
if err != nil {
return nil, fmt.Errorf("%w: %v", ErrRuntimeUpdatePreviewFailed, err)
}
command := spec.CacheUpdateCommand().Args()
catalogue, exactCatalogue, err := c.resolveRuntimeCatalogue(ctx, spec.Package, active, current)
if err != nil {
return nil, fmt.Errorf("%w: %v", ErrRuntimeUpdatePreviewFailed, err)
}
target := catalogue.Latest
if len(targetVersions) > 0 && strings.TrimSpace(targetVersions[0]) != "" {
target = strings.TrimSpace(targetVersions[0])
if _, err := managedruntime.ParseStableVersion(target); err != nil {
return nil, fmt.Errorf("%w: %v", ErrRuntimeUpdateTargetInvalid, err)
}
if exactCatalogue && !catalogue.Has(target) {
return nil, fmt.Errorf("%w: %s", ErrRuntimeUpdateTargetMissing, target)
}
}
operation, err := managedruntime.ClassifyOperation(active, current, target)
if err != nil {
return nil, fmt.Errorf("%w: %v", ErrRuntimeUpdateTargetInvalid, err)
}
command := spec.CacheUpdateCommand(target).Args()
if !exactCatalogue && (len(targetVersions) == 0 || strings.TrimSpace(targetVersions[0]) == "") {
// Keep the compatibility preview for embedders that provide only the
// legacy latest-version seam. Production uses the catalogue resolver and
// always previews an exact package@version command.
command = spec.CacheUpdateCommand().Args()
}
return &dto.AgentUpdatePreviewDTO{
AgentName: name,
Package: spec.Package,
CurrentVersion: current,
TargetVersion: target,
Command: command,
CommandString: buildCommandString(command),
AgentName: name,
Package: spec.Package,
CurrentVersion: current,
ActiveVersion: active,
TargetVersion: target,
Operation: string(operation),
AvailableVersions: runtimeVersionDTOs(catalogue),
Command: command,
CommandString: buildCommandString(command),
}, nil
}
func (c *Controller) resolveRuntimeCatalogue(
ctx context.Context,
packageName string,
extras ...string,
) (managedruntime.Catalogue, bool, error) {
if resolver, ok := c.runtimeUpdater.(RuntimeVersionResolver); ok {
metadata, err := resolver.ResolveVersions(ctx, packageName)
if err != nil {
return managedruntime.Catalogue{}, true, err
}
catalogue, err := managedruntime.BuildCatalogue(metadata.Versions, metadata.Latest, extras...)
return catalogue, true, err
}
target, err := c.runtimeUpdater.ResolveTarget(ctx, packageName)
if err != nil {
return managedruntime.Catalogue{}, false, err
}
catalogue, err := managedruntime.BuildCatalogue([]string{target}, target)
return catalogue, false, err
}
func runtimeVersionDTOs(catalogue managedruntime.Catalogue) []dto.AgentUpdateVersionDTO {
versions := make([]dto.AgentUpdateVersionDTO, 0, len(catalogue.Versions))
for _, version := range catalogue.Versions {
versions = append(versions, dto.AgentUpdateVersionDTO{
Version: version.Version,
Latest: version.Latest,
})
}
return versions
}
func (c *Controller) activeRuntimeVersion(
ctx context.Context,
agentName string,
packageName string,
) (string, error) {
if c.managedRuntimeSelections == nil {
return "", nil
}
selection, found, err := c.managedRuntimeSelections.Get(ctx, agentName, packageName)
if err != nil {
return "", fmt.Errorf("read active runtime version: %w", err)
}
if !found {
return "", nil
}
return selection.Version, nil
}
// RuntimeUpdater is the external-process and host-probe boundary used by
// managed runtime jobs. Implementations must execute commands as direct argv.
type RuntimeUpdater interface {
@@ -79,6 +162,30 @@ type RuntimeUpdater interface {
) (hostutility.AgentCapabilities, error)
}
// RuntimeVersionMetadata is the trusted npm catalogue used to authorize an
// exact target after the browser preview has been shown.
type RuntimeVersionMetadata struct {
Versions []string
Latest string
}
// RuntimeVersionResolver obtains package metadata without executing a package.
type RuntimeVersionResolver interface {
ResolveVersions(context.Context, string) (RuntimeVersionMetadata, error)
}
// RuntimeCandidateUpdater separates validation probes from live capability
// publication. The update job persists the selection between these calls.
type RuntimeCandidateUpdater interface {
Probe(context.Context, string, agents.Command) (hostutility.AgentCapabilities, error)
PublishCapabilities(string, hostutility.AgentCapabilities)
}
// ExactRuntimeCacheInvalidator removes only the version-specific npm tree.
type ExactRuntimeCacheInvalidator interface {
InvalidateExecutionCacheVersion(context.Context, string, string) error
}
type hostRuntimeUpdater struct {
host *hostutility.Manager
executor directCommandExecutor
@@ -123,7 +230,37 @@ func (u *hostRuntimeUpdater) ResolveTarget(ctx context.Context, packageName stri
if strings.TrimSpace(target) == "" {
return "", errors.New("npm target version is empty")
}
return strings.TrimSpace(target), nil
target = strings.TrimSpace(target)
if _, err := managedruntime.ParseStableVersion(target); err != nil {
return "", fmt.Errorf("npm target version is not stable: %w", err)
}
return target, nil
}
func (u *hostRuntimeUpdater) ResolveVersions(
ctx context.Context,
packageName string,
) (RuntimeVersionMetadata, error) {
command := agents.NewCommand("npm", "view", packageName, "versions", "dist-tags", "--json")
output, err := u.executor.Output(ctx, command)
if err != nil {
return RuntimeVersionMetadata{}, err
}
var metadata struct {
Versions []string `json:"versions"`
DistTags map[string]string `json:"dist-tags"`
}
if err := json.Unmarshal([]byte(strings.TrimSpace(output)), &metadata); err != nil {
return RuntimeVersionMetadata{}, fmt.Errorf("parse npm runtime metadata: %w", err)
}
latest := ""
if metadata.DistTags != nil {
latest = strings.TrimSpace(metadata.DistTags["latest"])
}
if latest == "" {
return RuntimeVersionMetadata{}, errors.New("npm latest runtime version is empty")
}
return RuntimeVersionMetadata{Versions: metadata.Versions, Latest: latest}, nil
}
func runDirectCommandOutput(ctx context.Context, command agents.Command) (string, error) {
@@ -148,30 +285,29 @@ func (u *hostRuntimeUpdater) RunUpdate(
return u.executor.Stream(ctx, command, onChunk)
}
func (u *hostRuntimeUpdater) InvalidateExecutionCache(ctx context.Context, packageName string) error {
packageName = strings.TrimSpace(packageName)
if packageName == "" {
return errors.New("managed runtime package is empty")
}
func (u *hostRuntimeUpdater) npxCacheRoot(ctx context.Context) (string, error) {
output, err := u.executor.Output(ctx, agents.NewCommand("npm", "config", "get", "cache"))
if err != nil {
return fmt.Errorf("resolve npm cache root: %w", err)
return "", fmt.Errorf("resolve npm cache root: %w", err)
}
cacheRoot := strings.TrimSpace(output)
if !filepath.IsAbs(cacheRoot) {
return fmt.Errorf("npm cache root is not absolute: %q", cacheRoot)
return "", fmt.Errorf("npm cache root is not absolute: %q", cacheRoot)
}
cacheRoot = filepath.Clean(cacheRoot)
if cacheRoot == string(filepath.Separator) {
return errors.New("refusing to invalidate execution cache under filesystem root")
return "", errors.New("refusing to invalidate execution cache under filesystem root")
}
npxRoot := filepath.Join(cacheRoot, "_npx")
if info, statErr := os.Lstat(npxRoot); statErr == nil && info.Mode()&os.ModeSymlink != 0 {
return fmt.Errorf("refusing to invalidate execution cache through symlink: %s", npxRoot)
return "", fmt.Errorf("refusing to invalidate execution cache through symlink: %s", npxRoot)
} else if statErr != nil && !errors.Is(statErr, os.ErrNotExist) {
return fmt.Errorf("inspect npm execution cache: %w", statErr)
return "", fmt.Errorf("inspect npm execution cache: %w", statErr)
}
key := (agents.ManagedNPMRuntimeSpec{Package: packageName}).ExecutionCacheKey()
return npxRoot, nil
}
func removeNpmExecutionCacheKey(npxRoot, key string) error {
target := filepath.Join(npxRoot, key)
rel, err := filepath.Rel(npxRoot, target)
if err != nil || rel != key {
@@ -183,6 +319,40 @@ func (u *hostRuntimeUpdater) InvalidateExecutionCache(ctx context.Context, packa
return nil
}
func (u *hostRuntimeUpdater) InvalidateExecutionCache(ctx context.Context, packageName string) error {
packageName = strings.TrimSpace(packageName)
if packageName == "" {
return errors.New("managed runtime package is empty")
}
npxRoot, err := u.npxCacheRoot(ctx)
if err != nil {
return err
}
key := (agents.ManagedNPMRuntimeSpec{Package: packageName}).ExecutionCacheKey()
return removeNpmExecutionCacheKey(npxRoot, key)
}
func (u *hostRuntimeUpdater) InvalidateExecutionCacheVersion(
ctx context.Context,
packageName string,
version string,
) error {
packageName = strings.TrimSpace(packageName)
version = strings.TrimSpace(version)
if packageName == "" || version == "" {
return errors.New("managed runtime package and version are required")
}
if _, err := managedruntime.ParseStableVersion(version); err != nil {
return err
}
npxRoot, err := u.npxCacheRoot(ctx)
if err != nil {
return err
}
spec := agents.ManagedNPMRuntimeSpec{Package: packageName}
return removeNpmExecutionCacheKey(npxRoot, spec.ExecutionCacheKey(version))
}
func (u *hostRuntimeUpdater) Refresh(
ctx context.Context,
agentName string,
@@ -191,6 +361,21 @@ func (u *hostRuntimeUpdater) Refresh(
return u.host.RefreshWithCommand(ctx, agentName, command)
}
func (u *hostRuntimeUpdater) Probe(
ctx context.Context,
agentName string,
command agents.Command,
) (hostutility.AgentCapabilities, error) {
return u.host.ProbeWithCommand(ctx, agentName, command)
}
func (u *hostRuntimeUpdater) PublishCapabilities(
agentName string,
caps hostutility.AgentCapabilities,
) {
u.host.PublishCapabilities(agentName, caps)
}
func runDirectCommand(ctx context.Context, command agents.Command, onChunk func(string)) error {
argv := command.Args()
if len(argv) == 0 {
@@ -246,10 +431,17 @@ func scanCommandOutput(
}
// EnqueueAgentUpdate starts or reuses an update for a built-in managed agent.
func (c *Controller) EnqueueAgentUpdate(name string) (*dto.AgentUpdateJobDTO, error) {
func (c *Controller) EnqueueAgentUpdate(
ctx context.Context,
name string,
targetVersion string,
) (*dto.AgentUpdateJobDTO, error) {
if c.updateJobStore == nil || c.runtimeUpdater == nil {
return nil, ErrRuntimeUpdaterUnavailable
}
if active, found := c.updateJobStore.GetActive(name); found {
return active, nil
}
ag, ok := c.agentRegistry.Get(name)
if !ok {
return nil, ErrAgentNotFound
@@ -262,7 +454,17 @@ func (c *Controller) EnqueueAgentUpdate(name string) (*dto.AgentUpdateJobDTO, er
if strings.TrimSpace(spec.Package) == "" {
return nil, ErrRuntimeUpdateUnsupported
}
job, err := c.updateJobStore.Enqueue(name, spec)
targetVersion = strings.TrimSpace(targetVersion)
if targetVersion == "" {
return nil, ErrRuntimeUpdateTargetRequired
}
if err := c.validateAgentUpdateTarget(ctx, spec, targetVersion); err != nil {
return nil, err
}
if noOp := c.alreadyActiveHealthyUpdate(ctx, name, spec, targetVersion); noOp != nil {
return noOp, nil
}
job, err := c.updateJobStore.Enqueue(name, spec, targetVersion)
if err != nil {
return nil, err
}
@@ -273,6 +475,65 @@ func (c *Controller) EnqueueAgentUpdate(name string) (*dto.AgentUpdateJobDTO, er
return &snapshot, nil
}
func (c *Controller) validateAgentUpdateTarget(
ctx context.Context,
spec agents.ManagedNPMRuntimeSpec,
targetVersion string,
) error {
if _, err := managedruntime.ParseStableVersion(targetVersion); err != nil {
return fmt.Errorf("%w: %v", ErrRuntimeUpdateTargetInvalid, err)
}
resolver, ok := c.runtimeUpdater.(RuntimeVersionResolver)
if !ok {
return nil
}
metadata, err := resolver.ResolveVersions(ctx, spec.Package)
if err != nil {
return fmt.Errorf("%w: %v", ErrRuntimeUpdatePreviewFailed, err)
}
catalogue, err := managedruntime.BuildCatalogue(metadata.Versions, metadata.Latest)
if err != nil {
return fmt.Errorf("%w: %v", ErrRuntimeUpdatePreviewFailed, err)
}
if !catalogue.Has(targetVersion) {
return fmt.Errorf("%w: %s", ErrRuntimeUpdateTargetMissing, targetVersion)
}
return nil
}
// alreadyActiveHealthyUpdate returns a terminal response without retaining a
// job when the requested version is already the exact active healthy runtime.
func (c *Controller) alreadyActiveHealthyUpdate(
ctx context.Context,
agentName string,
spec agents.ManagedNPMRuntimeSpec,
targetVersion string,
) *dto.AgentUpdateJobDTO {
if c.managedRuntimeSelections == nil {
return nil
}
caps, found := c.runtimeUpdater.CurrentCapabilities(agentName)
if !found || caps.Status != hostutility.StatusOK || caps.AgentVersion != targetVersion {
return nil
}
selection, found, err := c.managedRuntimeSelections.Get(ctx, agentName, spec.Package)
if err != nil || !found || selection.Package != spec.Package || selection.Version != targetVersion {
return nil
}
now := time.Now().UTC()
return &dto.AgentUpdateJobDTO{
AgentName: agentName,
Status: dto.AgentUpdateJobStatusSucceeded,
Operation: string(managedruntime.OperationUpToDate),
CurrentVersion: caps.AgentVersion,
ActiveVersion: selection.Version,
TargetVersion: targetVersion,
Output: "Runtime already up to date.\n",
StartedAt: now,
FinishedAt: &now,
}
}
func (c *Controller) ListAgentUpdateJobs() []dto.AgentUpdateJobDTO {
if c.updateJobStore == nil {
return nil
@@ -5,12 +5,14 @@ import (
"context"
"errors"
"fmt"
"strings"
"sync"
"time"
"github.com/google/uuid"
"github.com/kandev/kandev/internal/agent/agents"
"github.com/kandev/kandev/internal/agent/hostutility"
"github.com/kandev/kandev/internal/agent/managedruntime"
"github.com/kandev/kandev/internal/agent/settings/dto"
ws "github.com/kandev/kandev/pkg/websocket"
"go.uber.org/zap"
@@ -20,7 +22,9 @@ type AgentUpdateJob struct {
ID string
AgentName string
Status dto.AgentUpdateJobStatus
Operation managedruntime.Operation
CurrentVersion string
ActiveVersion string
TargetVersion string
Output *ringBuffer
StartedAt time.Time
@@ -30,15 +34,16 @@ type AgentUpdateJob struct {
}
type AgentUpdateJobStore struct {
mu sync.Mutex
jobs map[string]*AgentUpdateJob
activeByAgt map[string]*AgentUpdateJob
semaphore chan struct{}
hub JobBroadcaster
log *zap.Logger
updater RuntimeUpdater
maintenance *maintenanceCoordinator
onRefresh func()
mu sync.Mutex
jobs map[string]*AgentUpdateJob
activeByAgt map[string]*AgentUpdateJob
semaphore chan struct{}
hub JobBroadcaster
log *zap.Logger
updater RuntimeUpdater
maintenance *maintenanceCoordinator
onRefresh func()
selectionStore managedruntime.SelectionStore
}
func NewAgentUpdateJobStore(
@@ -47,25 +52,32 @@ func NewAgentUpdateJobStore(
updater RuntimeUpdater,
maintenance *maintenanceCoordinator,
onRefresh func(),
selectionStores ...managedruntime.SelectionStore,
) *AgentUpdateJobStore {
if maintenance == nil {
maintenance = newMaintenanceCoordinator()
}
var selectionStore managedruntime.SelectionStore
if len(selectionStores) > 0 {
selectionStore = selectionStores[0]
}
return &AgentUpdateJobStore{
jobs: make(map[string]*AgentUpdateJob),
activeByAgt: make(map[string]*AgentUpdateJob),
semaphore: make(chan struct{}, jobMaxParallel),
hub: hub,
log: log,
updater: updater,
maintenance: maintenance,
onRefresh: onRefresh,
jobs: make(map[string]*AgentUpdateJob),
activeByAgt: make(map[string]*AgentUpdateJob),
semaphore: make(chan struct{}, jobMaxParallel),
hub: hub,
log: log,
updater: updater,
maintenance: maintenance,
onRefresh: onRefresh,
selectionStore: selectionStore,
}
}
func (s *AgentUpdateJobStore) Enqueue(
agentName string,
spec agents.ManagedNPMRuntimeSpec,
targetVersions ...string,
) (*AgentUpdateJob, error) {
s.mu.Lock()
if existing, ok := s.activeByAgt[agentName]; ok {
@@ -79,6 +91,11 @@ func (s *AgentUpdateJobStore) Enqueue(
Output: newRingBuffer(jobOutputRingSize),
StartedAt: time.Now().UTC(),
}
requestedTarget := ""
if len(targetVersions) > 0 {
requestedTarget = strings.TrimSpace(targetVersions[0])
job.TargetVersion = requestedTarget
}
ref, claimed, err := s.maintenance.claim(agentName, MaintenanceKindUpdate, job.ID)
if err != nil {
s.mu.Unlock()
@@ -94,7 +111,7 @@ func (s *AgentUpdateJobStore) Enqueue(
s.mu.Unlock()
s.broadcast(ws.ActionAgentUpdateStarted, job.snapshot())
go s.run(job, spec, ref)
go s.run(job, spec, requestedTarget, ref)
return job, nil
}
@@ -109,6 +126,18 @@ func (s *AgentUpdateJobStore) Get(jobID string) (*dto.AgentUpdateJobDTO, bool) {
return &snapshot, true
}
// GetActive returns the current queued or running update for an agent.
func (s *AgentUpdateJobStore) GetActive(agentName string) (*dto.AgentUpdateJobDTO, bool) {
s.mu.Lock()
defer s.mu.Unlock()
job, ok := s.activeByAgt[agentName]
if !ok {
return nil, false
}
snapshot := job.snapshot()
return &snapshot, true
}
func (s *AgentUpdateJobStore) ListAll() []dto.AgentUpdateJobDTO {
s.mu.Lock()
defer s.mu.Unlock()
@@ -122,6 +151,7 @@ func (s *AgentUpdateJobStore) ListAll() []dto.AgentUpdateJobDTO {
func (s *AgentUpdateJobStore) run(
job *AgentUpdateJob,
spec agents.ManagedNPMRuntimeSpec,
requestedTarget string,
ref MaintenanceJobRef,
) {
s.semaphore <- struct{}{}
@@ -131,7 +161,7 @@ func (s *AgentUpdateJobStore) run(
defer cancel()
s.setStatus(job, dto.AgentUpdateJobStatusResolving)
target, err := s.updater.ResolveTarget(ctx, spec.Package)
target, exactTarget, err := s.resolveTarget(ctx, spec.Package, requestedTarget)
if err != nil {
s.finishFailed(job, ctx, fmt.Errorf("resolve target version: %w", err), ref)
return
@@ -143,17 +173,44 @@ func (s *AgentUpdateJobStore) run(
job.CurrentVersion = currentVersion
s.mu.Unlock()
}
activeVersion := ""
if s.selectionStore != nil {
selection, found, selectionErr := s.selectionStore.Get(ctx, job.AgentName, spec.Package)
if selectionErr != nil {
s.finishFailed(job, ctx, fmt.Errorf("read active runtime version: %w", selectionErr), ref)
return
}
if found {
activeVersion = selection.Version
}
}
operation, err := managedruntime.ClassifyOperation(activeVersion, currentVersion, target)
if err != nil {
s.finishFailed(job, ctx, fmt.Errorf("classify runtime operation: %w", err), ref)
return
}
s.mu.Lock()
job.TargetVersion = target
job.Operation = operation
job.ActiveVersion = activeVersion
s.mu.Unlock()
if currentVersion != "" && currentVersion == target {
if operation == managedruntime.OperationUpToDate ||
(s.selectionStore == nil && currentVersion != "" && currentVersion == target) {
s.finishAlreadyUpToDate(job, ref)
return
}
if candidate, ok := s.updater.(RuntimeCandidateUpdater); ok && s.selectionStore != nil {
s.runExactCandidate(ctx, job, spec, target, candidate, ref)
return
}
s.setStatus(job, dto.AgentUpdateJobStatusUpdating)
flusher := newUpdateOutputFlusher(s, job)
err = s.updater.RunUpdate(ctx, spec.CacheUpdateCommand(), flusher.append)
prepareCommand := spec.CacheUpdateCommand()
if exactTarget {
prepareCommand = spec.CacheUpdateCommand(target)
}
err = s.updater.RunUpdate(ctx, prepareCommand, flusher.append)
flusher.flush()
if err != nil {
flusher.append("managed runtime cache appears stale; repairing execution cache\n")
@@ -164,7 +221,7 @@ func (s *AgentUpdateJobStore) run(
}
flusher.append("retrying managed runtime update\n")
flusher.flush()
err = s.updater.RunUpdate(ctx, spec.CacheUpdateCommand(), flusher.append)
err = s.updater.RunUpdate(ctx, prepareCommand, flusher.append)
flusher.flush()
if err != nil {
s.finishFailed(job, ctx, fmt.Errorf("update runtime after cache repair: %w", err), ref)
@@ -173,10 +230,113 @@ func (s *AgentUpdateJobStore) run(
}
s.setStatus(job, dto.AgentUpdateJobStatusRefreshing)
caps, refreshErr := s.updater.Refresh(ctx, job.AgentName, spec.CachedACPCommand())
refreshCommand := spec.CachedACPCommand()
if exactTarget {
refreshCommand = spec.ACPCommand(target)
}
caps, refreshErr := s.updater.Refresh(ctx, job.AgentName, refreshCommand)
s.finishRefresh(job, ctx, caps, refreshErr, ref)
}
func (s *AgentUpdateJobStore) resolveTarget(
ctx context.Context,
packageName string,
requestedTarget string,
) (string, bool, error) {
if resolver, ok := s.updater.(RuntimeVersionResolver); ok {
return s.resolveTargetFromMetadata(ctx, resolver, packageName, requestedTarget)
}
if requestedTarget != "" {
if _, err := managedruntime.ParseStableVersion(requestedTarget); err != nil {
return "", true, fmt.Errorf("%w: %v", ErrRuntimeUpdateTargetInvalid, err)
}
return requestedTarget, true, nil
}
target, err := s.updater.ResolveTarget(ctx, packageName)
return target, false, err
}
func (s *AgentUpdateJobStore) resolveTargetFromMetadata(
ctx context.Context,
resolver RuntimeVersionResolver,
packageName string,
requestedTarget string,
) (string, bool, error) {
requestedTarget = strings.TrimSpace(requestedTarget)
if requestedTarget != "" {
// EnqueueAgentUpdate already checked this exact target against the
// package catalogue. The worker only needs to preserve that target,
// avoiding a second registry round-trip after the job is queued.
if _, err := managedruntime.ParseStableVersion(requestedTarget); err != nil {
return "", true, fmt.Errorf("%w: %v", ErrRuntimeUpdateTargetInvalid, err)
}
return requestedTarget, true, nil
}
metadata, err := resolver.ResolveVersions(ctx, packageName)
if err != nil {
return "", true, err
}
catalogue, err := managedruntime.BuildCatalogue(metadata.Versions, metadata.Latest)
if err != nil {
return "", true, err
}
return catalogue.Latest, true, nil
}
func (s *AgentUpdateJobStore) runExactCandidate(
ctx context.Context,
job *AgentUpdateJob,
spec agents.ManagedNPMRuntimeSpec,
target string,
candidate RuntimeCandidateUpdater,
ref MaintenanceJobRef,
) {
s.setStatus(job, dto.AgentUpdateJobStatusUpdating)
flusher := newUpdateOutputFlusher(s, job)
prepareCommand := spec.CacheUpdateCommand(target)
err := s.updater.RunUpdate(ctx, prepareCommand, flusher.append)
flusher.flush()
if err != nil {
flusher.append("managed runtime cache appears stale; repairing exact execution cache\n")
flusher.flush()
var repairErr error
if invalidator, ok := s.updater.(ExactRuntimeCacheInvalidator); ok {
repairErr = invalidator.InvalidateExecutionCacheVersion(ctx, spec.Package, target)
} else {
repairErr = s.updater.InvalidateExecutionCache(ctx, spec.Package)
}
if repairErr != nil {
s.finishFailed(job, ctx, fmt.Errorf("repair runtime execution cache: %w", repairErr), ref)
return
}
flusher.append("retrying managed runtime update\n")
flusher.flush()
err = s.updater.RunUpdate(ctx, prepareCommand, flusher.append)
flusher.flush()
if err != nil {
s.finishFailed(job, ctx, fmt.Errorf("update runtime after cache repair: %w", err), ref)
return
}
}
s.setStatus(job, dto.AgentUpdateJobStatusRefreshing)
caps, probeErr := candidate.Probe(ctx, job.AgentName, spec.ACPCommand(target))
if probeErr != nil {
s.finishFailed(job, ctx, fmt.Errorf("probe runtime candidate: %w", probeErr), ref)
return
}
if caps.Status != hostutility.StatusOK {
s.finishFailed(job, ctx, errors.New(capabilityRefreshError(caps)), ref)
return
}
if err := s.selectionStore.Save(ctx, job.AgentName, spec.Package, target); err != nil {
s.finishFailed(job, ctx, fmt.Errorf("persist active runtime version: %w", err), ref)
return
}
candidate.PublishCapabilities(job.AgentName, caps)
s.finishActivated(job, target, ref)
}
func (s *AgentUpdateJobStore) setStatus(job *AgentUpdateJob, status dto.AgentUpdateJobStatus) {
s.mu.Lock()
job.Status = status
@@ -219,6 +379,25 @@ func (s *AgentUpdateJobStore) finishAlreadyUpToDate(job *AgentUpdateJob, ref Mai
s.scheduleEviction(job.ID)
}
func (s *AgentUpdateJobStore) finishActivated(
job *AgentUpdateJob,
target string,
ref MaintenanceJobRef,
) {
s.mu.Lock()
job.Status = dto.AgentUpdateJobStatusSucceeded
job.ActiveVersion = target
s.maintenance.release(job.AgentName, ref)
s.finishLocked(job)
snapshot := job.snapshot()
s.mu.Unlock()
if s.onRefresh != nil {
s.onRefresh()
}
s.broadcast(ws.ActionAgentUpdateFinished, snapshot)
s.scheduleEviction(job.ID)
}
func (s *AgentUpdateJobStore) finishRefresh(
job *AgentUpdateJob,
ctx context.Context,
@@ -300,7 +479,9 @@ func (j *AgentUpdateJob) snapshot() dto.AgentUpdateJobDTO {
JobID: j.ID,
AgentName: j.AgentName,
Status: j.Status,
Operation: string(j.Operation),
CurrentVersion: j.CurrentVersion,
ActiveVersion: j.ActiveVersion,
TargetVersion: j.TargetVersion,
Output: j.Output.String(),
Error: j.Error,
@@ -0,0 +1,315 @@
package controller
import (
"context"
"errors"
"strings"
"sync"
"testing"
"github.com/kandev/kandev/internal/agent/agents"
"github.com/kandev/kandev/internal/agent/hostutility"
"github.com/kandev/kandev/internal/agent/managedruntime"
"github.com/kandev/kandev/internal/agent/settings/dto"
"go.uber.org/zap"
)
type recoverySelectionStore struct {
mu sync.Mutex
values map[string]managedruntime.Selection
err error
saveErr error
events *[]string
}
func newRecoverySelectionStore() *recoverySelectionStore {
return &recoverySelectionStore{values: make(map[string]managedruntime.Selection)}
}
func (s *recoverySelectionStore) Get(
_ context.Context,
agentName string,
packageName string,
) (managedruntime.Selection, bool, error) {
s.mu.Lock()
defer s.mu.Unlock()
if s.err != nil {
return managedruntime.Selection{}, false, s.err
}
selection, ok := s.values[agentName+"\x00"+packageName]
return selection, ok, nil
}
func (s *recoverySelectionStore) Save(
_ context.Context,
agentName string,
packageName string,
version string,
) error {
s.mu.Lock()
defer s.mu.Unlock()
if s.saveErr != nil {
return s.saveErr
}
s.values[agentName+"\x00"+packageName] = managedruntime.Selection{
Package: packageName,
Version: version,
}
if s.events != nil {
*s.events = append(*s.events, "persist")
}
return nil
}
type recoveryRuntimeUpdater struct {
mu sync.Mutex
metadata RuntimeVersionMetadata
metadataCalls int
current hostutility.AgentCapabilities
currentFound bool
probeCaps hostutility.AgentCapabilities
probeErr error
runErrs []error
runCalls int
prepare []string
probe []string
invalidate []string
events *[]string
}
func (u *recoveryRuntimeUpdater) CurrentCapabilities(string) (hostutility.AgentCapabilities, bool) {
u.mu.Lock()
defer u.mu.Unlock()
return u.current, u.currentFound
}
func (u *recoveryRuntimeUpdater) ResolveTarget(context.Context, string) (string, error) {
return u.metadata.Latest, nil
}
func (u *recoveryRuntimeUpdater) ResolveVersions(context.Context, string) (RuntimeVersionMetadata, error) {
u.mu.Lock()
defer u.mu.Unlock()
u.metadataCalls++
return u.metadata, nil
}
func (u *recoveryRuntimeUpdater) RunUpdate(
_ context.Context,
command agents.Command,
onChunk func(string),
) error {
u.mu.Lock()
u.runCalls++
u.prepare = append(u.prepare, strings.Join(command.Args(), " "))
index := u.runCalls - 1
var err error
if index < len(u.runErrs) {
err = u.runErrs[index]
}
u.mu.Unlock()
onChunk("prepared\n")
return err
}
func (u *recoveryRuntimeUpdater) InvalidateExecutionCache(context.Context, string) error {
return nil
}
func (u *recoveryRuntimeUpdater) InvalidateExecutionCacheVersion(
_ context.Context,
packageName string,
version string,
) error {
u.mu.Lock()
defer u.mu.Unlock()
u.invalidate = append(u.invalidate, packageName+"@"+version)
return nil
}
func (u *recoveryRuntimeUpdater) Refresh(
context.Context,
string,
agents.Command,
) (hostutility.AgentCapabilities, error) {
return hostutility.AgentCapabilities{}, errors.New("legacy refresh must not be used")
}
func (u *recoveryRuntimeUpdater) Probe(
_ context.Context,
_ string,
command agents.Command,
) (hostutility.AgentCapabilities, error) {
u.mu.Lock()
u.probe = append(u.probe, strings.Join(command.Args(), " "))
if u.events != nil {
*u.events = append(*u.events, "probe")
}
caps, err := u.probeCaps, u.probeErr
u.mu.Unlock()
return caps, err
}
func (u *recoveryRuntimeUpdater) PublishCapabilities(
_ string,
_ hostutility.AgentCapabilities,
) {
u.mu.Lock()
defer u.mu.Unlock()
if u.events != nil {
*u.events = append(*u.events, "publish")
}
}
func newRecoveryStore(
updater RuntimeUpdater,
selectionStore managedruntime.SelectionStore,
) (*AgentUpdateJobStore, <-chan dto.AgentUpdateJobDTO) {
hub := newUpdateTerminalBroadcaster()
return NewAgentUpdateJobStore(
hub,
zap.NewNop(),
updater,
newMaintenanceCoordinator(),
nil,
selectionStore,
), hub.completed
}
func TestAgentUpdateExactCandidatePersistsBeforePublishing(t *testing.T) {
selectionStore := newRecoverySelectionStore()
selectionStore.values["managed-acp\x00@example/managed-acp"] = managedruntime.Selection{
Package: "@example/managed-acp",
Version: "1.0.3",
}
events := make([]string, 0, 4)
selectionStore.events = &events
updater := &recoveryRuntimeUpdater{
metadata: RuntimeVersionMetadata{
Versions: []string{"1.0.1", "1.0.2", "1.0.3"},
Latest: "1.0.3",
},
current: hostutility.AgentCapabilities{Status: hostutility.StatusOK, AgentVersion: "1.0.3"},
currentFound: true,
probeCaps: hostutility.AgentCapabilities{Status: hostutility.StatusOK, AgentVersion: "1.0.2"},
}
updater.events = &events
store, completed := newRecoveryStore(updater, selectionStore)
job, err := store.Enqueue("managed-acp", managedRuntimeSpec(), "1.0.2")
if err != nil {
t.Fatalf("Enqueue: %v", err)
}
final := waitForUpdateStatus(t, completed, job.ID, dto.AgentUpdateJobStatusSucceeded)
if final.Operation != string(managedruntime.OperationRollback) {
t.Fatalf("operation = %q, want rollback", final.Operation)
}
if final.ActiveVersion != "1.0.2" {
t.Fatalf("active version = %q, want 1.0.2", final.ActiveVersion)
}
if len(updater.prepare) != 1 || !strings.Contains(updater.prepare[0], "--package=@example/managed-acp@1.0.2") {
t.Fatalf("prepare commands = %#v", updater.prepare)
}
if len(updater.probe) != 1 || !strings.Contains(updater.probe[0], "@example/managed-acp@1.0.2") {
t.Fatalf("probe commands = %#v", updater.probe)
}
if len(updater.invalidate) != 0 {
t.Fatalf("invalidate calls = %#v, want none", updater.invalidate)
}
if len(events) != 3 || events[0] != "probe" || events[1] != "persist" || events[2] != "publish" {
t.Fatalf("activation order = %#v", events)
}
}
func TestAgentUpdateExactTargetSkipsMetadataRefetch(t *testing.T) {
selectionStore := newRecoverySelectionStore()
updater := &recoveryRuntimeUpdater{
metadata: RuntimeVersionMetadata{
Versions: []string{"1.0.1", "1.0.2"},
Latest: "1.0.2",
},
current: hostutility.AgentCapabilities{Status: hostutility.StatusOK, AgentVersion: "1.0.1"},
currentFound: true,
probeCaps: hostutility.AgentCapabilities{Status: hostutility.StatusOK, AgentVersion: "1.0.2"},
}
store, completed := newRecoveryStore(updater, selectionStore)
job, err := store.Enqueue("managed-acp", managedRuntimeSpec(), "1.0.2")
if err != nil {
t.Fatalf("Enqueue: %v", err)
}
waitForUpdateStatus(t, completed, job.ID, dto.AgentUpdateJobStatusSucceeded)
updater.mu.Lock()
metadataCalls := updater.metadataCalls
updater.mu.Unlock()
if metadataCalls != 0 {
t.Fatalf("metadata calls = %d, want no refetch for a validated target", metadataCalls)
}
}
func TestAgentUpdateFailedCandidatePreservesSelectionAndCapabilities(t *testing.T) {
selectionStore := newRecoverySelectionStore()
selectionStore.values["managed-acp\x00@example/managed-acp"] = managedruntime.Selection{
Package: "@example/managed-acp",
Version: "1.0.3",
}
events := make([]string, 0, 2)
updater := &recoveryRuntimeUpdater{
metadata: RuntimeVersionMetadata{
Versions: []string{"1.0.2", "1.0.3"},
Latest: "1.0.3",
},
current: hostutility.AgentCapabilities{Status: hostutility.StatusOK, AgentVersion: "1.0.3"},
currentFound: true,
probeCaps: hostutility.AgentCapabilities{
Status: hostutility.StatusFailed,
Error: "ACP initialization failed",
},
}
updater.events = &events
store, completed := newRecoveryStore(updater, selectionStore)
job, err := store.Enqueue("managed-acp", managedRuntimeSpec(), "1.0.2")
if err != nil {
t.Fatalf("Enqueue: %v", err)
}
final := waitForUpdateStatus(t, completed, job.ID, dto.AgentUpdateJobStatusFailed)
if !strings.Contains(final.Error, "ACP initialization failed") {
t.Fatalf("error = %q", final.Error)
}
selection, found, err := selectionStore.Get(context.Background(), "managed-acp", "@example/managed-acp")
if err != nil || !found || selection.Version != "1.0.3" {
t.Fatalf("selection after failure = %#v, found=%v, err=%v", selection, found, err)
}
if len(events) != 1 || events[0] != "probe" {
t.Fatalf("candidate publication events = %#v", updater.events)
}
}
func TestAgentUpdateActiveHealthyTargetIsUpToDateWithoutPreparation(t *testing.T) {
selectionStore := newRecoverySelectionStore()
selectionStore.values["managed-acp\x00@example/managed-acp"] = managedruntime.Selection{
Package: "@example/managed-acp",
Version: "1.0.3",
}
updater := &recoveryRuntimeUpdater{
metadata: RuntimeVersionMetadata{Versions: []string{"1.0.3"}, Latest: "1.0.3"},
current: hostutility.AgentCapabilities{
Status: hostutility.StatusOK,
AgentVersion: "1.0.3",
},
currentFound: true,
}
store, completed := newRecoveryStore(updater, selectionStore)
job, err := store.Enqueue("managed-acp", managedRuntimeSpec(), "1.0.3")
if err != nil {
t.Fatalf("Enqueue: %v", err)
}
final := waitForUpdateStatus(t, completed, job.ID, dto.AgentUpdateJobStatusSucceeded)
if final.Operation != string(managedruntime.OperationUpToDate) {
t.Fatalf("operation = %q, want up_to_date", final.Operation)
}
if updater.runCalls != 0 || len(updater.probe) != 0 {
t.Fatalf("updater mutated up-to-date target: runs=%d probes=%d", updater.runCalls, len(updater.probe))
}
}
@@ -13,6 +13,7 @@ import (
"github.com/kandev/kandev/internal/agent/agents"
"github.com/kandev/kandev/internal/agent/hostutility"
"github.com/kandev/kandev/internal/agent/managedruntime"
"github.com/kandev/kandev/internal/agent/settings/dto"
ws "github.com/kandev/kandev/pkg/websocket"
"go.uber.org/zap"
@@ -41,6 +42,26 @@ type fakeRuntimeUpdater struct {
resolvedPackage string
}
type sequencedVersionUpdater struct {
fakeRuntimeUpdater
metadata RuntimeVersionMetadata
metadataErr error
metadataCall int
}
func (u *sequencedVersionUpdater) ResolveVersions(
_ context.Context,
_ string,
) (RuntimeVersionMetadata, error) {
u.mu.Lock()
defer u.mu.Unlock()
u.metadataCall++
if u.metadataCall > 1 && u.metadataErr != nil {
return RuntimeVersionMetadata{}, u.metadataErr
}
return u.metadata, nil
}
type recordingCommandExecutor struct {
outputCommand []string
output string
@@ -79,6 +100,25 @@ func TestHostRuntimeUpdaterResolvesTargetWithDirectNPMArgv(t *testing.T) {
}
}
func TestHostRuntimeUpdaterResolvesStableVersionCatalogue(t *testing.T) {
executor := &recordingCommandExecutor{
output: `{"versions":["1.0.1","1.0.2-beta.1","1.0.2"],"dist-tags":{"latest":"1.0.2"}}`,
}
updater := &hostRuntimeUpdater{executor: executor}
metadata, err := updater.ResolveVersions(context.Background(), "@example/managed-acp")
if err != nil {
t.Fatalf("ResolveVersions: %v", err)
}
if metadata.Latest != "1.0.2" || len(metadata.Versions) != 3 {
t.Fatalf("metadata = %#v", metadata)
}
want := []string{"npm", "view", "@example/managed-acp", "versions", "dist-tags", "--json"}
if got := strings.Join(executor.outputCommand, "\x00"); got != strings.Join(want, "\x00") {
t.Fatalf("command = %v, want %v", executor.outputCommand, want)
}
}
func TestHostRuntimeUpdaterInvalidatesOnlyManagedNPMExecutionTree(t *testing.T) {
cacheRoot := t.TempDir()
spec := agents.ManagedNPMRuntimeSpec{Package: "opencode-ai"}
@@ -225,7 +265,7 @@ func waitForUpdateStatus(
return &snapshot
}
}
t.Fatalf("job %s finished with status %s, want %v", jobID, snapshot.Status, statuses)
t.Fatalf("job %s finished with status %s, error %q, operation %q, want %v", jobID, snapshot.Status, snapshot.Error, snapshot.Operation, statuses)
return nil
}
@@ -316,6 +356,124 @@ func TestAgentUpdatePreviewRejectsUnsupportedAndResolutionFailure(t *testing.T)
}
}
func TestAgentUpdatePreviewSurfacesSelectionStoreFailure(t *testing.T) {
updater := &fakeRuntimeUpdater{target: "1.1.0"}
selectionStore := newRecoverySelectionStore()
selectionStore.err = errors.New("selection store locked")
ag := &managedTestAgent{
testAgent: testAgent{id: "managed-acp", name: "Managed", enabled: true},
spec: managedRuntimeSpec(),
}
ctrl := newTestController(map[string]agents.Agent{ag.ID(): ag})
ctrl.SetRuntimeUpdater(updater)
ctrl.SetManagedRuntimeSelectionStore(selectionStore)
_, err := ctrl.PreviewAgentUpdate(context.Background(), ag.ID())
if !errors.Is(err, ErrRuntimeUpdatePreviewFailed) {
t.Fatalf("PreviewAgentUpdate error = %v, want %v", err, ErrRuntimeUpdatePreviewFailed)
}
if !strings.Contains(err.Error(), "selection store locked") {
t.Fatalf("PreviewAgentUpdate error = %v, want selection error", err)
}
}
func TestEnqueueAgentUpdateReusesActiveJobBeforeMetadataResolution(t *testing.T) {
metadataErr := errors.New("registry unavailable")
updater := &sequencedVersionUpdater{
fakeRuntimeUpdater: fakeRuntimeUpdater{
current: hostutility.AgentCapabilities{AgentVersion: "1.0.0"},
currentFound: true,
refreshCaps: hostutility.AgentCapabilities{Status: hostutility.StatusOK, AgentVersion: "1.1.0"},
runStarted: make(chan struct{}),
releaseRun: make(chan struct{}),
},
metadata: RuntimeVersionMetadata{Versions: []string{"1.0.0", "1.1.0"}, Latest: "1.1.0"},
metadataErr: metadataErr,
}
hub := newUpdateTerminalBroadcaster()
ag := &managedTestAgent{
testAgent: testAgent{id: "managed-acp", name: "Managed", enabled: true},
spec: managedRuntimeSpec(),
}
ctrl := newTestController(map[string]agents.Agent{ag.ID(): ag})
ctrl.SetRuntimeUpdater(updater)
ctrl.updateJobStore = NewAgentUpdateJobStore(
hub,
zap.NewNop(),
updater,
newMaintenanceCoordinator(),
nil,
)
first, err := ctrl.EnqueueAgentUpdate(context.Background(), ag.ID(), "1.1.0")
if err != nil {
t.Fatalf("first EnqueueAgentUpdate: %v", err)
}
select {
case <-updater.runStarted:
case <-time.After(2 * time.Second):
t.Fatal("first update did not reach the running phase")
}
second, err := ctrl.EnqueueAgentUpdate(context.Background(), ag.ID(), "1.1.0")
if err != nil {
t.Fatalf("second EnqueueAgentUpdate: %v", err)
}
if second.JobID != first.JobID {
t.Fatalf("job IDs differ: %s != %s", second.JobID, first.JobID)
}
updater.mu.Lock()
metadataCalls := updater.metadataCall
updater.mu.Unlock()
if metadataCalls != 1 {
t.Fatalf("metadata calls = %d, want one initial validation", metadataCalls)
}
close(updater.releaseRun)
waitForUpdateStatus(t, hub.completed, first.JobID, dto.AgentUpdateJobStatusSucceeded)
}
func TestEnqueueAgentUpdateDoesNotCreateJobForAlreadyActiveHealthyTarget(t *testing.T) {
selectionStore := newRecoverySelectionStore()
selectionStore.values["managed-acp\x00@example/managed-acp"] = managedruntime.Selection{
Package: "@example/managed-acp",
Version: "1.1.0",
}
updater := &recoveryRuntimeUpdater{
metadata: RuntimeVersionMetadata{Versions: []string{"1.1.0"}, Latest: "1.1.0"},
current: hostutility.AgentCapabilities{
Status: hostutility.StatusOK,
AgentVersion: "1.1.0",
},
currentFound: true,
}
ag := &managedTestAgent{
testAgent: testAgent{id: "managed-acp", name: "Managed", enabled: true},
spec: managedRuntimeSpec(),
}
ctrl := newTestController(map[string]agents.Agent{ag.ID(): ag})
ctrl.SetManagedRuntimeSelectionStore(selectionStore)
ctrl.SetJobBroadcaster(newUpdateTerminalBroadcaster())
ctrl.SetRuntimeUpdater(updater)
result, err := ctrl.EnqueueAgentUpdate(context.Background(), ag.ID(), "1.1.0")
if err != nil {
t.Fatalf("EnqueueAgentUpdate: %v", err)
}
if result.JobID != "" {
t.Fatalf("no-op response job ID = %q, want no persisted job", result.JobID)
}
if result.Operation != string(managedruntime.OperationUpToDate) {
t.Fatalf("no-op operation = %q, want up_to_date", result.Operation)
}
if jobs := ctrl.ListAgentUpdateJobs(); len(jobs) != 0 {
t.Fatalf("retained jobs = %d, want none", len(jobs))
}
if updater.runCalls != 0 || len(updater.probe) != 0 {
t.Fatalf("no-op mutated updater: runs=%d probes=%d", updater.runCalls, len(updater.probe))
}
}
func TestAgentUpdateJobResolvesUpdatesRefreshesAndStreams(t *testing.T) {
updater := &fakeRuntimeUpdater{
current: hostutility.AgentCapabilities{AgentVersion: "1.0.0"},
@@ -10,6 +10,7 @@ import (
"github.com/kandev/kandev/internal/agent/discovery"
agentdto "github.com/kandev/kandev/internal/agent/dto"
"github.com/kandev/kandev/internal/agent/hostutility"
"github.com/kandev/kandev/internal/agent/managedruntime"
"github.com/kandev/kandev/internal/agent/mcpconfig"
"github.com/kandev/kandev/internal/agent/registry"
"github.com/kandev/kandev/internal/agent/settings/modelfetcher"
@@ -51,24 +52,25 @@ var (
)
type Controller struct {
repo store.Repository
discovery *discovery.Registry
agentRegistry *registry.Registry
sessionChecker SessionChecker
watcherDeps WatcherDependencyChecker
routingTierDeps RoutingTierDependencyChecker
automationDeps AutomationDependencyChecker
utilityDeps UtilityDependencyChecker
mcpService *mcpconfig.Service
modelCache *modelfetcher.Cache
hostUtility hostUtilityProvider
jobStore *JobStore
updateJobStore *AgentUpdateJobStore
runtimeUpdater RuntimeUpdater
maintenance *maintenanceCoordinator
hub JobBroadcaster
logger *logger.Logger
secretStore secrets.SecretStore
repo store.Repository
discovery *discovery.Registry
agentRegistry *registry.Registry
sessionChecker SessionChecker
watcherDeps WatcherDependencyChecker
routingTierDeps RoutingTierDependencyChecker
automationDeps AutomationDependencyChecker
utilityDeps UtilityDependencyChecker
mcpService *mcpconfig.Service
modelCache *modelfetcher.Cache
hostUtility hostUtilityProvider
jobStore *JobStore
updateJobStore *AgentUpdateJobStore
runtimeUpdater RuntimeUpdater
managedRuntimeSelections managedruntime.SelectionStore
maintenance *maintenanceCoordinator
hub JobBroadcaster
logger *logger.Logger
secretStore secrets.SecretStore
}
// SetSecretStore wires the metadata-only validator used by shared agent
@@ -251,6 +253,13 @@ func (c *Controller) SetRuntimeUpdater(updater RuntimeUpdater) {
c.initializeUpdateJobStore()
}
// SetManagedRuntimeSelectionStore wires the install-wide active-version
// persistence used by previews, jobs, and the available-agent catalogue.
func (c *Controller) SetManagedRuntimeSelectionStore(store managedruntime.SelectionStore) {
c.managedRuntimeSelections = store
c.initializeUpdateJobStore()
}
// SetJobBroadcaster initializes the install job store with a WS broadcaster
// for streaming install progress. Called once during handler registration.
// If unset (hub == nil), the streaming install API returns
@@ -301,6 +310,7 @@ func (c *Controller) initializeUpdateJobStore() {
c.runtimeUpdater,
c.maintenance,
c.BroadcastAvailableAgents,
c.managedRuntimeSelections,
)
}
@@ -11,6 +11,7 @@ import (
"github.com/kandev/kandev/internal/agent/agents"
"github.com/kandev/kandev/internal/agent/discovery"
"github.com/kandev/kandev/internal/agent/managedruntime"
"github.com/kandev/kandev/internal/agent/registry"
"github.com/kandev/kandev/internal/agent/settings/dto"
"github.com/kandev/kandev/internal/agent/settings/modelfetcher"
@@ -174,6 +175,25 @@ func TestController_PreviewAgentCommand_StandardCommand(t *testing.T) {
}
}
func TestController_PreviewAgentCommandUsesActiveManagedRuntimeVersion(t *testing.T) {
agent := agents.NewOpenCodeACP()
controller := newTestController(map[string]agents.Agent{agent.ID(): agent})
selectionStore := newRecoverySelectionStore()
selectionStore.values[agent.ID()+"\x00opencode-ai"] = managedruntime.Selection{
Package: "opencode-ai",
Version: "1.18.5",
}
controller.SetManagedRuntimeSelectionStore(selectionStore)
result, err := controller.PreviewAgentCommand(context.Background(), agent.ID(), CommandPreviewRequest{})
if err != nil {
t.Fatalf("PreviewAgentCommand() error = %v", err)
}
if !slices.Contains(result.Command, "opencode-ai@1.18.5") {
t.Fatalf("preview command = %v, want exact active version", result.Command)
}
}
func TestController_PreviewAgentCommand_RejectsInvalidCommandPrefix(t *testing.T) {
controller := newTestController(map[string]agents.Agent{
"test-agent": &testAgent{
@@ -236,6 +236,7 @@ type RuntimeUpdateDTO struct {
Supported bool `json:"supported"`
Package string `json:"package"`
CurrentVersion string `json:"current_version,omitempty"`
ActiveVersion string `json:"active_version,omitempty"`
}
type ListAvailableAgentsResponse struct {
@@ -296,7 +297,9 @@ type AgentUpdateJobDTO struct {
JobID string `json:"job_id"`
AgentName string `json:"agent_name"`
Status AgentUpdateJobStatus `json:"status"`
Operation string `json:"operation"`
CurrentVersion string `json:"current_version,omitempty"`
ActiveVersion string `json:"active_version,omitempty"`
TargetVersion string `json:"target_version,omitempty"`
Output string `json:"output,omitempty"`
Error string `json:"error,omitempty"`
@@ -308,12 +311,28 @@ type AgentUpdateJobDTO struct {
// AgentUpdatePreviewDTO is a read-only representation of the next managed
// runtime update. The command is derived from trusted built-in agent metadata.
type AgentUpdatePreviewDTO struct {
AgentName string `json:"agent_name"`
Package string `json:"package"`
CurrentVersion string `json:"current_version,omitempty"`
TargetVersion string `json:"target_version"`
Command []string `json:"command"`
CommandString string `json:"command_string"`
AgentName string `json:"agent_name"`
Package string `json:"package"`
CurrentVersion string `json:"current_version,omitempty"`
ActiveVersion string `json:"active_version,omitempty"`
TargetVersion string `json:"target_version"`
Operation string `json:"operation"`
AvailableVersions []AgentUpdateVersionDTO `json:"available_versions"`
Command []string `json:"command"`
CommandString string `json:"command_string"`
}
// AgentUpdateVersionDTO is one stable, selectable package version.
type AgentUpdateVersionDTO struct {
Version string `json:"version"`
Latest bool `json:"latest"`
}
// AgentUpdateRequest is the only state-changing input accepted by the
// managed-runtime update endpoint. Package identity and command arguments are
// always resolved from trusted built-in agent metadata.
type AgentUpdateRequest struct {
TargetVersion string `json:"target_version"`
}
type ListAgentUpdateJobsResponse struct {
@@ -14,6 +14,7 @@ import (
"github.com/kandev/kandev/internal/agent/agents"
"github.com/kandev/kandev/internal/agent/discovery"
"github.com/kandev/kandev/internal/agent/hostutility"
"github.com/kandev/kandev/internal/agent/managedruntime"
"github.com/kandev/kandev/internal/agent/registry"
"github.com/kandev/kandev/internal/agent/settings/controller"
"github.com/kandev/kandev/internal/agent/settings/dto"
@@ -28,8 +29,24 @@ type handlerRuntimeUpdater struct {
once sync.Once
}
type handlerSelectionStore struct {
selection managedruntime.Selection
}
func (s handlerSelectionStore) Get(
context.Context,
string,
string,
) (managedruntime.Selection, bool, error) {
return s.selection, true, nil
}
func (handlerSelectionStore) Save(context.Context, string, string, string) error {
return nil
}
func (u *handlerRuntimeUpdater) CurrentCapabilities(string) (hostutility.AgentCapabilities, bool) {
return hostutility.AgentCapabilities{AgentVersion: "1.0.0"}, true
return hostutility.AgentCapabilities{Status: hostutility.StatusOK, AgentVersion: "1.0.0"}, true
}
func (u *handlerRuntimeUpdater) ResolveTarget(context.Context, string) (string, error) {
@@ -140,6 +157,13 @@ func updateRequest(method, path string) *http.Request {
return request
}
func updateJSONRequest(method, path, body string) *http.Request {
request := httptest.NewRequest(method, path, strings.NewReader(body))
request.Header.Set("Content-Type", "application/json")
request.Header.Set(httpmw.InterimSettingsInterlockHeader, "test-interlock")
return request
}
func TestAgentUpdatePreviewEndpointIsReadOnly(t *testing.T) {
router, _, _ := newAgentUpdateRouter(t, &handlerRuntimeUpdater{})
response := httptest.NewRecorder()
@@ -171,7 +195,11 @@ func TestAgentUpdatePreviewEndpointIsReadOnly(t *testing.T) {
func TestAgentUpdateEndpointsAcceptAndRetainJobs(t *testing.T) {
router, _, completed := newAgentUpdateRouter(t, &handlerRuntimeUpdater{})
response := httptest.NewRecorder()
router.ServeHTTP(response, updateRequest(http.MethodPost, "/api/v1/agent-update/claude-acp"))
router.ServeHTTP(response, updateJSONRequest(
http.MethodPost,
"/api/v1/agent-update/claude-acp",
`{"target_version":"1.1.0"}`,
))
if response.Code != http.StatusAccepted {
t.Fatalf("POST status = %d, body = %s", response.Code, response.Body.String())
}
@@ -209,6 +237,38 @@ func TestAgentUpdateEndpointsAcceptAndRetainJobs(t *testing.T) {
}
}
func TestAgentUpdateEndpointDoesNotCreateAlreadyActiveHealthyJob(t *testing.T) {
router, ctrl, _ := newAgentUpdateRouter(t, &handlerRuntimeUpdater{})
selectionStore := handlerSelectionStore{selection: managedruntime.Selection{
Package: "@agentclientprotocol/claude-agent-acp",
Version: "1.0.0",
}}
ctrl.SetManagedRuntimeSelectionStore(selectionStore)
response := httptest.NewRecorder()
router.ServeHTTP(response, updateJSONRequest(
http.MethodPost,
"/api/v1/agent-update/claude-acp",
`{"target_version":"1.0.0"}`,
))
if response.Code != http.StatusAccepted {
t.Fatalf("POST status = %d, body = %s", response.Code, response.Body.String())
}
var result dto.AgentUpdateJobDTO
if err := json.Unmarshal(response.Body.Bytes(), &result); err != nil {
t.Fatalf("decode no-op response: %v", err)
}
if result.JobID != "" || result.Operation != string(managedruntime.OperationUpToDate) {
t.Fatalf("no-op response = %#v, want terminal up_to_date without job ID", result)
}
jobs := httptest.NewRecorder()
router.ServeHTTP(jobs, updateRequest(http.MethodGet, "/api/v1/agent-update/jobs"))
if jobs.Code != http.StatusOK || !strings.Contains(jobs.Body.String(), `"jobs":[]`) {
t.Fatalf("no-op jobs response = %d %s", jobs.Code, jobs.Body.String())
}
}
func TestAgentUpdateEndpointReturnsMaintenanceConflict(t *testing.T) {
updater := &handlerRuntimeUpdater{
started: make(chan struct{}),
@@ -223,9 +283,10 @@ func TestAgentUpdateEndpointReturnsMaintenanceConflict(t *testing.T) {
}
})
updateResponse := httptest.NewRecorder()
router.ServeHTTP(updateResponse, updateRequest(
router.ServeHTTP(updateResponse, updateJSONRequest(
http.MethodPost,
"/api/v1/agent-update/claude-acp",
`{"target_version":"1.1.0"}`,
))
if updateResponse.Code != http.StatusAccepted {
t.Fatalf("update status = %d, body = %s", updateResponse.Code, updateResponse.Body.String())
@@ -285,3 +346,18 @@ func TestAgentUpdateEndpointRejectsUnmanagedAgentAndMissingJob(t *testing.T) {
t.Fatalf("missing status = %d, body = %s", missing.Code, missing.Body.String())
}
}
func TestAgentUpdateEndpointRequiresExactTargetVersion(t *testing.T) {
router, _, _ := newAgentUpdateRouter(t, &handlerRuntimeUpdater{})
for _, body := range []string{"", `{}`, `{"target_version":"latest"}`} {
response := httptest.NewRecorder()
router.ServeHTTP(response, updateJSONRequest(
http.MethodPost,
"/api/v1/agent-update/claude-acp",
body,
))
if response.Code != http.StatusBadRequest {
t.Fatalf("body %q status = %d, want 400: %s", body, response.Code, response.Body.String())
}
}
}
@@ -123,8 +123,18 @@ func (h *Handlers) httpUpdateAgentRuntime(c *gin.Context) {
if !ok {
return
}
var request dto.AgentUpdateRequest
if err := c.ShouldBindJSON(&request); err != nil {
c.JSON(http.StatusBadRequest, gin.H{"error": "target version is required"})
return
}
request.TargetVersion = strings.TrimSpace(request.TargetVersion)
if request.TargetVersion == "" {
c.JSON(http.StatusBadRequest, gin.H{"error": "target version is required"})
return
}
h.enqueueMaintenance(c, name, "update", func() (any, error) {
return h.controller.EnqueueAgentUpdate(name)
return h.controller.EnqueueAgentUpdate(c.Request.Context(), name, request.TargetVersion)
}, classifyUpdateError)
}
@@ -133,7 +143,11 @@ func (h *Handlers) httpPreviewAgentUpdate(c *gin.Context) {
if !ok {
return
}
preview, err := h.controller.PreviewAgentUpdate(c.Request.Context(), name)
preview, err := h.controller.PreviewAgentUpdate(
c.Request.Context(),
name,
strings.TrimSpace(c.Query("target_version")),
)
if err == nil {
c.JSON(http.StatusOK, preview)
return
@@ -211,6 +225,12 @@ func classifyUpdateError(err error) (int, string, bool) {
return http.StatusBadRequest, "agent runtime update unsupported", true
case errors.Is(err, controller.ErrRuntimeUpdaterUnavailable):
return http.StatusServiceUnavailable, "agent update service not ready", true
case errors.Is(err, controller.ErrRuntimeUpdateTargetRequired):
return http.StatusBadRequest, "target version is required", true
case errors.Is(err, controller.ErrRuntimeUpdateTargetInvalid):
return http.StatusBadRequest, "target version is invalid", true
case errors.Is(err, controller.ErrRuntimeUpdateTargetMissing):
return http.StatusBadRequest, "target version is not published", true
default:
return 0, "", false
}
@@ -221,7 +241,13 @@ func classifyUpdatePreviewError(err error) (int, string, bool) {
return status, message, true
}
if errors.Is(err, controller.ErrRuntimeUpdatePreviewFailed) {
return http.StatusBadGateway, "unable to resolve latest runtime version", true
return http.StatusBadGateway, "unable to resolve runtime versions", true
}
if errors.Is(err, controller.ErrRuntimeUpdateTargetInvalid) {
return http.StatusBadRequest, "target version is invalid", true
}
if errors.Is(err, controller.ErrRuntimeUpdateTargetMissing) {
return http.StatusBadRequest, "target version is not published", true
}
return 0, "", false
}
@@ -7,6 +7,7 @@ import (
"go.uber.org/zap"
"github.com/kandev/kandev/internal/agent/credentials"
"github.com/kandev/kandev/internal/agent/managedruntime"
"github.com/kandev/kandev/internal/agent/mcpconfig"
"github.com/kandev/kandev/internal/agent/registry"
agentctl "github.com/kandev/kandev/internal/agent/runtime/agentctl"
@@ -29,6 +30,7 @@ func provideLifecycleManager(
agentRegistry *registry.Registry,
secretStore secrets.SecretStore,
baseBranchProvider lifecycle.BaseBranchProvider,
managedRuntimeSelections managedruntime.SelectionReader,
) (*lifecycle.Manager, error) {
log.Info("Initializing Agent Manager...")
@@ -129,6 +131,7 @@ func provideLifecycleManager(
// enrichment fields. Without a wired SkillDeployer this is a no-op,
// but the reader still lets future Wave-B/C consumers light up.
lifecycleMgr.SetAgentProfileReader(agentSettingsRepo)
lifecycleMgr.SetManagedRuntimeSelectionStore(managedRuntimeSelections)
// MCP handler is set later in main.go after MCP handlers are registered
// via lifecycleMgr.SetMCPHandler(gateway.Dispatcher)
+13 -1
View File
@@ -362,6 +362,7 @@ func startServices( //nolint:cyclop
log.Error("Failed to initialize services", zap.Error(err))
return false
}
agentRegistry.SetManagedRuntimeSelectionStore(services.ManagedRuntimeSelections)
if services.Workflow != nil {
addCleanup(services.Workflow.Close)
}
@@ -446,7 +447,17 @@ func startAgentInfrastructure(
// ============================================
// AGENT MANAGER
// ============================================
lifecycleMgr, err := provideLifecycleManager(ctx, cfg, log, eventBus, repos.AgentSettings, agentRegistry, userSecretStore, services.Task.TaskBaseBranches)
lifecycleMgr, err := provideLifecycleManager(
ctx,
cfg,
log,
eventBus,
repos.AgentSettings,
agentRegistry,
userSecretStore,
services.Task.TaskBaseBranches,
services.ManagedRuntimeSelections,
)
if err != nil {
log.Error("Failed to initialize agent manager", zap.Error(err))
return false
@@ -767,6 +778,7 @@ func startGatewayAndServe(
_, ok := agentRegistry.GetInferenceAgent(agentID)
return ok
}))
hostUtilityMgr.SetManagedRuntimeSelectionStore(services.ManagedRuntimeSelections)
// Wire the host utility manager into the settings controller so
// /api/v1/agent-models/:agentName reads live capability data.
agentSettingsController.SetHostUtility(hostUtilityMgr)
+25 -17
View File
@@ -12,6 +12,7 @@ import (
"github.com/kandev/kandev/internal/agent/discovery"
"github.com/kandev/kandev/internal/agent/hostutility"
"github.com/kandev/kandev/internal/agent/managedruntime"
"github.com/kandev/kandev/internal/agent/registry"
agentsettingscontroller "github.com/kandev/kandev/internal/agent/settings/controller"
analyticsservice "github.com/kandev/kandev/internal/analytics/service"
@@ -62,6 +63,12 @@ func provideServices(cfg *config.Config, log *logger.Logger, repos *Repositories
userSecretStore := secrets.NewUserVisibleStore(repos.Secrets)
agentSettingsController := agentsettingscontroller.NewController(repos.AgentSettings, discoveryRegistry, agentRegistry, repos.Task, log)
agentSettingsController.SetSecretStore(userSecretStore)
managedRuntimeSettings, err := systemsettings.NewStore(dbPool)
if err != nil {
return nil, nil, fmt.Errorf("initialize managed runtime settings: %w", err)
}
managedRuntimeSelections := managedruntime.NewStore(managedRuntimeSettings)
agentSettingsController.SetManagedRuntimeSelectionStore(managedRuntimeSelections)
userSvc := userservice.NewService(repos.User, eventBus, log)
editorSvc := editorservice.NewService(repos.Editor, repos.Task, userSvc)
@@ -214,23 +221,24 @@ func provideServices(cfg *config.Config, log *logger.Logger, repos *Repositories
}
services := &Services{
Task: taskSvc,
User: userSvc,
Editor: editorSvc,
Prompts: promptSvc,
Utility: utilitySvc,
Workflow: workflowSvc,
GitHub: githubSvc,
GitLab: gitlabSvc,
AzureDevOps: azureDevOpsSvc,
Jira: jiraSvc,
Linear: linearSvc,
Sentry: sentrySvc,
WorkflowSync: workflowSyncSvc,
Share: shareHTTP,
Automation: automationComponents,
Plugins: pluginsSvc,
GitCredentials: gitCredentialBroker,
ManagedRuntimeSelections: managedRuntimeSelections,
Task: taskSvc,
User: userSvc,
Editor: editorSvc,
Prompts: promptSvc,
Utility: utilitySvc,
Workflow: workflowSvc,
GitHub: githubSvc,
GitLab: gitlabSvc,
AzureDevOps: azureDevOpsSvc,
Jira: jiraSvc,
Linear: linearSvc,
Sentry: sentrySvc,
WorkflowSync: workflowSyncSvc,
Share: shareHTTP,
Automation: automationComponents,
Plugins: pluginsSvc,
GitCredentials: gitCredentialBroker,
// Office is constructed later in initOfficeServices once all
// of its dependencies (config loader, task integrations, etc.) are available.
Office: nil,
+15 -13
View File
@@ -3,6 +3,7 @@ package backendapp
import (
"errors"
"github.com/kandev/kandev/internal/agent/managedruntime"
settingsstore "github.com/kandev/kandev/internal/agent/settings/store"
analyticsrepository "github.com/kandev/kandev/internal/analytics/repository"
authservice "github.com/kandev/kandev/internal/auth"
@@ -66,19 +67,20 @@ type Repositories struct {
}
type Services struct {
Task *taskservice.Service
User *userservice.Service
Editor *editorservice.Service
Notification *notificationservice.Service
Prompts *promptservice.Service
Utility *utilityservice.Service
Workflow *workflowservice.Service
GitHub *github.Service
GitLab *gitlab.Service
AzureDevOps *azuredevops.Service
Jira *jira.Service
Linear *linear.Service
Sentry *sentry.Service
ManagedRuntimeSelections managedruntime.SelectionStore
Task *taskservice.Service
User *userservice.Service
Editor *editorservice.Service
Notification *notificationservice.Service
Prompts *promptservice.Service
Utility *utilityservice.Service
Workflow *workflowservice.Service
GitHub *github.Service
GitLab *gitlab.Service
AzureDevOps *azuredevops.Service
Jira *jira.Service
Linear *linear.Service
Sentry *sentry.Service
// WorkflowSync keeps workspace workflows in sync with definition files
// in a configured GitHub repository. Nil when GitHub is unavailable.
WorkflowSync *workflowsync.Service
+2 -2
View File
@@ -53,8 +53,8 @@ type InstalledAgentsSectionProps = {
resolveRuntimeUpdate: (name: string) => RuntimeUpdate | undefined;
installJobs: Record<string, InstallJob>;
updateJobs: Record<string, AgentUpdateJob>;
previewUpdate: (name: string) => Promise<AgentUpdatePreview>;
startUpdate: (name: string) => Promise<AgentUpdateJob>;
previewUpdate: (name: string, targetVersion?: string) => Promise<AgentUpdatePreview>;
startUpdate: (name: string, targetVersion: string) => Promise<AgentUpdateJob>;
setTuiDialogOpen: (open: boolean) => void;
handleRescan: () => Promise<void>;
};
@@ -2,7 +2,7 @@
import { useTranslation } from "react-i18next";
import type { TFunction } from "i18next";
import { IconAlertTriangle, IconLoader2, IconRefresh } from "@tabler/icons-react";
import { IconAlertTriangle, IconChevronDown, IconLoader2, IconRefresh } from "@tabler/icons-react";
import { Button } from "@kandev/ui/button";
import {
Dialog,
@@ -24,7 +24,11 @@ import { Tooltip, TooltipContent, TooltipTrigger } from "@kandev/ui/tooltip";
import { useResponsiveBreakpoint } from "@/hooks/use-responsive-breakpoint";
import {
canApproveAgentRuntimeUpdate,
resolveRuntimeActiveVersion,
resolveRuntimeOperation,
resolveRuntimeVersionPair,
latestRuntimeVersions,
runtimeOperationLabelKey,
} from "@/lib/agent-runtime-update";
import type { AgentUpdateJob, AgentUpdatePreview, InstallJob } from "@/lib/api";
import type { RuntimeUpdate } from "@/lib/types/http";
@@ -56,7 +60,7 @@ function updatePhase(t: TFunction, status: AgentUpdateJob["status"] | undefined)
function UpdateResult({ agentName, job }: { agentName: string; job?: AgentUpdateJob }) {
const { t } = useTranslation();
if (!job) return null;
const { versionsMatch } = resolveRuntimeVersionPair(null, job);
const isUpToDate = job.operation === "up_to_date";
if (job.status === "succeeded" && job.refresh_error) {
return (
<p
@@ -75,7 +79,7 @@ function UpdateResult({ agentName, job }: { agentName: string; job?: AgentUpdate
role="status"
data-testid={`agent-update-result-${agentName}`}
>
{versionsMatch ? t("agents:runtimeAlreadyUpToDate") : t("agents:runtimeUpdatedSuccess")}
{isUpToDate ? t("agents:runtimeAlreadyUpToDate") : t("agents:runtimeUpdatedSuccess")}
</p>
);
}
@@ -101,25 +105,38 @@ type UpdateBodyProps = {
approveError: string | null;
job?: AgentUpdateJob;
onRetryPreview: () => void;
selectedTarget: string;
onSelectTarget: (targetVersion: string) => void;
starting: boolean;
};
function RuntimeVersionSummary({
agentName,
preview,
job,
}: {
agentName: string;
preview: AgentUpdatePreview;
job?: AgentUpdateJob;
}) {
const { t } = useTranslation();
const { currentVersion, targetVersion, versionsMatch } = resolveRuntimeVersionPair(preview, job);
const { currentVersion, targetVersion } = resolveRuntimeVersionPair(preview, job);
const activeVersion = resolveRuntimeActiveVersion(preview, job);
const operation = resolveRuntimeOperation(preview, job);
const isUpToDate = operation === "up_to_date";
return (
<div className="space-y-1">
<p className="font-medium">{t("agents:runtimeVersion")}</p>
<div className="space-y-1" data-testid={`agent-update-version-summary-${agentName}`}>
<p className="font-medium">{t(runtimeOperationLabelKey(operation))}</p>
<p className="break-words font-mono text-sm">
{versionsMatch ? currentVersion : `${currentVersion} → ${targetVersion}`}
{isUpToDate ? currentVersion : `${currentVersion} → ${targetVersion}`}
</p>
{versionsMatch && (
{activeVersion && (
<p className="text-sm text-muted-foreground">
{t("agents:activeRuntimeVersion", { version: activeVersion })}
</p>
)}
{isUpToDate && (
<p className="text-sm text-muted-foreground" role="status">
{t("agents:upToDate")}
</p>
@@ -128,6 +145,77 @@ function RuntimeVersionSummary({
);
}
function RuntimeVersionSelector({
agentName,
preview,
selectedTarget,
loading,
starting,
job,
onSelectTarget,
}: {
agentName: string;
preview: AgentUpdatePreview;
selectedTarget: string;
loading: boolean;
starting: boolean;
job?: AgentUpdateJob;
onSelectTarget: (targetVersion: string) => void;
}) {
const { t } = useTranslation();
const versions = latestRuntimeVersions(
preview.available_versions ?? [{ version: preview.target_version, latest: false }],
);
const activeVersion = resolveRuntimeActiveVersion(preview, job);
return (
<div className="space-y-1">
<label className="font-medium" htmlFor={`agent-update-version-${agentName}`}>
{t("agents:selectRuntimeVersion")}
</label>
<div className="relative">
<select
id={`agent-update-version-${agentName}`}
className="h-11 w-full min-w-0 appearance-none rounded-md border bg-background px-3 pr-10 text-sm sm:h-10"
value={selectedTarget || preview.target_version}
onChange={(event) => onSelectTarget(event.target.value)}
disabled={Boolean(job && ACTIVE_UPDATE_STATUSES.has(job.status)) || starting || loading}
data-testid={`agent-update-version-${agentName}`}
>
{versions.map((version) => {
const markers = [
version.latest ? t("agents:latestRuntimeVersion") : "",
version.version === activeVersion ? t("agents:activeRuntimeVersionMarker") : "",
]
.filter(Boolean)
.join(", ");
const markerLabel = markers ? t("agents:runtimeVersionMarkerGroup", { markers }) : "";
return (
<option key={version.version} value={version.version}>
{t("agents:runtimeVersionOption", {
version: version.version,
markers: markerLabel,
})}
</option>
);
})}
</select>
<span
className="pointer-events-none absolute inset-y-0 right-3 flex items-center"
data-testid={loading ? `agent-update-version-loading-${agentName}` : undefined}
role={loading ? "status" : undefined}
>
{loading ? (
<IconLoader2 className="size-4 animate-spin text-muted-foreground" />
) : (
<IconChevronDown className="size-4 text-muted-foreground" aria-hidden="true" />
)}
{loading && <span className="sr-only">{t("agents:checkingLatestRuntimeVersion")}</span>}
</span>
</div>
</div>
);
}
function UpdateBody({
agentName,
preview,
@@ -136,15 +224,18 @@ function UpdateBody({
approveError,
job,
onRetryPreview,
selectedTarget,
onSelectTarget,
starting,
}: UpdateBodyProps) {
const { t } = useTranslation();
const phase = updatePhase(t, job?.status);
return (
<div
className="max-h-[calc(80dvh-10rem)] min-h-0 space-y-4 overflow-y-auto overscroll-contain px-4 py-3 text-xs/relaxed"
className="max-h-[calc(80dvh-10rem)] min-h-0 space-y-3 overflow-y-auto overscroll-contain px-4 py-3 text-xs/relaxed"
data-testid={`agent-update-dialog-body-${agentName}`}
>
{loading && (
{loading && !preview && (
<p className="flex items-center gap-2 text-muted-foreground" role="status">
<IconLoader2 className="size-4 animate-spin" />
{t("agents:checkingLatestRuntimeVersion")}
@@ -178,7 +269,16 @@ function UpdateBody({
)}
{preview && (
<>
<RuntimeVersionSummary preview={preview} job={job} />
<RuntimeVersionSummary agentName={agentName} preview={preview} job={job} />
<RuntimeVersionSelector
agentName={agentName}
preview={preview}
selectedTarget={selectedTarget}
loading={loading}
starting={starting}
job={job}
onSelectTarget={onSelectTarget}
/>
<div className="space-y-1 text-muted-foreground">
<p>{t("agents:runtimeUpdateExplainer")}</p>
<p>{t("agents:runtimeUpdateSessionsNote")}</p>
@@ -265,7 +365,9 @@ function UpdateFooter({
data-testid={`agent-update-confirm-${agentName}`}
>
{starting && <IconLoader2 className="mr-2 size-4 animate-spin" />}
{canRetry ? t("agents:retryUpdate") : t("agents:approveUpdate")}
{canRetry
? t("agents:retryUpdate")
: t(runtimeOperationLabelKey(job?.operation ?? preview?.operation))}
</Button>
)}
</>
@@ -333,8 +435,8 @@ export function AgentRuntimeUpdateControl({
runtimeUpdate: RuntimeUpdate;
job?: AgentUpdateJob;
installJob?: InstallJob;
onPreview: (agentName: string) => Promise<AgentUpdatePreview>;
onUpdate: (agentName: string) => Promise<AgentUpdateJob>;
onPreview: (agentName: string, targetVersion?: string) => Promise<AgentUpdatePreview>;
onUpdate: (agentName: string, targetVersion: string) => Promise<AgentUpdateJob>;
}) {
const { t } = useTranslation();
const { isMobile } = useResponsiveBreakpoint();
@@ -348,6 +450,8 @@ export function AgentRuntimeUpdateControl({
open,
preview,
previewError,
selectTarget,
selectedTarget,
starting,
} = useAgentUpdateDialogState({ agentName, job, onPreview, onUpdate });
const installInFlight = installJob?.status === "queued" || installJob?.status === "running";
@@ -362,7 +466,10 @@ export function AgentRuntimeUpdateControl({
previewError={previewError}
approveError={approveError}
job={activeJob}
onRetryPreview={() => void loadPreview()}
onRetryPreview={() => void loadPreview(selectedTarget || undefined)}
selectedTarget={selectedTarget}
onSelectTarget={selectTarget}
starting={starting}
/>
);
@@ -403,7 +510,7 @@ export function AgentRuntimeUpdateControl({
) : (
<Dialog open={open} onOpenChange={handleOpenChange}>
<DialogContent
className="max-h-[80dvh] gap-0 p-0 sm:max-w-xl"
className="max-h-[80dvh] gap-0 p-0 sm:max-w-2xl"
data-testid={`agent-update-dialog-${agentName}`}
>
<DialogHeader className="px-4 pt-4">
@@ -27,7 +27,7 @@ type Props = {
updateJob?: AgentUpdateJob;
installJob?: InstallJob;
onPreview?: (agentName: string) => Promise<AgentUpdatePreview>;
onUpdate?: (agentName: string) => Promise<AgentUpdateJob>;
onUpdate?: (agentName: string, targetVersion: string) => Promise<AgentUpdateJob>;
/**
* Called when the auth/shell dialog closes so the page can refresh
* discovery + availability. Without this the yellow lock stays put even
@@ -70,11 +70,20 @@ describe("useAgentUpdateDialogState", () => {
const { result } = renderHook(() =>
useAgentUpdateDialogState({
agentName: AGENT_NAME,
onPreview: vi.fn().mockResolvedValue(FIRST_PREVIEW),
onPreview: vi.fn().mockImplementation((_agentName: string, targetVersion?: string) =>
Promise.resolve({
...FIRST_PREVIEW,
target_version: targetVersion ?? FIRST_PREVIEW.target_version,
}),
),
onUpdate,
}),
);
await act(async () => {
await result.current.loadPreview();
});
await waitFor(() => expect(result.current.preview).toEqual(FIRST_PREVIEW));
act(() => {
void result.current.approve();
});
@@ -99,6 +108,10 @@ describe("useAgentUpdateDialogState", () => {
}),
);
await act(async () => {
await result.current.loadPreview();
});
await waitFor(() => expect(result.current.preview).toEqual(FIRST_PREVIEW));
await act(async () => {
await result.current.approve();
});
@@ -107,3 +120,150 @@ describe("useAgentUpdateDialogState", () => {
expect(result.current.approveError).toBe(UPDATE_ALREADY_RUNNING);
});
});
describe("useAgentUpdateDialogState target selection", () => {
it("keeps the current preview while a selected target is loading", async () => {
const selectedTargetPreview = deferred<AgentUpdatePreview>();
const onPreview = vi
.fn<(agentName: string, targetVersion?: string) => Promise<AgentUpdatePreview>>()
.mockResolvedValueOnce(FIRST_PREVIEW)
.mockReturnValueOnce(selectedTargetPreview.promise);
const { result } = renderHook(() =>
useAgentUpdateDialogState({
agentName: AGENT_NAME,
onPreview,
onUpdate: vi.fn(),
}),
);
await act(async () => {
await result.current.loadPreview();
});
act(() => result.current.selectTarget("0.61.0"));
await waitFor(() => expect(onPreview).toHaveBeenCalledWith(AGENT_NAME, "0.61.0"));
expect(result.current.preview).toEqual(FIRST_PREVIEW);
expect(result.current.loading).toBe(true);
await act(async () => {
selectedTargetPreview.resolve({ ...FIRST_PREVIEW, target_version: "0.61.0" });
await selectedTargetPreview.promise;
});
await waitFor(() => expect(result.current.preview?.target_version).toBe("0.61.0"));
});
it("refreshes a selected target and ignores an older target response", async () => {
const first = deferred<AgentUpdatePreview>();
const olderTarget = deferred<AgentUpdatePreview>();
const newerTarget = deferred<AgentUpdatePreview>();
const onPreview = vi
.fn<(agentName: string, targetVersion?: string) => Promise<AgentUpdatePreview>>()
.mockReturnValueOnce(first.promise)
.mockReturnValueOnce(olderTarget.promise)
.mockReturnValueOnce(newerTarget.promise);
const { result } = renderHook(() =>
useAgentUpdateDialogState({
agentName: AGENT_NAME,
onPreview,
onUpdate: vi.fn(),
}),
);
act(() => void result.current.loadPreview());
await waitFor(() => expect(onPreview).toHaveBeenCalledWith(AGENT_NAME, undefined));
await act(async () => {
first.resolve(FIRST_PREVIEW);
await first.promise;
});
act(() => result.current.selectTarget("0.61.0"));
act(() => result.current.selectTarget("0.60.0"));
await waitFor(() => expect(onPreview).toHaveBeenCalledTimes(3));
await act(async () => {
olderTarget.resolve({ ...FIRST_PREVIEW, target_version: "0.61.0" });
await olderTarget.promise;
});
expect(result.current.preview).toEqual(FIRST_PREVIEW);
await act(async () => {
newerTarget.resolve({ ...FIRST_PREVIEW, target_version: "0.60.0" });
await newerTarget.promise;
});
expect(result.current.selectedTarget).toBe("0.60.0");
expect(result.current.preview?.target_version).toBe("0.60.0");
});
it("approves the selected exact target", async () => {
const onUpdate = vi.fn().mockResolvedValue({
job_id: "job-1",
agent_name: AGENT_NAME,
status: "queued",
started_at: "2026-01-01T00:00:00.000Z",
} satisfies AgentUpdateJob);
const { result } = renderHook(() =>
useAgentUpdateDialogState({
agentName: AGENT_NAME,
onPreview: vi.fn().mockImplementation((_agentName: string, targetVersion?: string) =>
Promise.resolve({
...FIRST_PREVIEW,
target_version: targetVersion ?? FIRST_PREVIEW.target_version,
}),
),
onUpdate,
}),
);
await act(async () => {
await result.current.loadPreview();
});
act(() => result.current.selectTarget("0.61.0"));
await waitFor(() => expect(result.current.selectedTarget).toBe("0.61.0"));
await act(async () => {
await result.current.approve();
});
expect(onUpdate).toHaveBeenLastCalledWith(AGENT_NAME, "0.61.0");
});
});
describe("useAgentUpdateDialogState failed target selection", () => {
it("clears a failed active job when selecting a new target", async () => {
const failedJob: AgentUpdateJob = {
job_id: "runtime-update-job-1",
agent_name: AGENT_NAME,
status: "failed",
operation: "update",
current_version: "0.62.0",
target_version: "0.63.0",
started_at: "2026-01-01T00:00:00.000Z",
finished_at: "2026-01-01T00:01:00.000Z",
error: "The package registry is unavailable",
};
const onPreview = vi.fn().mockImplementation((_agentName: string, targetVersion?: string) =>
Promise.resolve({
...FIRST_PREVIEW,
target_version: targetVersion ?? FIRST_PREVIEW.target_version,
operation: targetVersion ? "rollback" : "update",
}),
);
const { result } = renderHook(() =>
useAgentUpdateDialogState({
agentName: AGENT_NAME,
job: failedJob,
onPreview,
onUpdate: vi.fn().mockResolvedValue(failedJob),
}),
);
await act(async () => {
await result.current.loadPreview();
});
await act(async () => {
await result.current.approve();
});
await waitFor(() => expect(result.current.activeJob?.job_id).toBe(failedJob.job_id));
act(() => result.current.selectTarget("0.61.0"));
await waitFor(() => expect(result.current.preview?.target_version).toBe("0.61.0"));
expect(result.current.activeJob).toBeUndefined();
});
});
@@ -10,8 +10,8 @@ function errorMessage(error: unknown) {
type UseAgentUpdateDialogStateOptions = {
agentName: string;
job?: AgentUpdateJob;
onPreview: (agentName: string) => Promise<AgentUpdatePreview>;
onUpdate: (agentName: string) => Promise<AgentUpdateJob>;
onPreview: (agentName: string, targetVersion?: string) => Promise<AgentUpdatePreview>;
onUpdate: (agentName: string, targetVersion: string) => Promise<AgentUpdateJob>;
};
export function useAgentUpdateDialogState({
@@ -26,6 +26,7 @@ export function useAgentUpdateDialogState({
const [approveError, setApproveError] = useState<string | null>(null);
const [loading, setLoading] = useState(false);
const [starting, setStarting] = useState(false);
const [selectedTarget, setSelectedTarget] = useState("");
const [activeJobID, setActiveJobID] = useState<string | null>(null);
const previewRequestID = useRef(0);
const activeJob = activeJobID === job?.job_id ? job : undefined;
@@ -37,24 +38,39 @@ export function useAgentUpdateDialogState({
setApproveError(null);
setLoading(false);
setStarting(false);
setSelectedTarget("");
setActiveJobID(null);
}, []);
const loadPreview = useCallback(async () => {
const requestID = ++previewRequestID.current;
setLoading(true);
setPreview(null);
setPreviewError(null);
setApproveError(null);
try {
const nextPreview = await onPreview(agentName);
if (requestID === previewRequestID.current) setPreview(nextPreview);
} catch (error) {
if (requestID === previewRequestID.current) setPreviewError(errorMessage(error));
} finally {
if (requestID === previewRequestID.current) setLoading(false);
}
}, [agentName, onPreview]);
const loadPreview = useCallback(
async (targetVersion?: string) => {
const requestID = ++previewRequestID.current;
setLoading(true);
setPreviewError(null);
setApproveError(null);
try {
const nextPreview = await onPreview(agentName, targetVersion);
if (requestID === previewRequestID.current) {
setPreview(nextPreview);
setSelectedTarget(nextPreview.target_version);
}
} catch (error) {
if (requestID === previewRequestID.current) setPreviewError(errorMessage(error));
} finally {
if (requestID === previewRequestID.current) setLoading(false);
}
},
[agentName, onPreview],
);
const selectTarget = useCallback(
(targetVersion: string) => {
setActiveJobID(null);
setSelectedTarget(targetVersion);
void loadPreview(targetVersion);
},
[loadPreview],
);
useEffect(() => {
if (open) void loadPreview();
@@ -67,10 +83,12 @@ export function useAgentUpdateDialogState({
const approve = async () => {
const requestID = previewRequestID.current;
const targetVersion = selectedTarget || preview?.target_version || "";
if (!targetVersion) return;
setStarting(true);
setApproveError(null);
try {
const nextJob = await onUpdate(agentName);
const nextJob = await onUpdate(agentName, targetVersion);
if (requestID === previewRequestID.current) setActiveJobID(nextJob.job_id);
} catch (error) {
if (requestID === previewRequestID.current) setApproveError(errorMessage(error));
@@ -89,6 +107,8 @@ export function useAgentUpdateDialogState({
open,
preview,
previewError,
selectTarget,
selectedTarget,
starting,
};
}
@@ -4,11 +4,14 @@ const AGENT_NAME = "claude-acp";
const NOW = "2026-07-26T12:00:00.000Z";
type UpdateStatus = "queued" | "resolving" | "updating" | "refreshing" | "succeeded" | "failed";
type UpdateOperation = "update" | "rollback" | "repair" | "up_to_date";
type UpdateJob = {
job_id: string;
agent_name: string;
status: UpdateStatus;
operation?: UpdateOperation;
active_version?: string;
current_version?: string;
target_version?: string;
output?: string;
@@ -22,7 +25,10 @@ type UpdatePreview = {
agent_name: string;
package: string;
current_version: string;
active_version?: string;
target_version: string;
operation?: UpdateOperation;
available_versions?: Array<{ version: string; latest: boolean }>;
command: string[];
command_string: string;
};
@@ -59,6 +65,7 @@ function catalogue(models: Array<{ id: string; name: string }>, displayName = "C
supported: true,
package: "@agentclientprotocol/claude-agent-acp",
current_version: "0.62.0",
active_version: "0.62.0",
},
updated_at: NOW,
},
@@ -99,10 +106,28 @@ function event(action: string, payload: unknown) {
});
}
function compareStableVersions(left: string, right: string) {
const leftParts = left.split(".").map(Number);
const rightParts = right.split(".").map(Number);
for (let index = 0; index < 3; index += 1) {
if (leftParts[index] !== rightParts[index])
return leftParts[index] > rightParts[index] ? 1 : -1;
}
return 0;
}
function operationForTarget(currentVersion: string, targetVersion: string): UpdateOperation {
const comparison = compareStableVersions(targetVersion, currentVersion);
if (comparison === 0) return "up_to_date";
return comparison > 0 ? "update" : "rollback";
}
export type RuntimeUpdateFixtureOptions = {
retainedJobs?: UpdateJob[];
postResponse?: UpdateJob;
previewResponse?: UpdatePreview;
previewFailures?: string[];
previewDelayMs?: number;
};
export async function installRuntimeUpdateFixture(
@@ -122,6 +147,10 @@ export async function installRuntimeUpdateFixture(
} satisfies UpdateJob);
let postCount = 0;
let previewCount = 0;
const previewTargets: string[] = [];
const postTargets: string[] = [];
const previewFailures = [...(options.previewFailures ?? [])];
const previewDelayMs = options.previewDelayMs ?? 0;
let previewResponse: UpdatePreview =
options.previewResponse ??
({
@@ -129,6 +158,14 @@ export async function installRuntimeUpdateFixture(
package: "@agentclientprotocol/claude-agent-acp",
current_version: "0.62.0",
target_version: "0.63.0",
operation: "update",
active_version: "0.62.0",
available_versions: [
{ version: "0.64.0", latest: true },
{ version: "0.63.0", latest: false },
{ version: "0.62.0", latest: false },
{ version: "0.61.0", latest: false },
],
command: [
"npm",
"exec",
@@ -167,7 +204,7 @@ export async function installRuntimeUpdateFixture(
body: JSON.stringify(savedAgents()),
}),
);
await page.route("**/api/v1/agent-update/**", (route) => {
await page.route("**/api/v1/agent-update/**", async (route) => {
const request = route.request();
const url = new URL(request.url());
if (
@@ -175,10 +212,30 @@ export async function installRuntimeUpdateFixture(
url.pathname.endsWith(`/agent-update/${AGENT_NAME}/preview`)
) {
previewCount += 1;
previewTargets.push(url.searchParams.get("target_version") ?? "");
const requestedTarget = url.searchParams.get("target_version");
if (requestedTarget && previewFailures.includes(requestedTarget)) {
previewFailures.splice(previewFailures.indexOf(requestedTarget), 1);
return route.fulfill({
status: 503,
contentType: "application/json",
body: JSON.stringify({ error: "preview temporarily unavailable" }),
});
}
if (requestedTarget && previewDelayMs > 0) {
await new Promise((resolve) => setTimeout(resolve, previewDelayMs));
}
const response = requestedTarget
? {
...previewResponse,
target_version: requestedTarget,
operation: operationForTarget(previewResponse.current_version, requestedTarget),
}
: previewResponse;
return route.fulfill({
status: 200,
contentType: "application/json",
body: JSON.stringify(previewResponse),
body: JSON.stringify(response),
});
}
if (request.method() === "GET" && url.pathname.endsWith("/agent-update/jobs")) {
@@ -190,6 +247,8 @@ export async function installRuntimeUpdateFixture(
}
if (request.method() === "POST" && url.pathname.endsWith(`/agent-update/${AGENT_NAME}`)) {
postCount += 1;
const body = request.postDataJSON() as { target_version?: string } | null;
postTargets.push(body?.target_version ?? "");
return route.fulfill({
status: 202,
contentType: "application/json",
@@ -241,6 +300,8 @@ export async function installRuntimeUpdateFixture(
},
postCount: () => postCount,
previewCount: () => previewCount,
previewTargets: () => [...previewTargets],
postTargets: () => [...postTargets],
async emit(action: string, payload: unknown) {
await expect.poll(() => Boolean(socket)).toBe(true);
await expect.poll(() => clientReady).toBe(true);
@@ -274,6 +335,7 @@ export function updateJob(overrides: Partial<UpdateJob> = {}): UpdateJob {
status: "updating",
current_version: "0.62.0",
target_version: "0.63.0",
operation: "update",
output: "Downloading @agentclientprotocol/claude-agent-acp…\n",
started_at: NOW,
...overrides,
@@ -33,6 +33,14 @@ test.describe("managed agent runtime updates", () => {
await trigger.click();
const dialog = testPage.getByTestId(`agent-update-dialog-${runtime.agentName}`);
await expect(dialog).toBeVisible();
const dialogBox = await dialog.boundingBox();
expect(dialogBox).not.toBeNull();
expect(dialogBox!.width).toBeGreaterThanOrEqual(640);
const selectorBox = await dialog
.getByTestId(`agent-update-version-${runtime.agentName}`)
.boundingBox();
expect(selectorBox).not.toBeNull();
expect(selectorBox!.height).toBeLessThanOrEqual(40);
await expect(dialog).toContainText("0.62.0 → 0.63.0");
await expect(dialog).toContainText(
'npm exec --yes --prefer-online --package=@agentclientprotocol/claude-agent-acp -- node -e ""',
@@ -51,6 +59,7 @@ test.describe("managed agent runtime updates", () => {
await testPage.getByTestId(`agent-update-confirm-${runtime.agentName}`).click();
expect(runtime.postCount()).toBe(1);
expect(runtime.postTargets()).toEqual(["0.63.0"]);
await runtime.emitUpdate(updateJob());
await runtime.emitOutput("Installed @agentclientprotocol/claude-agent-acp@0.63.0\n");
@@ -115,6 +124,7 @@ test.describe("managed agent runtime updates", () => {
package: "@agentclientprotocol/claude-agent-acp",
current_version: "0.64.0",
target_version: "0.64.0",
operation: "up_to_date",
command: ["npm", "exec"],
command_string: "npm exec",
},
@@ -124,8 +134,12 @@ test.describe("managed agent runtime updates", () => {
await testPage.getByTestId(`agent-update-trigger-${runtime.agentName}`).click();
const dialog = testPage.getByTestId(`agent-update-dialog-${runtime.agentName}`);
await expect(dialog.getByText("0.64.0", { exact: true })).toBeVisible();
await expect(dialog.getByText("Up to date", { exact: true })).toBeVisible();
await expect(
dialog.getByTestId(`agent-update-version-summary-${runtime.agentName}`).getByText("0.64.0", {
exact: true,
}),
).toBeVisible();
await expect(dialog.getByRole("status").filter({ hasText: "Up to date" })).toBeVisible();
await expect(dialog).not.toContainText("0.64.0 → 0.64.0");
await expect(testPage.getByTestId(`agent-update-confirm-${runtime.agentName}`)).toBeDisabled();
expect(runtime.postCount()).toBe(0);
@@ -134,10 +148,146 @@ test.describe("managed agent runtime updates", () => {
});
});
test("uses the job versions for a stale retry decision", async ({ testPage }) => {
test("keeps repair distinct when observed and target versions match", async ({ testPage }) => {
const runtime = await installRuntimeUpdateFixture(testPage, {
previewResponse: {
agent_name: "claude-acp",
package: "@agentclientprotocol/claude-agent-acp",
current_version: "0.64.0",
target_version: "0.64.0",
operation: "repair",
command: ["npm", "exec"],
command_string: "npm exec",
},
});
await testPage.goto("/settings/agents");
await testPage.getByTestId(`agent-update-trigger-${runtime.agentName}`).click();
const dialog = testPage.getByTestId(`agent-update-dialog-${runtime.agentName}`);
const summary = dialog.getByTestId(`agent-update-version-summary-${runtime.agentName}`);
await expect(summary).toContainText("Repair runtime");
await expect(summary).toContainText("0.64.0 → 0.64.0");
await expect(summary.getByText("Up to date", { exact: true })).toHaveCount(0);
const confirm = testPage.getByTestId(`agent-update-confirm-${runtime.agentName}`);
await expect(confirm).toBeEnabled();
await confirm.click();
await runtime.emitUpdate(
updateJob({
status: "succeeded",
operation: "repair",
current_version: "0.64.0",
target_version: "0.64.0",
finished_at: "2026-07-26T12:01:00.000Z",
}),
);
await expect(dialog.getByTestId(`agent-update-result-${runtime.agentName}`)).toContainText(
"Runtime updated successfully",
);
});
test("selects an older stable version for rollback", async ({ testPage }) => {
const runtime = await installRuntimeUpdateFixture(testPage);
await testPage.goto("/settings/agents");
await testPage.getByTestId(`agent-update-trigger-${runtime.agentName}`).click();
const dialog = testPage.getByTestId(`agent-update-dialog-${runtime.agentName}`);
await testPage.getByTestId(`agent-update-version-${runtime.agentName}`).selectOption("0.61.0");
await expect(dialog).toContainText("0.62.0 → 0.61.0");
await expect(testPage.getByTestId(`agent-update-confirm-${runtime.agentName}`)).toHaveText(
"Roll back runtime",
);
await testPage.getByTestId(`agent-update-confirm-${runtime.agentName}`).click();
expect(runtime.postTargets()).toEqual(["0.61.0"]);
expect(runtime.previewTargets()).toEqual(["", "0.61.0"]);
});
test("keeps the dialog content visible while changing versions", async ({ testPage }) => {
const runtime = await installRuntimeUpdateFixture(testPage, { previewDelayMs: 500 });
await testPage.goto("/settings/agents");
await testPage.getByTestId(`agent-update-trigger-${runtime.agentName}`).click();
const dialog = testPage.getByTestId(`agent-update-dialog-${runtime.agentName}`);
const body = dialog.getByTestId(`agent-update-dialog-body-${runtime.agentName}`);
await dialog.getByTestId(`agent-update-version-${runtime.agentName}`).selectOption("0.61.0");
await expect(
dialog.getByTestId(`agent-update-version-loading-${runtime.agentName}`),
).toBeVisible();
await expect(body).toContainText("Active sessions keep running");
await expect(body).toContainText("Command that will run");
await expect(dialog.getByTestId(`agent-update-version-${runtime.agentName}`)).toBeDisabled();
await expect(
dialog.getByTestId(`agent-update-version-loading-${runtime.agentName}`),
).toBeHidden();
});
test("limits the version selector to the ten newest options", async ({ testPage }) => {
const runtime = await installRuntimeUpdateFixture(testPage);
runtime.setPreviewResponse({
agent_name: "claude-acp",
package: "@agentclientprotocol/claude-agent-acp",
current_version: "0.62.0",
target_version: "0.74.0",
operation: "update",
active_version: "0.62.0",
available_versions: Array.from({ length: 12 }, (_, index) => ({
version: `0.${74 - index}.0`,
latest: index === 0,
})),
command: ["npm", "exec"],
command_string: "npm exec",
});
await testPage.goto("/settings/agents");
await testPage.getByTestId(`agent-update-trigger-${runtime.agentName}`).click();
const options = testPage
.getByTestId(`agent-update-version-${runtime.agentName}`)
.locator("option");
await expect(options).toHaveCount(10);
expect(
await options.evaluateAll((elements) =>
elements.map((element) => (element as HTMLOptionElement).value),
),
).toEqual([
"0.74.0",
"0.73.0",
"0.72.0",
"0.71.0",
"0.70.0",
"0.69.0",
"0.68.0",
"0.67.0",
"0.66.0",
"0.65.0",
]);
});
test("retries a failed preview for the selected target", async ({ testPage }) => {
const runtime = await installRuntimeUpdateFixture(testPage, {
previewFailures: ["0.61.0"],
});
await testPage.goto("/settings/agents");
await testPage.getByTestId(`agent-update-trigger-${runtime.agentName}`).click();
const dialog = testPage.getByTestId(`agent-update-dialog-${runtime.agentName}`);
await testPage.getByTestId(`agent-update-version-${runtime.agentName}`).selectOption("0.61.0");
await expect(dialog.getByRole("alert")).toContainText("preview temporarily unavailable");
await dialog.getByRole("button", { name: "Retry version check" }).click();
await expect(dialog).toContainText("0.62.0 → 0.61.0");
expect(runtime.previewTargets()).toEqual(["", "0.61.0", "0.61.0"]);
});
test("uses the job operation for a stale retry decision", async ({ testPage }) => {
const runtime = await installRuntimeUpdateFixture(testPage, {
postResponse: updateJob({
status: "failed",
operation: "up_to_date",
active_version: "0.63.0",
current_version: "0.63.0",
target_version: "0.63.0",
error: "The package registry is unavailable",
@@ -151,8 +301,12 @@ test.describe("managed agent runtime updates", () => {
const retryUpdate = testPage.getByTestId(`agent-update-confirm-${runtime.agentName}`);
await retryUpdate.click();
await expect(dialog.getByText("0.63.0", { exact: true })).toBeVisible();
await expect(dialog.getByText("Up to date", { exact: true })).toBeVisible();
await expect(
dialog.getByTestId(`agent-update-version-summary-${runtime.agentName}`).getByText("0.63.0", {
exact: true,
}),
).toBeVisible();
await expect(dialog.getByRole("status").filter({ hasText: "Up to date" })).toBeVisible();
await expect(retryUpdate).toHaveText("Retry update");
await expect(retryUpdate).toBeDisabled();
expect(runtime.postCount()).toBe(1);
@@ -180,4 +334,60 @@ test.describe("managed agent runtime updates", () => {
await retryUpdate.click();
expect(runtime.postCount()).toBe(2);
});
test("shows the newly activated version after a successful job", async ({ testPage }) => {
const runtime = await installRuntimeUpdateFixture(testPage);
await testPage.goto("/settings/agents");
await testPage.getByTestId(`agent-update-trigger-${runtime.agentName}`).click();
const dialog = testPage.getByTestId(`agent-update-dialog-${runtime.agentName}`);
await testPage.getByTestId(`agent-update-confirm-${runtime.agentName}`).click();
await runtime.emitUpdate(
updateJob({
status: "succeeded",
current_version: "0.63.0",
active_version: "0.63.0",
target_version: "0.63.0",
finished_at: "2026-07-26T12:01:00.000Z",
}),
);
await expect(dialog).toContainText("Active version: 0.63.0");
const successOptionText = await dialog
.getByTestId(`agent-update-version-${runtime.agentName}`)
.locator("option")
.allTextContents();
expect(
successOptionText.some((text) => text.includes("0.63.0") && text.includes("active")),
).toBe(true);
});
test("keeps the previous active version after a failed activation", async ({ testPage }) => {
const runtime = await installRuntimeUpdateFixture(testPage);
await testPage.goto("/settings/agents");
await testPage.getByTestId(`agent-update-trigger-${runtime.agentName}`).click();
const dialog = testPage.getByTestId(`agent-update-dialog-${runtime.agentName}`);
await testPage.getByTestId(`agent-update-confirm-${runtime.agentName}`).click();
await runtime.emitUpdate(
updateJob({
status: "failed",
active_version: "0.62.0",
error: "candidate ACP probe failed",
finished_at: "2026-07-26T12:01:00.000Z",
}),
);
await expect(dialog).toContainText("Active version: 0.62.0");
const failedOptionText = await dialog
.getByTestId(`agent-update-version-${runtime.agentName}`)
.locator("option")
.allTextContents();
expect(
failedOptionText.some((text) => text.includes("0.62.0") && text.includes("active")),
).toBe(true);
expect(
failedOptionText.some((text) => text.includes("0.63.0") && text.includes("active")),
).toBe(false);
});
});
@@ -26,6 +26,7 @@ test.describe("managed agent runtime updates on mobile", () => {
});
await testPage.getByTestId(`agent-update-confirm-${runtime.agentName}`).tap();
expect(runtime.postCount()).toBe(1);
expect(runtime.postTargets()).toEqual(["0.63.0"]);
await runtime.emitUpdate(
updateJob({
@@ -60,6 +61,7 @@ test.describe("managed agent runtime updates on mobile", () => {
package: "@agentclientprotocol/claude-agent-acp",
current_version: "0.64.0",
target_version: "0.64.0",
operation: "up_to_date",
command: ["npm", "exec"],
command_string: "npm exec",
},
@@ -69,8 +71,12 @@ test.describe("managed agent runtime updates on mobile", () => {
await testPage.getByTestId(`agent-update-trigger-${runtime.agentName}`).tap();
const drawer = testPage.getByTestId(`agent-update-drawer-${runtime.agentName}`);
await expect(drawer.getByText("0.64.0", { exact: true })).toBeVisible();
await expect(drawer.getByText("Up to date", { exact: true })).toBeVisible();
await expect(
drawer.getByTestId(`agent-update-version-summary-${runtime.agentName}`).getByText("0.64.0", {
exact: true,
}),
).toBeVisible();
await expect(drawer.getByRole("status").filter({ hasText: "Up to date" })).toBeVisible();
await expect(drawer).not.toContainText("0.64.0 → 0.64.0");
await expect(testPage.getByTestId(`agent-update-confirm-${runtime.agentName}`)).toBeDisabled();
expect(runtime.postCount()).toBe(0);
@@ -79,6 +85,27 @@ test.describe("managed agent runtime updates on mobile", () => {
});
});
test("selects an older stable version for rollback in the drawer", async ({ testPage }) => {
const runtime = await installRuntimeUpdateFixture(testPage);
await testPage.goto("/settings/agents");
await testPage.getByTestId(`agent-update-trigger-${runtime.agentName}`).tap();
const drawer = testPage.getByTestId(`agent-update-drawer-${runtime.agentName}`);
const selector = drawer.getByTestId(`agent-update-version-${runtime.agentName}`);
const selectorBox = await selector.boundingBox();
expect(selectorBox).not.toBeNull();
expect(selectorBox!.height).toBeGreaterThanOrEqual(44);
await selector.selectOption("0.61.0");
await expect(drawer).toContainText("0.62.0 → 0.61.0");
await expect(testPage.getByTestId(`agent-update-confirm-${runtime.agentName}`)).toHaveText(
"Roll back runtime",
);
await testPage.getByTestId(`agent-update-confirm-${runtime.agentName}`).tap();
expect(runtime.postTargets()).toEqual(["0.61.0"]);
expect(runtime.previewTargets()).toEqual(["", "0.61.0"]);
});
test("keeps retry available after an update job fails", async ({ testPage }) => {
const runtime = await installRuntimeUpdateFixture(testPage);
@@ -69,7 +69,7 @@ describe("useAgentRuntimeUpdates", () => {
const { result } = render();
await expect(result.current.startUpdate(AGENT)).rejects.toThrow(
await expect(result.current.startUpdate(AGENT, "1.1.0")).rejects.toThrow(
"Agent installation is already in progress.",
);
expect(getInstallJobMock).toHaveBeenCalledWith("job-1", { cache: "no-store" });
@@ -83,7 +83,9 @@ describe("useAgentRuntimeUpdates", () => {
const { result } = render();
await expect(result.current.startUpdate(AGENT)).resolves.toMatchObject({ job_id: "job-1" });
await expect(result.current.startUpdate(AGENT, "1.1.0")).resolves.toMatchObject({
job_id: "job-1",
});
expect(getAgentUpdateJobMock).toHaveBeenCalledWith("job-1", { cache: "no-store" });
});
@@ -92,7 +94,7 @@ describe("useAgentRuntimeUpdates", () => {
const { result } = render();
await expect(result.current.startUpdate(AGENT)).rejects.toThrow("network down");
await expect(result.current.startUpdate(AGENT, "1.1.0")).rejects.toThrow("network down");
expect(getInstallJobMock).not.toHaveBeenCalled();
expect(getAgentUpdateJobMock).not.toHaveBeenCalled();
});
@@ -102,6 +104,8 @@ describe("useAgentRuntimeUpdates", () => {
const { result } = render();
await expect(result.current.startUpdate(AGENT)).resolves.toMatchObject({ status: "queued" });
await expect(result.current.startUpdate(AGENT, "1.1.0")).resolves.toMatchObject({
status: "queued",
});
});
});
@@ -52,9 +52,9 @@ export function useAgentRuntimeUpdates() {
);
const startUpdate = useCallback(
async (agentName: string) => {
async (agentName: string, targetVersion: string) => {
try {
const job = await updateAgent(agentName);
const job = await updateAgent(agentName, targetVersion);
store.getState().upsertAgentUpdateJob(job);
return job;
} catch (error) {
@@ -69,7 +69,8 @@ export function useAgentRuntimeUpdates() {
);
const previewUpdate = useCallback(
(agentName: string) => previewAgentUpdate(agentName, { cache: "no-store" }),
(agentName: string, targetVersion?: string) =>
previewAgentUpdate(agentName, targetVersion, { cache: "no-store" }),
[],
);
+60 -1
View File
@@ -1,7 +1,25 @@
import { afterEach, describe, expect, it } from "vitest";
import i18n from "i18next";
import type { AgentUpdateJob, AgentUpdatePreview } from "@/lib/api";
import { canApproveAgentRuntimeUpdate, resolveRuntimeVersionPair } from "./agent-runtime-update";
import {
canApproveAgentRuntimeUpdate,
latestRuntimeVersions,
resolveRuntimeActiveVersion,
resolveRuntimeOperation,
resolveRuntimeVersionPair,
runtimeOperationLabelKey,
} from "./agent-runtime-update";
describe("latestRuntimeVersions", () => {
it("limits the selector to the ten newest options", () => {
const versions = Array.from({ length: 12 }, (_, index) => ({
version: `1.0.${12 - index}`,
latest: index === 0,
}));
expect(latestRuntimeVersions(versions)).toEqual(versions.slice(0, 10));
});
});
const preview = (overrides: Partial<AgentUpdatePreview> = {}): AgentUpdatePreview => ({
agent_name: "claude-acp",
@@ -46,6 +64,26 @@ describe("resolveRuntimeVersionPair", () => {
});
});
describe("resolveRuntimeActiveVersion", () => {
it("uses the successful job activation snapshot", () => {
expect(
resolveRuntimeActiveVersion(
preview({ active_version: "0.62.0" }),
job({ status: "succeeded", active_version: "0.63.0" }),
),
).toBe("0.63.0");
});
it("keeps the preview selection when activation fails", () => {
expect(
resolveRuntimeActiveVersion(
preview({ active_version: "0.62.0" }),
job({ status: "failed", active_version: "0.62.0" }),
),
).toBe("0.62.0");
});
});
describe("canApproveAgentRuntimeUpdate", () => {
const ready = {
preview: preview(),
@@ -60,6 +98,7 @@ describe("canApproveAgentRuntimeUpdate", () => {
it.each([
["differing versions", ready, true],
["equal versions", { ...ready, preview: preview({ target_version: "0.62.0" }) }, false],
["up-to-date operation", { ...ready, preview: preview({ operation: "up_to_date" }) }, false],
["missing current version", { ...ready, preview: preview({ current_version: "" }) }, false],
["missing target version", { ...ready, preview: preview({ target_version: "" }) }, false],
["loading preview", { ...ready, loading: true }, false],
@@ -75,6 +114,26 @@ describe("canApproveAgentRuntimeUpdate", () => {
])("returns %s = %s", (_name, state, expected) => {
expect(canApproveAgentRuntimeUpdate(state)).toBe(expected);
});
it("allows a repair when the backend says the observed version is unknown", () => {
expect(
canApproveAgentRuntimeUpdate({
...ready,
preview: preview({ current_version: "", operation: "repair" }),
}),
).toBe(true);
});
it("uses operation state instead of translated labels", () => {
const state = preview({ operation: "rollback" });
expect(resolveRuntimeOperation(state)).toBe("rollback");
expect(
resolveRuntimeOperation(preview({ operation: "update" }), job({ operation: "repair" })),
).toBe("repair");
expect(runtimeOperationLabelKey("rollback")).toBe("agents:rollBackRuntime");
expect(runtimeOperationLabelKey("repair")).toBe("agents:repairRuntime");
expect(runtimeOperationLabelKey("up_to_date")).toBe("agents:upToDateRuntime");
});
});
/**
+46 -3
View File
@@ -1,6 +1,17 @@
import type { AgentUpdateJob, AgentUpdatePreview } from "@/lib/api";
import type {
AgentUpdateJob,
AgentUpdateOperation,
AgentUpdatePreview,
AgentUpdateVersion,
} from "@/lib/api";
import { t } from "@/lib/i18n";
const MAX_VISIBLE_RUNTIME_VERSIONS = 10;
export function latestRuntimeVersions(versions: AgentUpdateVersion[]): AgentUpdateVersion[] {
return versions.slice(0, MAX_VISIBLE_RUNTIME_VERSIONS);
}
export type RuntimeVersionPair = {
/** Display copy — localized, and therefore never compared. */
currentVersion: string;
@@ -28,6 +39,34 @@ export function resolveRuntimeVersionPair(
return { currentVersion, hasCurrentVersion: Boolean(reported), targetVersion, versionsMatch };
}
export function resolveRuntimeActiveVersion(
preview: AgentUpdatePreview,
job?: AgentUpdateJob,
): string | undefined {
return job?.active_version ?? preview.active_version;
}
export function resolveRuntimeOperation(
preview: AgentUpdatePreview | null,
job?: AgentUpdateJob,
): AgentUpdateOperation | undefined {
return job?.operation ?? preview?.operation;
}
export function runtimeOperationLabelKey(operation: AgentUpdateOperation | undefined): string {
switch (operation) {
case "rollback":
return "agents:rollBackRuntime";
case "repair":
return "agents:repairRuntime";
case "up_to_date":
return "agents:upToDateRuntime";
case "update":
default:
return "agents:updateRuntime";
}
}
export function canApproveAgentRuntimeUpdate({
preview,
job,
@@ -45,12 +84,16 @@ export function canApproveAgentRuntimeUpdate({
starting: boolean;
installInFlight: boolean;
}): boolean {
const { currentVersion, hasCurrentVersion, targetVersion } = resolveRuntimeVersionPair(
const { hasCurrentVersion, targetVersion, versionsMatch } = resolveRuntimeVersionPair(
preview,
job,
);
const operation = resolveRuntimeOperation(preview, job);
const operationAllowsApproval = operation
? operation !== "up_to_date"
: hasCurrentVersion && !versionsMatch;
return (
Boolean(preview && hasCurrentVersion && targetVersion && currentVersion !== targetVersion) &&
Boolean(preview && targetVersion && operationAllowsApproval) &&
!previewError &&
!loading &&
!updateInFlight &&
@@ -0,0 +1,50 @@
import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
vi.mock("@/lib/config", () => ({
getBackendConfig: () => ({ apiBaseUrl: "http://api.test" }),
}));
import { previewAgentUpdate, updateAgent } from "./agent-update-api";
const fetchSpy = vi.fn<typeof fetch>();
beforeEach(() => {
fetchSpy.mockReset();
fetchSpy.mockResolvedValue(
new Response(
JSON.stringify({
agent_name: "opencode-acp",
package: "opencode-ai",
target_version: "1.18.5",
operation: "rollback",
available_versions: [],
command: [],
command_string: "",
}),
{ status: 200, headers: { "Content-Type": "application/json" } },
),
);
vi.stubGlobal("fetch", fetchSpy);
});
afterEach(() => vi.unstubAllGlobals());
describe("managed runtime update API", () => {
it("encodes an optional exact target in the preview query", async () => {
await previewAgentUpdate("opencode-acp", "1.18.5", { cache: "no-store" });
const [input, init] = fetchSpy.mock.calls[0] ?? [];
expect(String(input)).toBe(
"http://api.test/api/v1/agent-update/opencode-acp/preview?target_version=1.18.5",
);
expect(init?.cache).toBe("no-store");
});
it("sends only the exact target version in the update body", async () => {
await updateAgent("opencode-acp", "1.18.5");
const [, init] = fetchSpy.mock.calls[0] ?? [];
expect(init?.method).toBe("POST");
expect(init?.body).toBe(JSON.stringify({ target_version: "1.18.5" }));
});
});
+25 -3
View File
@@ -8,11 +8,20 @@ export type AgentUpdateJobStatus =
| "succeeded"
| "failed";
export type AgentUpdateOperation = "update" | "rollback" | "repair" | "up_to_date";
export type AgentUpdateVersion = {
version: string;
latest: boolean;
};
export type AgentUpdateJob = {
job_id: string;
agent_name: string;
status: AgentUpdateJobStatus;
operation?: AgentUpdateOperation;
current_version?: string;
active_version?: string;
target_version?: string;
output?: string;
error?: string;
@@ -25,25 +34,38 @@ export type AgentUpdatePreview = {
agent_name: string;
package: string;
current_version?: string;
active_version?: string;
target_version: string;
operation?: AgentUpdateOperation;
available_versions?: AgentUpdateVersion[];
command: string[];
command_string: string;
};
export async function previewAgentUpdate(
agentName: string,
targetVersion?: string,
options?: ApiRequestOptions,
): Promise<AgentUpdatePreview> {
return fetchJson<AgentUpdatePreview>(`/api/v1/agent-update/${agentName}/preview`, options);
const query = targetVersion ? `?${new URLSearchParams({ target_version: targetVersion })}` : "";
return fetchJson<AgentUpdatePreview>(
`/api/v1/agent-update/${encodeURIComponent(agentName)}/preview${query}`,
options,
);
}
export async function updateAgent(
agentName: string,
targetVersion: string,
options?: ApiRequestOptions,
): Promise<AgentUpdateJob> {
return fetchJson<AgentUpdateJob>(`/api/v1/agent-update/${agentName}`, {
return fetchJson<AgentUpdateJob>(`/api/v1/agent-update/${encodeURIComponent(agentName)}`, {
...options,
init: { method: "POST", ...(options?.init ?? {}) },
init: {
method: "POST",
body: JSON.stringify({ target_version: targetVersion }),
...(options?.init ?? {}),
},
});
}
+1
View File
@@ -217,6 +217,7 @@ export type RuntimeUpdate = {
supported: boolean;
package: string;
current_version?: string;
active_version?: string;
};
export type AvailableAgent = {
+10
View File
@@ -181,6 +181,16 @@
"runtimeUpdatedRefreshFailed": "Runtime updated, but capabilities could not be refreshed: {{error}}",
"runtimeUpdatedSuccess": "Runtime updated successfully.",
"runtimeVersion": "Runtime version",
"activeRuntimeVersion": "Active version: {{version}}",
"activeRuntimeVersionMarker": "active",
"latestRuntimeVersion": "latest",
"runtimeVersionMarkerGroup": "({{markers}})",
"runtimeVersionOption": "{{version}} {{markers}}",
"selectRuntimeVersion": "Version to activate",
"updateRuntime": "Update runtime",
"rollBackRuntime": "Roll back runtime",
"repairRuntime": "Repair runtime",
"upToDateRuntime": "Up to date",
"scanningForInstalledAgents": "Scanning for installed agents...",
"searchModels": "Search models...",
"searchModes": "Search modes...",
+10
View File
@@ -181,6 +181,16 @@
"runtimeUpdatedRefreshFailed": "Ŕũńţĩḿē ũƥďàţēď, ƀũţ ćàƥàƀĩĺĩţĩēś ćōũĺď ńōţ ƀē ŕēƒŕēśĥēď: {{error}}",
"runtimeUpdatedSuccess": "Ŕũńţĩḿē ũƥďàţēď śũććēśśƒũĺĺŷ.",
"runtimeVersion": "Ŕũńţĩḿē vēŕśĩōń",
"activeRuntimeVersion": "Àćţĩvē vēŕśĩōń: {{version}}",
"activeRuntimeVersionMarker": "àćţĩvē",
"latestRuntimeVersion": "ĺàţēśţ",
"runtimeVersionMarkerGroup": "({{markers}})",
"runtimeVersionOption": "{{version}} {{markers}}",
"selectRuntimeVersion": "Vēŕśĩōń ţō àćţĩvàţē",
"updateRuntime": "Ũƥďàţē ŕũńţĩḿē",
"rollBackRuntime": "Ŕōĺĺ ƀàćķ ŕũńţĩḿē",
"repairRuntime": "Ŕēƥàĩŕ ŕũńţĩḿē",
"upToDateRuntime": "Ũƥ ţō ďàţē",
"scanningForInstalledAgents": "Śćàńńĩńĝ ƒōŕ ĩńśţàĺĺēď àĝēńţś...",
"searchModels": "Śēàŕćĥ ḿōďēĺś...",
"searchModes": "Śēàŕćĥ ḿōďēś...",
+10
View File
@@ -173,6 +173,16 @@
"runtimeUpdatedRefreshFailed": "O runtime foi atualizado, mas não foi possível atualizar as capacidades: {{error}}",
"runtimeUpdatedSuccess": "Runtime atualizado com êxito.",
"runtimeVersion": "Versão do runtime",
"activeRuntimeVersion": "Versão ativa: {{version}}",
"activeRuntimeVersionMarker": "ativa",
"latestRuntimeVersion": "mais recente",
"runtimeVersionMarkerGroup": "({{markers}})",
"runtimeVersionOption": "{{version}} {{markers}}",
"selectRuntimeVersion": "Versão a ativar",
"updateRuntime": "Atualizar runtime",
"rollBackRuntime": "Reverter runtime",
"repairRuntime": "Reparar runtime",
"upToDateRuntime": "Atualizado",
"scanningForInstalledAgents": "À procura de agentes instalados...",
"searchModels": "Pesquisar modelos...",
"searchModes": "Pesquisar modos...",
+10
View File
@@ -181,6 +181,16 @@
"runtimeUpdatedRefreshFailed": "运行时已更新,但无法刷新能力:{{error}}",
"runtimeUpdatedSuccess": "运行时更新成功。",
"runtimeVersion": "运行时版本",
"activeRuntimeVersion": "活动版本:{{version}}",
"activeRuntimeVersionMarker": "活动",
"latestRuntimeVersion": "最新",
"runtimeVersionMarkerGroup": "({{markers}})",
"runtimeVersionOption": "{{version}} {{markers}}",
"selectRuntimeVersion": "要激活的版本",
"updateRuntime": "更新运行时",
"rollBackRuntime": "回滚运行时",
"repairRuntime": "修复运行时",
"upToDateRuntime": "已是最新",
"scanningForInstalledAgents": "正在扫描已安装的代理…",
"searchModels": "搜索模型…",
"searchModes": "搜索模式…",
@@ -1,6 +1,7 @@
# ADR-2026-07-26-user-managed-agent-runtime-updates: User-Managed Agent Runtime Updates
**Status:** accepted
**Status:** superseded by
[ADR-2026-08-12-validated-managed-runtime-version-selection](2026-08-12-validated-managed-runtime-version-selection.md)
**Date:** 2026-07-26
**Area:** backend, frontend, protocol
@@ -0,0 +1,87 @@
# ADR-2026-08-12-validated-managed-runtime-version-selection: Validate and Persist Managed Runtime Version Selection
**Status:** accepted
**Date:** 2026-08-12
**Area:** backend, frontend, protocol
**Supersedes:**
[ADR-2026-07-26-user-managed-agent-runtime-updates](2026-07-26-user-managed-agent-runtime-updates.md)
## Context
Kandev originally invoked managed npm ACP runtimes by an unversioned package
name. The Settings action could prepare the current npm `latest` target, but it
could not select an older version. This made recovery impossible when an npm
release was only partly published, platform artifacts were missing, or the
latest runtime failed ACP initialization. Clearing the matching `_npx` tree did
not help because the next unversioned invocation selected the same broken
release.
The recovery surface must not turn into an arbitrary package installer. Package
identity, registry location, and ACP arguments are trusted Kandev metadata.
Users need to choose among valid versions of that package, validate the
candidate, and keep a known-good version across Kandev restarts.
## Decision
Kandev lets an operator select an exact stable version for a built-in managed
npm runtime. The backend obtains the version catalogue from npm metadata,
validates strict stable SemVer values, and accepts only a version published for
the trusted package. Callers cannot provide a package name, registry URL, tag,
prerelease, command argument, or shell text.
Kandev prepares the candidate under its exact `package@version` npm execution
key and probes it through ACP before activation. Candidate preparation or probe
failure leaves the existing active selection and capability catalogue
unchanged. Kandev persists the trusted package identity and candidate as the
install-wide active version only after a successful ACP probe, then publishes
the candidate capabilities.
This ordering makes the persisted active version the last known good version;
automatic silent rollback is unnecessary.
Future standalone host probes, utility calls, and local agent sessions resolve
the persisted exact version. Existing sessions keep their current process.
SSH, container, and other remote runtimes do not inherit the host selection and
continue to resolve their own runtime. When no selection record exists, Kandev
retains the legacy unversioned host behavior until the first candidate is
successfully activated.
The selection is install-wide and per built-in agent. A saved selection applies
only while its stored package identity matches the agent's current trusted
package metadata; a package change starts with no selection and requires fresh
validation. The selection survives backend and browser restarts independently
of npm's best-effort cache. If reading a saved
selection fails, Kandev fails the new host-managed launch or probe visibly
instead of bypassing the selection with an unversioned package. If npm evicts
the selected version's cache, the exact version is prepared again when needed.
## Consequences
Operators can recover from a broken latest release in Settings without shell
access or a Kandev restart. Runtime changes become attributable: after the
first activation, host launches use the selected exact version until another
candidate passes validation.
The backend now owns a small durable selection record and must route it through
every host-local managed-runtime command path. Version catalogue lookup remains
dependent on registry availability, and cached versions are not a Kandev-owned
artifact inventory. A version that has disappeared from the registry can still
fail to reinstall after npm cache eviction.
The ACP probe is the activation boundary, not an assertion that every provider,
model, or future prompt will succeed. Authentication-required or failed probes
do not activate a candidate because Kandev cannot validate and publish its
capabilities.
## Alternatives Considered
- Latest-only repair was rejected because cache replacement selects the same
broken release and gives the operator no recovery path.
- Free-form package specs or versions were rejected because they would let a
Settings request execute an arbitrary npm package.
- Automatic fallback after a failed launch was rejected because it hides the
version actually used and can make separate launches behave differently.
- A Kandev-owned package directory and lockfile were rejected for this
iteration. Exact npm package specs and version-specific execution keys provide
transactional selection without reimplementing package storage.
- Applying the host selection to remote executors was rejected because each
remote runtime has separate platform, cache, credentials, and ownership.
+2 -1
View File
@@ -83,7 +83,8 @@ Read individual ADRs for full context. Create new ones via `/record decision` or
| 2026-07-22-runtime-mutable-task-workspace-sources | [Runtime-Mutable Task Workspace Sources](2026-07-22-runtime-mutable-task-workspace-sources.md) | accepted (amended by 2026-07-27) | backend, frontend, protocol | 2026-07-22 |
| 2026-07-24-opt-in-authentication | [Opt-in Authentication and Per-User Workspace Scoping](2026-07-24-opt-in-authentication.md) | accepted | backend, frontend, protocol, security | 2026-07-24 |
| 2026-07-24-semantic-notification-events | [Semantic notification events come from domain occurrences](2026-07-24-semantic-notification-events.md) | accepted | backend, frontend, desktop | 2026-07-24 |
| 2026-07-26-user-managed-agent-runtime-updates | [User-Managed Agent Runtime Updates](2026-07-26-user-managed-agent-runtime-updates.md) | accepted | backend, frontend, protocol | 2026-07-26 |
| 2026-07-26-user-managed-agent-runtime-updates | [User-Managed Agent Runtime Updates](2026-07-26-user-managed-agent-runtime-updates.md) | superseded by 2026-08-12-validated-managed-runtime-version-selection | backend, frontend, protocol | 2026-07-26 |
| 2026-08-12-validated-managed-runtime-version-selection | [Validate and Persist Managed Runtime Version Selection](2026-08-12-validated-managed-runtime-version-selection.md) | accepted | backend, frontend, protocol | 2026-08-12 |
| 2026-07-26-single-session-model-switching | [Single-Session Model Switching](2026-07-26-single-session-model-switching.md) | accepted (amended 2026-07-27) | workflow, infra | 2026-07-26 |
| 2026-07-27-task-git-credential-policy | [Separate GitHub Automation From Task Git Credential Policy](2026-07-27-task-git-credential-policy.md) | accepted | backend, frontend, security | 2026-07-27 |
| 2026-07-27-spa-failure-containment-and-deployment-recovery | [SPA Failure Containment and Deployment Recovery](2026-07-27-spa-failure-containment-and-deployment-recovery.md) | accepted | frontend | 2026-07-27 |
+202
View File
@@ -0,0 +1,202 @@
---
spec: docs/specs/agents/runtime-updates.md
decision: docs/decisions/2026-08-12-validated-managed-runtime-version-selection.md
created: 2026-08-12
updated: 2026-08-12
status: implemented
---
# Implementation Plan: Managed Runtime Version Recovery
## Overview
Turn the managed-runtime update dialog into a safe version recovery surface.
The backend will enumerate stable versions for each trusted built-in npm
package, stage and ACP-probe an exact candidate, and persist it only after
validation. The selected exact version will then drive host-local probes,
utility calls, and future standalone sessions. Desktop and mobile Settings will
support update, rollback, repair, and up-to-date outcomes without exposing
free-form package execution.
## Confirmed root cause
OpenCode's unversioned command selected `opencode-ai@1.18.16`. The wrapper
package existed, but its Linux x64 binary packages returned npm `E404`, so the
process exited before its first ACP response. The failed probe had no runtime
version, and the current update UI disabled approval. Rebuilding the unversioned
`_npx` tree selected the same incomplete release, so cache repair and a Kandev
restart could not recover the runtime.
The reproducible product failure is therefore not only an unknown-version UI
gate. It is the absence of an exact, validated, durable version choice.
## Architecture
### Trusted version foundation
- Add `internal/agent/managedruntime` as the owner of active-version records,
stable SemVer validation using the existing Masterminds SemVer dependency,
and the small selection-store interface.
- Persist one package-and-version system setting per built-in agent, keyed by
trusted agent ID, so parallel changes for separate agents cannot lose each
other through a shared JSON map and a future package-identity change cannot
inherit an unrelated old version.
- Extend `ManagedNPMRuntimeSpec` with exact `package@version` launch,
preparation, and deterministic execution-key helpers. Package identity and
ACP arguments remain built-in metadata.
- Add an internal managed-runtime version option to `agents.CommandOptions`.
The five managed agents use it only for their ACP `BuildCommand`; an empty
option preserves current unversioned behavior.
### Host-local command routing
- Wire one active-version store through the backend composition root to the
lifecycle manager, host utility manager, and settings controller.
- Resolve the active version immediately before standalone command building.
Propagate context into the launch command builder where needed. Do not set an
override for SSH or container runtimes, and preserve supported native-binary
preference.
- Centralize host-utility inference command resolution so boot probes, manual
refresh, model configuration, profile prompts, and sessionless prompts all
use the same exact active version.
- Split candidate probing from capability publication. A candidate probe must
return capabilities without replacing the live cache; the update job
publishes them only after persistence succeeds.
- Treat saved-selection read errors as launch or probe errors. Do not silently
fall back to an unversioned runtime when an active record exists but cannot be
read.
### Version catalogue and transactional activation
- Resolve npm `versions` and `dist-tags.latest` for the trusted package. Parse
strict stable SemVer, deduplicate, sort descending, and return the newest 50
plus active/current versions.
- Add optional `target_version` to preview and a required JSON target to POST.
Re-resolve metadata after approval and reject unpublished, prerelease, tag,
malformed, or package-like input.
- Return backend-derived `operation` (`update`, `rollback`, `repair`, or
`up_to_date`) and the exact preparation command.
- Stage the target under the deterministic key for `package@version`. On the
first preparation failure, invalidate only that exact tree and retry once.
- Probe the candidate without mutating live capabilities. On success, save the
active version and then publish capabilities. Every earlier failure leaves
the prior active version and catalogue untouched.
- Keep existing process-local job retention, maintenance exclusion, bounded
output, and WebSocket event names.
### Responsive Settings experience
- Keep the agent-card update icon as the desktop and mobile entry point.
- Add a shared version selector and render backend operation state. Desktop
remains a dialog; phone remains the existing bottom drawer, with no nested
drawer.
- Use **Update runtime**, **Roll back runtime**, **Repair runtime**, and **Up to
date** from structural operation state. A failed job can retry its exact
target or the operator can select another version.
- Keep one scroll owner, the safe-area footer, 44 px controls, keyboard access,
and non-color latest/active markers. Localize all copy in every agents
catalogue.
## API and data changes
- `RuntimeUpdateDTO`: add optional `active_version` while retaining observed
`current_version`.
- `AgentUpdatePreviewDTO`: add `active_version`, `operation`, and
`available_versions`; accept an optional selected target query.
- `POST /api/v1/agent-update/:agentName`: require
`{ "target_version": "X.Y.Z" }`.
- `AgentUpdateJobDTO`: add `operation` and `active_version`; update the active
version only at successful activation.
- Existing job statuses and WebSocket action names remain stable.
## Test strategy
- TDD the persistence, exact command generation, version filtering, operation
classification, and targeted cache key before controller orchestration.
- Prove every normal host-utility command path and standalone lifecycle launch
uses the active exact version, while SSH/container and no-selection paths do
not.
- Prove candidate preparation, one exact-tree retry, failed-probe preservation,
persistence-before-publication, restart reads, and request validation in
backend controller/handler tests.
- TDD frontend API payloads, stale preview cancellation, selection changes,
operation labels, disabled states, localization, and failed-target retry.
- Add desktop and `mobile-chrome` E2E coverage for rollback from an unknown
OpenCode version and viewport containment.
## Mobile design contract
- Entry point: the existing 44 px agent-card runtime action.
- Presentation: existing `Dialog` on desktop and existing `Drawer` on phone.
- Hierarchy: active/current summary, version selector, operation explanation,
trusted command, progress/output, fixed action footer.
- Scrolling: shared body is the only vertical scroll owner; long output wraps
or scrolls internally without horizontal page overflow.
- Parity: desktop and mobile can select the same versions, start the same
operation, observe progress, and recover from the same errors.
## Verification results
- Backend focused tests: 2,321 passed across managedruntime, agents,
hostutility, lifecycle, settings controller/handlers, and backendapp.
- Backend lint: `rtk make -C apps/backend lint` — 0 issues.
- Frontend focused Vitest suite: 31 passed across 4 files.
- Frontend typecheck and lint — passed.
- i18n check and ratchet — passed; the checker retained its existing advisory
real-locale parity warnings.
- Desktop Playwright: 6 passed. Mobile Playwright: 4 passed.
- Public documentation tests: 60 passed. Public validator: 41 pages validated.
- Fresh desktop/mobile PR screenshots were captured from synthetic fixtures,
visually inspected, compressed, and validated against their manifest.
## Post-implementation fixup verification
- Preserved the selected target across failed preview retries and cleared stale
failed-job state when selecting a new target.
- Kept repair distinct from up-to-date state, reused active jobs before npm
metadata lookup, skipped redundant exact-target metadata fetches, propagated
selection-store errors, and shared npm cache-root validation.
- Backend fixup tests: `rtk go test ./internal/agent/settings/controller
./internal/agent/runtime/lifecycle` — 1,705 passed.
- Frontend fixup tests: 27 passed in the runtime-operation and dialog-state
suites.
- Fixup E2E: desktop 8 passed; mobile 4 passed.
## Implementation waves
Wave 1:
- [x] [Task 01: Build exact-version foundation](task-01-build-exact-version-foundation.md) — done
Wave 2, after Task 01:
- [x] [Task 02: Route active host runtime](task-02-route-active-host-runtime.md) — done
Wave 3, after Tasks 01 and 02:
- [x] [Task 03: Activate validated runtime versions](task-03-activate-validated-runtime-versions.md) — done
Wave 4, after Task 03:
- [x] [Task 04: Add responsive version recovery UI](task-04-add-responsive-version-recovery-ui.md) — done
Wave 5, after Task 04:
- [x] [Task 05: Prove rollback on desktop and mobile](task-05-prove-rollback-desktop-mobile.md) — done
- [x] [Task 06: Document runtime version recovery](task-06-document-runtime-version-recovery.md) — done
Execution remains in the primary conversation unless the user explicitly
authorizes implementation subagents.
## Risks and boundaries
- An ACP probe proves initialization and advertised capabilities, not every
model/provider interaction. Authentication-required probes do not activate.
- Exact npm caches remain best-effort. Persisted selection prevents version
drift but does not guarantee offline artifact retention.
- Avoid a second command-resolution path. Every host utility caller must use
the shared resolver, including model configuration and profile prompts.
- Do not let request input reach package names, registry URLs, ACP arguments,
or shell parsing.
- Do not change remote/container runtime ownership, active sessions, native-only
installers, automatic update scheduling, or job persistence.
@@ -0,0 +1,79 @@
---
id: "01-build-exact-version-foundation"
title: "Build exact-version foundation"
status: done
wave: 1
depends_on: []
plan: "plan.md"
spec: "../../specs/agents/runtime-updates.md"
---
# Task 01: Build exact-version foundation
## Acceptance
- A typed install-wide store reads and writes one trusted package and active
exact version per built-in agent through `internal/system/settings`; a
package mismatch cannot apply an old version to replacement metadata.
- Strict stable SemVer parsing rejects prereleases, tags, package specs, and
malformed values and provides deterministic descending ordering.
- `ManagedNPMRuntimeSpec` builds launch, preparation, and execution-cache keys
from exact `package@version` while preserving the empty-version legacy path.
- Each managed agent honors an internal exact-version command option for ACP
commands; callers still cannot choose package identity or ACP arguments.
## TDD sequence
1. Add failing tests for selection-store round trips, missing values, invalid
stored values, and separate-agent writes.
2. Add failing table tests for stable version validation and ordering.
3. Add failing exact command/key tests, including scoped npm packages.
4. Implement the typed store and helpers, then minimally update the five
managed agent command builders.
5. Run focused packages, then backend lint for touched code.
## Files likely touched
- `apps/backend/internal/agent/managedruntime/selection.go`
- `apps/backend/internal/agent/managedruntime/selection_test.go`
- `apps/backend/internal/agent/managedruntime/versions.go`
- `apps/backend/internal/agent/managedruntime/versions_test.go`
- `apps/backend/internal/agent/agents/agent.go`
- `apps/backend/internal/agent/agents/managed_npm_runtime.go`
- `apps/backend/internal/agent/agents/managed_npm_runtime_test.go`
- `apps/backend/internal/agent/agents/{claude_acp,codex_acp,opencode_acp,copilot_acp,gemini}.go`
- `apps/backend/go.mod`
- `apps/backend/go.sum`
## Verification
```bash
make -C apps/backend test ARGS='./internal/agent/managedruntime ./internal/agent/agents'
make -C apps/backend lint
```
## Risks
- Use a key per trusted agent ID instead of a shared read-modify-write map.
- Do not use the update subsystem's Kandev-specific loose SemVer parser.
- Do not add a user-provided package or command field.
## Output contract
Record RED/GREEN evidence, files, checks, and risks in Results. Update this task
and `plan.md` status in the same implementation conversation.
## Results
RED covered the new selection, strict-version, exact-command, scoped-package,
and per-agent isolation contracts before their implementations were complete.
GREEN verification:
- `rtk go test ./internal/agent/managedruntime ./internal/agent/agents ./internal/agent/hostutility ./internal/agent/runtime/lifecycle ./internal/agent/settings/controller ./internal/agent/settings/handlers ./internal/backendapp` — 2,321 tests passed across 7 packages.
- `rtk make -C apps/backend lint` — 0 issues.
The implementation adds the typed install-wide selection store, strict stable
catalogue helpers, exact `package@version` command/key builders, and exact ACP
command support for all five managed npm agents. The remaining risk is the
normal npm availability boundary: persisted selection prevents version drift,
but does not promise offline artifact retention.
@@ -0,0 +1,84 @@
---
id: "02-route-active-host-runtime"
title: "Route active host runtime"
status: done
wave: 2
depends_on: ["01-build-exact-version-foundation"]
plan: "plan.md"
spec: "../../specs/agents/runtime-updates.md"
---
# Task 02: Route active host runtime
## Acceptance
- Standalone managed-agent launches use the persisted exact active version;
no-selection launches preserve legacy unversioned behavior.
- Boot/manual probes, model-configuration resolution, profile prompts, and
sessionless utility prompts use the same host command resolver.
- SSH and container launches receive no host version override; supported native
binary preference remains unchanged.
- A saved-selection read failure fails the new host launch/probe visibly rather
than silently selecting npm latest.
- Candidate probes remain able to supply a trusted exact command override
without changing the active resolver.
## TDD sequence
1. Add lifecycle tests that expect exact standalone argv and unchanged SSH,
container, native, and no-selection argv.
2. Add host-utility tests for every call site currently reading
`InferenceConfig().Command` directly.
3. Add the active-version provider to lifecycle and host utility, make launch
command building context-aware where required, and centralize utility
command resolution.
4. Wire one store instance from backend startup into lifecycle, host utility,
and the settings controller; add composition tests.
5. Run focused packages and backend lint.
## Files likely touched
- `apps/backend/internal/agent/runtime/lifecycle/manager.go`
- `apps/backend/internal/agent/runtime/lifecycle/manager_launch.go`
- `apps/backend/internal/agent/runtime/lifecycle/manager_interaction.go`
- `apps/backend/internal/agent/runtime/lifecycle/*_test.go`
- `apps/backend/internal/agent/hostutility/manager.go`
- `apps/backend/internal/agent/hostutility/public.go`
- `apps/backend/internal/agent/hostutility/manager_test.go`
- `apps/backend/internal/backendapp/main.go`
- `apps/backend/internal/backendapp/agents.go`
- `apps/backend/internal/backendapp/*_test.go`
## Verification
```bash
make -C apps/backend test ARGS='./internal/agent/runtime/lifecycle ./internal/agent/hostutility ./internal/backendapp'
make -C apps/backend lint
```
## Risks
- Cover restart/fresh-command rebuilding as well as initial launches.
- Do not rewrite static `Runtime().Cmd` globally; route only trusted host-local
dynamic commands.
- Preserve command prefixes, CLI flags, resume arguments, and native preference.
## Output contract
Record RED/GREEN evidence, exact command assertions, checks, and risks in
Results. Update this task and `plan.md` status.
## Results
RED covered exact standalone/worktree command routing, legacy no-selection
behavior, SSH/container exclusions, and selection read errors at the lifecycle
and host-utility boundaries. GREEN verification:
- `rtk go test ./internal/agent/managedruntime ./internal/agent/agents ./internal/agent/hostutility ./internal/agent/runtime/lifecycle ./internal/agent/settings/controller ./internal/agent/settings/handlers ./internal/backendapp` — 2,321 tests passed across 7 packages.
- `rtk make -C apps/backend lint` — 0 issues.
One selection store instance is wired through backend startup into lifecycle,
host utility, and update orchestration. Host-local probes, model resolution,
profile prompts, sessionless prompts, and standalone launches share the exact
version resolver. Remote/container command ownership and native preference are
unchanged.
@@ -0,0 +1,83 @@
---
id: "03-activate-validated-runtime-versions"
title: "Activate validated runtime versions"
status: done
wave: 3
depends_on: ["01-build-exact-version-foundation", "02-route-active-host-runtime"]
plan: "plan.md"
spec: "../../specs/agents/runtime-updates.md"
---
# Task 03: Activate validated runtime versions
## Acceptance
- Preview returns the newest 50 stable versions plus active/current values,
validates an optional target, and derives operation and exact command.
- POST accepts only `target_version`, re-resolves trusted npm metadata, and
rejects malformed, prerelease, unpublished, disappeared, or package-like
input before mutation.
- A candidate is prepared under its exact execution key, one failed preparation
invalidates only that tree, and a successful ACP probe is required.
- Persistence happens before capability publication. Every failure preserves
the previous active version and capability catalogue.
- Jobs and catalogue DTOs expose active version and operation while retaining
current status, maintenance, output-bound, retention, and WebSocket behavior.
## TDD sequence
1. Extend fake-updater tests for catalogue parsing, operation classification,
target request validation, and exact command/key construction.
2. Add orchestration tests for update, rollback, unknown-version repair,
up-to-date no-op, targeted retry, failed probe, auth-required probe,
persistence failure, and success ordering.
3. Add handler tests for query/body decoding and rejection before enqueue.
4. Implement DTOs, registry resolver, controller, job lifecycle, persistence,
and catalogue projection in that order.
5. Run focused tests, backend lint, and generated/API compatibility checks used
by the touched packages.
## Files likely touched
- `apps/backend/internal/agent/settings/dto/dto.go`
- `apps/backend/internal/agent/settings/controller/agent_update.go`
- `apps/backend/internal/agent/settings/controller/agent_update_job.go`
- `apps/backend/internal/agent/settings/controller/agent_update_test.go`
- `apps/backend/internal/agent/settings/controller/agent_discovery.go`
- `apps/backend/internal/agent/settings/handlers/handlers.go`
- `apps/backend/internal/agent/settings/handlers/agent_update_handlers_test.go`
## Verification
```bash
make -C apps/backend test ARGS='./internal/agent/settings/controller ./internal/agent/settings/handlers'
make -C apps/backend lint
```
## Risks
- Resolve registry metadata again after approval; do not trust a stale browser
list as authorization.
- Do not publish candidate capabilities before the active selection is durable.
- Authentication-required is not a successful activation boundary.
- Keep raw registry credentials and unbounded output out of DTOs.
## Output contract
Record RED/GREEN evidence, ordering assertions, API examples, checks, and risks
in Results. Update this task and `plan.md` status.
## Results
RED covered catalogue projection, operation classification, target validation,
exact preparation retry, failed-probe preservation, persistence-before-
publication, and required request-body behavior. GREEN verification:
- `rtk go test ./internal/agent/managedruntime ./internal/agent/agents ./internal/agent/hostutility ./internal/agent/runtime/lifecycle ./internal/agent/settings/controller ./internal/agent/settings/handlers ./internal/backendapp` — 2,321 tests passed across 7 packages.
- `rtk make -C apps/backend lint` — 0 issues.
The controller re-resolves trusted npm metadata after approval, the candidate
probe does not replace live capabilities, and the active selection is saved
before capabilities are published. Failed preparation, probe, authentication,
or persistence leaves the previous active selection and capability cache in
place. Handler tests cover JSON target decoding and invalid-target responses.
@@ -0,0 +1,97 @@
---
id: "04-add-responsive-version-recovery-ui"
title: "Add responsive version recovery UI"
status: done
wave: 4
depends_on: ["03-activate-validated-runtime-versions"]
plan: "plan.md"
spec: "../../specs/agents/runtime-updates.md"
---
# Task 04: Add responsive version recovery UI
## Acceptance
- The API client previews a selected target and sends it explicitly in POST.
- The shared dialog state defaults to backend latest, refreshes the trusted
preview when selection changes, ignores stale responses, and preserves the
selected target through job progress and retry.
- Structural operation state renders **Update runtime**, **Roll back runtime**,
**Repair runtime**, or disabled **Up to date** in every locale.
- Desktop dialog and phone drawer share version selection and business logic;
the picker is keyboard/touch accessible with visible latest/active markers.
- Registry, candidate, and activation failures allow retry or another version
selection without exposing package/command input.
## TDD sequence
1. Add failing API tests for encoded preview query and JSON POST body.
2. Add failing hook tests for default selection, target changes, stale preview
cancellation, active-job idempotency, and exact-target retry.
3. Add failing pure-state tests for operation labels and approval gates without
translated-string comparison.
4. Implement the shared selector/body/footer and all localized copy.
5. Run focused tests, typecheck, lint, i18n check, and i18n ratchet.
## Files likely touched
- `apps/web/lib/api/domains/agent-update-api.ts`
- `apps/web/lib/api/domains/agent-update-api.test.ts`
- `apps/web/lib/agent-runtime-update.ts`
- `apps/web/lib/agent-runtime-update.test.ts`
- `apps/web/components/settings/use-agent-update-dialog-state.ts`
- `apps/web/components/settings/use-agent-update-dialog-state.test.ts`
- `apps/web/components/settings/agent-runtime-update-control.tsx`
- `apps/web/src/locales/{en,pt-pt,zh-cn,pseudo}/agents.json`
## Mobile requirements
- Keep the existing bottom drawer and introduce no nested drawer.
- Keep all interactive controls at least 44 px high.
- Keep the shared body as the only vertical scroll owner and the footer inside
the safe-area inset.
- Avoid browser-chrome collisions and horizontal page overflow for long
versions, commands, and output.
## Verification
Fresh-worktree bootstrap, when needed:
```bash
cd apps && pnpm install --frozen-lockfile
```
```bash
cd apps && pnpm --filter @kandev/web test -- --run lib/api/domains/agent-update-api.test.ts lib/agent-runtime-update.test.ts components/settings/use-agent-update-dialog-state.test.ts
cd apps/web && pnpm run typecheck
cd apps && pnpm --filter @kandev/web lint
cd apps/web && pnpm run i18n:check
cd apps/web && pnpm run i18n:ratchet
```
## Risks
- Do not classify versions in TypeScript; render backend operation state.
- Do not compare localized copy to decide state.
- Avoid refetch loops and stale selection overwrites when targets change fast.
## Output contract
Record RED/GREEN evidence, responsive behavior, checks, and risks in Results.
Update this task and `plan.md` status.
## Results
RED covered encoded target queries, exact POST bodies, stale preview response
handling, exact-target approval, operation labels, and localized missing-version
gates. GREEN verification:
- `rtk pnpm --filter @kandev/web test -- --run lib/api/domains/agent-update-api.test.ts lib/agent-runtime-update.test.ts components/settings/use-agent-update-dialog-state.test.ts hooks/domains/settings/use-agent-runtime-updates.test.tsx` — 31 tests passed across 4 files.
- `rtk pnpm run typecheck` — passed.
- `rtk pnpm --filter @kandev/web lint` — passed.
- `rtk pnpm run i18n:check` — passed; existing 117 real-locale parity warnings remain advisory.
- `rtk pnpm run i18n:ratchet` — passed with 0 added and 8 modified files clean.
The desktop dialog and mobile drawer share the selector and state machine,
submit only trusted exact targets, derive action copy from backend operation
state, and retain 44 px mobile controls with one scroll owner.
@@ -0,0 +1,74 @@
---
id: "05-prove-rollback-desktop-mobile"
title: "Prove rollback on desktop and mobile"
status: done
wave: 5
depends_on: ["04-add-responsive-version-recovery-ui"]
plan: "plan.md"
spec: "../../specs/agents/runtime-updates.md"
---
# Task 05: Prove rollback on desktop and mobile
## Acceptance
- Desktop E2E covers an unknown-version repair state and selects an older stable
version for rollback, reviews the exact command, and submits one rollback.
- `mobile-chrome` completes the same behavior through the bottom drawer with no
nested overlay, clipped action, browser-chrome collision, or page overflow.
- Failed candidate validation keeps the previous active marker and lets the
operator select another version.
- Existing update, same-version, install-conflict, output, and page-reload
scenarios continue to pass with explicit targets.
## TDD sequence
1. Update mock routes and helpers to require target query/body values.
2. Add the desktop rollback scenario and confirm RED before UI wiring.
3. Add the mobile parity and containment scenario.
4. Add failed-candidate preservation coverage where it is not already proven
by component tests.
5. Run focused projects, inspect artifacts on failure, and clean generated
screenshots/traces/videos not intentionally retained.
## Files likely touched
- `apps/web/e2e/tests/settings/agent-runtime-update-helpers.ts`
- `apps/web/e2e/tests/settings/agent-runtime-update.spec.ts`
- `apps/web/e2e/tests/settings/mobile-agent-runtime-update.spec.ts`
## Verification
```bash
cd apps/web && pnpm e2e:raw --project=chromium e2e/tests/settings/agent-runtime-update.spec.ts
cd apps/web && pnpm e2e:raw --project=mobile-chrome e2e/tests/settings/mobile-agent-runtime-update.spec.ts
```
## Risks
- Assert request payload and rendered outcome, not only button visibility.
- Keep deterministic mocked registry data; do not contact public npm in E2E.
- Verify one scroll owner and touch reachability at the narrow shipped viewport.
## Output contract
Record test counts, viewport, artifacts, cleanup evidence, checks, and risks in
Results. Update this task and `plan.md` status.
## Results
GREEN verification:
- `rtk pnpm e2e:raw --project=chromium e2e/tests/settings/agent-runtime-update.spec.ts` — 6 passed.
- `rtk pnpm e2e:raw --project=mobile-chrome e2e/tests/settings/mobile-agent-runtime-update.spec.ts` — 4 passed.
- Request assertions verified target query/body values for update and rollback,
operation labels, up-to-date disabling, failed-job retry, mobile drawer
containment, and long-output scrolling.
- Fresh disposable capture runs passed once per viewport. The compressed
synthetic assets are `desktop-runtime-version-selector` and
`mobile-runtime-version-selector`; both manifest entries map to non-empty
PNGs under ignored `apps/web/.pr-assets`.
Temporary capture specs were removed after publication assets were validated.
The only environment cleanup was disposal of the recoverable Go build cache
after an `ENOSPC` during the first capture attempt.
@@ -0,0 +1,69 @@
---
id: "06-document-runtime-version-recovery"
title: "Document runtime version recovery"
status: done
wave: 5
depends_on: ["04-add-responsive-version-recovery-ui"]
plan: "plan.md"
spec: "../../specs/agents/runtime-updates.md"
---
# Task 06: Document runtime version recovery
## Acceptance
- Public agent/profile guidance explains selecting update, rollback, and repair
targets and that activation follows a successful ACP validation.
- The guide states that the active exact version survives Kandev restarts,
affects only later host-local probes/utility calls/sessions, and does not
change active or remote/container sessions.
- Troubleshooting covers incomplete latest releases, failed candidates,
authentication-required validation, and retrying another stable version.
- The guide does not recommend global npm cache cleanup or imply Kandev owns an
offline artifact inventory.
## Implementation
1. Replace the current latest-only update steps in the existing how-to section.
2. Add a concise troubleshooting entry for selecting the previous stable
version when latest cannot initialize.
3. Check all labels and guarantees against the implemented API/UI and spec.
4. Run documentation link and formatting checks available in the repository.
## Files likely touched
- `docs/public/agents-and-profiles.md`
## Verification
```bash
rtk rg -n "Update a managed agent runtime|Roll back runtime|Repair runtime|npm cache" docs/public/agents-and-profiles.md
rtk rg -n "docs/public|markdown" Makefile apps/package.json package.json
```
Run the repository documentation check discovered by the second command and
record the exact command/result.
## Risks
- Describe host scope and persistence precisely; do not promise remote updates
or cached offline reinstall.
- Keep this as an operator how-to, not an implementation narrative.
## Output contract
Record changed sections, checks, and risks in Results. Update this task and
`plan.md` status.
## Results
Updated `docs/public/agents-and-profiles.md` with exact-version selection,
update/rollback/repair behavior, ACP validation, restart and host-local scope,
active-session and remote/container boundaries, failed-candidate preservation,
and retry guidance. GREEN verification:
- `rtk node --test scripts/validate-public-docs.test.mjs` — 60 tests passed.
- `rtk node scripts/validate-public-docs.mjs` — 41 published docs pages validated.
The guide does not promise global npm cache cleanup or an offline artifact
inventory.
+14 -7
View File
@@ -37,17 +37,24 @@ The update icon is available on managed Claude, Codex, OpenCode, Copilot, and
Gemini agent cards. It updates the runtime on the Kandev host.
1. Select the update icon.
2. Review the current version, target version, and command.
3. Select **Approve update**. If the update fails, select **Retry update**.
4. Wait for the capability refresh to finish.
2. Review the current version, active version, available stable versions, and command.
3. Keep the latest version selected for a normal update, or select an older stable version to roll back.
4. Select **Update runtime**, **Roll back runtime**, or **Repair runtime**.
5. Wait for the exact version to prepare and pass its ACP capability probe.
Kandev disables approval when the versions already match or the version check
is incomplete. A successful refresh updates the advertised models, modes,
Kandev enables the action only after the backend validates the selected version
against the trusted package catalogue. It does not accept package names, npm
tags, prereleases, registry URLs, or command text. When the active version,
observed version, and target version match, the action is disabled as **Up to
date**. A successful activation updates the advertised models, modes,
configuration options, commands, and runtime version without a page reload.
- Active sessions keep running; later probes and launches use the refreshed runtime.
- The active exact version survives Kandev and browser restarts.
- Later host-local probes, utility calls, and standalone sessions use the active exact version.
- Active sessions keep running. They are not restarted or hot-swapped.
- Passthrough agents, authentication helpers, remote executors, and running containers are unchanged.
- If the update or refresh fails, Kandev keeps the previous capability catalogue and shows the error. Authenticate the host agent, then retry.
- If preparation, ACP validation, authentication, or persistence fails, Kandev keeps the previous active version and capability catalogue. Select another stable version or retry the same target.
- Kandev may prepare the exact version again if npm removes its cache entry. Kandev does not own an offline package inventory, and global npm cache cleanup is not required.
<details>
<summary>Add a custom terminal agent</summary>
+219 -197
View File
@@ -1,53 +1,49 @@
---
status: approved
created: 2026-07-26
updated: 2026-08-12
owner: Kandev
---
# Managed Agent Runtime Updates
# Managed Agent Runtime Version Recovery
## Why
Operators need newly released agent capabilities and models without waiting for
a Kandev release. They also need normal agent launches to avoid paying an
upstream package-resolution cost on every session when a usable npm execution
cache is already present.
Operators need newly released agent models without waiting for a Kandev
release. They also need a UI recovery path when the newest npm release is
partly published, incompatible with ACP, or otherwise cannot start. Rebuilding
an npm cache is not sufficient when an unversioned command selects the same
broken release again.
## What
- Kandev launches the managed npm runtime for Claude, Codex, OpenCode, Copilot,
and Gemini by package name without an exact version or an explicit `latest`
tag.
- Normal launches may reuse npm's execution cache. Cache reuse is best-effort;
Kandev does not present it as a durable installed-version guarantee.
- Each supported installed agent has a compact, accessible update icon action
on its Settings > Agents card on desktop and mobile. Update versions,
command details, progress, output, and results are not rendered in the card.
- Opening the update action is read-only. It opens an update dialog that
resolves and shows the current runtime version, upstream target version,
exact built-in command, host-only scope, capability refresh, and active
session behavior before an update can start.
- When the resolved current and upstream target versions are identical, the
update dialog shows the version once with an **Up to date** status and keeps
approval disabled because running the package update would not advance the
managed runtime.
- The update starts only after the operator approves it in the dialog. The
dialog then shows live stdout/stderr, progress, and the terminal success or
failure state.
- A successful package update automatically starts a fresh host capability
probe. The returned runtime version, models, modes, configuration options,
commands, and capability status replace the previous cached values.
- An update affects new host probes, utility calls, and sessions. It does not
restart or mutate an already-running agent session.
- Kandev uses the ACP initialization protocol version and advertised
capabilities as the compatibility boundary. Kandev does not gate managed
npm runtimes by a repository-maintained package-version allowlist.
- Package update commands are defined by Kandev's built-in agent metadata.
Callers cannot submit package names, versions, registry URLs, or shell text.
- Update jobs for the same agent are idempotent while queued or running. An
install and update for the same agent cannot run concurrently.
- Settings exposes version management for the built-in managed npm runtimes
used by Claude, Codex, OpenCode, Copilot, and Gemini.
- The update dialog lists stable versions published for the trusted package.
The list contains the newest 50 stable versions plus the active and last
observed versions when either falls outside that window. The upstream
`latest` stable version is selected initially.
- The backend classifies the selected action as `update`, `rollback`, `repair`,
or `up_to_date`. The UI uses this structural state for copy and approval; it
never compares translated labels or version strings itself.
- Kandev stages the exact trusted `package@version`, ACP-probes that candidate,
and activates it only after a successful probe. Candidate failure preserves
the prior active version and capability catalogue.
- A successful activation persists the exact version for this Kandev install.
Later standalone host probes, utility calls, and local sessions use that
exact package spec. Active sessions continue unchanged.
- When no active selection exists, legacy host launches remain unversioned.
The first successful update, rollback, or repair establishes the durable
active version.
- SSH, containers, and other remote executors do not use the host selection.
- Package name, ACP arguments, and command shape remain trusted built-in
metadata. A caller can submit only a version returned by the trusted
package's npm metadata. Tags, prereleases, package specs, registry URLs, and
shell text are rejected.
- Jobs for one agent are idempotent while queued or running. Installation and
version management for the same agent cannot run concurrently.
The initial managed package set is:
The managed package set is:
| Agent | Managed runtime package |
| --- | --- |
@@ -57,11 +53,35 @@ The initial managed package set is:
| Copilot | `@github/copilot` |
| Gemini | `@google/gemini-cli` |
The managed package is the runtime Kandev uses for ACP capability discovery.
Separately configured passthrough commands and native authentication helpers
remain outside this update action when they use another package or installer.
Passthrough commands, native authentication helpers, and native-only agents
remain outside this version action when they use another installer or package.
Decision: [ADR-2026-07-26-user-managed-agent-runtime-updates](../../decisions/2026-07-26-user-managed-agent-runtime-updates.md).
Decision:
[ADR-2026-08-12-validated-managed-runtime-version-selection](../../decisions/2026-08-12-validated-managed-runtime-version-selection.md).
## Version and operation semantics
Kandev distinguishes three version values:
- `current_version` is the version reported by the last successful host ACP
probe. It can be absent after a failed probe.
- `active_version` is the exact version persisted for future host-local
managed-runtime commands. It can be absent before the first activation.
- `target_version` is the stable version selected by the operator.
The backend derives the operation from `active_version` when present and
otherwise from `current_version`:
| Condition | Operation | Approval |
| --- | --- | --- |
| Target is newer than the effective version. | `update` | **Update runtime** |
| Target is older than the effective version. | `rollback` | **Roll back runtime** |
| Current is unknown, versions cannot be compared, or the observed version matches but has not been activated exactly. | `repair` | **Repair runtime** |
| Active, current, and target versions match. | `up_to_date` | Disabled as **Up to date** |
Only strict stable SemVer values from npm's published version list are
selectable. Kandev does not offer prereleases. Version ordering and operation
classification are backend responsibilities.
## API surface
@@ -73,37 +93,73 @@ Installed-agent catalogue entries expose optional runtime-management metadata:
{
"runtime_update": {
"supported": true,
"package": "@agentclientprotocol/claude-agent-acp",
"current_version": "0.62.0"
"package": "opencode-ai",
"current_version": "1.18.5",
"active_version": "1.18.5"
}
}
```
`current_version` is omitted when no successful capability probe has reported a
runtime version. Unmanaged agents omit `runtime_update`.
`current_version` and `active_version` are independently omitted when unknown
or not yet established. Unmanaged agents omit `runtime_update`.
### Update jobs
### Preview and jobs
- `GET /api/v1/agent-update/:agentName/preview` resolves the current and
upstream target versions and returns the exact trusted built-in update
command without starting an update.
- `POST /api/v1/agent-update/:agentName` starts or returns the active update
job for a built-in managed agent.
- `GET /api/v1/agent-update/jobs` returns active and recently completed update
jobs.
- `GET /api/v1/agent-update/jobs/:id` returns one retained update job.
- State-changing update requests use the same Settings interlock as agent
installation and profile mutation.
- `GET /api/v1/agent-update/:agentName/preview` returns the version catalogue
and previews the upstream latest stable target.
- `GET /api/v1/agent-update/:agentName/preview?target_version=1.18.5`
validates and previews one selected version without mutation.
- `POST /api/v1/agent-update/:agentName` accepts JSON
`{ "target_version": "1.18.5" }` and starts or returns the active job.
- `GET /api/v1/agent-update/jobs` and
`GET /api/v1/agent-update/jobs/:id` retain their current polling behavior.
- State-changing requests use the Settings mutation interlock.
An update job contains:
A preview contains:
```json
{
"agent_name": "opencode-acp",
"package": "opencode-ai",
"current_version": "1.18.5",
"active_version": "1.18.5",
"target_version": "1.18.16",
"operation": "update",
"available_versions": [
{ "version": "1.18.16", "latest": true },
{ "version": "1.18.5", "latest": false }
],
"command": [
"npm",
"exec",
"--yes",
"--prefer-online",
"--package=opencode-ai@1.18.16",
"--",
"node",
"-e",
""
],
"command_string": "npm exec --yes --prefer-online --package=opencode-ai@1.18.16 -- node -e \"\""
}
```
The POST endpoint resolves npm metadata again and rejects a target that is no
longer a published stable version. The request never controls the package,
registry, command, or ACP arguments.
A job retains the existing timestamps, output, and errors and adds the
authoritative operation and active version:
```json
{
"job_id": "uuid",
"agent_name": "claude-acp",
"status": "resolving",
"current_version": "0.62.0",
"target_version": "0.63.0",
"agent_name": "opencode-acp",
"status": "refreshing",
"operation": "rollback",
"current_version": "1.18.16",
"active_version": "1.18.16",
"target_version": "1.18.5",
"output": "",
"error": "",
"refresh_error": "",
@@ -112,154 +168,120 @@ An update job contains:
}
```
`current_version`, `target_version`, `finished_at`, `error`, and
`refresh_error` are optional until known. The backend emits
`agent.update.started`, `agent.update.output`, and `agent.update.finished`
notifications with the same job identity and state. Output notifications carry
only the appended output chunk.
`active_version` reflects the persisted selection at that job snapshot. It
changes to the target only after successful validation and persistence. The
existing `agent.update.started`, `agent.update.output`, and
`agent.update.finished` WebSocket notifications carry the same job fields.
An update preview contains:
## Activation lifecycle
```json
{
"agent_name": "claude-acp",
"package": "@agentclientprotocol/claude-agent-acp",
"current_version": "0.62.0",
"target_version": "0.63.0",
"command": [
"npm",
"exec",
"--yes",
"--prefer-online",
"--package=@agentclientprotocol/claude-agent-acp",
"--",
"node",
"-e",
""
],
"command_string": "npm exec --yes --prefer-online --package=@agentclientprotocol/claude-agent-acp -- node -e \"\""
}
```
The preview endpoint accepts only the built-in agent name. Package names,
versions, registry URLs, and command arguments are not caller-controlled.
## State machine
| State | Trigger | Observable behavior |
| State | Backend behavior | Observable behavior |
| --- | --- | --- |
| `queued` | The backend accepts an update request. | The action is disabled and shows that the update is queued. |
| `resolving` | A worker starts the job. | Kandev discovers the current runtime version and upstream npm target. |
| `updating` | Version resolution succeeds. | Kandev streams package-update output and shows current → target. |
| `refreshing` | The package update succeeds. | Kandev re-probes the host runtime and keeps the action disabled. |
| `succeeded` | The capability probe succeeds, or the package updated but capability refresh returned a recoverable error. | The UI shows the installed target. When refresh succeeded, it replaces model and mode data. A refresh-only error is shown without claiming the package update was rolled back. |
| `failed` | Registry lookup or package update fails, the command times out, or ACP initialization is incompatible. | The UI retains the previous model list and shows the captured error and output. |
| `queued` | Accept the selected version and maintenance claim. | The version picker and action are disabled. |
| `resolving` | Re-read npm versions, validate the exact target, and classify the operation. | The UI shows the selected target and resolving progress. |
| `updating` | Prepare `package@target` in its version-specific npm execution tree. On first failure, invalidate only that exact tree and retry once. | Bounded stdout and stderr stream into the dialog. |
| `refreshing` | Probe the candidate command without replacing cached capabilities. On success, persist the target and then publish the candidate capabilities. | The UI explains that Kandev is validating before activation. |
| `succeeded` | The exact target is active and its capabilities are published. | The catalogue and models refresh without a page reload. |
| `failed` | Resolution, preparation, probe, or persistence failed. The previous active version and capabilities remain unchanged. | The UI shows the captured error and permits a new selection or retry. |
Jobs are terminal after `succeeded` or `failed`. Retrying creates a new job.
Jobs are terminal after `succeeded` or `failed`. Selecting the active, healthy
version produces `up_to_date` in preview and starts no job. Selecting the active
version while its current probe is unknown produces a repair job.
## Failure modes
## Host command routing
- If npm registry metadata cannot be resolved, the job fails before changing
the runtime and retains the prior capability data.
- If the first package update command fails, Kandev may remove only the
deterministic npm execution-cache directory for that built-in package and
retry the update once. It never runs a global npm cache clean. If the repair
or retry fails or times out, the job fails and retains the prior capability
data.
- If preview version resolution fails, the dialog shows the error and keeps
approval disabled. No update job or package command starts.
- If the package update succeeds but the capability probe fails because
authentication is required or another recoverable probe error occurs, the
job reports package-update success plus `refresh_error`; the previous model
list remains visible and the operator can authenticate or retry the refresh.
- If the updated runtime negotiates an unsupported ACP protocol version or
cannot initialize, the job fails visibly. Kandev does not silently fall back
to a repository-pinned runtime.
- Raw process output is bounded using the existing in-memory job output limit.
Package-manager credentials and configured registry authentication are never
returned as structured fields.
- Loss of the browser connection does not cancel a running job. Reopening the
page recovers retained job progress through the jobs endpoint.
- A standalone managed-agent launch reads the active selection immediately
before building its command and passes the exact version through trusted
command options.
- Boot probes, manual capability refreshes, model-configuration resolution, and
sessionless utility prompts use the same active-version resolver.
- Native-binary preference continues to win when an agent deliberately selects
its supported native binary path.
- SSH and container command builders receive no host version override.
- A saved selection read error fails the new host command with an actionable
error. It does not fall back to an unversioned package.
- Candidate validation bypasses the active selection only for the trusted exact
candidate command created by the version job.
## Failure and recovery behavior
- Registry failure during preview keeps approval disabled and runs no command.
- Registry failure or target disappearance after approval fails before staging.
- Preparation failure invalidates only the deterministic `_npx` tree for the
exact `package@version` and retries once. Kandev never runs a global npm cache
clean.
- ACP initialization failure, unsupported protocol behavior, authentication
required, or an unsuccessful capability probe does not activate the
candidate. The staged npm cache may remain for a later retry.
- Persistence failure after a successful candidate probe does not publish the
candidate capabilities and leaves the previous active selection unchanged.
- Browser disconnect does not cancel a running job. The jobs endpoint can
recover process-local progress while the backend remains running.
- Active sessions are never restarted, replaced, or hot-swapped.
## Persistence guarantees
- Update jobs and capability data are process-local and do not survive a Kandev
backend restart.
- Completed jobs remain queryable for the existing short job-retention window.
- Settings does not rehydrate retained update jobs after a browser page
restart. Update dialog state, output, and results are intentionally
page-local and disappear when the page is restarted.
- npm's host cache may survive Kandev restarts, but Kandev does not own or
guarantee that cache.
- After a backend restart, normal host capability probing reports whichever
runtime npm resolves in that environment.
- The trusted package identity and active version are stored install-wide per
built-in agent in the system settings store and survive backend and browser
restarts. A record whose package no longer matches the agent's built-in
metadata is treated as having no active selection and is not applied to the
replacement package.
- The active version is written only after successful candidate validation, so
it is also the last known good selection.
- Jobs, process output, and capability cache remain process-local and do not
survive a backend restart.
- npm's execution cache is best-effort and is not Kandev-owned inventory. If an
exact selected cache entry disappears, npm may prepare that same exact
version again; it must not advance to another version.
- Dialog selection, output, and result remain page-local after a browser page
restart.
## Desktop and mobile behavior
- The existing agent-card update icon remains the entry point on desktop and
mobile and keeps a minimum 44 px touch target.
- Desktop uses the existing dialog. Phone layouts use the existing bottom
drawer; no nested drawer is introduced.
- The version selector is inside the shared body, is keyboard and touch
accessible, and shows latest and active markers without encoding state in
color alone.
- The body is the single internal scroll owner. The safe-area-aware footer
keeps the operation action reachable while long version lists and process
output remain viewport-contained.
- Selection state, preview loading, operation labels, request payloads, and
terminal results are shared across desktop and mobile presentations.
## Scenarios
- **GIVEN** a managed agent with a cached runtime, **WHEN** a new session starts
without an explicit update, **THEN** Kandev invokes the unversioned package
spec and does not require a repository-maintained version pin.
- **GIVEN** Claude reports runtime version `0.62.0` and npm reports `0.63.0`,
**WHEN** the operator opens its update action, **THEN** the dialog shows
`0.62.0 → 0.63.0`, the exact built-in command, and how the host update
affects capabilities and active sessions without starting the command.
- **GIVEN** the current runtime and upstream target both report version
`0.64.0`, **WHEN** the operator opens the update action, **THEN** the dialog
shows `0.64.0` once with **Up to date**, does not show a version transition,
keeps **Approve update** disabled on desktop and mobile, and starts no update
job.
- **GIVEN** the update dialog has a resolved preview, **WHEN** the operator
approves the update, **THEN** Kandev starts exactly one update and the dialog
streams stdout/stderr until the job is terminal.
- **GIVEN** an update succeeds and the new runtime advertises an additional
model, **WHEN** the automatic capability probe completes, **THEN** the new
model appears without a page reload or manual Rescan.
- **GIVEN** an update is already queued, resolving, updating, or refreshing,
**WHEN** the operator selects the action again, **THEN** Kandev returns the
existing job and does not run a second update.
- **GIVEN** an install is active for an agent, **WHEN** an update is requested
for that agent, **THEN** Kandev returns the active maintenance job rather
than running install and update concurrently.
- **GIVEN** npm registry lookup fails while preparing the dialog, **WHEN** the
update action is opened, **THEN** the dialog shows a retryable preview failure,
keeps approval disabled, and starts no update job.
- **GIVEN** npm registry lookup succeeds for the preview but fails after
approval because the registry changed, **WHEN** the update job resolves its
target again, **THEN** the dialog shows a retryable update failure and retains
the previous models.
- **GIVEN** a managed package's extracted `_npx` execution tree is corrupt,
**WHEN** the first update preparation fails, **THEN** Kandev invalidates only
that built-in package's deterministic execution-cache directory, retries
once, and probes the rebuilt runtime before reporting success.
- **GIVEN** the package update succeeds but the fresh probe requires
authentication, **WHEN** the job finishes, **THEN** the dialog reports the new
package version and refresh error, the previous models remain available, and
the card keeps its existing authentication recovery action.
- **GIVEN** an agent is unmanaged or native-only, **WHEN** Settings renders its
installed card, **THEN** no update action is shown.
- **GIVEN** an update dialog has shown progress or a terminal result, **WHEN**
the operator restarts the page, **THEN** the dialog is closed and no prior
update details, output, or result appear on the agent card or in a newly
opened dialog.
- **GIVEN** an update is running on a phone viewport, **WHEN** the operator
views the update surface, **THEN** current and target versions, the command,
progress, output, and retry state are reachable by touch without horizontal
page scrolling.
- **GIVEN** an agent session is already running, **WHEN** its host runtime is
updated, **THEN** the existing session continues unchanged and only later
probes or launches use the updated runtime.
- **GIVEN** OpenCode latest is partly published and its ACP probe fails,
**WHEN** an operator selects an older published stable version and approves
**Roll back runtime**, **THEN** Kandev prepares and probes that exact version,
persists it only after success, and restores its model list without restart.
- **GIVEN** a healthy exact active version, **WHEN** Kandev restarts, **THEN**
boot probes and later standalone sessions use the same exact version.
- **GIVEN** a candidate fails ACP initialization, **WHEN** the job ends,
**THEN** the previous active version and capabilities remain authoritative.
- **GIVEN** the current version is unknown and there is no active selection,
**WHEN** the operator selects a published target, **THEN** the UI offers
**Repair runtime** and validation establishes the first exact active version.
- **GIVEN** active, current, and target versions match, **WHEN** the dialog
opens, **THEN** it shows **Up to date** and starts no job.
- **GIVEN** a different target is submitted while a job is active for the same
agent, **WHEN** the backend receives it, **THEN** it returns the existing job
and does not run a second candidate concurrently.
- **GIVEN** an SSH or container session, **WHEN** the host active version
changes, **THEN** that executor's command remains unchanged.
- **GIVEN** a phone viewport and a long version catalogue or process log,
**WHEN** the operator selects and activates a version, **THEN** the drawer
remains contained and the primary action remains touch-reachable.
## Out of scope
- Scheduled or automatic package updates.
- Automatically deleting or rebuilding npm execution caches during every
ordinary agent launch.
- Exact package-version pins, version allowlists, rollback, or user-selected
historical versions.
- Updating configured remote executors or every running container from the
host Settings action.
- Restarting or hot-swapping active agent sessions.
- Managing native-only update channels such as Cursor.
- Updating separately distributed passthrough or authentication helper
packages when they are not the managed ACP runtime.
- Resuming or recovering update dialog state after a browser page restart.
- Scheduled or automatic updates and automatic rollback after launch failure.
- Prerelease, tag, arbitrary package-spec, registry, or shell-command input.
- Kandev-owned npm artifact retention or a package lockfile.
- Applying host selections to SSH, container, or other remote runtimes.
- Restarting or hot-swapping active sessions.
- Native-only update channels and separately distributed passthrough or
authentication packages.
- Persisting job output or reopening the dialog after a browser restart.