@djangocfg/widget-assistant 0.2.9 → 0.3.2

package/README.md

@@ -46,10 +46,26 @@ An unknown `type` is ignored. `wire/fixtures/events.json` holds one of each fram
 
 `createTransport` takes `streamUrl` (a path, or a function of the send, for a thread id in the path), `buildBody`, `headers`, `streamFetch`, `getToken` (signed in) or `visitorToken` (anonymous, sent as `x-visitor-token`). Omit `api` from `useSession` for an anonymous host: nothing is fetched and the room starts empty. `context` is a plain record the host defines; the package never reads it. `examples/KbAssistant.tsx` is a knowledge-base host with a `citations` payload, the reference the tests mount.
 
+## Sessions (0.3)
+
+A session is one thread on the server. `useSession({ transport, api, storage, getContext })` shows one at a time and gives the host `startNew()`, `switchTo(id)`, `sessions` / `refreshSessions()` and `busy` (a turn is streaming: starting or switching waits, Stop ends it).
+
+*   `api: ThreadApi` is three calls the host maps to its endpoints: `list(signal)` (newest activity first), `create()` (`POST threads/`, always a new row) and `load(id, signal)` (throws `ThreadNotFoundError` on a 404: a stranger's or purged session).
+*   On load the remembered session (`storage: { read, write }`, the host picks the key; reads and writes must not throw) is shown, else the newest, else a blank page. **A session is created on the first send, never on load**; the transcript is not reseeded then, so the live message survives.
+*   `createTransport({ streamUrl: ({ threadId }) => … })` posts to the session in the path; `SendInput.threadId` is what `threadFor` returned.
+*   `<SessionsMenu session={session} />` is the header control: "New chat" and the list of earlier chats (title, "5 minutes ago", a check on the current one). Words come from the bundled dictionaries (`newChat`, `sessions`, `sessionsEmpty`).
+*   `<AssistantChat draftRoom={session.thread.session ?? 'new'} />` keeps each session's unsent draft under its own id.
+*   There is no delete and no `clear()`: "clear" is "new chat". Retention is the server's job.
+*   Without `api` (anonymous host) nothing is listed; `startNew()` just empties the room.
+
 ## Tests
 
 `pnpm --filter @djangocfg/widget-assistant check test`: the wire, stream and boundary tests, and `tsc --noEmit`.
 
 ## Migrating from 0.1 (a host that spoke the film frames)
 
-0.2 breaks the wire. In the host's server: `run` carries `thread_id` and `message_id` (not `run_id`, `user_message_id`, `assistant_message_id`); `status.phase` is `thinking|searching|answering` (`reading` and `choosing` are gone); `done` carries no message id; a card payload is `ui_payload {kind: 'film_cards', data}` as before, but the package no longer validates it, so register it: `dataRenderers={{ film_cards: … }}` and `payloadKinds={['film_cards']}`. A stored message has `parts: [{kind, data}]` in place of `widgets: [{kind, ids, caption}]`. `ChatContext` is a plain record (the old `title` and `browse` kinds are the host's to define). `createTransport` still opens `/apix/chat/v1/stream` when no `streamUrl` is given; that default goes in 0.3. The dictionaries lose `statusReading` and `statusChoosing` and gain `statusAnswering`; the bundled `lockedBody` and `hint` no longer talk about films.
+0.2 breaks the wire. In the host's server: `run` carries `thread_id` and `message_id` (not `run_id`, `user_message_id`, `assistant_message_id`); `status.phase` is `thinking|searching|answering` (`reading` and `choosing` are gone); `done` carries no message id; a card payload is `ui_payload {kind: 'film_cards', data}` as before, but the package no longer validates it, so register it: `dataRenderers={{ film_cards: … }}` and `payloadKinds={['film_cards']}`. A stored message has `parts: [{kind, data}]` in place of `widgets: [{kind, ids, caption}]`. `ChatContext` is a plain record (the old `title` and `browse` kinds are the host's to define). `createTransport` still opens `/apix/chat/v1/stream` when no `streamUrl` is given; that default stays for anonymous hosts only; a signed-in host with sessions sets `streamUrl`. The dictionaries lose `statusReading` and `statusChoosing` and gain `statusAnswering`; the bundled `lockedBody` and `hint` no longer talk about films.
+
+## Migrating from 0.2 (one thread, `clear()`)
+
+0.3 replaces the single-thread `ThreadApi { load, clear }` with `ThreadApi { list, create, load(id, signal) }` (`useSession` takes an optional `storage`), removes `Session.clear` (use `startNew`), swaps the dictionary keys `clear`, `clearConfirm`, `clearYes` for `newChat`, `sessions`, `sessionsEmpty`, and adds `ThreadNotFoundError`, the `not_found` reject code, `SendInput.threadId`, `AdapterDeps.threadFor` / `onActive`, `AssistantChat.draftRoom`, `SessionsMenu`, `useAssistantLocale` and `relativeTime`. A host that kept a hand-written sessions bar can delete it.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@djangocfg/widget-assistant",
-  "version": "0.2.9",
+  "version": "0.3.2",
   "description": "A site assistant on top of @djangocfg/widget-chat: the SSE wire and session layer, a persistent host, docked column, floating button and sheet, dictation, Help and 17 built-in locales",
   "keywords": [
     "chat",
@@ -48,15 +48,15 @@
     "zustand": "^5.0.16"
   },
   "peerDependencies": {
-    "@djangocfg/i18n": "^2.1.619",
-    "@djangocfg/ui-core": "^2.1.619",
+    "@djangocfg/i18n": "^2.1.621",
+    "@djangocfg/ui-core": "^2.1.621",
     "lucide-react": "^1.68.0",
     "react": "^19.0.0"
   },
   "devDependencies": {
-    "@djangocfg/i18n": "^2.1.619",
-    "@djangocfg/typescript-config": "^2.1.619",
-    "@djangocfg/ui-core": "^2.1.619",
+    "@djangocfg/i18n": "^2.1.621",
+    "@djangocfg/typescript-config": "^2.1.621",
+    "@djangocfg/ui-core": "^2.1.621",
     "@storybook/react-vite": "^10.6.5",
     "@types/node": "^25.9.5",
     "@types/react": "19.3.0",

package/src/AssistantChat.tsx

@@ -33,8 +33,10 @@ interface Props {
   adapter: ChatAdapter;
   /** Example prompts shown in an empty chat. */
   suggestions: string[];
-  /** The room on screen: `id` changes when the thread is reloaded (reconcile, clear), which reseeds the transcript. */
+  /** The room on screen: `id` changes when the thread is reloaded (reconcile, a new or another session), which reseeds the transcript. */
   conversation?: { id?: string; history: readonly ChatMessage[] };
+  /** What the unsent draft is kept under: the session's own id, so each session keeps its draft across reseeds. Absent: the conversation `id`. */
+  draftRoom?: string;
   /** The host's drawing of structured parts, by `kind` (for example `citations`). Unknown kinds fall through to the widget. */
   dataRenderers?: Readonly<Record<string, DataPartRenderer>>;
   /** Dictation language and its picker (the microphone menu). Absent: the browser's default engine with the widget's default language. */
@@ -57,7 +59,7 @@ const NO_RENDERERS: Readonly<Record<string, DataPartRenderer>> = {};
  * recall of sent prompts with the arrow keys, an unsent draft that survives a reload). The widget's packaged layout shows only a bare composer, so the layout
  * is composed here from its own primitives: every behaviour is the widget's, nothing is re-implemented.
  */
-export function AssistantChat({ adapter, suggestions, conversation = EMPTY_ROOM, dataRenderers = NO_RENDERERS, speech, notice, onRetry, focusWhen, refocus, className }: Props) {
+export function AssistantChat({ adapter, suggestions, conversation = EMPTY_ROOM, draftRoom, dataRenderers = NO_RENDERERS, speech, notice, onRetry, focusWhen, refocus, className }: Props) {
   const renderers = useMemo(
     () => ({
       text: ({ part }: PartRenderProps) => (part.type === 'text' ? <Response>{part.text}</Response> : null),
@@ -106,7 +108,7 @@ export function AssistantChat({ adapter, suggestions, conversation = EMPTY_ROOM,
         children: (
           <>
             <ChatTranscript footer={(message) => <MessageFooter message={message} />} />
-            <AssistantComposer speech={speech} draftRoom={conversation.id ?? 'assistant'} focusWhen={focusWhen} refocus={refocus} />
+            <AssistantComposer speech={speech} draftRoom={draftRoom ?? conversation.id ?? 'assistant'} focusWhen={focusWhen} refocus={refocus} />
           </>
         ),
       }}

package/src/i18n/index.ts

@@ -34,3 +34,6 @@ const kit = createCopy(ASSISTANT_DICTIONARIES);
  * `@djangocfg/i18n` provider, else English. The host passes no strings.
  */
 export const useAssistantCopy = kit.useCopy;
+
+/** The bundled locale the assistant resolved to (feed it to `Intl`). */
+export const useAssistantLocale = kit.useLocale;

package/src/i18n/locales/ar.ts

@@ -20,9 +20,9 @@ export const ar: AssistantCopy = {
   reconnecting: 'إعادة الاتصال…',
   stalled: 'ما زالت الإجابة قيد الإعداد.',
   retry: 'إعادة المحاولة',
-  clear: 'مسح المحادثة',
-  clearConfirm: 'حذف هذه المحادثة؟ لا يمكن التراجع.',
-  clearYes: 'حذف',
+  newChat: 'محادثة جديدة',
+  sessions: 'المحادثات السابقة',
+  sessionsEmpty: 'لا توجد محادثات سابقة بعد',
   loadError: 'تعذّر تحميل المحادثة.',
   helpLabel: 'مساعدة',
   helpDictate: 'بدء الإملاء أو إيقافه',

package/src/i18n/locales/da.ts

@@ -20,9 +20,9 @@ export const da: AssistantCopy = {
   reconnecting: 'Forbinder igen…',
   stalled: 'Svaret er stadig undervejs.',
   retry: 'Prøv igen',
-  clear: 'Ryd chatten',
-  clearConfirm: 'Slet denne samtale? Det kan ikke fortrydes.',
-  clearYes: 'Slet',
+  newChat: 'Ny chat',
+  sessions: 'Tidligere chats',
+  sessionsEmpty: 'Ingen tidligere chats endnu',
   loadError: 'Samtalen kunne ikke indlæses.',
   helpLabel: 'Hjælp',
   helpDictate: 'Start eller stop diktering',

package/src/i18n/locales/de.ts

@@ -20,9 +20,9 @@ export const de: AssistantCopy = {
   reconnecting: 'Verbinde neu…',
   stalled: 'Die Antwort wird noch erstellt.',
   retry: 'Erneut versuchen',
-  clear: 'Chat leeren',
-  clearConfirm: 'Diese Unterhaltung löschen? Das lässt sich nicht rückgängig machen.',
-  clearYes: 'Löschen',
+  newChat: 'Neuer Chat',
+  sessions: 'Frühere Chats',
+  sessionsEmpty: 'Noch keine früheren Chats',
   loadError: 'Die Unterhaltung konnte nicht geladen werden.',
   helpLabel: 'Hilfe',
   helpDictate: 'Diktat starten oder beenden',

package/src/i18n/locales/en.ts

@@ -20,9 +20,9 @@ export const en: AssistantCopy = {
   reconnecting: 'Reconnecting…',
   stalled: 'Still working on the answer.',
   retry: 'Retry',
-  clear: 'Clear chat',
-  clearConfirm: 'Delete this conversation? This cannot be undone.',
-  clearYes: 'Delete',
+  newChat: 'New chat',
+  sessions: 'Earlier chats',
+  sessionsEmpty: 'No earlier chats yet',
   loadError: 'Could not load the conversation.',
   helpLabel: 'Help',
   helpDictate: 'Start or stop dictation',

package/src/i18n/locales/es.ts

@@ -20,9 +20,9 @@ export const es: AssistantCopy = {
   reconnecting: 'Reconectando…',
   stalled: 'La respuesta sigue en curso.',
   retry: 'Reintentar',
-  clear: 'Borrar chat',
-  clearConfirm: '¿Eliminar esta conversación? No se puede deshacer.',
-  clearYes: 'Eliminar',
+  newChat: 'Nuevo chat',
+  sessions: 'Chats anteriores',
+  sessionsEmpty: 'Aún no hay chats anteriores',
   loadError: 'No se pudo cargar la conversación.',
   helpLabel: 'Ayuda',
   helpDictate: 'Iniciar o detener el dictado',

package/src/i18n/locales/fr.ts

@@ -20,9 +20,9 @@ export const fr: AssistantCopy = {
   reconnecting: 'Reconnexion…',
   stalled: 'La réponse est encore en cours.',
   retry: 'Réessayer',
-  clear: 'Effacer le chat',
-  clearConfirm: 'Supprimer cette conversation ? Cette action est irréversible.',
-  clearYes: 'Supprimer',
+  newChat: 'Nouvelle discussion',
+  sessions: 'Discussions précédentes',
+  sessionsEmpty: 'Aucune discussion précédente',
   loadError: 'Impossible de charger la conversation.',
   helpLabel: 'Aide',
   helpDictate: 'Démarrer ou arrêter la dictée',

package/src/i18n/locales/it.ts

@@ -20,9 +20,9 @@ export const it: AssistantCopy = {
   reconnecting: 'Riconnessione…',
   stalled: 'La risposta è ancora in corso.',
   retry: 'Riprova',
-  clear: 'Cancella chat',
-  clearConfirm: 'Eliminare questa conversazione? Non si può annullare.',
-  clearYes: 'Elimina',
+  newChat: 'Nuova chat',
+  sessions: 'Chat precedenti',
+  sessionsEmpty: 'Ancora nessuna chat precedente',
   loadError: 'Impossibile caricare la conversazione.',
   helpLabel: 'Aiuto',
   helpDictate: 'Avvia o ferma la dettatura',

package/src/i18n/locales/ja.ts

@@ -20,9 +20,9 @@ export const ja: AssistantCopy = {
   reconnecting: '再接続中…',
   stalled: 'まだ回答を作成中です。',
   retry: '再試行',
-  clear: 'チャットを消去',
-  clearConfirm: 'この会話を削除しますか？元に戻せません。',
-  clearYes: '削除',
+  newChat: '新しいチャット',
+  sessions: '過去のチャット',
+  sessionsEmpty: '過去のチャットはまだありません',
   loadError: '会話を読み込めませんでした。',
   helpLabel: 'ヘルプ',
   helpDictate: '音声入力の開始/停止',

package/src/i18n/locales/ko.ts

@@ -20,9 +20,9 @@ export const ko: AssistantCopy = {
   reconnecting: '다시 연결하는 중…',
   stalled: '아직 답변을 준비 중입니다.',
   retry: '다시 시도',
-  clear: '대화 지우기',
-  clearConfirm: '이 대화를 삭제할까요? 되돌릴 수 없습니다.',
-  clearYes: '삭제',
+  newChat: '새 채팅',
+  sessions: '이전 채팅',
+  sessionsEmpty: '이전 채팅이 아직 없습니다',
   loadError: '대화를 불러오지 못했습니다.',
   helpLabel: '도움말',
   helpDictate: '음성 입력 시작/중지',

package/src/i18n/locales/nl.ts

@@ -20,9 +20,9 @@ export const nl: AssistantCopy = {
   reconnecting: 'Opnieuw verbinden…',
   stalled: 'Het antwoord wordt nog gemaakt.',
   retry: 'Opnieuw proberen',
-  clear: 'Chat wissen',
-  clearConfirm: 'Dit gesprek verwijderen? Dit kan niet ongedaan worden gemaakt.',
-  clearYes: 'Verwijderen',
+  newChat: 'Nieuwe chat',
+  sessions: 'Eerdere chats',
+  sessionsEmpty: 'Nog geen eerdere chats',
   loadError: 'Het gesprek kon niet worden geladen.',
   helpLabel: 'Help',
   helpDictate: 'Dicteren starten of stoppen',

package/src/i18n/locales/no.ts

@@ -20,9 +20,9 @@ export const no: AssistantCopy = {
   reconnecting: 'Kobler til igjen…',
   stalled: 'Svaret lages fortsatt.',
   retry: 'Prøv igjen',
-  clear: 'Tøm chatten',
-  clearConfirm: 'Slette denne samtalen? Det kan ikke angres.',
-  clearYes: 'Slett',
+  newChat: 'Ny chat',
+  sessions: 'Tidligere chatter',
+  sessionsEmpty: 'Ingen tidligere chatter ennå',
   loadError: 'Samtalen kunne ikke lastes.',
   helpLabel: 'Hjelp',
   helpDictate: 'Start eller stopp diktering',

package/src/i18n/locales/pl.ts

@@ -20,9 +20,9 @@ export const pl: AssistantCopy = {
   reconnecting: 'Łączę ponownie…',
   stalled: 'Odpowiedź wciąż powstaje.',
   retry: 'Spróbuj ponownie',
-  clear: 'Wyczyść czat',
-  clearConfirm: 'Usunąć tę rozmowę? Nie można tego cofnąć.',
-  clearYes: 'Usuń',
+  newChat: 'Nowy czat',
+  sessions: 'Wcześniejsze czaty',
+  sessionsEmpty: 'Brak wcześniejszych czatów',
   loadError: 'Nie udało się wczytać rozmowy.',
   helpLabel: 'Pomoc',
   helpDictate: 'Włącz lub zatrzymaj dyktowanie',

package/src/i18n/locales/pt-BR.ts

@@ -20,9 +20,9 @@ export const ptBR: AssistantCopy = {
   reconnecting: 'Reconectando…',
   stalled: 'A resposta ainda está sendo preparada.',
   retry: 'Tentar de novo',
-  clear: 'Limpar conversa',
-  clearConfirm: 'Excluir esta conversa? Não dá para desfazer.',
-  clearYes: 'Excluir',
+  newChat: 'Novo chat',
+  sessions: 'Chats anteriores',
+  sessionsEmpty: 'Ainda não há chats anteriores',
   loadError: 'Não foi possível carregar a conversa.',
   helpLabel: 'Ajuda',
   helpDictate: 'Iniciar ou parar o ditado',

package/src/i18n/locales/ru.ts

@@ -20,9 +20,9 @@ export const ru: AssistantCopy = {
   reconnecting: 'Подключаемся снова…',
   stalled: 'Ответ ещё готовится.',
   retry: 'Повторить',
-  clear: 'Очистить чат',
-  clearConfirm: 'Удалить этот разговор? Это нельзя отменить.',
-  clearYes: 'Удалить',
+  newChat: 'Новый чат',
+  sessions: 'Прошлые чаты',
+  sessionsEmpty: 'Прошлых чатов пока нет',
   loadError: 'Не удалось загрузить разговор.',
   helpLabel: 'Справка',
   helpDictate: 'Начать или остановить диктовку',

package/src/i18n/locales/sv.ts

@@ -20,9 +20,9 @@ export const sv: AssistantCopy = {
   reconnecting: 'Återansluter…',
   stalled: 'Svaret är fortfarande på väg.',
   retry: 'Försök igen',
-  clear: 'Rensa chatten',
-  clearConfirm: 'Ta bort den här konversationen? Det går inte att ångra.',
-  clearYes: 'Ta bort',
+  newChat: 'Ny chatt',
+  sessions: 'Tidigare chattar',
+  sessionsEmpty: 'Inga tidigare chattar ännu',
   loadError: 'Konversationen kunde inte laddas.',
   helpLabel: 'Hjälp',
   helpDictate: 'Starta eller stoppa diktering',

package/src/i18n/locales/tr.ts

@@ -20,9 +20,9 @@ export const tr: AssistantCopy = {
   reconnecting: 'Yeniden bağlanıyor…',
   stalled: 'Yanıt hâlâ hazırlanıyor.',
   retry: 'Tekrar dene',
-  clear: 'Sohbeti temizle',
-  clearConfirm: 'Bu konuşma silinsin mi? Geri alınamaz.',
-  clearYes: 'Sil',
+  newChat: 'Yeni sohbet',
+  sessions: 'Önceki sohbetler',
+  sessionsEmpty: 'Henüz önceki sohbet yok',
   loadError: 'Konuşma yüklenemedi.',
   helpLabel: 'Yardım',
   helpDictate: 'Dikteyi başlat veya durdur',

package/src/i18n/locales/zh.ts

@@ -20,9 +20,9 @@ export const zh: AssistantCopy = {
   reconnecting: '正在重新连接…',
   stalled: '仍在生成回答。',
   retry: '重试',
-  clear: '清空对话',
-  clearConfirm: '删除此对话？此操作无法撤销。',
-  clearYes: '删除',
+  newChat: '新对话',
+  sessions: '以前的对话',
+  sessionsEmpty: '还没有以前的对话',
   loadError: '无法加载对话。',
   helpLabel: '帮助',
   helpDictate: '开始或停止听写',

package/src/i18n/types.ts

@@ -26,10 +26,10 @@ export interface AssistantCopy {
   reconnecting: string;
   stalled: string;
   retry: string;
-  /** Deleting the conversation. */
-  clear: string;
-  clearConfirm: string;
-  clearYes: string;
+  /** Sessions: start a new chat, the list of earlier ones, and its empty line. */
+  newChat: string;
+  sessions: string;
+  sessionsEmpty: string;
   loadError: string;
   /** The "Help" link under the composer and its list of keys. */
   helpLabel: string;

package/src/index.ts

@@ -1,19 +1,21 @@
 export { AssistantChat, type DataPartRenderer } from './AssistantChat';
 export { scriptedTransport, type ScriptStep } from './stream/scriptedTransport';
-export { useAssistantCopy, ASSISTANT_DICTIONARIES, type AssistantCopy } from './i18n';
+export { useAssistantCopy, useAssistantLocale, ASSISTANT_DICTIONARIES, type AssistantCopy } from './i18n';
 export { ChatDock } from './shell/ChatDock';
 export { AssistantFrame, type FrameLabels } from './shell/AssistantFrame';
 export { AssistantFab, type FabHint } from './shell/AssistantFab';
 export { AssistantLocked } from './shell/AssistantLocked';
 export { createAssistantUi, useMediaQuery, type UiOptions, type UiState, type UiStorage } from './shell/panelState';
 export { AssistantHostProvider, AssistantPortal, AssistantSlot } from './Host';
-export { useSession, type Session, type SessionCopy, type SessionDeps, type SessionNotice, type ThreadApi, type ThreadState } from './stream/useSession';
+export { useSession, type Session, type SessionCopy, type SessionDeps, type SessionNotice, type ThreadState } from './stream/useSession';
+export { relativeTime, restoreSession, type SessionStorage, type ThreadApi } from './stream/sessions';
+export { SessionsMenu } from './sessions/SessionsMenu';
 export { createStreamAdapter, type AdapterDeps } from './stream/adapter';
 export { reconcile, type Reconciled } from './stream/reconcile';
 export { fromStored, fromStoredThread } from './stream/fromStored';
-export { createTransport, ChatHttpError, ChatNetworkError, type ChatTransport, type RejectCode, type SendInput, type TransportConfig } from './wire/transport';
+export { createTransport, ChatHttpError, ChatNetworkError, ThreadNotFoundError, type ChatTransport, type RejectCode, type SendInput, type TransportConfig } from './wire/transport';
 export { StreamLostError } from './wire/parseSSE';
 export { decodeFrame, WIRE_VERSION } from './wire/frames';
 export type { ChatContext, Frame, Phase, StreamErrorCode } from './wire/frames';
-export type { StoredConversation, StoredMessage, StoredPart, StoredStatus } from './wire/stored';
+export type { StoredConversation, StoredMessage, StoredPart, StoredStatus, StoredThread } from './wire/stored';
 export { citationsRenderer, KB_RENDERERS, KB_PAYLOAD_KINDS, type Citation } from './examples/KbAssistant';

package/src/sessions/SessionsMenu.tsx

@@ -0,0 +1,59 @@
+'use client';
+
+import { Check, History, Plus } from 'lucide-react';
+
+import { Button, DropdownMenu, DropdownMenuContent, DropdownMenuItem, DropdownMenuLabel, DropdownMenuTrigger } from '@djangocfg/ui-core/components';
+
+import { useAssistantCopy, useAssistantLocale } from '../i18n';
+import type { Session } from '../stream/useSession';
+import { relativeTime } from '../stream/sessions';
+
+interface Props {
+  session: Pick<Session, 'thread' | 'sessions' | 'busy' | 'startNew' | 'switchTo' | 'refreshSessions'>;
+  /** The language tag for "5 minutes ago". Absent: the assistant's active language. */
+  locale?: string;
+  /** Hide the list and keep only "New chat" (a host with no list endpoint, such as an anonymous one). */
+  newOnly?: boolean;
+}
+
+/**
+ * The chat's header controls: "New chat" (a new session; the old ones stay) and the list of earlier sessions, newest first, to switch back.
+ * Both wait while an answer streams: Stop ends it first. Words come from the assistant's own dictionaries.
+ */
+export function SessionsMenu({ session, locale, newOnly = false }: Props) {
+  const copy = useAssistantCopy(locale);
+  const active = useAssistantLocale(locale);
+  const current = session.thread.kind === 'ready' ? session.thread.session : null;
+  return (
+    <div className="flex items-center" data-testid="sessions-menu">
+      <Button variant="ghost" size="icon" aria-label={copy.newChat} title={copy.newChat} disabled={session.busy} onClick={() => void session.startNew()}>
+        <Plus className="size-5" aria-hidden="true" />
+      </Button>
+      {newOnly ? null : (
+        <DropdownMenu onOpenChange={(open) => open && session.refreshSessions()}>
+          <DropdownMenuTrigger asChild>
+            <Button variant="ghost" size="icon" aria-label={copy.sessions} title={copy.sessions}>
+              <History className="size-5" aria-hidden="true" />
+            </Button>
+          </DropdownMenuTrigger>
+          <DropdownMenuContent align="end" sideOffset={4} className="max-h-96 w-72 overflow-y-auto">
+            <DropdownMenuLabel>{copy.sessions}</DropdownMenuLabel>
+            {session.sessions === null ? null : session.sessions.length === 0 ? (
+              <p className="px-2 py-1.5 text-xs text-muted-foreground">{copy.sessionsEmpty}</p>
+            ) : (
+              session.sessions.map((item) => (
+                <DropdownMenuItem key={item.id} disabled={session.busy} onSelect={() => void session.switchTo(item.id)} className="items-start gap-2">
+                  <Check className={`mt-0.5 size-4 shrink-0 ${item.id === current ? '' : 'invisible'}`} aria-hidden="true" />
+                  <span className="min-w-0 flex-1">
+                    <span className="block truncate">{item.title || copy.newChat}</span>
+                    <span className="block text-xs text-muted-foreground">{relativeTime(item.last_message_at, active)}</span>
+                  </span>
+                </DropdownMenuItem>
+              ))
+            )}
+          </DropdownMenuContent>
+        </DropdownMenu>
+      )}
+    </div>
+  );
+}

package/src/stream/adapter.ts

@@ -6,6 +6,8 @@ import { ChatHttpError, ChatNetworkError, type ChatTransport } from '../wire/tra
 
 export interface AdapterDeps {
   transport: ChatTransport;
+  /** The session this message goes to: the current one, or a new one created now (the first send of a user who has none). A rejection ends the turn as a failed message. Absent: no session (an anonymous host). */
+  threadFor?: () => Promise<string>;
   /** Scope of this turn, read at send time (the page the user is on). */
   getContext: () => ChatContext | undefined;
   /** Ephemeral progress for the live label above the composer; `null` when the run ends. Never enters the transcript. */
@@ -17,6 +19,8 @@ export interface AdapterDeps {
   onUnknownPayload?: (kind: string) => void;
   /** The stream ended without a terminal frame: the host reconciles from the server. */
   onInterrupted?: () => void;
+  /** A turn is in flight (true at the send, false when its stream ends): the host holds session switching meanwhile. */
+  onActive?: (active: boolean) => void;
   /** A network-level failure, for the connectivity monitor. */
   onNetworkFailure?: () => void;
   /** One plain sentence per outcome (the catalogue). */
@@ -56,6 +60,7 @@ export function createStreamAdapter(deps: AdapterDeps): ChatAdapter {
           let pending = '';
           let timer: ReturnType<typeof setTimeout> | null = null;
           let terminal = false;
+          deps.onActive?.(true);
 
           const open = (id: string) => {
             messageId = id;
@@ -114,7 +119,8 @@ export function createStreamAdapter(deps: AdapterDeps): ChatAdapter {
           };
 
           try {
-            for await (const frame of deps.transport.open({ text, clientId, context: deps.getContext(), signal })) {
+            const threadId = deps.threadFor ? await deps.threadFor() : undefined;
+            for await (const frame of deps.transport.open({ threadId, text, clientId, context: deps.getContext(), signal })) {
               handle(frame);
               if (terminal) break;
             }
@@ -142,6 +148,7 @@ export function createStreamAdapter(deps: AdapterDeps): ChatAdapter {
           } finally {
             if (timer) clearTimeout(timer);
             deps.onStatus(null);
+            deps.onActive?.(false);
             controller.close();
           }
         },

package/src/stream/sessions.ts

@@ -0,0 +1,58 @@
+import type { StoredConversation, StoredThread } from '../wire/stored';
+import { ThreadNotFoundError } from '../wire/transport';
+
+/** The session endpoints (`/apix/chat/v1/threads`), supplied by the app. `load` throws `ThreadNotFoundError` for a session that is not the viewer's or is gone. */
+export interface ThreadApi {
+  /** The viewer's sessions with messages, newest activity first. */
+  list: (signal: AbortSignal) => Promise<StoredThread[]>;
+  /** A new, empty session (`POST threads`). */
+  create: () => Promise<StoredThread>;
+  /** One session with its last messages. */
+  load: (id: string, signal: AbortSignal) => Promise<StoredConversation>;
+}
+
+/** Where the last used session id is kept (the host picks the key). Reads and writes must never throw. */
+export interface SessionStorage {
+  read: () => string | null;
+  write: (id: string | null) => void;
+}
+
+export const NO_SESSION: StoredConversation = { id: null, messages: [] };
+
+/**
+ * The session to show on page load: the remembered one, else the newest, else none (a session is created on the first send, never on load).
+ * A remembered id that is gone (another account on this browser, a purged session) is forgotten and the newest takes over.
+ */
+export async function restoreSession({ api, storage, signal }: { api: ThreadApi; storage?: SessionStorage; signal: AbortSignal }): Promise<StoredConversation> {
+  const remembered = storage?.read() ?? null;
+  if (remembered) {
+    try {
+      return await api.load(remembered, signal);
+    } catch (error) {
+      if (!(error instanceof ThreadNotFoundError)) throw error;
+      storage?.write(null);
+    }
+  }
+  const [newest] = await api.list(signal);
+  return newest ? api.load(newest.id, signal) : NO_SESSION;
+}
+
+const STEPS: ReadonlyArray<[Intl.RelativeTimeFormatUnit, number]> = [
+  ['year', 31_536_000],
+  ['month', 2_592_000],
+  ['week', 604_800],
+  ['day', 86_400],
+  ['hour', 3_600],
+  ['minute', 60],
+];
+
+/** "5 minutes ago" in the viewer's language; under a minute it is `now` (the unit `numeric: 'auto'` words as "now"). */
+export function relativeTime(iso: string, locale: string, now: number = Date.now()): string {
+  const seconds = Math.round((Date.parse(iso) - now) / 1000);
+  const formatter = new Intl.RelativeTimeFormat(locale, { numeric: 'auto' });
+  const abs = Math.abs(seconds);
+  for (const [unit, size] of STEPS) {
+    if (abs >= size) return formatter.format(Math.round(seconds / size), unit);
+  }
+  return formatter.format(0, 'second');
+}

package/src/stream/useSession.ts

@@ -8,17 +8,12 @@ import { useAssistantCopy } from '../i18n';
 import { sessionCopyFor } from '../i18n/sessionCopy';
 
 import type { ChatContext, Phase } from '../wire/frames';
-import type { StoredConversation } from '../wire/stored';
-import type { ChatHttpError, ChatTransport } from '../wire/transport';
+import type { StoredConversation, StoredThread } from '../wire/stored';
+import { ThreadNotFoundError, type ChatHttpError, type ChatTransport } from '../wire/transport';
 import { createStreamAdapter, type AdapterDeps } from './adapter';
 import { fromStoredThread } from './fromStored';
 import { reconcile } from './reconcile';
-
-/** The conversation endpoints, supplied by the app (signed-in hosts). */
-export interface ThreadApi {
-  load: (signal: AbortSignal) => Promise<StoredConversation>;
-  clear: () => Promise<void>;
-}
+import { NO_SESSION, restoreSession, type SessionStorage, type ThreadApi } from './sessions';
 
 export interface SessionCopy {
   messages: AdapterDeps['messages'];
@@ -30,19 +25,22 @@ export interface SessionCopy {
 
 export interface SessionDeps {
   transport: ChatTransport;
-  /** Absent: an anonymous session. Nothing is fetched, the room starts empty, and a lost stream cannot be reconciled (the notice offers Retry). */
+  /** Absent: an anonymous session. Nothing is fetched or listed, the room starts empty, "new chat" empties it, and a lost stream cannot be reconciled (the notice offers Retry). */
   api?: ThreadApi;
+  /** Remembers the last used session so a reload returns to it. Absent: the newest session is shown. */
+  storage?: SessionStorage;
   getContext: () => ChatContext | undefined;
-  /** Absent: the bundled words for the active language. */
-  copy?: SessionCopy;
   /** The `kind`s the host draws; any other live payload is dropped and reported. */
   payloadKinds?: readonly string[];
   onUnknownPayload?: (kind: string) => void;
+  /** Absent: the bundled words for the active language. */
+  copy?: SessionCopy;
   onRejected?: (error: ChatHttpError) => void;
   onNetworkFailure?: () => void;
 }
 
-export type ThreadState = { kind: 'loading' } | { kind: 'error' } | { kind: 'ready'; id: string; history: ChatMessage[] };
+/** `id` is the transcript's identity (the session plus a revision: a new one reseeds the widget); `session` is the session itself, `null` before the first send. */
+export type ThreadState = { kind: 'loading' } | { kind: 'error' } | { kind: 'ready'; id: string; session: string | null; history: ChatMessage[] };
 
 /** `reconnecting`: the stream was lost and the server is being asked; `stalled`: the answer is still running after the budget (offer Retry). */
 export type SessionNotice = 'reconnecting' | 'stalled';
@@ -53,14 +51,21 @@ export interface Session {
   /** Live progress label while a run streams; null otherwise. */
   statusLabel: string | null;
   notice: SessionNotice | null;
-  /** Load the thread again (after a load error or a stalled run). */
+  /** Load the session again (after a load error or a stalled run). */
   reload: () => void;
-  /** Delete the conversation; the next message starts a new one. */
-  clear: () => Promise<void>;
+  /** The viewer's sessions, newest activity first; `null` until `refreshSessions` has answered once. */
+  sessions: StoredThread[] | null;
+  refreshSessions: () => void;
+  /** A turn is in flight: starting or switching a session waits for it (Stop ends it). */
+  busy: boolean;
+  /** "New chat": a new empty session, shown at once. A no-op while the current one is empty. Resolves `false` when it failed (nothing changed). */
+  startNew: () => Promise<boolean>;
+  /** Show another session. Resolves `false` when it failed (the current one stays). */
+  switchTo: (id: string) => Promise<boolean>;
 }
 
 /**
- * One signed-in conversation: the thread from the server (no client copy), the adapter for new messages, the live status label, and the reconcile
+ * The signed-in assistant's sessions: the shown session from the server (no client copy), the adapter for new messages, the live status label, and the reconcile
  * that runs when a stream is lost. A new `history` identity (`id` carries a revision) reseeds the widget only between runs.
  */
 export function useSession(given: SessionDeps): Session {
@@ -71,27 +76,53 @@ export function useSession(given: SessionDeps): Session {
   const [thread, setThread] = useState<ThreadState>({ kind: 'loading' });
   const [phase, setPhase] = useState<Phase | null>(null);
   const [notice, setNotice] = useState<SessionNotice | null>(null);
+  const [sessions, setSessions] = useState<StoredThread[] | null>(null);
+  const [busy, setBusy] = useState(false);
   const revision = useRef(0);
   const live = useRef<AbortController | null>(null);
+  /** The shown session's id; `null` before the first send. Written with the storage, in one place. */
+  const current = useRef<string | null>(null);
 
-  const seed = useCallback((conversation: StoredConversation) => {
-    revision.current += 1;
-    setThread({ kind: 'ready', id: `${conversation.id ?? 'new'}:${revision.current}`, history: fromStoredThread(conversation.messages, ref.current.copy.failedText) });
+  const remember = useCallback((id: string | null) => {
+    current.current = id;
+    ref.current.storage?.write(id);
   }, []);
 
+  const seed = useCallback(
+    (conversation: StoredConversation) => {
+      revision.current += 1;
+      remember(conversation.id);
+      setThread({
+        kind: 'ready',
+        id: `${conversation.id ?? 'new'}:${revision.current}`,
+        session: conversation.id,
+        history: fromStoredThread(conversation.messages, ref.current.copy.failedText),
+      });
+    },
+    [remember],
+  );
+
   const load = useCallback(() => {
     live.current?.abort();
     const controller = new AbortController();
     live.current = controller;
-    setNotice(null);
-    const api = ref.current.api;
-    if (!api) return seed({ id: null, messages: [] });
     setThread({ kind: 'loading' });
-    api.load(controller.signal).then(
+    setNotice(null);
+    const { api, storage } = ref.current;
+    if (!api) return seed(NO_SESSION);
+    const restore = () => restoreSession({ api, storage, signal: controller.signal });
+    const read = current.current
+      ? api.load(current.current, controller.signal).catch((error: unknown) => {
+          if (!(error instanceof ThreadNotFoundError)) throw error;
+          remember(null); // the shown session is gone: fall back to the newest
+          return restore();
+        })
+      : restore();
+    read.then(
       (conversation) => !controller.signal.aborted && seed(conversation),
       () => !controller.signal.aborted && setThread({ kind: 'error' }),
     );
-  }, [seed]);
+  }, [seed, remember]);
 
   useEffect(() => {
     load();
@@ -102,11 +133,25 @@ export function useSession(given: SessionDeps): Session {
     () =>
       createStreamAdapter({
         transport: deps.transport,
+        // The first send of a viewer with no session creates one; the shown transcript is not reseeded (that would drop the live message).
+        threadFor: ref.current.api
+          ? async () => {
+              if (current.current) return current.current;
+              const created = await ref.current.api!.create();
+              remember(created.id);
+              return created.id;
+            }
+          : undefined,
         getContext: () => ref.current.getContext(),
         onStatus: setPhase,
         payloadKinds: deps.payloadKinds,
         onUnknownPayload: (kind) => ref.current.onUnknownPayload?.(kind),
-        onRejected: (error) => ref.current.onRejected?.(error),
+        onActive: setBusy,
+        onRejected: (error) => {
+          // The session vanished (purged, or another account's): forget it, the next send starts a fresh one.
+          if (error.code === 'not_found') remember(null);
+          ref.current.onRejected?.(error);
+        },
         onNetworkFailure: () => ref.current.onNetworkFailure?.(),
         messages: {
           rejected: (error) => ref.current.copy.messages.rejected(error),
@@ -116,12 +161,12 @@ export function useSession(given: SessionDeps): Session {
           },
         },
         onInterrupted: () => {
-          setNotice('reconnecting');
           const api = ref.current.api;
           if (!api) return setNotice('stalled');
+          setNotice('reconnecting');
           const controller = new AbortController();
           live.current = controller;
-          reconcile({ fetchConversation: api.load, signal: controller.signal }).then(
+          reconcile({ fetchConversation: (signal) => api.load(current.current ?? '', signal), signal: controller.signal }).then(
             (result) => {
               if (controller.signal.aborted) return;
               if (result.outcome === 'timeout') return setNotice('stalled');
@@ -133,14 +178,46 @@ export function useSession(given: SessionDeps): Session {
         },
       }),
     // The transport is one per mounted chat; everything else is read through `ref`.
-    [deps.transport, deps.payloadKinds, seed],
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+    [deps.transport, deps.payloadKinds, Boolean(deps.api), seed, remember],
   );
 
-  const clear = useCallback(async () => {
-    await ref.current.api?.clear();
-    live.current?.abort();
-    seed({ id: null, messages: [] });
-  }, [seed]);
+  const refreshSessions = useCallback(() => {
+    ref.current.api?.list(new AbortController().signal).then(setSessions, () => undefined);
+  }, []);
+
+  const show = useCallback(
+    async (read: (signal: AbortSignal) => Promise<StoredConversation>): Promise<boolean> => {
+      live.current?.abort();
+      const controller = new AbortController();
+      live.current = controller;
+      try {
+        const conversation = await read(controller.signal);
+        if (controller.signal.aborted) return false;
+        setNotice(null);
+        seed(conversation);
+        return true;
+      } catch {
+        return false;
+      }
+    },
+    [seed],
+  );
+
+  const startNew = useCallback(async () => {
+    if ((ref.current.api && current.current === null) || (thread.kind === 'ready' && thread.history.length === 0)) return true; // already a blank page
+    const api = ref.current.api;
+    if (!api) return show(async () => NO_SESSION);
+    return show(async () => {
+      const created = await api.create();
+      return { id: created.id, messages: [] };
+    });
+  }, [show, thread]);
+
+  const switchTo = useCallback(
+    async (id: string) => (id === current.current || !ref.current.api ? true : show((signal) => ref.current.api!.load(id, signal))),
+    [show],
+  );
 
-  return { thread, adapter, statusLabel: phase ? ref.current.copy.status[phase] : null, notice, reload: load, clear };
+  return { thread, adapter, statusLabel: phase ? ref.current.copy.status[phase] : null, notice, reload: load, sessions, refreshSessions, busy, startNew, switchTo };
 }

package/src/wire/stored.ts

@@ -18,7 +18,16 @@ export interface StoredMessage {
   created_at: string;
 }
 
+/** One session with its last messages; `id: null` is the state before the first send (no session exists yet, or the host is anonymous). */
 export interface StoredConversation {
   id: string | null;
   messages: StoredMessage[];
 }
+
+/** A session in the list (`GET threads/`): `title` is the first user message, empty until its first answer finishes. */
+export interface StoredThread {
+  id: string;
+  title: string;
+  last_message_at: string;
+  message_count: number;
+}

package/src/wire/transport.ts

@@ -2,7 +2,7 @@ import { decodeFrame, IDLE_MS, type ChatContext, type Frame } from './frames';
 import { parseSSE, StreamLostError } from './parseSSE';
 
 /** Problem codes the API answers before a stream starts (CONTRACT.md "Auth and errors"). */
-export type RejectCode = 'unauthorized' | 'busy' | 'invalid' | 'rate_limited' | 'unavailable' | 'failed';
+export type RejectCode = 'unauthorized' | 'busy' | 'invalid' | 'rate_limited' | 'unavailable' | 'not_found' | 'failed';
 
 /** The request was refused before any frame: nothing ran, so a retry with the same `client_id` is safe. */
 export class ChatHttpError extends Error {
@@ -19,6 +19,13 @@ export class ChatHttpError extends Error {
   }
 }
 
+/** The session is not there (never was, or it is someone else's: the API answers both with a 404). The host forgets the remembered id. */
+export class ThreadNotFoundError extends Error {
+  constructor() {
+    super('chat thread not found');
+  }
+}
+
 /** No answer at all (offline, DNS, reset before the response): nothing is known to have run. */
 export class ChatNetworkError extends Error {
   constructor() {
@@ -27,6 +34,8 @@ export class ChatNetworkError extends Error {
 }
 
 export interface SendInput {
+  /** The session this message goes to (set by the session layer; read by `streamUrl`). Absent for an anonymous host. */
+  threadId?: string;
   text: string;
   clientId: string;
   context?: ChatContext;
@@ -41,7 +50,7 @@ export interface ChatTransport {
 export interface TransportConfig {
   /** API origin, no trailing slash; prefixes a relative `streamUrl`. The stream is called directly, never through a Next rewrite. */
   baseUrl: string;
-  /** Where one run is opened: a path or URL, or a function read per request (a thread id in the path). Absent: the legacy `/apix/chat/v1/stream` (deprecated, removed in 0.3). */
+  /** Where one run is opened: a path or URL, or a function read per request (a thread id in the path). Absent: the legacy `/apix/chat/v1/stream` (anonymous hosts only; a signed-in host with sessions always sets this). */
   streamUrl?: string | ((input: SendInput) => string);
   /** The request body. Absent: `{text, client_id, context?}`. */
   buildBody?: (input: SendInput) => unknown;
@@ -58,7 +67,7 @@ export interface TransportConfig {
   fetch?: typeof fetch;
 }
 
-const CODES: readonly string[] = ['unauthorized', 'busy', 'invalid', 'rate_limited', 'unavailable'];
+const CODES: readonly string[] = ['unauthorized', 'busy', 'invalid', 'rate_limited', 'unavailable', 'not_found'];
 /** A server may name a bad request its own way; these read as `invalid`. */
 const INVALID: readonly string[] = ['validation_error'];
 
@@ -67,6 +76,7 @@ function rejectCode(status: number, body: unknown): RejectCode {
   if (typeof code === 'string' && CODES.includes(code)) return code as RejectCode;
   if (typeof code === 'string' && INVALID.includes(code)) return 'invalid';
   if (status === 401) return 'unauthorized';
+  if (status === 404) return 'not_found';
   if (status === 409) return 'busy';
   if (status === 400 || status === 422) return 'invalid';
   if (status === 429) return 'rate_limited';