--- status: draft created: 2026-07-02 owner: José Almeida --- # Quick Chat Persistence & Expiration ## Why A user reported her quick chats "disappearing much faster." Quick chats are ephemeral tasks whose open-tab list lives only in the in-memory frontend store, so a page reload drops every tab even though the underlying task, session, and workspace directory still exist on the backend. Those now-unreachable rows and directories never get cleaned up, so they leak indefinitely. Users want their recent quick chats to survive a reload, and the system needs a bound so abandoned quick chats don't accumulate forever. ## What - Open quick-chat tabs SHALL be restored after a full page reload, reconstructed from backend state rather than client-only memory. - A quick chat that has been idle longer than the retention window SHALL be deleted automatically (task row, its sessions, and its workspace directory), the same as an explicit close. - The default retention window is **7 days** of inactivity, applied per quick chat based on its last activity. The window is a hardcoded constant; it is not user-configurable in this iteration. - Expiration SHALL reuse the existing quick-chat delete path so that workspace directory cleanup and task-lifecycle events fire exactly as they do for a user-initiated close. - Only quick chats expire. Config-mode chats, automation-run ephemeral tasks, and non-ephemeral kanban/office tasks are untouched. - A quick chat that is actively in use (recent message or running session) SHALL NOT expire, regardless of how old it is. ## Data model No new tables. This feature operates on existing `tasks` and `task_sessions` rows. A **quick chat** is precisely the set of tasks matching: ``` tasks is_ephemeral = 1 workflow_id = '' -- ephemeral tasks carry no workflow origin != 'automation_run' -- excludes run-mode ephemeral tasks metadata.config_mode IS NOT 1 -- excludes config-mode settings chats archived_at IS NULL ``` This mirrors the existing list filters: `onlyEphemeral = true` plus the `excludeConfigModePredicate` (`json_extract(metadata,'$.config_mode') IS NOT 1`, `internal/task/repository/sqlite/task.go:62`) plus an `origin != 'automation_run'` guard. The `origin` guard distinguishes user-started quick chats (`origin = 'manual'`) from automation run-mode ephemeral tasks. **Last-activity timestamp** for a quick chat is defined as: ``` last_activity = MAX(task.updated_at, MAX(session.updated_at) over its task_sessions) ``` Using the greater of the task row and its newest session row makes the metric robust to whichever row a message/turn bumps. A quick chat expires when `now - last_activity > 7 days`. ## API surface - **Hydration (read):** reuse the existing workspace task listing rather than a new endpoint. The frontend fetches quick chats via `ListTasksByWorkspace(workspaceId, workflowID="", …, onlyEphemeral=true, excludeConfig=true)` and filters out `origin == "automation_run"`, then rebuilds the `quickChat.sessions` store slice (one tab per returned task, in most-recently-active-first order). Each restored tab needs `{ sessionId, workspaceId, agentProfileId }`, all resolvable from the task and its primary session. The persisted display name is already available via `getStoredQuickChatName` / `setStoredQuickChatName`. - **Deletion (expiration):** no new external contract. Expiration runs as a backend background sweep that calls the existing `Service.DeleteTask` path (which invokes `cleanupQuickChatDirs`, `internal/task/service/service_tasks.go:1402`, and publishes `task.deleted`). Deleted quick chats propagate to any connected client through the existing `task.deleted` WS handler. ## State machine A quick chat task is created `active`, and reaches a terminal `deleted` state via one of these triggers (this feature adds only the last one): | Trigger | Actor | Existing? | |---|---|---| | User closes a tab (confirm) | user | yes (`use-quick-chat-modal.ts` `handleConfirmClose`) | | Rapid re-pick supersedes an in-flight start | frontend | yes (`useAgentSelection` orphan cleanup) | | Agent profile deleted | user | yes (`DeleteEphemeralTasksByAgentProfile`) | | **Idle longer than retention window** | **background sweep** | **new** | All four converge on `Service.DeleteTask`, so directory cleanup and event publishing are identical. ## Failure modes - **Last-activity query fails / returns error:** the sweep fails closed — it deletes nothing that pass and logs a warning. A transient DB error must never cause an over-broad delete. - **A single quick chat delete fails** (dir busy, session stop error): the sweep logs the failure, leaves that task in place, and continues with the rest. One bad row does not abort the batch. The next sweep retries it. - **Hydration list query fails on boot:** quick chat tabs render empty (current behavior); the app is otherwise unaffected. No error toast is required — this degrades to today's behavior. - **A hydrated tab's backend session is already stopped/gone** (e.g. backend was restarted between reloads): the tab still restores and shows its history; sending a new message follows the normal resume/relaunch path. A tab whose task no longer exists is simply not returned by the list and thus not shown. - **Clock skew / non-monotonic time:** expiration compares stored timestamps to `now`; it does not assume monotonic wall clock beyond the 7-day granularity. ## Persistence guarantees - **Survives reload:** open quick-chat tabs (restored from backend), quick-chat task rows, sessions, and workspace directories — until they expire or are closed. - **Survives backend restart:** quick-chat task rows and directories (subject to the same 7-day idle expiration). Tab restoration on the client depends only on the backend list, so it works across a backend restart as long as the task row still exists. - **Does NOT survive:** a quick chat idle > 7 days (deleted on the next sweep). The in-memory `quickChat.sessions` slice remains client-only and is rebuilt from the backend on each load rather than persisted to `localStorage`. - **Retention window:** 7 days of inactivity, hardcoded. Sweep cadence is an implementation detail (piggy-backing on an existing periodic job is acceptable) but SHALL run at least daily so expiry is observed within roughly a day of the window elapsing. ## Scenarios - **GIVEN** an open quick chat with one or more tabs, **WHEN** the user reloads the page, **THEN** the same tabs reappear, ordered most-recently-active first, each showing its prior chat history and persisted name. - **GIVEN** a quick-chat task whose `last_activity` is 8 days ago, **WHEN** the expiration sweep runs, **THEN** the task, its sessions, and its workspace directory are deleted, a `task.deleted` event is published, and the tab disappears from any connected client. - **GIVEN** a quick-chat task with a message sent 10 minutes ago (older than 7 days since creation but recently active), **WHEN** the sweep runs, **THEN** the task is retained. - **GIVEN** a config-mode chat (`metadata.config_mode = 1`) idle for 30 days, **WHEN** the sweep runs, **THEN** it is NOT deleted. - **GIVEN** an automation-run ephemeral task (`origin = 'automation_run'`) idle for 30 days, **WHEN** the sweep runs, **THEN** it is NOT deleted. - **GIVEN** a non-ephemeral kanban task idle for a year, **WHEN** the sweep runs, **THEN** it is NOT deleted. - **GIVEN** the last-activity query errors, **WHEN** the sweep runs, **THEN** no quick chats are deleted and a warning is logged. - **GIVEN** two idle quick chats where deleting the first fails, **WHEN** the sweep runs, **THEN** the second is still evaluated and deleted, and the failure on the first is logged. - **GIVEN** the workspace has 12 quick chats within the retention window, **WHEN** the user reloads, **THEN** all 12 tabs restore (no count cap in this iteration). ## Out of scope - A user-configurable retention window (per-workspace or global setting). Ships as a hardcoded 7-day constant; revisit only if requested. - A hard count cap on number of quick chats (idle TTL only). If clutter becomes a problem, a cap is a follow-up. - Persisting quick-chat tabs to `localStorage`. Backend is the source of truth; no client-side durable store. - Archiving/soft-deleting expired quick chats — they are hard-deleted, matching the existing close behavior. - Changing config-mode chat, automation-run, or kanban/office task lifecycles. ## Open questions - Does a message/turn in a quick chat currently bump `tasks.updated_at`, or only `task_sessions.updated_at` / turn rows? The `MAX(task, session)` definition is chosen to be correct either way, but the implementation should confirm which row actually moves so the sweep query reads the right column(s).