basalt-ui 1.41.0 → 2.0.0

package/src/agent/parts.ts

@@ -8,10 +8,6 @@
  * but do NOT let the runtime throw, or one malformed chunk kills the whole transcript. See
  * `mergeToolPart`'s default branch for that shape.
  *
- * Eden #231 doctrine: the server-side Elysia route MUST declare `: AsyncGenerator<AgentPart>`
- * explicitly and carry NO t.Object/t.Union response schema. Validate at yield-time. See
- * agent/rules/basalt-agent.md for the full doctrine.
- *
  * Part identity: every variant carries a stable `id` (see `PartBase`). Transports are permitted to
  * yield a DRAFT — `id` omitted — via `AgentPartDraft`; the consuming hooks (or `withPartIds`)
  * normalize a draft into a fully-identified part before it is ever accumulated. `parseAgentPart`
@@ -47,25 +43,28 @@ type PartBase = { readonly id: string }
 export type StartPart = PartBase & {
   readonly type: 'start'
   readonly runId: string
-  readonly resumeToken?: string
+  readonly resumeToken?: string | undefined
 }
 
 /**
- * A streamed text fragment from the assistant. `offset` is the character position of this delta
- * inside its part (undefined = append at the tail) — the mechanism `mergePart` uses to splice a
- * replayed delta in place rather than duplicating it.
+ * A streamed text fragment from the assistant. `text` is a DELTA, not the cumulative text: parts
+ * sharing an `id` are merged into one, in order. `offset` is the character position in that
+ * accumulated text where this delta starts (undefined = append at the tail, which is what a plain
+ * transport emits; `aiSdkTransport` sets it to the length already seen). The merge writes `text`
+ * over `[offset, offset + text.length)`, so replaying a whole run from `offset: 0` rebuilds the same
+ * text instead of duplicating it. An out-of-range offset is clamped, never thrown on.
  */
 export type TextPart = PartBase & {
   readonly type: 'text'
   readonly text: string
-  readonly offset?: number
+  readonly offset?: number | undefined
 }
 
 /** An internal reasoning/thinking fragment (may be hidden in the UI). Same `offset` mechanism as TextPart. */
 export type ReasoningPart = PartBase & {
   readonly type: 'reasoning'
   readonly text: string
-  readonly offset?: number
+  readonly offset?: number | undefined
 }
 
 // ── ToolCallPart — mirrors AI SDK v7's UIToolInvocation ─────────────────────
