Files
kandev/docs/specs/tasks/system-design/quick-chat-session-resumption.md
T
2026-08-29 09:31:38 +00:00

98 lines
5.1 KiB
Markdown

---
status: current
system: tasks
requirements:
- REQ-TASKS-QUICK-CHAT-EXPIRATION-001
created: 2026-08-29
owners:
- kandev
---
# Quick Chat Session Resumption System Design
## Purpose and boundaries
The task system owns recovery of persisted Quick Chat task sessions after the agent runtime stops
or the backend restarts. The shared Quick Chat dialog remains a presentation over those task
sessions. It does not own a separate runtime lifecycle. This design covers ordinary,
configuration, and passthrough Quick Chat conversations on desktop and mobile. It does not change
the responsive dialog composition, session protocol, or backend resume semantics.
## Requirement mapping
| Requirement | Design sections |
| ------------------------------------- | ---------------------------------------------------------------------------- |
| `REQ-TASKS-QUICK-CHAT-EXPIRATION-001` | Session identity, open-time control flow, failure and recovery, verification |
## Session identity
Every persisted `QuickChatSession` carries its backing task ID and session ID. Creation responses,
boot hydration, reconnect list responses, and task lifecycle events preserve both identities.
`taskSessions.items[sessionId].task_id` is the fallback when an older in-memory descriptor does not
yet contain its task ID. Client-only setup tabs have no backing task and never render the persisted
session view.
## Open-time control flow
`QuickChatSessionView` first ensures that the persisted task-session row is available. While the row
is absent, it passes a null task ID to the shared resumption hook so a status request cannot race the
authoritative HTTP hydration. Once the row exists, it resolves the backing task ID from the Quick
Chat descriptor or the hydrated task-session row and mounts the shared
`useSessionResumption(taskId, sessionId)` lifecycle for the visible conversation.
The shared hook owns the remaining lifecycle:
1. Wait for the WebSocket connection and request `task.session.status`.
2. Leave an already-running agent unchanged.
3. When the session needs resume and is resumable, apply
`preventAutoStartAgentOnOpen`. Resume automatically when the preference is disabled. Otherwise,
retain the stopped state and the existing composer hint behavior.
4. Fall back to workspace restoration when a runtime resume fails according to the existing task
session recovery policy.
5. Accept agent startup and capability events through the existing session subscriptions so model,
command, and configuration controls become available.
The hook is mounted before selecting the ordinary chat, configuration chat, or passthrough terminal
presentation. All persisted conversation kinds therefore use one recovery policy. Changing the
active tab changes the task/session inputs, resets the hook's guarded attempt state, and checks the
newly visible session once.
## Failure and recovery
If the descriptor lacks a task ID, session hydration can supply it and trigger the status check on a
later render. If neither source supplies a task ID, no resume request is sent. If the active tab
changes while hydration is in flight, the request is cancelled and its session ID becomes retryable
when the tab is revisited. If a status path inserts a placeholder row before the HTTP response,
hydration still merges the authoritative row. The existing tab resync then reconciles a deleted or
inaccessible conversation. Stale status responses remain subject to the shared monotonic
session-state guards.
The change adds no new error copy. Existing session resumption and workspace-restoration errors
retain their current handling.
## Responsive behavior
Desktop, tablet, and mobile Quick Chat use the same `QuickChatSessionView` and lifecycle hook. The
change does not alter layout, navigation, focus, scroll ownership, touch targets, safe-area
handling, or tab controls. The existing full-screen mobile Quick Chat surface remains the mobile
exemplar and receives the same restored runtime state as desktop.
## Verification
- A focused component test proves that a persisted Quick Chat resolves its backing task identity
and mounts shared session resumption only after hydration, including descriptor precedence and the
hydrated-row fallback.
- Deferred hydration tests prove that placeholder status rows do not cancel the authoritative row
and that a switched-away tab can retry hydration when revisited.
- Existing `useSessionResumption` tests continue to prove status, automatic-resume preference,
workspace fallback, and stale-state behavior.
- A desktop Playwright scenario restarts the backend, reloads the application, opens the restored
Quick Chat tab, and proves the agent resumes and dynamic session model controls return.
- No new mobile Playwright scenario is required because the repair changes only shared state and
lifecycle behavior inside the existing responsive component. It introduces no viewport-specific
presentation or interaction.
## Related decisions
- [Typed Utility Chats Share the Quick Chat Session Model](../../../decisions/2026-07-14-typed-utility-chat-sessions.md)