Files
kandev/docs/specs/tasks/quick-chat-expiration.md
T
José Almeida 1ed2c59997 feat: persist and expire quick chats (#1612)
* feat: persist and expire quick chats

* fix: address quick chat review feedback

* fix: resolve quick chat review findings

* fix: close remaining quick chat review gaps

* fix: avoid repeated quick chat expiration rechecks

* fix: guard quick chat expiration deletes

* fix: expire abandoned starting quick chats

* fix: ignore missing quick chat expiration candidates
2026-07-08 12:11:28 +01:00

169 lines
8.7 KiB
Markdown

---
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).