[heartstone] Phase 11 — Session Management + Reconnection

[kevinpschaaf]

What

Adds a "Sessions" devtools tab for per-graph session management, session reconnection with event replay, and a unified suspend/resume flow for all input types (inputNode, waitForInput, waitForChoice).

Why

Previously, running a graph created a session with no way to reconnect if the browser tab was closed or the user navigated away. Completed and suspended sessions were invisible. This phase makes sessions first-class: users can view session history, reconnect to running/suspended sessions, and delete old ones — all through the existing devtools panel.

Changes

Backend (opal-backend)

• Session monitor SSE endpoint (GET /v1beta1/graphSessions?graphId=X): streams the current session list plus live status changes as sessions progress
• Delete endpoint (DELETE /v1beta1/graphSessions/{id}): removes a session and its graph index entry
• replayComplete marker: emitted after replaying historical events so the frontend knows when to switch from replay to live mode
• graph_id made required in GraphSessionStore.create (protocol + impl) — every session must be associated with a graph
• Access token forwarding through the resume flow for agent authentication

Frontend (visual-editor)

• SessionHistoryController: signal-backed controller under editor.devtools tracking the active session, connection state, and session list
• session-actions.ts: SCA actions for connect/disconnect/delete/monitor — connectToSession uses handleInputRequested for the input lifecycle
• sessions-panel.ts: devtools "Sessions" tab UI showing per-graph session history with status dots, timestamps (now with date), and connect/delete controls
• GraphRunService extensions: connectSession(), monitorSessions(), deleteSession(), and cancelSession() methods for session lifecycle management
• Unified handleSuspend: single handler for inputNode, waitForInput, and waitForChoice suspend events, replacing scattered suspend logic
• consumeSessionEvents extraction: deduplicated the event loop between startBackendRun and connectToSession (~150 lines removed), with shared initRunState setup helper
• waitForChoice rendering: uses ChoicePresenter + A2UIInteraction to render proper choice buttons instead of falling back to a text input

Tests

• 8 new handleSuspend tests: covers all three suspend types, early-return guards (no suspendEvent, no console entry, unknown type), schema behavior verification, and abort handling
• Backend test updates: graph_id now required in all store.create calls across test_graph_session_store.py, test_agent_integration.py, test_headless_mode.py
• New test_graph_session_router.py: integration tests for session creation, SSE streaming, replay, and the monitor endpoint

Testing

# Backend tests
cd packages/opal-backend
.venv/bin/python -m pytest tests/test_graph_session_store.py tests/test_graph_session_router.py tests/test_agent_integration.py tests/test_headless_mode.py -v

# Frontend tests
cd packages/visual-editor
npm run test:file -- './dist/tsc/tests/sca/actions/run/backend-run-action.test.js'

Manual verification:

1. Run a graph → sessions tab shows the active session with a green dot
2. Click a different session → UI replays events and reconnects
3. Close/reopen the sessions tab → session list persists via SSE monitor
4. Delete a session → removed from list
5. Reconnect to a suspended session → input UI appears after replay