Files
kandev/docs/specs/agents/system-design/runtime-updates-01.md
T

534 lines
27 KiB
Markdown

---
status: draft
system: agents
requirements:
- REQ-AGENTS-RUNTIME-UPDATES-001
created: 2026-07-26
updated: 2026-09-07
owners:
- Kandev
---
# Managed Agent Runtime Versions and Updates System Design Part 1
## Purpose and boundaries
This design preserves the technical source detail for `REQ-AGENTS-RUNTIME-UPDATES-001` during migration.
## Requirement mapping
| Requirement | Design section |
| --- | --- |
| `REQ-AGENTS-RUNTIME-UPDATES-001` | [Migrated source detail](#migrated-source-detail) |
## Migrated source detail
## Why
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.
Operators also need to know that a newer managed agent bridge exists before
they open its version dialog. Kandev must provide a stable reviewed default for
unmodified installations without preventing an operator from selecting a newer
validated version between Kandev releases.
Managed npm runtime recovery now has an authoritative requirement and design:
[managed npm runtime recovery](requirements/managed-npm-runtime-recovery.md).
## What
- 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.
- Every managed npm runtime has an exact Kandev default version. A successful
activation persists an exact selection for the current default generation.
The selection is effective until the operator or a later generation replaces it.
- Kandev does not persist the default as an operator selection. Startup removes
an earlier selection when the trusted package or default version changes.
- Every Kandev-built ACP command for the managed package uses the effective
exact version, including probes, utility calls, standalone sessions,
containers, and SSH executors. Active sessions continue unchanged.
- Settings lets the operator clear the selected version and return to the
Kandev default after that default passes the normal candidate validation.
- 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.
- Managed runtime resolution changes only the structured ACP command surfaces.
When an agent's interactive passthrough CLI is distributed separately from
its ACP adapter, passthrough keeps its own package, executable, and install
recipe.
- Jobs for one agent are idempotent while queued or running. Installation and
version management for the same agent cannot run concurrently.
- Managed npm runtime recovery follows the authoritative
[recovery requirement](requirements/managed-npm-runtime-recovery.md).
- When the Agents settings page loads, Kandev checks each available managed
package against npm's stable `latest` version through one batch status
request. A newer version marks the existing update control with a blue dot
and accessible update information.
- An update-status check is read-only. It never prepares, probes, selects, or
starts a runtime. Registry failure leaves the status unknown, keeps the update
control usable, and does not show a false up-to-date result.
- Kandev caches successful registry status checks for six hours per package and
failed checks for fifteen minutes. Opening the version dialog still performs
an authoritative live preview.
- The authoritative preview normalizes valid stable package metadata returned
by supported npm CLI versions, including npm versions that wrap a
multi-field `npm view` response in a one-element array. A valid response
always produces the same stable version catalogue for the operator.
- The version dialog presents a compact status summary and quick choices for
the latest and Kandev default versions. The complete stable catalogue stays
behind an explicit browse action and can be searched by version.
- The initial preview fits within the desktop dialog and phone drawer without
body overflow. The shared body becomes scrollable only when the version
browser or streamed job output needs more space.
- Opening the version browser uses an anchored popover. The popover must not
increase the dialog or drawer height, must remain viewport-contained, and
must close after a version is selected.
The managed package set is:
| Agent | Managed runtime package |
| --- | --- |
| Claude | `@agentclientprotocol/claude-agent-acp` |
| Codex | `@agentclientprotocol/codex-acp` |
| OpenCode | `opencode-ai` |
| Copilot | `@github/copilot` |
| Gemini | `@google/gemini-cli` |
Passthrough commands, native authentication helpers, and native-only agents
remain outside this version action when they use another installer or package.
Decision:
[ADR-2026-08-12-validated-managed-runtime-version-selection](../../../decisions/2026-08-12-validated-managed-runtime-version-selection.md).
Upgrade-time precedence is defined by the
[runtime default activation design](runtime-default-activation.md).
## Version and operation semantics
Kandev distinguishes six version values:
- `current_version` is the version reported by the last successful host ACP
probe. It can be absent after a failed probe.
- `default_version` is the exact reviewed version shipped with Kandev.
- `active_version` is the exact operator-selected version for the current
default generation. It is absent when the operator follows the Kandev default.
- `effective_version` is `active_version` when present and `default_version`
otherwise. It is never empty for a supported managed runtime.
- `latest_version` is npm's stable `latest` version from the most recent update
status check or authoritative preview. It is absent when that check fails.
- `target_version` is the stable version selected by the operator.
The backend derives the operation from `effective_version` and
`current_version`. When an active operator selection exists and the operator
chooses `default_version`, `use_default` takes precedence over version
comparison. Without that reset condition, the backend classifies the request as
`update`, `rollback`, `repair`, or `up_to_date`:
| 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 or versions cannot be compared. | `repair` | **Repair runtime** |
| Effective, current, and target versions match. | `up_to_date` | Disabled as **Up to date** |
| An active operator selection exists and the operator chooses the shipped default. | `use_default` | **Use Kandev default** |
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
### Agent catalogue
Installed-agent catalogue entries expose optional runtime-management metadata:
```json
{
"runtime_update": {
"supported": true,
"package": "opencode-ai",
"current_version": "1.18.5",
"default_version": "1.18.5",
"effective_version": "1.18.5"
}
}
```
`current_version` and `active_version` are independently omitted when unknown
or not selected. `default_version` and `effective_version` are required when
`supported` is true. Unmanaged agents omit `runtime_update`.
### Update status
- `GET /api/v1/agent-update/status` returns one status for every available
built-in managed runtime.
- The backend queries stale package entries concurrently with a fixed bound and
reuses fresh per-package cache entries.
- One package lookup failure does not fail the full response.
```json
{
"statuses": [
{
"agent_name": "opencode-acp",
"package": "opencode-ai",
"default_version": "1.18.5",
"effective_version": "1.18.5",
"latest_version": "1.18.16",
"check_state": "update_available",
"checked_at": "timestamp"
}
]
}
```
`check_state` is `update_available`, `up_to_date`, or `unknown`. The backend
sets `update_available` only when strict stable SemVer ordering proves that
`latest_version` is newer than `effective_version`. It does not flag an older
upstream version as an update. An unknown entry omits `latest_version` and
`checked_at` when no successful cached value exists.
### Preview and jobs
- `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.
- `GET /api/v1/agent-update/:agentName/preview?use_default=true` previews
returning to the trusted shipped default.
- `POST /api/v1/agent-update/:agentName` accepts JSON
`{ "target_version": "1.18.5" }` or `{ "use_default": true }` and starts or
returns the active job. `use_default` resolves the target from trusted agent
metadata; callers do not supply both fields.
- `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.
A preview contains:
```json
{
"agent_name": "opencode-acp",
"package": "opencode-ai",
"current_version": "1.18.5",
"default_version": "1.18.5",
"effective_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": "opencode-acp",
"status": "refreshing",
"operation": "rollback",
"current_version": "1.18.16",
"active_version": "1.18.16",
"default_version": "1.18.5",
"effective_version": "1.18.16",
"target_version": "1.18.5",
"output": "",
"error": "",
"refresh_error": "",
"started_at": "timestamp",
"finished_at": "timestamp"
}
```
`active_version` reflects the persisted operator selection at that job
snapshot. `effective_version` reflects the version future managed commands use.
For a selected target, both become the target only after successful validation
and persistence. For `use_default`, `active_version` is removed and
`effective_version` becomes `default_version` only after successful validation. The
existing `agent.update.started`, `agent.update.output`, and
`agent.update.finished` WebSocket notifications carry the same job fields.
## Activation lifecycle
| State | Backend behavior | Observable behavior |
| --- | --- | --- |
| `queued` | Accept the selected version and maintenance claim. | The version picker and action are disabled. |
| `resolving` | Re-read npm versions, resolve the requested exact target or trusted default, 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, save the selected target or delete the selection for `use_default`, 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 effective 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`. Selecting the effective,
healthy version produces `up_to_date` in preview and starts no job. Returning
to the default still validates that default before deleting an existing
selection. Selecting the effective version while its current probe is unknown
produces a repair job.
## Command routing
- Every managed-agent command resolves the effective version immediately before
building its command. It emits the trusted `package@effective_version` spec.
- Boot probes, manual capability refreshes, model-configuration resolution,
sessionless utility prompts, standalone sessions, containers, and SSH
executors use the same effective-version resolver.
- Native-binary preference continues to win when an agent deliberately selects
its supported native binary path.
- Passthrough command construction does not receive or apply the active managed
ACP version. It continues to use the agent's declared interactive CLI.
- A saved selection read error fails the new managed command with an actionable
error. It does not fall back to the default or an unversioned package.
- Candidate validation bypasses the active selection only for the trusted exact
candidate command created by the version job.
- No supported managed-runtime command emits an unversioned package spec.
## Launch-time stale metadata recovery
The [managed npm runtime recovery requirement](requirements/managed-npm-runtime-recovery.md)
and its [system design](system-design/managed-npm-runtime-recovery.md) are
authoritative for launch-time stale metadata recovery.
## Failure and recovery behavior
- Registry failure during preview keeps approval disabled and runs no command.
- A valid package metadata response in a supported npm CLI output shape is not
treated as a registry failure. Malformed, empty, or ambiguous metadata still
fails closed and keeps approval disabled.
- 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.
- Launch-time recovery does not change the active version. The authoritative
[recovery requirement](requirements/managed-npm-runtime-recovery.md) defines
its observable behavior.
- Registry failure during the batch update-status check returns `unknown` for
only the affected package. It does not disable the update control, show an
error badge, or claim that the package is up to date.
- A stale update-available dot can remain until the successful six-hour cache
entry expires. Opening the dialog always replaces that hint with a live
authoritative preview. A successful update or reset invalidates the affected
status cache and refreshes the page state.
## Persistence guarantees
- The trusted package identity and operator-selected version are stored
install-wide per built-in agent. Current-generation selections survive
restarts while the shipped package and default version remain unchanged. A
legacy selection without a generation marker is reset during the first
startup that applies this behavior.
- Startup records one applied default generation per managed agent. A changed
package or default removes the earlier selection before runtime consumers start.
- The Kandev default is compiled into the managed runtime catalogue and is not
copied into the settings database. Clearing a selection deletes its settings
record only after the default candidate passes validation.
- An operator-selected 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.
- Update-status results and timestamps are process-local cache entries. They do
not survive a backend restart and do not require a database migration.
- npm's execution cache is best-effort and is not Kandev-owned inventory. If an
exact effective 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.
- Terminal launch-time npm resolution metadata follows the authoritative
[recovery design](system-design/managed-npm-runtime-recovery.md).
## 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.
- When `check_state` is `update_available`, the update icon shows a blue dot.
The button's accessible name and desktop tooltip state the current effective
and latest versions, so color is not the only signal. The dot is absent for
`up_to_date` and `unknown`.
- 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 compact dialog does not render the complete catalogue by default. The
browse surface exposes the complete list only after the operator requests it,
provides a search field, and keeps the selected, latest, active, and default
markers available.
- 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.
- Tapping the dotted control on a phone opens the same version drawer and shows
the authoritative version summary. The dot itself is not a separate touch
target and does not depend on hover.
- A failed automatic launch retry uses the existing inline recovery card in
Kanban chat and Office chat. It does not open a dialog or drawer.
- The card states that npm could not prepare the agent runtime. It states that
Kandev refreshed package data and retried once. Technical details are
collapsed initially.
- The card offers one **Retry runtime** action. When a resume token exists, the
action resumes the session. Otherwise, it starts a replacement run. The card
does not present session history loss as a fix for an npm problem.
- Phone actions stack when needed, remain at least 44 px high, and do not add a
second scroll container.
- Launch-time recovery presentation follows the authoritative
[recovery requirement](requirements/managed-npm-runtime-recovery.md).
## Scenarios
- **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 and an unchanged default generation,
**WHEN** Kandev restarts, **THEN** boot probes and later commands use that version.
- **GIVEN** an agent has no operator selection, **WHEN** Kandev builds any of
its managed npm ACP commands, **THEN** the command uses the exact reviewed
Kandev default and never an unversioned package spec.
- **GIVEN** an agent has a current-generation operator selection, **WHEN**
Kandev builds a managed ACP command, **THEN** the command uses that selection.
- **GIVEN** an operator selection exists, **WHEN** the operator chooses **Use
Kandev default**, **THEN** Kandev validates the exact default, deletes the
selection only after success, and future commands follow shipped defaults.
- **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 the effective version is known,
**WHEN** the operator selects a published target, **THEN** the UI offers
**Repair runtime** and validation establishes the selected exact version.
- **GIVEN** effective, 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 agent whose interactive passthrough CLI is separate from its
managed ACP adapter, **WHEN** the effective ACP version changes, **THEN**
later passthrough sessions still launch the declared interactive CLI and do
not launch the ACP package under a PTY.
- **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.
- **GIVEN** npm reports a newer stable version than the effective version,
**WHEN** the Agents settings page loads, **THEN** the existing update control
shows a blue dot and exposes both versions in accessible update information.
- **GIVEN** the update-status lookup fails for one managed package, **WHEN** the
Agents settings page loads, **THEN** that package shows no blue dot, its
update control remains usable, and other package statuses still render.
- **GIVEN** npm returns valid stable package metadata in either its object form
or a supported one-element collection form, **WHEN** the operator opens a
managed runtime update dialog, **THEN** the dialog lists the stable versions,
selects npm's stable latest version, and does not show a resolution error.
- **GIVEN** a managed runtime has a long stable version catalogue, **WHEN** the
operator opens its update dialog, **THEN** the dialog shows the status summary
and quick choices without rendering the full version history.
- **GIVEN** the operator opens the full version browser and enters a version
fragment, **WHEN** matching versions exist, **THEN** only matching stable
versions remain selectable and selecting one previews that exact target.
- **GIVEN** the operator opens the full version browser on a phone, **WHEN** the
operator searches or selects a version, **THEN** the existing update drawer
keeps one contained scroll owner, exposes 44px touch rows, and preserves the
same target selection behavior as desktop.
- **GIVEN** the operator opens a long version catalogue, **WHEN** the operator
opens the version selector, **THEN** the catalogue appears in an anchored
popover without increasing the dialog or drawer height, and selecting a
version closes the popover.
- **GIVEN** a dotted update control on a phone, **WHEN** the operator taps it,
**THEN** the existing update drawer opens and shows a live authoritative
preview without requiring hover.
- Managed npm runtime recovery scenarios follow the authoritative
[recovery requirement](requirements/managed-npm-runtime-recovery.md).
## Scheduled pin-update workflow
The weekly and manual pin-maintenance path satisfies
`AC-AGENTS-RUNTIME-UPDATES-001.9` and
`AC-AGENTS-RUNTIME-UPDATES-001.10`. The trusted catalogue is updated by
[`scripts/update-agent-runtime-pins.mjs`](../../../scripts/update-agent-runtime-pins.mjs)
and orchestrated by
[`update-agent-runtime-pins.yml`](../../../.github/workflows/update-agent-runtime-pins.yml).
The workflow checks out `main`, runs the updater and managed-runtime validation
before any branch mutation, and then pushes the stable
`automation/update-managed-runtime-pins` branch only when the catalogue
changed. It creates or refreshes one grouped review pull request and never
merges it or activates a runtime.
The workflow uses the repository-scoped built-in `GITHUB_TOKEN`. Its effective
permissions are limited to `contents: write`, `pull-requests: write`, and
`actions: write`. `gh auth setup-git` configures the token after the trusted
checkout. No GitHub-App variable, private-key secret, or personal access token
is required. The workflow keeps `persist-credentials: false` on checkout and
does not run pull-request-controlled code.
GitHub does not recursively start `push` or `pull_request` workflows for events
created with `GITHUB_TOKEN`. Each required validation workflow therefore also
declares `workflow_dispatch`, and the pin-maintenance workflow explicitly
dispatches these workflows against the exact
`automation/update-managed-runtime-pins` commit after the grouped PR exists:
`backend-tests.yml`, `frontend-tests.yml`, `e2e-tests.yml`,
`architecture-lint.yml`, `lint-action-pinning.yml`, and
`lint-harness-files.yml`. The manual architecture run derives its baseline from
the fork point with `main`; the other validation gates fail open to a full run
when a manual event has no push or pull-request base. This keeps the six
required check contexts reportable without a separate App or PAT.
The repository or organization setting **Allow GitHub Actions to create and
approve pull requests** must remain enabled for the built-in token to create or
refresh the grouped PR. GitHub may still apply its approval policy to generated
workflow runs; that policy is operationally distinct from the event-suppression
problem solved by explicit dispatch.
## Out of scope
- Automatic runtime installation, selection changes outside default-generation
activation, and automatic rollback after launch failure.
- Global npm cache cleanup, registry replacement, dependency substitution, or
automatic selection of another package version.
- Prerelease, tag, arbitrary package-spec, registry, or shell-command input.
- Kandev-owned npm artifact retention or a package lockfile.
- Removing npm or network access from the launch path, or locking transitive
dependency ranges inside upstream packages.
- 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.