Developer
caadd59441
Move the following audited-and-implemented changes into openspec/changes/archive/2026-06-12-completed-changes-archive/: - backend-frontend-refactoring - config-profile-git-mounts - config-profile-includes-ui - config-profile-multi-repo-mounts - container-monitoring-notifications - git-mount-url-validation - home-path-expansion - mobile-terminal-ux - mount-specificity-ordering - notification-center - persistent-terminal-sessions - session-list-overhaul - ssh-key-mounting - terminal-fullscreen-unified-header - tool-session-progress-and-updates Also regenerated .pi-map*.md files for openspec/changes so the remaining active changes (multi-session-terminal-ux, reorganize-long-files, working-copies, workspace-first-ui) reflect the new layout.
72 lines
3.9 KiB
Markdown
72 lines
3.9 KiB
Markdown
# Design: Tool Session Progress and Live Updates
|
|
|
|
## Goals / Non-Goals
|
|
|
|
**Goals:**
|
|
- Provide structured, real-time progress feedback for every tool lifecycle action.
|
|
- Ensure all session lists (nav, dashboard, sessions page) update immediately after create/delete.
|
|
- Remove blocking and card-dimming overlays that hide context and provide no step detail.
|
|
- Keep the change frontend-only, reusing existing SSE and session APIs.
|
|
|
|
**Non-Goals:**
|
|
- No new backend endpoints or event types.
|
|
- No changes to the actual Docker/container orchestration logic.
|
|
- No redesign of the session card layout beyond action/progress affordances.
|
|
|
|
## Decisions
|
|
|
|
### Decision: Global progress panel in the corner
|
|
A fixed panel (bottom-right desktop, bottom sheet style on mobile) lists in-flight operations. Each operation shows:
|
|
- Action icon + session display name
|
|
- Current step label derived from the latest SSE event
|
|
- A compact stepper: Created → Building → Starting → Probing → Ready/Error
|
|
- Dismiss button once settled
|
|
|
|
This is non-blocking, works across pages, and does not interfere with the modal create flow.
|
|
|
|
### Decision: SSE event-driven updates
|
|
The panel subscribes to `useEvents`. When an operation is started we record `instanceId` + `action`. Incoming events that match a tracked instance update the operation's message, status, and step. Events handled:
|
|
- `instance.created`, `instance.started`, `instance.restarted` → advance
|
|
- `instance.health_changed` with `status=running` → complete success
|
|
- `instance.error` → complete error
|
|
- `instance.stopped` → complete for stop action
|
|
- `instance.deleted` → complete for delete action
|
|
|
|
### Decision: Shared session state
|
|
`SessionsContext` is promoted from a nav-only data holder to the authoritative session list:
|
|
- Holds `sessions`, `isLoading`, `error`, `refreshSessions()`.
|
|
- Provides `addOrUpdateSession`, `removeSession` for optimistic updates.
|
|
- `AppShell`, `DashboardPage`, and `SessionsPage` read from this context instead of fetching independently.
|
|
|
|
### Decision: Optimistic create/delete updates
|
|
- **Create**: after the API returns a pending instance, add it to shared state and start tracking. Subsequent SSE events update its status.
|
|
- **Delete**: remove from shared state as soon as the API succeeds; the progress panel tracks the action until the `instance.deleted` event confirms it.
|
|
- **Other actions**: keep the existing per-action busy flag on the card for button disabled states, but the panel provides the detailed progress.
|
|
|
|
### Decision: Remove legacy overlays
|
|
- Delete `loading-overlay` and workflow step markup from `CreateSessionForm`.
|
|
- Remove `session-busy-overlay` and `instance-busy-overlay` (the dimming overlays), but keep button disabled states and small inline spinners.
|
|
|
|
## Risks / Trade-offs
|
|
|
|
**Risk: Shared context causes extra re-renders**
|
|
→ Mitigation: context value is memoized; lists use the same data they already fetched.
|
|
|
|
**Risk: SSE events arriving before operation is tracked**
|
|
→ Mitigation: start tracking before calling the create/start API; for deletes the removal is optimistic and the panel reconciles on the event.
|
|
|
|
**Risk: Duplicate feedback between panel and toasts**
|
|
→ Mitigation: panel shows in-flight steps; toasts remain for terminal success/error only. Existing `EventToastBridge` logic is left largely unchanged.
|
|
|
|
## Migration Plan
|
|
|
|
1. Extend `SessionsContext` with loading/error/refresh/update helpers.
|
|
2. Create `SessionOperationsContext` + `SessionProgressPanel` and render it in `AppShell`.
|
|
3. Update `useInstanceActions` to use shared state and start/stop tracking operations.
|
|
4. Update `ToolStarter`/`StartToolFAB` to add pending sessions and start tracking.
|
|
5. Update `CreateSessionForm` to remove overlay and report status to parent.
|
|
6. Update `InstanceList` to refresh shared state after create/delete.
|
|
7. Update `SessionsPage` and `DashboardPage` to consume shared context.
|
|
8. Remove legacy overlay styles.
|
|
9. Run typecheck, lint, and tests.
|