Files
headquarter/openspec/changes/tool-session-progress-and-updates/proposal.md
T
Developer 7440720b7b feat: implement tool-session progress panel and live list updates
- Add SessionOperationsContext + SessionProgressPanel for global,
  non-blocking lifecycle progress (create/start/stop/restart/delete/
  recreate-tunnel) driven by SSE events.
- Promote SessionsContext to authoritative shared session state with
  refresh, addOrUpdateSession, and removeSession helpers.
- Wire AppShell, DashboardPage, SessionsPage, useInstanceActions,
  ToolStarter, and InstanceList into shared state so lists update
  immediately after create/delete without manual refresh.
- Remove legacy blocking overlays from CreateSessionForm, SessionCard,
  and InstanceList; keep disabled states and inline spinners only.
- Update DashboardPage tests to wrap with SessionsProvider and
  SessionOperationsProvider.
- Add .cache/ to .gitignore.

Quality gates: npm run typecheck, npm run lint, npm test -- --run
(82 passed).
2026-06-12 13:19:58 +00:00

2.7 KiB

Tool Session Progress Indication and Live Updates

Why

Creating or deleting a tool session currently leaves the UI out of sync. After starting a tool from the floating action button, the new session does not appear on /sessions or the dashboard until the user manually refreshes or the 30-second poll fires. The existing progress feedback is also poor: CreateSessionForm shows a blocking overlay with only two static messages ("Creating instance…", "Starting container…"), and SessionCard/InstanceCard dim the whole card with a generic spinner. Users cannot see real backend progress (building, starting, probing, running, error) and receive no confirmation when an action finishes.

What Changes

  • Introduce a global session progress panel that tracks all lifecycle actions (create, start, stop, restart, delete, recreate tunnel) using the existing SSE event stream (instance.created, instance.started, instance.health_changed, instance.error, instance.stopped, instance.deleted, instance.restarted).
  • Make lists update immediately after create/delete by sharing session state across AppShell, DashboardPage, and SessionsPage.
  • Remove the blocking full-screen overlay in CreateSessionForm and the card-level busy overlays; replace them with minimal disabled/spinner states and the global panel.
  • Keep existing toast notifications for terminal states (success/error) while the panel handles in-flight progress.

Capabilities

New Capabilities

  • session-progress-panel: Global, non-blocking progress UI for tool lifecycle actions driven by SSE events.
  • shared-session-state: Centralized session list used by navigation, dashboard, and sessions page.

Modified Capabilities

  • session-lifecycle-ux: Delete and stop actions now update shared state immediately; create/start actions add a pending session and show progress.
  • sessions-hub: Dashboard and sessions lists reflect new/deleted sessions without manual refresh.

Impact

  • Frontend: new state/session-operations.tsx, new components/features/session/session-progress-panel.tsx, updates to state/sessions.tsx, AppShell, SessionsPage, DashboardPage, hooks/use-instance-actions.ts, components/features/tool/instance-list.tsx, components/features/tool/tool-starter.tsx, components/features/session/create-session-form.tsx, components/features/session/session-card.tsx, and styles.
  • No API changes: relies on existing lifecycle events and /users/me/sessions.

Quality Gates

  • npm run typecheck
  • npm run lint
  • Existing frontend tests still pass
  • Manual verification: create and delete sessions from the FAB and repository detail page; verify panel updates and lists refresh without manual reload.