Merge pull request #58 from huggingface/mobile/persist-draft

docs/conversation-view.md

@@ -244,6 +244,25 @@ pane with nothing to render (a shell) simply stays a terminal.
   same optimistic echo: your prompt appears at the bottom with a `working` line until the
   transcript catches up. Only a trace with **no agent behind it** — a shared file, an import — is
   read-only, which is what `readOnly` is for.
+- **A half-typed reply is kept** (`drafts.ts`, `useDraft.ts`). Reported from a phone: start typing
+  an answer, switch apps, come back, and the text is gone. The pane is not what loses it — App.tsx
+  keeps a dozen panes warm, so an in-app trip to the session list already survived — the
+  **document** is. A phone evicts a backgrounded tab, and the Hub rebuilds the Space's iframe on
+  every visit, so coming back is a cold mount. That rules out both in-memory state and the URL
+  (the Hub owns the iframe's `src`): it has to be storage, written through on every change, because
+  a tab being killed does not reliably run unload handlers.
+
+  One draft per **agent**, shared by the card and the reader, because they are the same act on the
+  same session. Restoring only fills the box — never focus, never send. Sending clears it, via the
+  `setDraft('')` the send already did. It is bounded on three axes, because a composer that throws
+  on a keystroke is far worse than one that forgets: 32 KB per draft (past that it stays in memory
+  only), 128 KB in total with the oldest evicted first, and **24 hours**, after which it is deleted
+  rather than merely hidden — an unsent draft is text you typed on a device that may not be only
+  yours. Quota failures and storage being denied outright both degrade in silence.
+
+  Writes pause between `compositionstart` and `compositionend`: a phone keyboard composes, and the
+  pre-composition snapshot is a string the user meant, where a mid-composition one is half a
+  syllable.
 - **Share** moves here from the sidebar. One session, one place.
 - **Handover** ("continue from this trace in a new agent") lives in the conversation footer, beside
   the provenance line — the only place where its meaning is obvious.

web/package.json

@@ -13,7 +13,7 @@
     "dev": "vite",
     "build": "tsc --noEmit && vite build",
     "typecheck": "tsc --noEmit",
-    "test": "node test/exchanges.test.mjs && node test/sessionTitle.test.mjs && node test/overviewSort.test.mjs",
+    "test": "node test/exchanges.test.mjs && node test/sessionTitle.test.mjs && node test/overviewSort.test.mjs && node test/drafts.test.mjs",
     "preview": "vite preview"
   },
   "dependencies": {

web/src/components/Overview.tsx

@@ -10,6 +10,7 @@ import type { Rankable } from '../lib/overviewSort';
 import Logo from './Logo';
 import { SendGlyph } from './icons';
 import ExchangeView from './conversation/Exchange';
+import { useDraft } from './conversation/useDraft';
 import { writePaneMode } from '../lib/paneMode';
 import { splitExchanges } from './conversation/exchanges';
 
@@ -130,7 +131,11 @@ export function Card({ s, color, group, pending, isMobile, onOpen, onClose }: {
   onClose?: () => void; // present when the card lives in the conversation window
 }) {
   const d = s.digest;
-  const [draft, setDraft] = useState('');
+  const inputRef = useRef<HTMLTextAreaElement>(null);
+  // One unsent reply per agent, shared with reader mode: it is the same act on
+  // the same session, so the text you started in the card is the text the reader
+  // hands back. See drafts.ts for what it survives.
+  const [draft, setDraft] = useDraft(s.id, inputRef);
   const [sending, setSending] = useState(false);
   const [failed, setFailed] = useState(false);
   // Optimistic echo: the sent text becomes the prompt line the moment the
@@ -140,7 +145,6 @@ export function Card({ s, color, group, pending, isMobile, onOpen, onClose }: {
   const [histIdx, setHistIdx] = useState(0); // digest fallback only: n-th answer back
   const [back, setBack] = useState(0);       // how many earlier turns are shown
   const [openWork, setOpenWork] = useState(false);
-  const inputRef = useRef<HTMLTextAreaElement>(null);
   const bodyRef = useRef<HTMLDivElement>(null);
   const latestRef = useRef<HTMLDivElement>(null);
   // The window is the only place the card can grow; inline in the list it stays

web/src/components/conversation/ConversationView.tsx

@@ -18,6 +18,7 @@ import * as api from '../../api';
 import type { TraceTurn } from '../../api';
 import { useTraceWindows, type TraceSource } from '../../lib/traceWindows';
 import type { Session } from '../../types';
+import { useDraft } from './useDraft';
 import { fmtTok, splitExchanges } from './exchanges';
 import ExchangeView from './Exchange';
 import { SendGlyph } from '../icons';
@@ -48,11 +49,14 @@ export default function ConversationView({ session, paused, isMobile, readOnly,
   const stick = useRef(true);
   // Reading a conversation and answering it are the same act — the card has
   // always known that. Only a trace with no agent behind it is read-only.
-  const [draft, setDraft] = useState('');
+  const inputRef = useRef<HTMLTextAreaElement>(null);
+  // A half-typed reply outlives this component. On a phone, leaving the reader
+  // and coming back is usually a cold mount — the tab was evicted, or the Hub
+  // rebuilt the iframe — and plain state loses the text. drafts.ts.
+  const [draft, setDraft] = useDraft(session.id, inputRef);
   const [sending, setSending] = useState(false);
   const [failed, setFailed] = useState(false);
   const [sent, setSent] = useState<{ text: string; at: number } | null>(null);
-  const inputRef = useRef<HTMLTextAreaElement>(null);
 
   const live = session.state === 'working' && !paused;
 

web/src/components/conversation/drafts.ts

@@ -0,0 +1,161 @@
+// What the composer remembers when you walk away from it.
+//
+// Reported from a phone: open an agent's reader, start typing a reply, switch
+// apps or lock the screen, come back — the text is gone. Two layers can lose it,
+// and only one of them turned out to be guilty:
+//
+//   · The pane does NOT unmount on an in-app trip back to the session list —
+//     App.tsx keeps a dozen terminal panes warm, reader and composer included —
+//     so React state alone already survives that. Measured on `main`, not assumed.
+//   · What kills it is the DOCUMENT going away: a reload, a backgrounded tab
+//     evicted under memory pressure, and the Hub rebuilding the Space's iframe
+//     on every visit. Coming back is a cold mount, not a resume.
+//
+// So in-memory state cannot be the answer, and neither can the URL (the Hub owns
+// the iframe's src). It has to be storage, written through on every keystroke —
+// a phone killing a backgrounded tab does not reliably run unload handlers.
+//
+// Same shape as filesMemory.ts, with one deliberate difference: every draft
+// lives in ONE key rather than one key per session, because the two things that
+// have to stay bounded — total bytes, and how long a draft may sit around — are
+// properties of the whole set, and enumerating per-session keys to enforce them
+// is how you end up with an unbounded pile nobody sweeps.
+const KEY = 'am.drafts';
+const VERSION = 1;
+
+/**
+ * Per draft. A reply is a message, not a file: past this you have pasted a log
+ * into the box, and it stays in memory (so a pane switch is still lossless)
+ * without being written to a ~5 MB budget shared with the whole app.
+ */
+const MAX_TEXT = 32 * 1024;
+/** Every draft, together. The oldest fall off the end first. */
+const MAX_TOTAL = 128 * 1024;
+/**
+ * A draft is text you typed and never sent, sitting in the storage of whatever
+ * device you typed it on — which on a phone is not always only yours. A day is
+ * long enough to cover the case this exists for (you left, you came back) and
+ * short enough that last week's half-written answer is not still recoverable
+ * from the browser. Sending clears it immediately; this is only the floor.
+ */
+const MAX_AGE_MS = 24 * 60 * 60 * 1000;
+
+interface Entry { t: string; at: number }
+type Store = Record<string, Entry>;
+
+// First line of defence: a pane switch stays lossless even where storage is
+// denied outright (private mode, or a third-party iframe under cross-site
+// tracking prevention). Storage is the second line — it is what survives the
+// document.
+const mem = new Map<string, string>();
+
+/**
+ * `at` orders the set as well as dating it, and Date.now() is not fine-grained
+ * enough to order two drafts saved in the same millisecond — which is how an
+ * eviction pass ends up shedding an arbitrary one instead of the oldest. This
+ * only ever moves forward, so it stays a timestamp (to the millisecond, for
+ * expiry) and is a strict order (for eviction).
+ */
+let stamped = 0;
+const stamp = () => {
+  stamped = Math.max(Date.now(), stamped + 1);
+  return stamped;
+};
+
+/** `dropped` is true when expired entries were filtered out and should be swept. */
+function read(): { store: Store; dropped: boolean } {
+  try {
+    const raw = localStorage.getItem(KEY);
+    if (!raw) return { store: {}, dropped: false };
+    const parsed = JSON.parse(raw) as { v?: number; d?: Store };
+    if (parsed?.v !== VERSION || !parsed.d || typeof parsed.d !== 'object') {
+      // A older version, or something else's data under our key. Not ours to
+      // read; the next write replaces it.
+      return { store: {}, dropped: true };
+    }
+    const cutoff = Date.now() - MAX_AGE_MS;
+    const out: Store = {};
+    let dropped = false;
+    for (const [id, e] of Object.entries(parsed.d)) {
+      if (e && typeof e.t === 'string' && typeof e.at === 'number' && e.at > cutoff) out[id] = e;
+      else dropped = true;
+    }
+    return { store: out, dropped };
+  } catch {
+    // Denied, or nonsense under our key. Either way: no remembered drafts, which
+    // is exactly the behaviour we had before this file.
+    return { store: {}, dropped: false };
+  }
+}
+
+const load = (): Store => read().store;
+
+function save(store: Store) {
+  // Newest first, and drop from the tail once the set is over budget: the draft
+  // being typed right now is the newest, so it is the last thing to go.
+  const byNewest = Object.entries(store).sort((a, b) => b[1].at - a[1].at);
+  let total = 0;
+  let out: Store = {};
+  for (const [id, e] of byNewest) {
+    total += e.t.length + id.length + 24;
+    if (total > MAX_TOTAL) break;
+    out[id] = e;
+  }
+  // That budget is ours; the quota is the browser's, and the rest of the app
+  // spends from it too. A write that fails sheds the oldest draft and tries
+  // again, and if it still fails it gives up without a word — a composer that
+  // throws on a keystroke is far worse than one that forgets.
+  for (let attempt = 0; attempt < 8; attempt += 1) {
+    try {
+      localStorage.setItem(KEY, JSON.stringify({ v: VERSION, d: out }));
+      return;
+    } catch {
+      const oldest = Object.keys(out).sort((a, b) => out[a].at - out[b].at)[0];
+      if (!oldest) {
+        try { localStorage.removeItem(KEY); } catch { /* nothing left to try */ }
+        return;
+      }
+      const next = { ...out };
+      delete next[oldest];
+      out = next;
+    }
+  }
+}
+
+/** The draft for one session — '' when there isn't one. */
+export function recallDraft(id: string): string {
+  const held = mem.get(id);
+  if (held !== undefined) return held;
+  const { store, dropped } = read();
+  // Expiring has to mean deleted, not merely hidden: an abandoned draft that is
+  // no longer offered but is still sitting in localStorage has not expired in
+  // any sense the person who typed it would recognise. Reading is the moment we
+  // know — the app reads on every mount, so nothing waits for a write.
+  if (dropped) save(store);
+  const text = store[id]?.t || '';
+  if (text) mem.set(id, text);
+  return text;
+}
+
+/**
+ * Hold a draft in memory only. For text mid-IME-composition: it is what the
+ * textarea contains, but not something the user has committed yet.
+ */
+export function holdDraft(id: string, text: string) {
+  if (text) mem.set(id, text);
+  else mem.delete(id);
+}
+
+/** Hold it, and write it through so it survives the document. */
+export function rememberDraft(id: string, text: string) {
+  holdDraft(id, text);
+  const store = load();
+  if (!text || text.length > MAX_TEXT) delete store[id];
+  else store[id] = { t: text, at: stamp() };
+  save(store);
+}
+
+/** Forget one session's draft everywhere. */
+export function forgetDraft(id: string) {
+  rememberDraft(id, '');
+}

web/src/components/conversation/useDraft.ts

@@ -0,0 +1,78 @@
+// The composer's draft, as React state.
+//
+// The rules the text obeys once it leaves the box — where it is kept, how big it
+// may get, how long it lives — are drafts.ts. This is the binding: it reads the
+// remembered draft on mount, writes every change through, and keeps an IME
+// composition from being persisted half-finished.
+import { useCallback, useEffect, useRef, useState } from 'react';
+import type { RefObject } from 'react';
+import { holdDraft, recallDraft, rememberDraft } from './drafts';
+
+/**
+ * The composer's text, for one session, across everything that can take the
+ * page away. A drop-in for `useState('')`.
+ *
+ * Restoring only ever fills the box: no focus, no cursor move, no send. The send
+ * action stays exactly where it was — under the user's thumb. Clearing is the
+ * caller's existing `setDraft('')` on a successful send, so a sent message
+ * stops being a draft without anything new having to remember to say so.
+ *
+ * `inputRef` is the textarea the draft is typed into, and is used for one thing:
+ * an IME composition gate. A phone keyboard composes — pinyin, kana, autocorrect
+ * with candidates — and mid-composition the textarea holds a string the user has
+ * not committed. Persisting that means a discard can restore half a syllable, so
+ * writes are held back until `compositionend` and the pre-composition snapshot
+ * stands in the meantime. The listeners are the hook's own rather than JSX props
+ * deliberately: the composer markup is being unified in PR #49, and this has no
+ * opinion about which element renders it.
+ */
+export function useDraft(
+  sessionId: string,
+  inputRef?: RefObject<HTMLTextAreaElement | null>,
+): [string, (text: string) => void] {
+  const [draft, setDraftState] = useState(() => recallDraft(sessionId));
+  const composing = useRef(false);
+  const held = useRef<string | null>(null);
+
+  // A pane is mounted per session, so this fires on mount and then only if one
+  // is ever re-pointed at another agent.
+  useEffect(() => { setDraftState(recallDraft(sessionId)); }, [sessionId]);
+
+  // Composition events bubble, so this listens on the document and asks "was
+  // that my textarea?" rather than binding the node. Binding the node looks
+  // tidier and is wrong: the reader renders `reading the trace…` on its first
+  // commit, so at the moment the effect runs there is no textarea to bind, and
+  // nothing re-runs it when one appears. The gate silently did nothing — caught
+  // by driving a real composition sequence in a browser, not by reading it.
+  useEffect(() => {
+    if (!inputRef) return undefined;
+    const mine = (e: Event) => e.target === inputRef.current;
+    const start = (e: Event) => { if (mine(e)) composing.current = true; };
+    const end = (e: Event) => {
+      if (!mine(e)) return;
+      composing.current = false;
+      if (held.current === null) return;
+      rememberDraft(sessionId, held.current);
+      held.current = null;
+    };
+    document.addEventListener('compositionstart', start, true);
+    document.addEventListener('compositionend', end, true);
+    return () => {
+      document.removeEventListener('compositionstart', start, true);
+      document.removeEventListener('compositionend', end, true);
+      // Unmounting mid-composition: commit what the box held rather than leave
+      // the last committed keystroke behind forever.
+      if (composing.current && held.current !== null) rememberDraft(sessionId, held.current);
+      composing.current = false;
+      held.current = null;
+    };
+  }, [sessionId, inputRef]);
+
+  const setDraft = useCallback((text: string) => {
+    setDraftState(text);
+    if (composing.current) { held.current = text; holdDraft(sessionId, text); return; }
+    rememberDraft(sessionId, text);
+  }, [sessionId]);
+
+  return [draft, setDraft];
+}

web/test/drafts.test.mjs

@@ -0,0 +1,175 @@
+// The rules a remembered draft has to obey, without a browser in the way.
+//
+// The end-to-end behaviour (does a phone that leaves and comes back still have
+// the text?) is a playwright question. These are the ones a browser test can
+// only ever pass vacuously: what happens at the size cap, at the browser's
+// quota, and after the expiry window.
+//
+// No test runner: esbuild is already here for vite, so the module is transpiled
+// and imported directly. Run with:  node test/drafts.test.mjs
+import assert from 'node:assert/strict';
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+import { fileURLToPath, pathToFileURL } from 'node:url';
+import { build } from 'esbuild';
+
+const HERE = path.dirname(fileURLToPath(import.meta.url));
+const out = path.join(fs.mkdtempSync(path.join(os.tmpdir(), 'drafts-')), 'drafts.mjs');
+await build({
+  entryPoints: [path.join(HERE, '../src/components/conversation/drafts.ts')],
+  outfile: out, format: 'esm', bundle: false, logLevel: 'error',
+});
+
+// A localStorage that can be told to be full, or to be denied outright.
+class Store {
+  constructor() { this.map = new Map(); this.limit = Infinity; this.denied = false; }
+  getItem(k) { if (this.denied) throw new Error('denied'); return this.map.has(k) ? this.map.get(k) : null; }
+  setItem(k, v) {
+    if (this.denied) throw new Error('denied');
+    const size = [...this.map].reduce((n, [a, b]) => n + a.length + b.length, 0)
+      - (this.map.get(k)?.length || 0) - (this.map.has(k) ? k.length : 0)
+      + k.length + v.length;
+    if (size > this.limit) { const e = new Error('QuotaExceededError'); e.name = 'QuotaExceededError'; throw e; }
+    this.map.set(k, v);
+  }
+  removeItem(k) { if (this.denied) throw new Error('denied'); this.map.delete(k); }
+}
+const store = new Store();
+globalThis.localStorage = store;
+
+const { recallDraft, rememberDraft, holdDraft, forgetDraft } = await import(pathToFileURL(out).href);
+
+const KEY = 'am.drafts';
+const raw = () => { try { return JSON.parse(store.map.get(KEY)).d || {}; } catch { return {}; } };
+// recallDraft prefers the in-memory copy, which is the point of it — so reading
+// "what would a cold mount see?" means asking the stored blob directly.
+const cold = (id) => raw()[id]?.t ?? '';
+// reset() clears the disk, not the module's in-memory map (nothing exported can,
+// and that map is deliberately hard to lose). So any test that reads through
+// recallDraft uses ids no other test has touched.
+const reset = () => { store.map.clear(); store.limit = Infinity; store.denied = false; };
+const tests = [];
+const test = (name, fn) => tests.push([name, fn]);
+
+test('a draft comes back for the session it was typed in', () => {
+  reset();
+  rememberDraft('a', 'for a');
+  rememberDraft('b', 'for b');
+  assert.equal(cold('a'), 'for a');
+  assert.equal(cold('b'), 'for b');
+  assert.equal(cold('c'), '');
+  assert.equal(recallDraft('a'), 'for a');
+});
+
+test('an empty draft is deleted, not stored as empty', () => {
+  reset();
+  rememberDraft('a', 'something');
+  rememberDraft('a', '');
+  assert.equal(Object.keys(raw()).length, 0);
+  assert.equal(recallDraft('a'), '');
+  rememberDraft('a', 'again');
+  forgetDraft('a');
+  assert.equal(recallDraft('a'), '');
+});
+
+test('a draft past the size cap stays in memory but is not written', () => {
+  reset();
+  const huge = 'x'.repeat(40 * 1024);
+  rememberDraft('a', huge);
+  assert.equal(cold('a'), '', 'not on disk');
+  assert.equal(recallDraft('a'), huge, 'still in memory, so a pane switch keeps it');
+});
+
+test('over the total budget, the oldest drafts fall off and the newest survives', () => {
+  reset();
+  const big = 'y'.repeat(30 * 1024);
+  for (const id of ['s1', 's2', 's3', 's4', 's5', 's6']) rememberDraft(id, big);
+  const kept = Object.keys(raw());
+  assert.ok(kept.includes('s6'), `the newest is kept, got ${kept}`);
+  assert.ok(!kept.includes('s1'), `the oldest fell off, got ${kept}`);
+  assert.ok(kept.length < 6, `something was evicted, got ${kept}`);
+});
+
+test('a quota error sheds old drafts rather than throwing', () => {
+  reset();
+  rememberDraft('old', 'a'.repeat(2000));
+  rememberDraft('mid', 'b'.repeat(2000));
+  // Now there is room for roughly one draft, not three.
+  store.limit = 2600;
+  assert.doesNotThrow(() => rememberDraft('new', 'c'.repeat(2000)));
+  assert.equal(cold('new'), 'c'.repeat(2000), 'the draft being typed is the one kept');
+  assert.ok(!('old' in raw()), 'the oldest was shed');
+});
+
+test('a quota that cannot be satisfied at all degrades quietly', () => {
+  reset();
+  store.limit = 10;
+  assert.doesNotThrow(() => rememberDraft('a', 'no room for this'));
+  assert.equal(recallDraft('a'), 'no room for this', 'memory still has it');
+});
+
+test('storage denied outright never throws', () => {
+  reset();
+  store.denied = true;
+  assert.doesNotThrow(() => rememberDraft('a', 'private mode'));
+  assert.equal(recallDraft('a'), 'private mode', 'memory carries it for this page');
+  assert.doesNotThrow(() => forgetDraft('a'));
+});
+
+test('a draft older than the window is not restored', () => {
+  reset();
+  store.map.set(KEY, JSON.stringify({
+    v: 1,
+    d: {
+      stale: { t: 'typed two days ago', at: Date.now() - 48 * 60 * 60 * 1000 },
+      fresh: { t: 'typed an hour ago', at: Date.now() - 60 * 60 * 1000 },
+    },
+  }));
+  assert.equal(cold('stale'), 'typed two days ago', 'still on disk until something reads it');
+  // A read drops it, and the next write persists that.
+  rememberDraft('other', 'x');
+  assert.ok(!('stale' in raw()), 'swept on the next write');
+  assert.equal(raw().fresh.t, 'typed an hour ago', 'the fresh one is untouched');
+});
+
+test('a corrupt or foreign blob reads as no drafts, and is replaced', () => {
+  const junks = ['not json', '{}', '[]', 'null', '{"v":99,"d":{"j0":{"t":"x","at":9e12}}}'];
+  for (const [i, junk] of junks.entries()) {
+    reset();
+    store.map.set(KEY, junk);
+    // Through the module, not through JSON.parse: refusing a blob we did not
+    // write IS the behaviour under test.
+    assert.equal(recallDraft(`j${i}`), '', `junk survived: ${junk}`);
+    assert.doesNotThrow(() => rememberDraft(`k${i}`, 'recovers'), `threw on: ${junk}`);
+    assert.deepEqual(Object.keys(raw()), [`k${i}`], `not replaced: ${junk}`);
+  }
+});
+
+test('a stale draft is deleted on read, not just hidden', () => {
+  reset();
+  store.map.set(KEY, JSON.stringify({
+    v: 1,
+    d: {
+      gone: { t: 'sensitive, and two days old', at: Date.now() - 48 * 60 * 60 * 1000 },
+      kept: { t: 'from ten minutes ago', at: Date.now() - 10 * 60 * 1000 },
+    },
+  }));
+  assert.equal(recallDraft('kept'), 'from ten minutes ago');
+  assert.ok(!('gone' in raw()), 'reading swept it off the device');
+  assert.equal(raw().kept.t, 'from ten minutes ago');
+});
+
+test('holdDraft keeps it out of storage', () => {
+  reset();
+  holdDraft('a', 'mid-composition');
+  assert.equal(Object.keys(raw()).length, 0, 'nothing written');
+  assert.equal(recallDraft('a'), 'mid-composition', 'but the box can be refilled');
+});
+
+let failed = 0;
+for (const [name, fn] of tests) {
+  try { fn(); console.log(`  ok    ${name}`); } catch (e) { failed += 1; console.log(`  FAIL  ${name}\n        ${e.message}`); }
+}
+console.log(`\n${tests.length - failed}/${tests.length} passed`);
+process.exit(failed ? 1 : 0);