kandev/docs/plans/agent-runtime-update-dialog/plan.md

---
spec: docs/specs/agents/requirements/runtime-updates.md
created: 2026-07-27
status: complete
---

# Implementation Plan: Agent Runtime Update Dialog

## Overview

PR #1950 placed retained update state, versions, output, and results directly
inside installed-agent cards. It also configured PR previews with
`KANDEV_MOCK_AGENT=only`, which intentionally removes every real agent from the
registry and therefore leaves the install catalogue empty. This repair restores
the preview catalogue, adds a read-only update-preview contract, and moves the
approval and ephemeral streaming lifecycle into a responsive dialog.

## Confirmed root causes

- `apps/backend/cmd/preview/sprite_ops.go` exports
  `KANDEV_MOCK_AGENT=only`. `registry.Provide` treats `only` as an isolated E2E
  mode and registers only `mock-agent`; `ListAvailableAgents` can only return
  registry entries, so Settings receives no real install candidates.
- `AgentRuntimeUpdateControl` is rendered inside `InstalledAgentCard`, so all
  versions, output, and terminal state expand the card.
- `useAgentRuntimeUpdates` calls `listAgentUpdateJobs` on mount and upserts
  retained backend jobs into the global Settings store, explicitly restoring
  output and terminal state after a page restart.
- The only preparation path is `POST /agent-update/:agentName`; target-version
  resolution happens after enqueue, so the UI cannot show the next version and
  exact command before mutation.

## Backend

### Preview environment catalogue

Change `buildExtractScript` in
`apps/backend/cmd/preview/sprite_ops.go` to use
`KANDEV_MOCK_AGENT=true`. That mode retains the enabled mock agent while loading
the built-in real-agent catalogue, allowing unavailable agents with install
scripts to appear in Settings. Update the focused script assertion in
`apps/backend/cmd/preview/sprite_ops_test.go`; keep the registry mode test as
supporting evidence that `true` loads defaults and `only` does not.

### Read-only update preview

Add `AgentUpdatePreviewDTO` in
`apps/backend/internal/agent/settings/dto/dto.go` with agent, package, current
version, target version, argv, and display command fields.

Add `Controller.PreviewAgentUpdate(ctx, name)` in
`apps/backend/internal/agent/settings/controller/agent_update.go`. It validates
the same built-in `ManagedNPMRuntimeAgent` boundary as enqueue, reads the current
capability version, resolves the upstream target through `RuntimeUpdater`, and
serializes `CacheUpdateCommand()` with the existing `buildCommandString`
helper. Extend that helper to preserve empty argv entries as `""`, so the
displayed recipe remains an exact representation of the direct argv command.
It never claims maintenance state, creates a job, or executes the update command.

Register `GET /api/v1/agent-update/:agentName/preview` and a focused handler in
`apps/backend/internal/agent/settings/handlers/handlers.go`. Reuse the existing
update error classification for not-found, unsupported, unavailable, and
version-resolution failures.

## Frontend

### API and page-local update lifecycle

Add `AgentUpdatePreview` and `previewAgentUpdate` to
`apps/web/lib/api/domains/agent-update-api.ts`.

Refactor `useAgentRuntimeUpdates` so it does not list or hydrate retained update
jobs on mount. Starting an update returns or binds the accepted job identity for
the currently open dialog; WebSocket snapshots and chunks may continue using
the existing bounded Settings store, but the dialog displays only the job
started or recovered during its current page-local interaction.

### Installed-agent card and responsive update surface

Replace the inline `AgentRuntimeUpdateControl` composition with a compact
icon-only trigger in `apps/web/components/settings/installed-agent-card.tsx`.
The icon remains visually small while its standalone hitbox is at least 44px
and has an agent-specific accessible label and tooltip. Unmanaged agents omit
the trigger.

Replace `agent-runtime-update-control.tsx` with a responsive update surface:

- Desktop uses a centered `Dialog`.
- Phone uses an inset bottom `Drawer`, following
  `components/kanban/mobile-menu-sheet.tsx`, because this is a temporary,
  single-purpose approval flow rather than a primary route.
- Header and approval/dismiss actions remain fixed; one `min-h-0 flex-1
  overflow-y-auto` body owns scrolling and clears the bottom safe area.
- Opening fetches the read-only preview and shows current/target versions,
  host-only scope, automatic capability refresh, unchanged active sessions,
  and the exact wrapping command.
- Approval is disabled until preview succeeds and is the only action that
  sends the update POST.
- After approval, the same surface shows phase, bounded stdout/stderr, terminal
  result, and retry. Closing or restarting the page discards the UI selection
  and presentation state.
- No update information is rendered in the card.

### Public documentation

Update `docs/public/agents-and-profiles.md` to describe the icon-triggered
preview and approval flow, the exact-command disclosure, dialog-only streaming,
and the intentionally ephemeral browser presentation. The preview launcher
environment change is internal and does not need public environment-variable
documentation.

## Tests

- **Preview catalogue mode:** change `TestBuildExtractScript` first and confirm
  it fails while the script still exports `only`, then make it pass with
  `true`. File: `apps/backend/cmd/preview/sprite_ops_test.go`.
- **Read-only preview:** controller tests prove current/target/command output,
  empty-argument display, unmanaged rejection, registry failure, and absence
  of update execution.
  File:
  `apps/backend/internal/agent/settings/controller/agent_update_test.go`.
- **Exact display command:** extend the existing table test for
  `buildCommandString` with an empty argument. File:
  `apps/backend/internal/agent/settings/controller/controller_test.go`.
- **Preview handler:** handler tests prove the GET response and errors while
  preserving POST enqueue behavior. File:
  `apps/backend/internal/agent/settings/handlers/agent_update_handlers_test.go`.
- **Ephemeral state helper behavior:** retain focused Settings slice/WS tests
  for bounded same-job output merging, and remove the retained-job hydration
  expectation from the hook path. Files:
  `apps/web/lib/state/slices/settings/settings-slice.test.ts` and
  `apps/web/lib/ws/handlers/agents.test.ts`.
- **Public docs:** run `node --test scripts/validate-public-docs.test.mjs` and
  `node scripts/validate-public-docs.mjs`.

## E2E Tests

- **Desktop approval:** opening the card icon shows versions, explanation, and
  exact command while POST count remains zero; approving starts one job and
  streams output/result inside the dialog.
- **Restart reset:** after progress or a terminal result, restarting the page
  leaves only the icon on the card; a newly opened dialog contains a fresh
  preview and no prior output/result.
- **Mobile parity:** the Pixel 5 flow taps the 44px icon, uses the bottom
  drawer, reads the preview before approval, streams a long output without
  document horizontal overflow, and reaches the fixed final actions.

Files:

- `apps/web/e2e/tests/settings/agent-runtime-update.spec.ts`
- `apps/web/e2e/tests/settings/mobile-agent-runtime-update.spec.ts`
- `apps/web/e2e/tests/settings/agent-runtime-update-helpers.ts`

## Implementation Waves And Parallel Candidates

Execution is sequential in the primary conversation. No subagents are
authorized.

Wave 1:

- [x] [Task 01: Restore the preview install catalogue](task-01-preview-catalogue.md)
- [x] [Task 02: Add the read-only update preview API](task-02-update-preview-api.md)

Wave 2:

- [x] [Task 03: Move updates into an ephemeral responsive dialog](task-03-update-dialog-ui.md)

Wave 3:

- [x] [Task 04: Verify desktop and mobile update flows](task-04-update-dialog-e2e.md)

Tasks 01 and 02 touch disjoint files, but remain sequential unless the user
explicitly authorizes subagents after the model checkpoint.