basalt-ui 1.9.0 → 1.11.0

package/src/agent/use-agent-thread-runs.ts

@@ -40,10 +40,14 @@
 import { useCallback, useEffect, useRef, useState } from 'react'
 import type { Dispatch, MutableRefObject, SetStateAction } from 'react'
 import type { ChatMessage } from './history'
+import { withPartIds } from './id'
+import { mergePart } from './merge'
+import type { PartLike } from './merge'
 import type { AgentOutcome, OutcomeResolver } from './outcome'
 import { isStartPart } from './parts'
 import type { AgentPart } from './parts'
 import type { AgentThread, ThreadStatus, ThreadsStore } from './thread'
+import { isResumable } from './transport'
 import type { AgentTransport } from './transport'
 
 // ── ThreadRunState ────────────────────────────────────────────────────────────
@@ -106,9 +110,14 @@ export type UseAgentThreadRunsReturn<TPart = AgentPart> = {
    * `threadId` has never had a turn started, or already has one in flight.
    */
   readonly retry: (threadId: string) => void
-  /** Abort the in-flight stream for `threadId` (no-op if idle). */
+  /**
+   * Abort the in-flight stream for `threadId` (no-op if idle). Preserves whatever content had
+   * already arrived: if the run had accumulated any parts, they're persisted as an assistant
+   * ChatMessage with `finish: 'stopped'` (unless that message already landed — see finalizeStop),
+   * then distilled into an outcome and the thread is settled to 'done'.
+   */
   readonly stop: (threadId: string) => void
-  /** Abort every in-flight stream across all threads. */
+  /** Abort every in-flight stream across all threads, settling each the same way stop() would. */
   readonly stopAll: () => void
 }
 
