feat: improve agent runtime update flow (#1982)
This commit is contained in:
@@ -0,0 +1,173 @@
|
||||
---
|
||||
spec: docs/specs/agents/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.
|
||||
@@ -0,0 +1,51 @@
|
||||
---
|
||||
id: "01-preview-catalogue"
|
||||
title: "Restore the preview install catalogue"
|
||||
status: done
|
||||
wave: 1
|
||||
depends_on: []
|
||||
plan: "plan.md"
|
||||
spec: "../../specs/agents/runtime-updates.md"
|
||||
---
|
||||
|
||||
# Task 01: Restore the preview install catalogue
|
||||
|
||||
## Acceptance
|
||||
|
||||
- PR previews enable `mock-agent` while retaining the built-in real-agent
|
||||
catalogue.
|
||||
- Settings can derive unavailable built-in agents and their install scripts
|
||||
from the preview registry.
|
||||
- E2E-only `KANDEV_MOCK_AGENT=only` semantics remain unchanged elsewhere.
|
||||
|
||||
## Verification
|
||||
|
||||
- RED/GREEN:
|
||||
`cd apps/backend && go test -run TestBuildExtractScript ./cmd/preview`
|
||||
- Supporting:
|
||||
`cd apps/backend && go test -run TestProvide_MockAgentModes ./internal/agent/registry`
|
||||
|
||||
## Files likely touched
|
||||
|
||||
- `apps/backend/cmd/preview/sprite_ops.go`
|
||||
- `apps/backend/cmd/preview/sprite_ops_test.go`
|
||||
|
||||
## Dependencies
|
||||
|
||||
None.
|
||||
|
||||
## Parallelism
|
||||
|
||||
Sequential by default. It is file-disjoint from Task 02 and may run in
|
||||
parallel only with explicit user authorization.
|
||||
|
||||
## Inputs
|
||||
|
||||
- Spec agent-catalogue and Settings scenarios
|
||||
- `registry.Provide` mock-mode contract
|
||||
- Confirmed preview script root cause in `plan.md`
|
||||
|
||||
## Output contract
|
||||
|
||||
Report RED and GREEN results, changed files, preview-mode risk, and update this
|
||||
task plus `plan.md` status in the primary conversation.
|
||||
@@ -0,0 +1,60 @@
|
||||
---
|
||||
id: "02-update-preview-api"
|
||||
title: "Add the read-only update preview API"
|
||||
status: done
|
||||
wave: 1
|
||||
depends_on: []
|
||||
plan: "plan.md"
|
||||
spec: "../../specs/agents/runtime-updates.md"
|
||||
---
|
||||
|
||||
# Task 02: Add the read-only update preview API
|
||||
|
||||
## Acceptance
|
||||
|
||||
- A managed installed agent exposes current version, upstream target version,
|
||||
trusted update argv, and a display command through a read-only endpoint.
|
||||
- The display command quotes the update recipe's empty final argv entry as
|
||||
`""`, preserving the exact direct-execution command.
|
||||
- Preview never creates a job, claims maintenance state, or executes the
|
||||
update command.
|
||||
- Unmanaged, missing, unavailable-updater, and registry-resolution failures
|
||||
return explicit errors and do not mutate runtime state.
|
||||
|
||||
## Verification
|
||||
|
||||
- RED/GREEN controller:
|
||||
`cd apps/backend && go test -run 'TestAgentUpdatePreview' ./internal/agent/settings/controller`
|
||||
- RED/GREEN handler:
|
||||
`cd apps/backend && go test -run 'TestAgentUpdatePreviewEndpoint' ./internal/agent/settings/handlers`
|
||||
|
||||
## Files likely touched
|
||||
|
||||
- `apps/backend/internal/agent/settings/dto/dto.go`
|
||||
- `apps/backend/internal/agent/settings/controller/controller.go`
|
||||
- `apps/backend/internal/agent/settings/controller/controller_test.go`
|
||||
- `apps/backend/internal/agent/settings/controller/agent_update.go`
|
||||
- `apps/backend/internal/agent/settings/controller/agent_update_test.go`
|
||||
- `apps/backend/internal/agent/settings/handlers/handlers.go`
|
||||
- `apps/backend/internal/agent/settings/handlers/agent_update_handlers_test.go`
|
||||
|
||||
## Dependencies
|
||||
|
||||
None.
|
||||
|
||||
## Parallelism
|
||||
|
||||
Sequential by default. It is file-disjoint from Task 01 and may run in
|
||||
parallel only with explicit user authorization.
|
||||
|
||||
## Inputs
|
||||
|
||||
- Spec update-preview API and approval scenarios
|
||||
- Existing `RuntimeUpdater`, `ManagedNPMRuntimeSpec.CacheUpdateCommand`, and
|
||||
`buildCommandString`
|
||||
- Existing update handler error mapping and direct-argv security boundary
|
||||
|
||||
## Output contract
|
||||
|
||||
Report RED and GREEN results, response/error contracts, changed files, command
|
||||
trust-boundary risk, and update this task plus `plan.md` status.
|
||||
@@ -0,0 +1,70 @@
|
||||
---
|
||||
id: "03-update-dialog-ui"
|
||||
title: "Move updates into an ephemeral responsive dialog"
|
||||
status: done
|
||||
wave: 2
|
||||
depends_on: ["02-update-preview-api"]
|
||||
plan: "plan.md"
|
||||
spec: "../../specs/agents/runtime-updates.md"
|
||||
---
|
||||
|
||||
# Task 03: Move updates into an ephemeral responsive dialog
|
||||
|
||||
## Acceptance
|
||||
|
||||
- Managed cards show only a compact, accessible update icon; versions, command,
|
||||
output, progress, and results appear only in the opened surface.
|
||||
- Opening is read-only and approval is unavailable until current version,
|
||||
target version, explanation, and exact command are visible.
|
||||
- The approved job streams stdout/stderr and terminal state in the current
|
||||
surface, while closing or restarting the page discards its presentation.
|
||||
- Desktop uses a centered dialog; phone uses an inset bottom drawer with a
|
||||
44px trigger, fixed header/footer, one safe-area-aware scrolling body, and no
|
||||
document horizontal overflow.
|
||||
- Public Agents documentation describes the preview/approval dialog and notes
|
||||
that its visible progress and results reset on page restart.
|
||||
|
||||
## Verification
|
||||
|
||||
- Targeted state/WS tests:
|
||||
`cd apps && pnpm --filter @kandev/web test -- --run lib/state/slices/settings/settings-slice.test.ts lib/ws/handlers/agents.test.ts`
|
||||
- Typecheck:
|
||||
`cd apps/web && pnpm run typecheck`
|
||||
- Lint:
|
||||
`cd apps && pnpm --filter @kandev/web lint`
|
||||
- Public docs:
|
||||
`node --test scripts/validate-public-docs.test.mjs && node scripts/validate-public-docs.mjs`
|
||||
|
||||
## Files likely touched
|
||||
|
||||
- `apps/web/lib/api/domains/agent-update-api.ts`
|
||||
- `apps/web/lib/api/index.ts`
|
||||
- `apps/web/hooks/domains/settings/use-agent-runtime-updates.ts`
|
||||
- `apps/web/app/settings/agents/page.tsx`
|
||||
- `apps/web/components/settings/installed-agent-card.tsx`
|
||||
- `apps/web/components/settings/agent-runtime-update-control.tsx`
|
||||
- `apps/web/components/settings/use-agent-update-dialog-state.ts`
|
||||
- `apps/web/lib/state/slices/settings/settings-slice.test.ts`
|
||||
- `docs/public/agents-and-profiles.md`
|
||||
|
||||
## Dependencies
|
||||
|
||||
Task 02 defines the read-only preview contract.
|
||||
|
||||
## Parallelism
|
||||
|
||||
Sequential.
|
||||
|
||||
## Inputs
|
||||
|
||||
- Spec approval, non-persistence, failure, and mobile scenarios
|
||||
- `components/kanban/mobile-menu-sheet.tsx` mobile surface exemplar
|
||||
- Existing Settings WS job merging and install/update conflict handling
|
||||
- Mobile contract in `plan.md`
|
||||
- `/docs-maintainer` task-oriented documentation requirements
|
||||
|
||||
## Output contract
|
||||
|
||||
Report RED/GREEN evidence where non-visual logic changes, rendered desktop and
|
||||
phone evidence, changed files, accessibility/mobile/state risks, and update
|
||||
this task plus `plan.md` status.
|
||||
@@ -0,0 +1,55 @@
|
||||
---
|
||||
id: "04-update-dialog-e2e"
|
||||
title: "Verify desktop and mobile update dialog flows"
|
||||
status: done
|
||||
wave: 3
|
||||
depends_on: ["01-preview-catalogue", "02-update-preview-api", "03-update-dialog-ui"]
|
||||
plan: "plan.md"
|
||||
spec: "../../specs/agents/runtime-updates.md"
|
||||
---
|
||||
|
||||
# Task 04: Verify desktop and mobile update dialog flows
|
||||
|
||||
## Acceptance
|
||||
|
||||
- Desktop Playwright proves the icon opens a read-only preview, approval starts
|
||||
one job, and stdout/stderr plus terminal state remain inside the dialog.
|
||||
- Restart coverage proves prior progress/output/result is absent from the card
|
||||
and a newly opened dialog.
|
||||
- Mobile Chrome proves the 44px icon and bottom drawer deliver the same value,
|
||||
keep long content internally reachable, clear safe areas, and do not create
|
||||
document horizontal overflow.
|
||||
|
||||
## Verification
|
||||
|
||||
- Desktop:
|
||||
`cd apps/web && pnpm e2e:run tests/settings/agent-runtime-update.spec.ts`
|
||||
- Mobile:
|
||||
`cd apps/web && pnpm e2e:run tests/settings/mobile-agent-runtime-update.spec.ts -- --project=mobile-chrome`
|
||||
|
||||
## 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`
|
||||
- Runtime-update UI files only for test IDs or regressions exposed by RED
|
||||
|
||||
## Dependencies
|
||||
|
||||
Tasks 01-03.
|
||||
|
||||
## Parallelism
|
||||
|
||||
Sequential.
|
||||
|
||||
## Inputs
|
||||
|
||||
- Every revised user-visible spec scenario
|
||||
- `/e2e` production-build and mobile input-modality requirements
|
||||
- Mobile geometry contract in `plan.md`
|
||||
|
||||
## Output contract
|
||||
|
||||
Report exact RED and GREEN commands/results, rendered artifacts inspected,
|
||||
desktop/mobile geometry evidence, uncertainties, and update this task plus
|
||||
`plan.md` status.
|
||||
Reference in New Issue
Block a user