115 lines
4.8 KiB
Markdown
115 lines
4.8 KiB
Markdown
---
|
|
id: "03-surface-runtime-failure"
|
|
title: "Surface runtime failure and recovery"
|
|
status: done
|
|
wave: 2
|
|
depends_on: ["02-publish-agent-runtime-availability"]
|
|
plan: "plan.md"
|
|
spec: "../../specs/platform/requirements/agent-runtime-availability.md"
|
|
---
|
|
|
|
# Task 03: Surface runtime failure and recovery
|
|
|
|
## Intent
|
|
|
|
Hydrate the backend-owned runtime snapshot and show a persistent, accessible
|
|
shell-level explanation with the supported Kandev restart path.
|
|
|
|
## Acceptance
|
|
|
|
- Zustand hydrates and replaces the full `agentRuntime` snapshot from boot and
|
|
`system.agent_runtime.status_changed` without modifying domain data.
|
|
- One non-dismissible `role="alert"` renders for unavailable state on every
|
|
authenticated route, including when the App status bar feature is disabled.
|
|
- Copy explains the local runtime impact, saved-data safety, and required full
|
|
restart without exposing raw diagnostics.
|
|
- Supported supervisors show a working **Restart Kandev** action and existing
|
|
restart progress flow; unsupported or failed capability lookup shows localized
|
|
manual guidance.
|
|
- Restart request errors leave the alert mounted and readable.
|
|
- A new available snapshot removes the alert; browser connection changes alone
|
|
do not.
|
|
- All new user-visible copy is localized in every shipped locale.
|
|
|
|
## TDD sequence
|
|
|
|
1. Add store/hydration and system-event handler tests for unavailable, available,
|
|
and unrelated reconnect updates; confirm RED before the state contract exists.
|
|
2. Add alert/provider tests with the App status bar disabled, retained route
|
|
children, supported capability, unsupported capability, restart error, and
|
|
recovery; confirm RED before rendering.
|
|
3. Implement the type, store state/action, handler, alert, provider placement,
|
|
capability selection, restart flow reuse, and translations.
|
|
4. Rerun focused tests, typecheck, and i18n checks before refactoring.
|
|
|
|
## Files likely touched
|
|
|
|
- `apps/web/lib/types/agent-runtime.ts`
|
|
- `apps/web/lib/state/default-state.ts`
|
|
- `apps/web/lib/state/store.ts`
|
|
- `apps/web/lib/state/store-overrides.ts`
|
|
- `apps/web/lib/ws/handlers/system-events.ts`
|
|
- `apps/web/lib/ws/handlers/system-events.test.ts`
|
|
- `apps/web/components/app-status-bar/agent-runtime-unavailable-alert.tsx`
|
|
- `apps/web/components/app-status-bar/agent-runtime-unavailable-alert.test.tsx`
|
|
- `apps/web/components/app-status-bar/app-status-surface-provider.tsx`
|
|
- `apps/web/components/app-status-bar/app-status-surface-provider.test.tsx`
|
|
- `apps/web/src/locales/en/system.json`
|
|
- `apps/web/src/locales/pt-pt/system.json`
|
|
- `apps/web/src/locales/zh-cn/system.json`
|
|
|
|
## Dependencies
|
|
|
|
Task 02's final boot and WebSocket contract.
|
|
|
|
## Parallelism
|
|
|
|
`sequential` — this task consumes the backend contract and owns the shared shell
|
|
surface used by Task 04.
|
|
|
|
## Mobile parity
|
|
|
|
The nearest shell exemplar is the in-flow App status surface, while the nearest
|
|
error exemplar is the existing SPA/session recovery alert. Phone composition
|
|
stacks copy and action, keeps the action at least 44 px, remains inside the
|
|
route/status column, and adds no fixed or bottom surface. Unit tests assert
|
|
responsive classes and semantics; Task 04 verifies real viewport geometry.
|
|
|
|
## Verification
|
|
|
|
- `cd apps && pnpm --filter @kandev/web test -- --run lib/state lib/ws/handlers/system-events.test.ts components/app-status-bar`
|
|
- `cd apps/web && pnpm run typecheck`
|
|
- `cd apps/web && pnpm run i18n:check && pnpm run i18n:ratchet`
|
|
|
|
## Inputs
|
|
|
|
- Task 02 public snapshot and action.
|
|
- Existing `useRestartCapability`, `useKandevRestart`, and
|
|
`RestartProgressDialog` behavior.
|
|
- App status surface shell geometry and mobile UI language reference.
|
|
|
|
## Output contract
|
|
|
|
Record focused unit, typecheck, and i18n results plus the final localized copy
|
|
keys and any deliberate change to alert placement.
|
|
|
|
## Results
|
|
|
|
Implemented the backend-shaped `agentRuntime` snapshot in the web store,
|
|
hydrated it from boot state, and replaced it on the global runtime WebSocket
|
|
event without clearing domain state. Added the in-flow localized alert outside
|
|
the App status bar feature gate, reusing the existing capability and restart
|
|
progress hooks. Supported supervisors expose `Restart Kandev`; capability
|
|
lookup failures render manual guidance, and restart errors leave the alert
|
|
mounted until an available snapshot arrives.
|
|
|
|
Focused validation passed:
|
|
|
|
- `pnpm --filter @kandev/web test -- --run lib/state/store.test.ts lib/ws/handlers/system-events.test.ts components/app-status-bar/agent-runtime-unavailable-alert.test.tsx components/app-status-bar/app-status-surface-provider.test.tsx` — 21 tests passed.
|
|
- `pnpm run typecheck` — passed.
|
|
- `pnpm run i18n:check && pnpm run i18n:ratchet` — passed; pseudo catalog regenerated and synced.
|
|
|
|
The alert uses localized English, Portuguese, Chinese, and pseudo-locale
|
|
entries, remains in normal shell flow on phone layouts, and keeps its restart
|
|
action at the required 44 px minimum.
|