@@ -116,7 +125,7 @@ export type UseAgentThreadRunsReturn<TPart = AgentPart> = {
 
 /** Default toUserParts: wraps raw input in a single text part. */
 function defaultToUserParts(input: string): AgentPart[] {
-  return [{ type: 'text', text: input }]
+  return [{ id: crypto.randomUUID(), type: 'text', text: input }]
 }
 
 /**
@@ -161,12 +170,13 @@ function buildDoneSnapshot<TPart>(
  * the resume path passes 'interrupted' (a failed resume falls back to the same terminal state a
  * non-resumable orphaned thread already lands in).
  */
-async function consumeAndFinalize<TPart>(args: {
+async function consumeAndFinalize<TPart extends PartLike>(args: {
   threadId: string
   controller: AbortController
   generator: AsyncGenerator<TPart>
   userMessage: ChatMessage<TPart>
   controllersRef: MutableRefObject<Map<string, AbortController>>
+  appendedRef: MutableRefObject<Map<string, AbortController>>
   storeRef: MutableRefObject<ThreadsStore<TPart>>
   resolveOutcome: OutcomeResolver<TPart>
   setRuns: Dispatch<SetStateAction<Map<string, ThreadRunState<TPart>>>>
@@ -178,12 +188,13 @@ async function consumeAndFinalize<TPart>(args: {
     generator,
     userMessage,
     controllersRef,
+    appendedRef,
     storeRef,
     resolveOutcome,
     setRuns,
     onFailureStatus,
   } = args
-  const parts: TPart[] = []
+  let parts: TPart[] = []
   try {
     for await (const part of generator) {
       // Guard: a newer call superseded this stream's controller for this thread, or it
@@ -194,10 +205,13 @@ async function consumeAndFinalize<TPart>(args: {
         storeRef.current.setResumeToken(threadId, part.resumeToken)
         continue
       }
-      parts.push(part)
+      // mergePart REWRITES an existing id in place (never mutates `parts` — reassigns to the new
+      // array it returns), so the local accumulator and the rendered `runs` snapshot below stay
+      // identical: a replayed/resumed delta rewrites its part instead of duplicating it.
+      parts = mergePart(parts, part)
       setRuns((prev) => {
         const next = new Map(prev)
-        next.set(threadId, { status: 'streaming', parts: [...parts] })
+        next.set(threadId, { status: 'streaming', parts })
         return next
       })
     }
@@ -211,17 +225,33 @@ async function consumeAndFinalize<TPart>(args: {
       role: 'assistant',
       parts,
       createdAt: Date.now(),
+      finish: 'complete',
     }
     storeRef.current.appendMessage(threadId, assistantMessage)
+    // Record the terminal-append fact for THIS run (identified by `controller`, mirroring
+    // controllersRef's own per-thread/per-run keying) — see appendedRef's doc on why this, and not
+    // array-reference equality, is what finalizeStop checks.
+    appendedRef.current.set(threadId, controller)
 
     const priorThread = storeRef.current.threads.find((thread) => thread.id === threadId)
     const snapshot = buildDoneSnapshot(priorThread, threadId, userMessage, assistantMessage)
     const outcome: AgentOutcome = await resolveOutcome(snapshot)
 
+    // Re-check: resolveOutcome above is the only await in this function's success path, and
+    // stop() may have run while it was pending — aborting the controller, appending its own
+    // 'stopped' message only if appendedRef didn't already carry this run's marker (see
+    // finalizeStop), and already forcing the thread to 'done'. Without this recheck, a slow
+    // resolveOutcome settling AFTER stop() has already finalized the thread would silently
+    // overwrite that outcome with whatever THIS call resolved to.
+    if (controllersRef.current.get(threadId) !== controller || controller.signal.aborted) {
+      return
+    }
+
     storeRef.current.setOutcome(threadId, outcome)
     storeRef.current.setStatus(threadId, outcome.status)
     storeRef.current.setResumeToken(threadId, undefined)
     controllersRef.current.delete(threadId)
+    appendedRef.current.delete(threadId)
     setRuns((prev) => {
       if (!prev.has(threadId)) return prev
       const next = new Map(prev)
@@ -237,6 +267,7 @@ async function consumeAndFinalize<TPart>(args: {
     if (controller.signal.aborted) return
     storeRef.current.setStatus(threadId, onFailureStatus)
     controllersRef.current.delete(threadId)
+    appendedRef.current.delete(threadId)
     setRuns((prev) => {
       if (!prev.has(threadId)) return prev
       const next = new Map(prev)
@@ -246,6 +277,56 @@ async function consumeAndFinalize<TPart>(args: {
   }
 }
 
+/**
+ * Finalizes a stop() call for `threadId` — the counterpart to consumeAndFinalize's success path,
+ * reused so the persist/settle/resolve sequence exists exactly once. `parts` is the accumulated
+ * (possibly partial) content read out of the run's `ThreadRunState` at the moment stop() was
+ * called; the caller has already aborted the controller and cleared `controllersRef` before
+ * invoking this. `alreadyAppended` is precomputed by the caller (stop()) from `appendedRef` — see
+ * that ref's doc for why this is an explicit marker rather than an inferred comparison.
+ *
+ * Ordering: the append, forcing status to 'done', clearing the resume token, and tearing down the
+ * run entry ALL happen synchronously (this function's body runs synchronously up to its one
+ * `await`) — status is never derived from the resolved outcome, so it doesn't need to wait on one,
+ * matching useAgentStream's stop(), which settles 'done' immediately rather than blocking on async
+ * work. Only `setOutcome` — which genuinely needs the resolved value — happens after the await.
+ */
+async function finalizeStop<TPart extends PartLike>(args: {
+  threadId: string
+  parts: TPart[]
+  alreadyAppended: boolean
+  storeRef: MutableRefObject<ThreadsStore<TPart>>
+  resolveOutcome: OutcomeResolver<TPart>
+  setRuns: Dispatch<SetStateAction<Map<string, ThreadRunState<TPart>>>>
+}): Promise<void> {
+  const { threadId, parts, alreadyAppended, storeRef, resolveOutcome, setRuns } = args
+
+  if (!alreadyAppended && parts.length > 0) {
+    const stoppedMessage: ChatMessage<TPart> = {
+      id: crypto.randomUUID(),
+      role: 'assistant',
+      parts,
+      createdAt: Date.now(),
+      finish: 'stopped',
+    }
+    storeRef.current.appendMessage(threadId, stoppedMessage)
+  }
+
+  storeRef.current.setStatus(threadId, 'done')
+  storeRef.current.setResumeToken(threadId, undefined)
+  setRuns((prev) => {
+    if (!prev.has(threadId)) return prev
+    const next = new Map(prev)
+    next.delete(threadId)
+    return next
+  })
+
+  const snapshot = storeRef.current.threads.find((thread) => thread.id === threadId)
+  if (snapshot === undefined) return
+  const outcome: AgentOutcome = await resolveOutcome(snapshot)
+  storeRef.current.setOutcome(threadId, outcome)
+}
+
 // ── useAgentThreadRuns ────────────────────────────────────────────────────────
 
 /**
@@ -259,16 +340,43 @@ async function consumeAndFinalize<TPart>(args: {
  * start(threadB, 'What changed in the last release?')
  * // both stream concurrently; runs.get(threadA) / runs.get(threadB) update independently
  */
-export function useAgentThreadRuns<TPart = AgentPart>({
+export function useAgentThreadRuns<TPart extends PartLike = AgentPart>({
   transport,
   store,
   resolveOutcome,
   toUserParts,
 }: UseAgentThreadRunsArgs<TPart>): UseAgentThreadRunsReturn<TPart> {
   const [runs, setRuns] = useState<Map<string, ThreadRunState<TPart>>>(new Map())
+  // Mirrors the latest `runs` state every render so stop() (a plain callback, not a render) can
+  // synchronously read a thread's accumulated parts without going through an async setState
+  // updater — same mirroring pattern as storeRef/transportRef below.
+  const runsRef = useRef(runs)
+  runsRef.current = runs
 
   // Refs: mutable per-render state that must not trigger re-renders.
   const controllersRef = useRef<Map<string, AbortController>>(new Map())
+  // Explicit single-writer marker: has THIS run's terminal assistant message already been
+  // appended? Keyed the same way as controllersRef (threadId -> the specific run's controller),
+  // set by consumeAndFinalize the instant it appends, and cleared on every path that ends a run
+  // (normal completion, the error path, stop(), and unmount) — same lifecycle discipline as
+  // controllersRef, deliberately, since that's the existing coordination channel between
+  // consumeAndFinalize and stop()/finalizeStop.
+  //
+  // This replaces an earlier reference-equality check (`lastMessage.parts === parts`) that
+  // compared the array runsRef mirrors against the array the message actually persisted. That
+  // comparison implicitly depended on THREE things staying true at once: the run-state mirror not
+  // re-copying `parts` on every delta, the accumulator reassigning (never mutating) `parts`, and —
+  // the one that actually broke it — React's flush timing: runsRef is only updated during a
+  // render (`runsRef.current = runs`, assigned unconditionally on every render, not in an effect),
+  // so a setRuns dispatch that hasn't yet flushed into a render leaves runsRef holding an EARLIER
+  // parts array. A stop() landing between consumeAndFinalize's post-loop appendMessage and its
+  // `await resolveOutcome` resolving could observe exactly that staleness and defeat the
+  // reference-equality guard, double-appending — see the regression test with "resolveOutcome"
+  // in its name. Keying by controller identity (an AbortController, freshly minted per run) makes
+  // a false-positive match across two different runs on the same thread structurally
+  // impossible — no render, no array-copy semantics, no accumulator-reassignment assumption is
+  // load-bearing anymore.
+  const appendedRef = useRef<Map<string, AbortController>>(new Map())
   // Caches the last user input per thread so retry() can replay a failed turn without the
   // caller having to hold onto (or re-collect) what was typed.
   const lastInputRef = useRef<Map<string, string>>(new Map())
@@ -305,10 +413,17 @@ export function useAgentThreadRuns<TPart = AgentPart>({
     return resolved
   }
 
-  // Abort every in-flight stream on unmount to stop the async generators.
+  // Abort every in-flight stream on unmount to stop the async generators. Also clears the map —
+  // leaving aborted entries behind would make the mount-reconcile effect below see a
+  // `controllersRef.current.has(id)` of `true` for a thread whose only consumer was just aborted,
+  // skipping the orphan-resume path and wedging the thread in 'streaming' forever. Reachable
+  // whenever this fiber's effects re-run without the fiber itself unmounting (React 19 StrictMode
+  // double-invoke; `<Activity>` hide/show) — see this hook's `@example`-adjacent doc / the F3 note.
   useEffect(
     () => () => {
       controllersRef.current.forEach((controller) => controller.abort())
+      controllersRef.current.clear()
+      appendedRef.current.clear()
     },
     [],
   )
@@ -334,8 +449,10 @@ export function useAgentThreadRuns<TPart = AgentPart>({
       const lastUserMessage = thread.messages.filter((message) => message.role === 'user').at(-1)
       const resolvedTransport = resolveTransport(thread.id)
 
+      // isResumable requires BOTH `resume` and the literal `idempotentReplay: true` assertion —
+      // a transport with `resume` alone is not enough (see ResumableAgentTransport's doc).
       if (
-        resolvedTransport.resume === undefined ||
+        !isResumable(resolvedTransport) ||
         resumeToken === undefined ||
         lastUserMessage === undefined
       ) {
@@ -355,9 +472,17 @@ export function useAgentThreadRuns<TPart = AgentPart>({
       void consumeAndFinalize({
         threadId: thread.id,
         controller,
-        generator: resume(resumeToken, controller.signal),
+        // Namespaced by thread.id (stable across a thread's whole lifetime, including this
+        // resume) rather than per-call — see withPartIds' own doc for why this is NOT a replay-
+        // convergence guarantee on its own: it only protects against two id-less drafts within
+        // ONE generator colliding (the F1 bug). A transport whose resume() needs genuine replay
+        // safety must assert `idempotentReplay: true` AND mint its own content-stable ids (as
+        // aiSdkTransport does) — withPartIds is then a no-op passthrough for it, not the mechanism
+        // providing that safety.
+        generator: withPartIds(thread.id, resume(resumeToken, controller.signal)),
         userMessage: lastUserMessage,
         controllersRef,
+        appendedRef,
         storeRef,
         resolveOutcome,
         setRuns,
@@ -397,9 +522,11 @@ export function useAgentThreadRuns<TPart = AgentPart>({
       void consumeAndFinalize({
         threadId,
         controller,
-        generator: resolvedTransport.stream(input, controller.signal),
+        // Namespaced by threadId — same choice, same caveat, as the mount-time resume call above.
+        generator: withPartIds(threadId, resolvedTransport.stream(input, controller.signal)),
         userMessage,
         controllersRef,
+        appendedRef,
         storeRef,
         resolveOutcome,
         setRuns,
@@ -418,23 +545,46 @@ export function useAgentThreadRuns<TPart = AgentPart>({
     [start],
   )
 
-  const stop = useCallback((threadId: string): void => {
-    controllersRef.current.get(threadId)?.abort()
-    controllersRef.current.delete(threadId)
-    storeRef.current.setStatus(threadId, 'done')
-    setRuns((prev) => {
-      if (!prev.has(threadId)) return prev
-      const next = new Map(prev)
-      next.delete(threadId)
-      return next
-    })
-  }, [])
+  const stop = useCallback(
+    (threadId: string): void => {
+      const controller = controllersRef.current.get(threadId)
+      // No in-flight run for this thread — true no-op, matching this hook's stop() JSDoc. Decided
+      // from controllersRef, NOT runsRef: controllersRef is written synchronously by start() (line
+      // ~509, before consumeAndFinalize is even invoked), while runsRef only mirrors `runs` as of
+      // the last FLUSHED RENDER (`runsRef.current = runs`, assigned during render, above). A
+      // start() immediately followed by stop() in the same synchronous tick/act() batch — e.g.
+      // `onClick={() => { start(id, text); stop(id) }}` — has controllersRef already populated but
+      // runsRef still holding the PREVIOUS render's (empty) map. Gating on runsRef here would read
+      // `undefined`, wrongly treat this as a no-op, leave the controller registered and never
+      // abort it — stranding the run in 'streaming' (see the F4 regression test).
+      if (controller === undefined) return
+
+      controllersRef.current.delete(threadId)
+      // Read the accumulated parts straight out of the live run entry (runsRef mirrors `runs` as of
+      // the last flushed render) — falls back to [] for the same synchronous start()-then-stop()
+      // case above, where no render has flushed yet; finalizeStop already treats an empty `parts`
+      // as "nothing to persist".
+      const parts = runsRef.current.get(threadId)?.parts ?? []
+
+      controller.abort()
+
+      // Was THIS run's terminal message already appended by consumeAndFinalize's own success path
+      // (it can race this call — see appendedRef's doc)? Matched by controller identity, not by
+      // comparing `parts` against anything React-observed, so this is correct regardless of
+      // whether runsRef has flushed the latest delta yet.
+      const alreadyAppended = appendedRef.current.get(threadId) === controller
+      appendedRef.current.delete(threadId)
+
+      void finalizeStop({ threadId, parts, alreadyAppended, storeRef, resolveOutcome, setRuns })
+    },
+    [resolveOutcome],
+  )
 
   const stopAll = useCallback((): void => {
-    controllersRef.current.forEach((controller) => controller.abort())
-    controllersRef.current.clear()
-    setRuns(new Map())
-  }, [])
+    for (const threadId of Array.from(controllersRef.current.keys())) {
+      stop(threadId)
+    }
+  }, [stop])
 
   return { runs, start, retry, stop, stopAll }
 }

package/src/agent/use-agent-thread-runs.wedge.test.tsx

@@ -0,0 +1,301 @@
+/**
+ * F3 — the mount-reconcile / unmount-cleanup wedge in useAgentThreadRuns.
+ *
+ * The bug: the unmount-cleanup effect (`controllersRef.current.forEach(c => c.abort())`) aborted
+ * every in-flight controller but never CLEARED the map. The mount-reconcile effect treats a thread
+ * as "orphaned" (worth a resume attempt) only when `!controllersRef.current.has(thread.id)`. If
+ * this fiber's effects re-run WITHOUT the fiber itself unmounting — React 19 StrictMode's
+ * dev-only double-invoke, or a `<Activity>` boundary being hidden then shown again — the stale,
+ * now-aborted entry survives into the second reconcile pass, `orphaned` reads `false`, no new
+ * resume is attempted, and the one live consumer that WAS attempted already returned silently on
+ * its AbortError (`consumeAndFinalize`'s guard at the top of its try block). The thread is left in
+ * `'streaming'` forever with nothing left to resolve it.
+ *
+ * Both halves matter equally here:
+ *
+ *   (a) REFUTED — a genuine unmount + remount (a fresh component instance, not a re-run of THIS
+ *       fiber's effects) gets a brand-new `useRef` Map. There is nothing for the fix to protect
+ *       against here; the test exists so nobody "fixes" this non-bug later.
+ *   (b) CONFIRMED — React 19 StrictMode's dev-only double-invoke reuses the SAME fiber (and thus
+ *       the same ref) across a simulated unmount+remount within one commit.
+ *   (c) CONFIRMED — React 19.2's `<Activity>` does the SAME thing in PRODUCTION: hiding an
+ *       Activity boundary destroys the subtree's effects and re-creates them on show, while state,
+ *       DOM, and ref identity survive. This is the reachable-in-prod half of the wedge, not a
+ *       StrictMode-only curiosity — hence testing it directly against `<Activity>` from `react`
+ *       rather than only through Mantine's `Collapse`. At the `@mantine/core` 9.3.0 pinned in THIS
+ *       repo, `Collapse` has no `keepMounted` DEFAULT — with the prop unset it keeps `children`
+ *       permanently mounted (the `else` branch below), so a bare `<Collapse>` cannot wedge and a
+ *       default-Collapse-based test would not reproduce the bug. But a consumer writing
+ *       `<Collapse keepMounted>` on this SAME 9.3.0 does hit the `<Activity>` path — read
+ *       the installed `@mantine/core` 9.3.0 `Collapse.mjs` source directly: it imports
+ *       `Activity` from `react` and, when `keepMounted === true`, renders
+ *       `jsx(Activity, { mode: isExited ? 'hidden' : 'visible', … })` on the ordinary non-zero-
+ *       duration path (only the `duration === 0` fast path carries a `&& env !== 'test'` guard). So
+ *       the Activity hazard is live on THIS pinned version, not only on the 9.4.1 argo resolves —
+ *       testing `<Activity>` directly is still the right call because it is what a `keepMounted`
+ *       consumer actually gets here today, not because 9.3.0 is exempt.
+ *
+ * Verified manually while writing this file (reported alongside the test suite, not re-asserted
+ * here as a runtime check): reverting the one-line `controllersRef.current.clear()` fix makes (b)
+ * and (c) fail — the thread's status stays `'streaming'` instead of settling — while (a) passes
+ * either way, exactly as the "refutation" framing above expects.
+ *
+ * Both (b) and (c) observe `resume()` invoked TWICE post-fix (once for the pass that gets aborted,
+ * once for the pass that survives), not once — React's whole justification for double-invoking a
+ * mount effect with a side effect (a network call here) is to surface exactly this
+ * non-idempotence; a spec that anticipated "resume() attempted exactly once" for this scenario
+ * does not match observed React 19.2.7 behavior. What's invariant, and what these tests assert, is
+ * that the thread SETTLES (leaves `'streaming'`) rather than wedging — the resume() call count is
+ * asserted too, but as an observed constant with the doubling explained, not as evidence of a
+ * single attempt.
+ */
+import { describe, expect, test } from 'bun:test'
+import { Activity, StrictMode, useState } from 'react'
+import { act, render, renderHook, waitFor } from '@testing-library/react'
+import { useAgentThreadRuns } from './use-agent-thread-runs'
+import type { AgentThread, ThreadsStore } from './thread'
+import type { AgentTransport } from './transport'
+import type { AgentPart } from './parts'
+import type { ChatMessage } from './history'
+import type { AgentOutcome } from './outcome'
+
+// ── test-only ThreadsStore double ────────────────────────────────────────────
+//
+// A plain mutable object satisfying the ThreadsStore contract — no React state, no
+// localStorage/useSyncExternalStore. useAgentThreadRuns only ever reads `store.threads` and calls
+// its action methods synchronously (via `storeRef.current`), so a hand-rolled mutable double gives
+// the test full, synchronous, non-persisted control over what a "reload mid-stream" looked like —
+// exactly what these mount-reconcile tests need to seed.
+function createTestThreadsStore(initial: AgentThread<AgentPart>[] = []): ThreadsStore<AgentPart> {
+  let threads = initial
+  let activeId: string | null = null
+  return {
+    get threads() {
+      return threads
+    },
+    get activeId() {
+      return activeId
+    },
+    select(id) {
+      activeId = id
+    },
+    create(opts) {
+      const id = crypto.randomUUID()
+      const now = Date.now()
+      const thread: AgentThread<AgentPart> = {
+        id,
+        messages: [],
+        outcome: null,
+        status: 'pending',
+        read: false,
+        createdAt: now,
+        updatedAt: now,
+        ...(opts?.meta !== undefined ? { meta: opts.meta } : {}),
+      }
+      threads = [thread, ...threads]
+      return id
+    },
+    appendMessage(id, message) {
+      threads = threads.map((thread) =>
+        thread.id === id
+          ? { ...thread, messages: [...thread.messages, message], updatedAt: Date.now() }
+          : thread,
+      )
+    },
+    setOutcome(id, outcome) {
+      threads = threads.map((thread) =>
+        thread.id === id ? { ...thread, outcome, updatedAt: Date.now() } : thread,
+      )
+    },
+    setStatus(id, status) {
+      threads = threads.map((thread) =>
+        thread.id === id ? { ...thread, status, updatedAt: Date.now() } : thread,
+      )
+    },
+    setResumeToken(id, token) {
+      threads = threads.map((thread) => {
+        if (thread.id !== id) return thread
+        const { resumeToken: _resumeToken, ...rest } = thread
+        return {
+          ...rest,
+          ...(token !== undefined ? { resumeToken: token } : {}),
+          updatedAt: Date.now(),
+        }
+      })
+    },
+    markRead(id) {
+      threads = threads.map((thread) => (thread.id === id ? { ...thread, read: true } : thread))
+    },
+    remove(id) {
+      threads = threads.filter((thread) => thread.id !== id)
+      if (activeId === id) activeId = null
+    },
+    clear() {
+      threads = []
+      activeId = null
+    },
+  }
+}
+
+function makeThread(overrides: Partial<AgentThread<AgentPart>> = {}): AgentThread<AgentPart> {
+  const now = Date.now()
+  return {
+    id: crypto.randomUUID(),
+    messages: [],
+    outcome: null,
+    status: 'pending',
+    read: false,
+    createdAt: now,
+    updatedAt: now,
+    ...overrides,
+  }
+}
+
+function deferred<T>(): { promise: Promise<T>; resolve: (value: T) => void } {
+  let resolve!: (value: T) => void
+  const promise = new Promise<T>((r) => {
+    resolve = r
+  })
+  return { promise, resolve }
+}
+
+const resolveOutcome = (): AgentOutcome => ({ title: 'title', summary: 'summary', status: 'done' })
+
+describe('useAgentThreadRuns — F3 mount-reconcile / unmount-cleanup wedge', () => {
+  test('(a) REFUTED: a genuine unmount + remount gets a fresh controllers map — resolves to interrupted, never re-enters streaming', () => {
+    const store = createTestThreadsStore()
+    const threadId = store.create()
+
+    // No `resume` on this transport: on remount, the orphaned thread must fall straight to
+    // 'interrupted' with no async wait involved.
+    const transport: AgentTransport<AgentPart, string> = {
+      // oxlint-disable-next-line require-yield -- hangs until aborted; never has anything to yield
+      async *stream(_input, signal) {
+        await new Promise((resolve) => {
+          signal?.addEventListener('abort', () => resolve(undefined))
+        })
+      },
+    }
+
+    const { result, unmount } = renderHook(() =>
+      useAgentThreadRuns({ transport, store, resolveOutcome }),
+    )
+
+    act(() => {
+      result.current.start(threadId, 'hello')
+    })
+    expect(store.threads.find((thread) => thread.id === threadId)?.status).toBe('streaming')
+
+    unmount()
+
+    // A brand-new component instance against the SAME store object — a fresh fiber, fresh
+    // `useRef` Map. This must hold both before AND after the F3 fix.
+    renderHook(() => useAgentThreadRuns({ transport, store, resolveOutcome }))
+
+    expect(store.threads.find((thread) => thread.id === threadId)?.status).toBe('interrupted')
+  })
+
+  test('(b) CONFIRMED: React 19 StrictMode double-invoke resumes the orphaned thread instead of wedging it in streaming', async () => {
+    const userMessage: ChatMessage<AgentPart> = {
+      id: crypto.randomUUID(),
+      role: 'user',
+      parts: [{ type: 'text', text: 'hello' }],
+      createdAt: Date.now(),
+    }
+    const thread = makeThread({
+      status: 'streaming',
+      resumeToken: 'resume-token-1',
+      messages: [userMessage],
+    })
+    const store = createTestThreadsStore([thread])
+
+    let resumeCalls = 0
+    const transport = {
+      async *stream() {},
+      async *resume() {
+        resumeCalls++
+        yield { type: 'text', text: 'resumed' }
+      },
+      idempotentReplay: true as const,
+    }
+
+    renderHook(() => useAgentThreadRuns({ transport, store, resolveOutcome }), {
+      wrapper: StrictMode,
+    })
+
+    await waitFor(() => {
+      expect(store.threads.find((t) => t.id === thread.id)?.status).toBe('done')
+    })
+    // Observed constant for this scenario (see file doc): the aborted first pass plus the
+    // surviving second pass, not "exactly once".
+    expect(resumeCalls).toBe(2)
+  })
+
+  test('(c) CONFIRMED: an <Activity> hide/show cycle resumes the orphaned thread instead of wedging it in streaming', async () => {
+    const userMessage: ChatMessage<AgentPart> = {
+      id: crypto.randomUUID(),
+      role: 'user',
+      parts: [{ type: 'text', text: 'hello' }],
+      createdAt: Date.now(),
+    }
+    const thread = makeThread({
+      status: 'streaming',
+      resumeToken: 'resume-token-2',
+      messages: [userMessage],
+    })
+    const store = createTestThreadsStore([thread])
+
+    // Gates the first resume() attempt so the hide happens strictly before it settles — an
+    // explicit happens-before, not a scheduler coincidence a `setTimeout(…, 0)` would only
+    // usually win.
+    const gate = deferred<void>()
+
+    let resumeCalls = 0
+    const transport = {
+      async *stream() {},
+      async *resume() {
+        resumeCalls++
+        await gate.promise
+        yield { type: 'text', text: 'resumed' }
+      },
+      idempotentReplay: true as const,
+    }
+
+    let externalSetMode: ((mode: 'visible' | 'hidden') => void) | undefined
+
+    function Probe(): null {
+      useAgentThreadRuns({ transport, store, resolveOutcome })
+      return null
+    }
+
+    function Harness(): JSX.Element {
+      const [mode, setMode] = useState<'visible' | 'hidden'>('visible')
+      externalSetMode = setMode
+      return (
+        <Activity mode={mode}>
+          <Probe />
+        </Activity>
+      )
+    }
+
+    await act(async () => {
+      render(<Harness />)
+    })
+
+    // First resume attempt is in flight (its gate hasn't been released yet) — hide now to abort
+    // it via the F3-fixed cleanup effect. `gate.resolve()` only runs after this completes, so the
+    // hide is guaranteed to land before the first attempt could ever settle.
+    await act(async () => {
+      externalSetMode?.('hidden')
+    })
+    gate.resolve()
+    await act(async () => {
+      externalSetMode?.('visible')
+    })
+
+    await waitFor(() => {
+      expect(store.threads.find((t) => t.id === thread.id)?.status).toBe('done')
+    })
+    expect(resumeCalls).toBe(2)
+  })
+})

package/src/agent-chat/index.ts

@@ -2,11 +2,12 @@
  * Mantine-styled thread-chat components over the headless `basalt-ui/agent` layer, capped by the
  * flagship `ThreadWorkspace` composite.
  *
- * This module is Mantine-coupled by design and lives under the root entry (unlike `basalt-ui/agent`,
- * which stays headless so it can be styled by any consumer).
+ * This module is Mantine-coupled by design and ships its own `basalt-ui/agent-chat` subpath
+ * (also re-exported from the root entry, unchanged for existing consumers) — unlike
+ * `basalt-ui/agent`, which stays headless so it can be styled by any consumer.
  *
  * @example
- * import { ThreadWorkspace } from 'basalt-ui'
+ * import { ThreadWorkspace } from 'basalt-ui/agent-chat'
  * import { createThreadsStore, edenTransport, heuristicOutcome } from 'basalt-ui/agent'
  */
 
@@ -33,3 +34,7 @@ export type { ComposerProps } from './composer'
 // ── threadPartRenderers + ThreadTranscript ────────────────────────────────────
 export { threadPartRenderers, ThreadTranscript } from './thread-message'
 export type { ThreadTranscriptProps } from './thread-message'
+
+// ── ToolChip ──────────────────────────────────────────────────────────────────
+export { ToolChip } from './tool-chip'
+export type { ToolChipProps } from './tool-chip'