@@ -89,18 +88,18 @@ export type ReasoningPart = PartBase & {
 /** The nested approval envelope — mirrors the SDK's shape verbatim, never flattened. */
 type ToolApproval = {
   readonly id: string
-  readonly approved?: boolean
-  readonly reason?: string
-  readonly isAutomatic?: boolean
-  readonly signature?: string
+  readonly approved?: boolean | undefined
+  readonly reason?: string | undefined
+  readonly isAutomatic?: boolean | undefined
+  readonly signature?: string | undefined
 }
 
 type ToolCallBase = PartBase & {
   readonly type: 'tool'
   readonly toolName: string
   /** Wall-clock time from first sighting of this toolCallId to its terminal state. */
-  readonly durationMs?: number
-  readonly providerExecuted?: boolean
+  readonly durationMs?: number | undefined
+  readonly providerExecuted?: boolean | undefined
 }
 
 /**
@@ -134,7 +133,7 @@ type Identified = ToolCallBase & { readonly toolCallId: string }
  * test that built one. A `''` toolCallId is not a value any state accepts; `parseToolCallPart`
  * normalizes one to absent at the wire boundary, so it never reaches the type or a consumer.
  */
-type MaybeIdentified = ToolCallBase & { readonly toolCallId?: string }
+type MaybeIdentified = ToolCallBase & { readonly toolCallId?: string | undefined }
 
 export type ToolCallPart =
   | (Identified & { readonly state: 'input-streaming'; readonly input?: unknown })
@@ -153,8 +152,8 @@ export type ToolCallPart =
       readonly state: 'output-available'
       readonly input: unknown
       readonly output: unknown
-      readonly preliminary?: boolean
-      readonly approval?: ToolApproval & { readonly approved?: true }
+      readonly preliminary?: boolean | undefined
+      readonly approval?: (ToolApproval & { readonly approved?: true }) | undefined
     })
   | (MaybeIdentified & {
       readonly state: 'output-error'
@@ -163,7 +162,7 @@ export type ToolCallPart =
       readonly errorText: string
       /** The only place the raw, un-parsed input survives — what lets a UI render a call whose input never validated. */
       readonly rawInput?: unknown
-      readonly approval?: ToolApproval & { readonly approved?: true }
+      readonly approval?: (ToolApproval & { readonly approved?: true }) | undefined
     })
   | (MaybeIdentified & {
       readonly state: 'output-denied'
@@ -185,7 +184,7 @@ export function isToolCallSettled(part: ToolCallPart): boolean {
 export type SourcePart = PartBase & {
   readonly type: 'source'
   readonly url: string
-  readonly title?: string
+  readonly title?: string | undefined
 }
 
 /** A fatal or recoverable error emitted in-stream by the agent. */
@@ -208,7 +207,9 @@ export type AgentPart = StartPart | TextPart | ReasoningPart | ToolCallPart | So
  * `Drafted<AgentPart>` is `Drafted<StartPart> | Drafted<TextPart> | ...` rather than one flattened
  * (and wrong) shape.
  */
-export type Drafted<T> = T extends unknown ? Omit<T, 'id'> & { readonly id?: string } : never
+export type Drafted<T> = T extends unknown
+  ? Omit<T, 'id'> & { readonly id?: string | undefined }
+  : never
 export type AgentPartDraft = Drafted<AgentPart>
 
 // ── parseAgentPart ───────────────────────────────────────────────────────────

package/src/agent/run-committer.ts

@@ -0,0 +1,64 @@
+/**
+ * The commit side of a run: when accumulated parts reach `useAgentThreadRuns`' `runs` state.
+ * Mantine-free and React-free so it is testable on its own.
+ */
+import type { PartLike } from './merge'
+import type { LiveRunStatus } from './thread'
+
+export type RunCommitter<TPart> = {
+  /** Queue a commit; `immediate` (or `wait <= 0`) bypasses the window and drops any pending one. */
+  readonly push: (parts: TPart[], status: LiveRunStatus, immediate?: boolean) => void
+  /** Commit the pending snapshot now, if any. */
+  readonly flush: () => void
+  /** Drop the pending snapshot and its timer. */
+  readonly cancel: () => void
+}
+
+/**
+ * Leading + trailing throttle over `runs` commits (the semantics of `useChat`'s stable
+ * `throttle`): the first push commits at once, pushes inside the window collapse into one trailing
+ * commit of the LATEST snapshot.
+ */
+export function createRunCommitter<TPart>(
+  wait: number,
+  commit: (parts: TPart[], status: LiveRunStatus) => void,
+): RunCommitter<TPart> {
+  let timer: ReturnType<typeof setTimeout> | undefined
+  let lastCommitAt = Number.NEGATIVE_INFINITY
+  let pending: { parts: TPart[]; status: LiveRunStatus } | undefined
+
+  const clear = (): void => {
+    if (timer === undefined) return
+    clearTimeout(timer)
+    timer = undefined
+  }
+  const flush = (): void => {
+    clear()
+    if (pending === undefined) return
+    const { parts, status } = pending
+    pending = undefined
+    lastCommitAt = Date.now()
+    commit(parts, status)
+  }
+  return {
+    push(parts, status, immediate = false) {
+      pending = { parts, status }
+      const windowOpen = timer === undefined && Date.now() - lastCommitAt >= wait
+      if (wait <= 0 || immediate || windowOpen) {
+        flush()
+        return
+      }
+      timer ??= setTimeout(flush, Math.max(0, wait - (Date.now() - lastCommitAt)))
+    },
+    flush,
+    cancel() {
+      clear()
+      pending = undefined
+    },
+  }
+}
+
+/** True for the parts that end `'submitted'`: model output, not the synthetic start/source/error. */
+export function isContentPart(part: PartLike): boolean {
+  return part.type === 'text' || part.type === 'reasoning' || part.type === 'tool'
+}

package/src/agent/run-records.ts

@@ -0,0 +1,147 @@
+/**
+ * The per-thread run lifecycle of `useAgentThreadRuns`, in ONE record per thread id.
+ *
+ * The hook used to keep a run's controller, live parts, "final message landed" flag and how it
+ * ended in four parallel maps, written at different places, and `runs` (React state, which only
+ * mirrors the last flushed render) was consulted for the rest. Every drift between those was a
+ * bug: `stop()` deciding from a stale `runs`, a second `stop()` appending twice. Here a run is
+ * begun, ended and swept through three functions, so the pieces change together.
+ *
+ * A record is LIVE while `ended === undefined`; `ended` is written synchronously where a run stops
+ * being driven, long before the `setRuns` it queues renders. That window is what the record
+ * covers: it outlives the run only until a render shows the outcome (`sweepFlushed`).
+ */
+
+/** The part of a rendered `runs` entry this module reads. */
+type RenderedRun<TPart> = { readonly status: string; readonly parts: TPart[] }
+
+export type RunEnd = 'settled' | 'failed' | 'stopped'
+
+export type RunRecord<TPart> = {
+  readonly controller: AbortController
+  /** The unthrottled accumulator; `runs` may lag it by one throttle window. Emptied when the run ends. */
+  parts: TPart[]
+  /** The turn's terminal assistant message is in the thread. */
+  appended: boolean
+  /** `consumeAndFinalize`'s own `resolveOutcome` is in flight. */
+  resolving: boolean
+  ended: RunEnd | undefined
+  /** A newer run began on the same thread (set by `beginRun` on the record it replaces). */
+  superseded: boolean
+}
+
+export type RunRecords<TPart> = Map<string, RunRecord<TPart>>
+
+/** Registers a live run for `threadId`, replacing whatever record the previous run left. */
+export function beginRun<TPart>(
+  records: RunRecords<TPart>,
+  threadId: string,
+  controller: AbortController,
+): RunRecord<TPart> {
+  const record: RunRecord<TPart> = {
+    controller,
+    parts: [],
+    appended: false,
+    resolving: false,
+    ended: undefined,
+    superseded: false,
+  }
+  const previous = records.get(threadId)
+  if (previous !== undefined) previous.superseded = true
+  records.set(threadId, record)
+  return record
+}
+
+/** Marks a run as no longer driven and drops the content it held. */
+export function endRun<TPart>(record: RunRecord<TPart>, reason: RunEnd): void {
+  record.ended = reason
+  record.parts = []
+}
+
+/** True while `controller`'s run is still the thread's live one. */
+export function isLive<TPart>(
+  records: RunRecords<TPart>,
+  threadId: string,
+  controller: AbortController,
+): boolean {
+  const record = records.get(threadId)
+  return record?.controller === controller && record.ended === undefined
+}
+
+/** What `stop(threadId)` must do. */
+export type StopPlan<TPart> =
+  | { readonly kind: 'noop' }
+  /** A failed run: only its error entry goes. */
+  | { readonly kind: 'dismiss' }
+  /** A live run: abort it, persist its parts, settle the thread. */
+  | { readonly kind: 'stop'; readonly record: RunRecord<TPart>; readonly parts: TPart[] }
+
+/**
+ * True while `threadId` has a live (not yet ended) run.
+ */
+export function hasLiveRun<TPart>(records: RunRecords<TPart>, threadId: string): boolean {
+  const record = records.get(threadId)
+  return record !== undefined && record.ended === undefined
+}
+
+/**
+ * Decides `stop()` from the record, falling back to the rendered `entry` only when no record
+ * exists (an unmount re-run — StrictMode, `<Activity>` — clears records while `runs` state
+ * survives). A live `entry` with no record is a phantom nothing drives; it is settled once: the
+ * ended tombstone record this WRITES (the side effect in the name) makes a second `stop()` in the
+ * same tick a no-op.
+ */
+export function planStopWithTombstone<TPart>(
+  records: RunRecords<TPart>,
+  threadId: string,
+  entry: RenderedRun<TPart> | undefined,
+): StopPlan<TPart> {
+  const record = records.get(threadId)
+  if (record !== undefined) {
+    if (record.ended === undefined) return { kind: 'stop', record, parts: record.parts }
+    return record.ended === 'failed' ? { kind: 'dismiss' } : { kind: 'noop' }
+  }
+  if (entry === undefined) return { kind: 'noop' }
+  if (entry.status === 'error') return { kind: 'dismiss' }
+  const tombstone = beginRun(records, threadId, new AbortController())
+  endRun(tombstone, 'stopped')
+  return { kind: 'stop', record: tombstone, parts: entry.parts }
+}
+
+/** Thread ids whose failed entry `stopAll()` must dismiss: the records AND what `runs` shows. */
+export function failedThreadIds<TPart>(
+  records: RunRecords<TPart>,
+  runs: ReadonlyMap<string, RenderedRun<TPart>>,
+): string[] {
+  const ids = new Set<string>()
+  for (const [threadId, record] of records) if (record.ended === 'failed') ids.add(threadId)
+  for (const [threadId, entry] of runs) if (entry.status === 'error') ids.add(threadId)
+  return [...ids]
+}
+
+/**
+ * A failed entry was dismissed: its record has nothing left to cover. (`sweepFlushed` cannot tell
+ * "dismissed" from "not rendered yet", so the dismissal itself drops it.)
+ */
+export function dismissRun<TPart>(records: RunRecords<TPart>, threadId: string): void {
+  if (records.get(threadId)?.ended === 'failed') records.delete(threadId)
+}
+
+/** True unless a newer run has taken the thread over since `record` began. */
+export function isLatestRun<TPart>(record: RunRecord<TPart>): boolean {
+  return !record.superseded
+}
+
+/** Drops the terminal records a render has already caught up with, so ids are not kept forever. */
+export function sweepFlushed<TPart>(
+  records: RunRecords<TPart>,
+  runs: ReadonlyMap<string, RenderedRun<TPart>>,
+): void {
+  for (const [threadId, record] of records) {
+    // A pending resolver still reports to its record (superseded-ness included): keep it.
+    if (record.ended === undefined || record.resolving) continue
+    const shown = runs.get(threadId)
+    const flushed = record.ended === 'failed' ? shown?.status === 'error' : shown === undefined
+    if (flushed) records.delete(threadId)
+  }
+}

package/src/agent/thread.ts

@@ -1,30 +1,5 @@
-/**
- * createThreadsStore — persisted, ring-buffered multi-thread registry on createPersistedState.
- *
- * Mirrors createChatHistoryStore's shape but one level up: instead of a single message list,
- * this tracks many AgentThreads (each carrying its own message list plus a distilled
- * AgentOutcome for feed rendering). Threads are stored NEWEST-FIRST so index 0 is always the
- * most recent. Both threads and each thread's messages are ring-buffered independently.
- *
- * SSR-safe: the underlying createPersistedState handles the server snapshot (returns initial).
- * Cross-tab: the 'storage' event propagates changes to other tabs automatically.
- *
- * @example
- * import { createThreadsStore } from 'basalt-ui/agent'
- *
- * // Call once at module scope with a stable key:
- * const useThreads = createThreadsStore({ key: 'main-threads', version: 1 })
- *
- * // In a component:
- * function ThreadFeed() {
- *   const { threads, activeId, select, create } = useThreads()
- *   // ...
- * }
- */
-import { useCallback, useRef } from 'react'
-import { createPersistedState } from '../state'
+/** AgentThread / ThreadsStore — the thread contract a consumer-owned store implements. */
 import type { ChatMessage } from './history'
-import { mintThreadId } from './id'
 import type { AgentOutcome } from './outcome'
 import type { AgentPart } from './parts'
 
@@ -37,9 +12,9 @@ import type { AgentPart } from './parts'
  * `'pending'`/`'streaming'` when `useAgentThreadRuns` mounts with no live run for it (e.g. after a
  * reload mid-stream) — see `useAgentThreadRuns`'s mount-reconciliation effect.
  *
- * This is one of THREE overlapping status-shaped unions in the agent layer: `StreamStatus`
- * (single-turn stream lifecycle, `./use-agent-stream`), this `ThreadStatus` (persisted thread
- * lifecycle), and `AgentOutcome['status']` (`./outcome` — the terminal `'done' | 'attention' |
+ * This is one of THREE overlapping status-shaped unions in the agent layer: the internal
+ * `StreamStatus` (single-turn stream lifecycle, below), this `ThreadStatus`
+ * (persisted thread lifecycle), and `AgentOutcome['status']` (`./outcome` — the terminal `'done' | 'attention' |
  * 'error'` subset of this union, once a turn has settled). Vocabulary note: `StreamStatus`'s
  * `'idle'` (no turn in flight) corresponds to this union's `'pending'` (thread created, no turn
  * started yet) — the literal rename is intentionally deferred, see `AgentOutcome['status']`'s doc.
@@ -76,7 +51,7 @@ export type AgentThread<TPart = AgentPart> = {
    * useAgentThreadRuns to attempt resumption after a disconnected reload. Cleared once the run
    * finalizes.
    */
-  readonly resumeToken?: string
+  readonly resumeToken?: string | undefined
   /**
    * Freeform consumer metadata (e.g. `{ source: 'sidebar' }`, `{ model: 'gpt-5' }`) — set once at
    * `create()` time and otherwise opaque to this store. Intentionally untyped: the framework has
@@ -91,27 +66,7 @@ export type AgentThread<TPart = AgentPart> = {
    * Revisit trigger: promote this to a `TMeta` generic only once a real consumer needs typed,
    * validated meta (not just a documented convention) — don't add the generic speculatively.
    */
-  readonly meta?: Record<string, unknown>
-}
-
-// ── createThreadsStore options ────────────────────────────────────────────────
-
-export type ThreadsStoreOptions = {
-  /** localStorage key (namespaced as `basalt:<key>`). Stable — changes key lose history. */
-  readonly key: string
-  /** Envelope version. Increment when the AgentThread shape changes to clear old data. */
-  readonly version: number
-  /**
-   * Maximum number of threads to retain. Oldest threads (end of the newest-first array) are
-   * dropped when exceeded.
-   * @default 50
-   */
-  readonly maxThreads?: number
-  /**
-   * Maximum number of messages to retain per thread. Oldest messages are dropped when exceeded.
-   * @default 100
-   */
-  readonly maxMessagesPerThread?: number
+  readonly meta?: Record<string, unknown> | undefined
 }
 
 // ── Return type of the factory hook ──────────────────────────────────────────
@@ -124,7 +79,7 @@ export type ThreadsStore<TPart = AgentPart> = {
   /** Select a thread as active (or clear the selection with null). */
   readonly select: (id: string | null) => void
   /** Create a new thread, prepend it, and return its id. Does not change activeId. */
-  readonly create: (opts?: { readonly meta?: Record<string, unknown> }) => string
+  readonly create: (opts?: { readonly meta?: Record<string, unknown> | undefined }) => string
   /** Append a message to a thread. Trims to maxMessagesPerThread (ring-buffer: drops oldest). */
   readonly appendMessage: (id: string, message: ChatMessage<TPart>) => void
   /** Set a thread's distilled outcome. Bumps updatedAt. */
@@ -140,197 +95,35 @@ export type ThreadsStore<TPart = AgentPart> = {
   /** Remove all threads and clear the active selection. */
   readonly clear: () => void
   /**
-   * Whether `threads` reflects the backing store yet. Always `true` for the localStorage store
-   * (createPersistedState resolves synchronously); meaningful only for an async, server-backed
-   * store built with `createAdapterThreadsStore` (./adapter), where it stays `false` until the
-   * first `listThreads` SUCCEEDS. Pair it with `error` — `!hydrated && error !== undefined` is a
+   * Whether `threads` reflects the backing store yet. Always `true` for a synchronous store;
+   * meaningful only for an async, server-backed store, where it stays `false` until the first
+   * `listThreads` SUCCEEDS. Pair it with `error` — `!hydrated && error !== undefined` is a
    * failed load, `!hydrated && error === undefined` is still loading.
    *
-   * Gating an empty state on this is the CALLER's job when hand-assembling `ThreadFeed` /
-   * `ThreadDetailPanel`; the shipped `ThreadWorkspace` already does it internally, so an
-   * async store never flashes "no threads yet" through it before it actually knows.
+   * Gating an empty state on this is the CALLER's job when rendering `ThreadFeed`, so an async
+   * store never flashes "no threads yet" before it actually knows.
    */
   readonly hydrated: boolean
   /**
-   * The most recent persistence failure, or `undefined`. Always `undefined` for the localStorage
-   * store, which has no failure the caller can act on. An async store surfaces the rejected
+   * The most recent persistence failure, or `undefined`. Always `undefined` for a synchronous
+   * local store, which has no failure the caller can act on. An async store surfaces the rejected
    * load/write here after rolling its optimistic edit back.
    */
   readonly error: unknown
 }
 
-// ── createThreadsStore ────────────────────────────────────────────────────────
-
 /**
- * Creates a stable persisted multi-thread hook for the given key + version.
- *
- * Call this ONCE per module (not inside a component). The returned hook can be called in any
- * component that needs access to the same thread registry. All instances sharing the same key
- * stay in sync across tabs via the 'storage' event.
- *
- * @example
- * // src/chat/threads.ts — ONE stable creation per key:
- * export const useThreads = createThreadsStore({ key: 'main-threads', version: 1 })
- *
- * // In a component:
- * const { threads, activeId, select, create, appendMessage } = useThreads()
- * const id = create({ meta: { source: 'sidebar' } })
- * appendMessage(id, { id: crypto.randomUUID(), role: 'user', parts: [...], createdAt: Date.now() })
+ * The live status of one in-flight stream, as the chat rows render it. Not exported from the `./agent`
+ * barrel (the chat UI imports it from this module); consumers derive it from `ThreadFeedRow`'s `liveStatus` prop. `'submitted'` is a turn
+ * sent but not yet producing content: the chat rows treat it as live (Stop shows, the composer is
+ * gated) exactly like `'streaming'`.
  */
-export function createThreadsStore<TPart = AgentPart>(
-  opts: ThreadsStoreOptions,
-): () => ThreadsStore<TPart> {
-  const maxThreads = opts.maxThreads ?? 50
-  const maxMessages = opts.maxMessagesPerThread ?? 100
-
-  type Persisted = { threads: AgentThread<TPart>[]; activeId: string | null }
-
-  const usePersistedThreads = createPersistedState<Persisted>({
-    key: opts.key,
-    version: opts.version,
-    initial: { threads: [], activeId: null },
-  })
-
-  return function useThreadsStore(): ThreadsStore<TPart> {
-    const [state, setState] = usePersistedThreads()
-
-    // Ref mirrors the latest committed value so that two synchronous action calls in one
-    // render cycle accumulate correctly. createPersistedState's setter is a whole-value setter
-    // (not a functional updater), so the second call would otherwise overwrite the first.
-    const ref = useRef(state)
-    ref.current = state
-
-    const commit = useCallback(
-      (next: Persisted): void => {
-        ref.current = next // sync so a second action in the same tick sees the update
-        setState(next)
-      },
-      [setState],
-    )
-
-    const select = useCallback(
-      (id: string | null): void => {
-        commit({ ...ref.current, activeId: id })
-      },
-      [commit],
-    )
-
-    const create = useCallback(
-      (createOpts?: { readonly meta?: Record<string, unknown> }): string => {
-        const id = mintThreadId()
-        const now = Date.now()
-        const thread: AgentThread<TPart> = {
-          id,
-          messages: [],
-          outcome: null,
-          status: 'pending',
-          read: false,
-          createdAt: now,
-          updatedAt: now,
-          ...(createOpts?.meta !== undefined ? { meta: createOpts.meta } : {}),
-        }
-        const threads = [thread, ...ref.current.threads]
-        // Ring-buffer: drop the oldest threads (the tail) when over maxThreads.
-        const trimmed = threads.length > maxThreads ? threads.slice(0, maxThreads) : threads
-        commit({ ...ref.current, threads: trimmed })
-        return id
-      },
-      [commit],
-    )
-
-    const appendMessage = useCallback(
-      (id: string, message: ChatMessage<TPart>): void => {
-        const threads = ref.current.threads.map((thread) => {
-          if (thread.id !== id) return thread
-          const messages = [...thread.messages, message]
-          // Ring-buffer: trim to maxMessages, dropping oldest entries first.
-          const trimmed =
-            messages.length > maxMessages ? messages.slice(messages.length - maxMessages) : messages
-          return { ...thread, messages: trimmed, updatedAt: Date.now() }
-        })
-        commit({ ...ref.current, threads })
-      },
-      [commit],
-    )
-
-    const setOutcome = useCallback(
-      (id: string, outcome: AgentOutcome): void => {
-        const threads = ref.current.threads.map((thread) =>
-          thread.id === id ? { ...thread, outcome, updatedAt: Date.now() } : thread,
-        )
-        commit({ ...ref.current, threads })
-      },
-      [commit],
-    )
-
-    const setStatus = useCallback(
-      (id: string, status: ThreadStatus): void => {
-        const threads = ref.current.threads.map((thread) =>
-          thread.id === id ? { ...thread, status, updatedAt: Date.now() } : thread,
-        )
-        commit({ ...ref.current, threads })
-      },
-      [commit],
-    )
-
-    const setResumeToken = useCallback(
-      (id: string, token: string | undefined): void => {
-        const threads = ref.current.threads.map((thread) => {
-          if (thread.id !== id) return thread
-          // exactOptionalPropertyTypes: drop the key entirely to clear it rather than assigning
-          // `resumeToken: undefined` (which the optional-but-not-nullable type disallows).
-          const { resumeToken: _resumeToken, ...rest } = thread
-          return {
-            ...rest,
-            ...(token !== undefined ? { resumeToken: token } : {}),
-            updatedAt: Date.now(),
-          }
-        })
-        commit({ ...ref.current, threads })
-      },
-      [commit],
-    )
-
-    const markRead = useCallback(
-      (id: string): void => {
-        const threads = ref.current.threads.map((thread) =>
-          thread.id === id ? { ...thread, read: true } : thread,
-        )
-        commit({ ...ref.current, threads })
-      },
-      [commit],
-    )
-
-    const remove = useCallback(
-      (id: string): void => {
-        const threads = ref.current.threads.filter((thread) => thread.id !== id)
-        const activeId = ref.current.activeId === id ? null : ref.current.activeId
-        commit({ threads, activeId })
-      },
-      [commit],
-    )
+export type StreamStatus = 'idle' | 'submitted' | 'streaming' | 'done' | 'error'
 
-    const clear = useCallback((): void => {
-      commit({ threads: [], activeId: null })
-    }, [commit])
+/** The two states a turn is in flight in. */
+export type LiveRunStatus = Extract<StreamStatus, 'submitted' | 'streaming'>
 
-    return {
-      threads: state.threads,
-      activeId: state.activeId,
-      select,
-      create,
-      appendMessage,
-      setOutcome,
-      setStatus,
-      setResumeToken,
-      markRead,
-      remove,
-      clear,
-      // localStorage resolves synchronously and swallows its own quota errors, so there is never
-      // a pending load to await nor a failure a caller could act on. See ./adapter for the async
-      // store where these two carry real information.
-      hydrated: true,
-      error: undefined,
-    }
-  }
+/** True while a turn is in flight (`'submitted'` or `'streaming'`); `'error'` and the rest are not. */
+export function isLiveStatus(status: StreamStatus | undefined): status is LiveRunStatus {
+  return status === 'submitted' || status === 'streaming'
 }