basalt-ui 1.40.3 → 2.0.0

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

@@ -1,7 +1,6 @@
 /**
  * useAgentThreadRuns — concurrent multi-thread stream run manager.
  *
- * Unlike useAgentStream (ONE in-flight turn — a new send() aborts the previous one),
  * useAgentThreadRuns runs N CONCURRENT streams, one per thread id, so a user can fire many
  * short chats that each stream and resolve independently in the background. Each thread's
  * turn is appended to an injected ThreadsStore and distilled into an AgentOutcome via an
@@ -14,61 +13,94 @@
  * per thread id and cached: `transport: (threadId) => aiSdkTransport(opts).forThread(threadId)`.
  *
  * @example
- * import { useAgentThreadRuns, createThreadsStore, edenTransport, heuristicOutcome } from 'basalt-ui/agent'
+ * import { useAgentThreadRuns, aiSdkTransport } from 'basalt-ui/agent'
  *
- * const useThreads = createThreadsStore({ key: 'main-threads', version: 1 })
- * const transport = edenTransport((input, signal) =>
- *   api.chat.post({ body: { message: input }, fetch: { signal } }),
- * )
+ * const transport = aiSdkTransport({ api: '/api/chat' })
  *
  * function ThreadFeed() {
- *   const store = useThreads()
+ *   const store = useMyThreadsStore() // consumer-owned ThreadsStore
  *   const { runs, start, stop } = useAgentThreadRuns({
  *     transport,
  *     store,
- *     resolveOutcome: heuristicOutcome,
+ *     resolveOutcome, // your OutcomeResolver
  *   })
  *   const id = store.create()
+ *   const status = runs.get(id)?.status // 'submitted' | 'streaming' | 'error' | undefined
+ *   const isLive = status === 'submitted' || status === 'streaming'
  *   return (
  *     <div>
  *       <button onClick={() => start(id, 'Hello')}>Send</button>
- *       {runs.get(id)?.status === 'streaming' && <button onClick={() => stop(id)}>Stop</button>}
+ *       {isLive && <button onClick={() => stop(id)}>Stop</button>}
  *     </div>
  *   )
  * }
  */
-import { useCallback, useEffect, useRef, useState } from 'react'
+import { useCallback, useContext, useEffect, useMemo, useRef, useState } from 'react'
 import type { Dispatch, MutableRefObject, SetStateAction } from 'react'
 import type { ChatMessage } from './history'
+import { toAgentError } from './error'
+import type { AgentError } from './error'
 import { mintMessageId, mintThreadId, 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 { createRunCommitter, isContentPart } from './run-committer'
+import {
+  beginRun,
+  endRun,
+  failedThreadIds,
+  dismissRun,
+  hasLiveRun,
+  isLatestRun,
+  isLive,
+  planStopWithTombstone,
+  sweepFlushed,
+} from './run-records'
+import type { RunRecord, RunRecords } from './run-records'
+import type { AgentThread, LiveRunStatus, ThreadStatus, ThreadsStore } from './thread'
 import { isResumable } from './transport'
 import type { AgentTransport } from './transport'
+import { TelemetryContext, createEmitter, errorName, now } from '../telemetry'
+import type { BasaltEvent, Telemetry } from '../telemetry'
 
 // ── ThreadRunState ────────────────────────────────────────────────────────────
 
 /**
- * The live stream state of a single thread's in-flight turn.
+ * The stream state of a single thread's most recent turn, while it is in flight or has failed.
  *
- * A thread only has an entry in the `runs` map while its turn is actively streaming — once a
- * turn finishes (success or error), its entry is deleted from the map (the outcome lives on the
- * persisted `AgentThread` instead). So `status` only ever holds `'streaming'`; there is no
- * `'done'`/`'idle'`/`'error'` to observe here.
+ * `status` mirrors AI SDK's `ChatStatus`: `'submitted'` from send until the first content part
+ * (text, reasoning or tool) arrives, then `'streaming'`, or `'error'` once the turn failed. A turn
+ * that settles successfully (or is stopped) has its entry deleted from the `runs` map — the
+ * outcome lives on the persisted `AgentThread` instead.
+ *
+ * A turn that FAILS keeps its entry — `status: 'error'`, `error` set, the parts received so far —
+ * until the next `start()`/`retry()` on that thread replaces it or `stop()` dismisses it. So
+ * `runs.has(id)` means "in flight or failed"; `run.status` alone says which, and
+ * `liveStatus={runs.get(id)?.status}` is correct for the chat rows (`'error'` is not live).
  *
  * @example
  * const state: ThreadRunState = { status: 'streaming', parts: [{ type: 'text', text: 'Hi' }] }
  */
-export type ThreadRunState<TPart = AgentPart> = {
-  /** Always `'streaming'` — see the type doc for why no other status is reachable here. */
-  readonly status: 'streaming'
-  /** Accumulated parts from the current stream for this thread. */
-  readonly parts: TPart[]
-}
+export type ThreadRunState<TPart = AgentPart> =
+  | {
+      /** `'submitted'` until the first content part arrives, then `'streaming'`. */
+      readonly status: LiveRunStatus
+      /** Accumulated parts from the current stream for this thread. */
+      readonly parts: TPart[]
+      readonly error?: undefined
+    }
+  | {
+      readonly status: 'error'
+      /**
+       * The parts received before the failure. Empty when the turn's final message already landed
+       * in the thread (a failure after `appendMessage`, e.g. in `resolveOutcome`), so the feed
+       * never renders the same content twice.
+       */
+      readonly parts: TPart[]
+      readonly error: AgentError
+    }
 
 // ── useAgentThreadRuns args ───────────────────────────────────────────────────
 
@@ -95,15 +127,33 @@ export type UseAgentThreadRunsArgs<TPart = AgentPart> = {
    * Converts raw user input into the thread's part shape. Defaults to a single text part.
    * Required when TPart is not the default AgentPart union.
    */
-  readonly toUserParts?: (input: string) => TPart[]
+  readonly toUserParts?: ((input: string) => TPart[]) | undefined
+  /**
+   * Called with the RAW thrown value when a turn's stream throws — never for the aborts this hook
+   * issues itself (`stop()`, supersede, unmount). An abort that comes from elsewhere (the
+   * transport, the network layer) is a failure and fires, as `kind: 'aborted'` on the run. Fires
+   * from the SAME catch branch that sets `onFailureStatus` on the thread, so a caller wanting a
+   * toast/notification for a genuine transport error (a 409/503/401, argo's hermes-chat S19) no
+   * longer has to wrap every transport call in its own generator to intercept the throw — see
+   * `consumeAndFinalize`'s catch block.
+   */
+  readonly onError?:
+    | ((info: { readonly threadId: string; readonly error: unknown }) => void)
+    | undefined
+  /**
+   * Minimum ms between `runs` commits while a part stream is flowing — `useChat`'s stable
+   * `throttle` semantics: the first part commits immediately, later parts within the window are
+   * batched into one trailing commit. The `submitted → streaming` edge, a failure, the end of the
+   * stream and `stop()` never wait on it, so no final part is lost. Default `100`; `0` commits
+   * every part.
+   */
+  readonly throttle?: number | undefined
   /**
-   * Called when a turn's stream throws — never for an `AbortError` (an intentional stop()/
-   * supersede, not a failure worth surfacing). Fires from the SAME catch branch that sets
-   * `onFailureStatus` on the thread, so a caller wanting a toast/notification for a genuine
-   * transport error (a 409/503/401, argo's hermes-chat S19) no longer has to wrap every transport
-   * call in its own generator to intercept the throw — see `consumeAndFinalize`'s catch block.
+   * Receives one `chat.turn` event when a turn completes or fails (V2-SPEC § 7); a `stop()`ped
+   * turn emits nothing. Omitted, it defaults to the enclosing `BasaltProvider`'s `telemetry` sink,
+   * and outside a provider nothing is delivered. A throwing sink never breaks the turn.
    */
-  readonly onError?: (info: { readonly threadId: string; readonly error: unknown }) => void
+  readonly telemetry?: Telemetry | undefined
 }
 
 // ── useAgentThreadRuns return type ────────────────────────────────────────────
@@ -132,21 +182,25 @@ export type UseAgentThreadRunsReturn<TPart = AgentPart> = {
    */
   readonly retry: (threadId: string) => void
   /**
-   * Abort the in-flight stream for `threadId` (true no-op only if BOTH `controllersRef` and
-   * `runs` have nothing for it — i.e. the thread genuinely isn't live). Preserves whatever content
+   * Abort the in-flight stream for `threadId`. A no-op when the thread has no live run and no
+   * failed entry. 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'.
    *
-   * Defense-in-depth: if `runs` reports `threadId` as `'streaming'` but no controller is
-   * registered for it (a phantom entry — not reachable via any path in this hook today, since the
-   * unmount-cleanup effect and `finalizeStop` both tear down `controllersRef` and `runs` together,
-   * but guarded against here so nothing in this file can EVER wedge a thread the UI shows as live
-   * with no way to reach a terminal state), `stop()` still settles it instead of silently
-   * no-opping forever.
+   * A FAILED turn's entry (`status: 'error'`) has no controller: `stop()` just dismisses it and
+   * leaves the thread's `'error'` status alone. A turn that has already settled is a no-op.
+   *
+   * Defense-in-depth: if `runs` reports `threadId` as live but no run record exists for it (a
+   * phantom entry — not reachable via any path in this hook today, since the unmount-cleanup
+   * effect and `finalizeStop` both tear down the records and `runs` together), `stop()` still
+   * settles it, once, instead of silently no-opping forever.
    */
   readonly stop: (threadId: string) => void
-  /** Abort every in-flight stream across all threads, settling each the same way stop() would. */
+  /**
+   * Abort every in-flight stream across all threads, settling each the same way stop() would, and
+   * dismiss every failed entry.
+   */
   readonly stopAll: () => void
 }
 
@@ -199,56 +253,64 @@ function buildDoneSnapshot<TPart>(
  * completes. Shared by both start() (a fresh turn) and the mount-time resume path (reconnecting
  * an orphaned thread) so the ~40-line accumulate/finalize/error logic exists exactly once.
  *
- * `onFailureStatus` is the ThreadStatus to set when the generator throws (excluding AbortError,
- * which is always a no-op): start() passes 'error' (today's behavior for a fresh turn that fails);
+ * `onFailureStatus` is the ThreadStatus to set when the generator throws (excluding the aborts
+ * this hook issues itself — stop(), supersede, unmount — which are always a no-op; an abort from
+ * elsewhere is a failure): start() passes 'error' (today's behavior for a fresh turn that fails);
  * 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 extends PartLike>(args: {
   threadId: string
-  controller: AbortController
+  record: RunRecord<TPart>
   generator: AsyncGenerator<TPart>
   userMessage: ChatMessage<TPart>
-  controllersRef: MutableRefObject<Map<string, AbortController>>
-  appendedRef: MutableRefObject<Map<string, AbortController>>
+  recordsRef: MutableRefObject<RunRecords<TPart>>
   storeRef: MutableRefObject<ThreadsStore<TPart>>
   resolveOutcome: OutcomeResolver<TPart>
   setRuns: Dispatch<SetStateAction<Map<string, ThreadRunState<TPart>>>>
   onFailureStatus: ThreadStatus
+  throttle: number
+  emit: Telemetry
   onError?: (info: { readonly threadId: string; readonly error: unknown }) => void
 }): Promise<void> {
   const {
     threadId,
-    controller,
+    record,
     generator,
     userMessage,
-    controllersRef,
-    appendedRef,
+    recordsRef,
     storeRef,
     resolveOutcome,
     setRuns,
     onFailureStatus,
+    throttle,
+    emit,
     onError,
   } = args
+  const { controller } = record
+  const live = (): boolean => isLive(recordsRef.current, threadId, controller)
+  const owns = (): boolean => isLatestRun(record)
   let parts: TPart[] = []
+  const startedAt = now()
+  let firstContentAt: number | undefined
+  // Every commit re-checks run ownership: a trailing timer that fires after stop()/unmount/a newer
+  // run took the thread over must not resurrect or clobber its `runs` entry.
+  const committer = createRunCommitter<TPart>(throttle, (committed, status) => {
+    if (!live()) return
+    setRuns((prev) => {
+      const next = new Map(prev)
+      next.set(threadId, { status, parts: committed })
+      return next
+    })
+  })
   try {
     for await (const part of generator) {
-      // Guard: a newer call superseded this stream's controller for this thread, or it
-      // was aborted — stop updating state.
-      //
-      // Deliberately NOT a `runs` teardown site (considered and rejected): `controllersRef`
-      // mismatch here is ambiguous between "this run was aborted and nothing replaced it" and "a
-      // newer run (a mount-reconcile resume, keyed by the SAME threadId) has already taken over
-      // and is live in `runs` right now". Only the first case should ever clear `runs[threadId]`,
-      // and only the abort's OWN originator can tell the two apart without a race — the unmount-
-      // cleanup effect (see its doc) does that teardown synchronously, in the same tick as the
-      // abort, before any newer run could exist to be confused with. If this guard also deleted
-      // `runs[threadId]`, a superseding resume's fresh entry would be clobbered out from under it
-      // by its OWN predecessor's late-settling loop iteration — reintroducing a wedge instead of
-      // fixing one. `stop()`'s own abort path has the same property (finalizeStop's teardown runs
-      // synchronously before `stop()` returns, never racing a subsequent call).
-      if (controllersRef.current.get(threadId) !== controller) return
-      if (controller.signal.aborted) return
+      // Guard: the run ended (stop(), unmount) or a newer run replaced its record — stop updating
+      // state. Deliberately NOT a `runs` teardown site: a mismatch is ambiguous between "aborted
+      // and nothing replaced it" and "a newer run (a mount-reconcile resume on the SAME threadId)
+      // is live in `runs` right now", and only the ender can tell which; stop() and the unmount
+      // cleanup tear `runs` down synchronously with the end, before a newer run can exist.
+      if (!live()) return
       if (isStartPart(part)) {
         storeRef.current.setResumeToken(threadId, part.resumeToken)
         continue
@@ -257,16 +319,17 @@ async function consumeAndFinalize<TPart extends PartLike>(args: {
       // 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 })
-        return next
-      })
-    }
-    // Only proceed if this stream is still the current one and wasn't aborted.
-    if (controllersRef.current.get(threadId) !== controller || controller.signal.aborted) {
-      return
+      record.parts = parts
+      // The submitted → streaming edge commits at once (it is the TTFT mark and must not wait on
+      // the throttle window); later parts ride the throttle.
+      const firstContent = firstContentAt === undefined && isContentPart(part)
+      if (firstContent) firstContentAt = now()
+      committer.push(parts, firstContentAt === undefined ? 'submitted' : 'streaming', firstContent)
     }
+    // The throttle's trailing commit: the last parts must reach `runs` before the settle below.
+    committer.flush()
+    // Only proceed if this stream is still the current one.
+    if (!live()) return
 
     const assistantMessage: ChatMessage<TPart> = {
       // appendMessage's idempotency key — mintMessageId, never mintThreadId (see that helper's
@@ -278,53 +341,89 @@ async function consumeAndFinalize<TPart extends PartLike>(args: {
       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)
+    // The terminal-append fact for THIS run, on its record: stop() reads it to avoid a second
+    // message, and the failure path reads it to avoid re-rendering the landed content as live.
+    record.appended = true
 
     const priorThread = storeRef.current.threads.find((thread) => thread.id === threadId)
     const snapshot = buildDoneSnapshot(priorThread, threadId, userMessage, assistantMessage)
-    const outcome: AgentOutcome = await resolveOutcome(snapshot)
+    record.resolving = true
+    let outcome: AgentOutcome
+    try {
+      outcome = await resolveOutcome(snapshot)
+    } finally {
+      // Settled either way: the record may now be swept once a render shows its outcome.
+      record.resolving = false
+    }
 
-    // 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) {
+    // Re-check: resolveOutcome above is the only await in this success path. If stop() ran while
+    // it was pending, stop() already settled the thread to 'done' (appending nothing: the message
+    // had landed) and deliberately did NOT call resolveOutcome a second time; this result is the
+    // one outcome of the turn, so it is recorded here. Any other end (unmount, a newer run)
+    // leaves the thread to whoever ended it.
+    if (!live()) {
+      // Only while no newer run has taken the thread: a stale resolver must not overwrite it.
+      if (record.ended === 'stopped' && record.appended && owns()) {
+        storeRef.current.setOutcome(threadId, outcome)
+      }
       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)
+    endRun(record, 'settled')
     setRuns((prev) => {
       if (!prev.has(threadId)) return prev
       const next = new Map(prev)
       next.delete(threadId)
       return next
     })
+    emit(
+      buildTurnEvent({
+        threadId,
+        startedAt,
+        firstContentAt,
+        partCount: parts.length,
+        status: outcome.status,
+      }),
+    )
   } catch (err) {
-    // Ignore abort errors — they are intentional (stop() was called or superseded).
-    if (err instanceof Error && err.name === 'AbortError') return
-    // Guard: don't corrupt state if a newer stream has taken over this thread.
-    if (controllersRef.current.get(threadId) !== controller) return
-    // Guard: don't overwrite a user-cancelled state if the signal was aborted.
-    if (controller.signal.aborted) return
+    // Guard: the run ended (stop(), unmount — which abort the controller, so their AbortError lands
+    // here) or a newer stream took the thread over. Only an abort from somewhere else gets past.
+    if (!live()) {
+      // A resolveOutcome that stop() handed the outcome to and that then REJECTED: the stopped turn
+      // stays 'done', but the failure still reaches the caller (raw, like any other).
+      if (record.ended === 'stopped' && record.appended) onError?.({ threadId, error: err })
+      return
+    }
+    const agentError = toAgentError(err)
+    // The turn's final message already landed in the thread (resolveOutcome or a store call failed
+    // AFTER appendMessage): the feed renders it from the thread, so the error entry keeps no parts.
+    const messageLanded = record.appended
+    endRun(record, 'failed')
     storeRef.current.setStatus(threadId, onFailureStatus)
-    controllersRef.current.delete(threadId)
-    appendedRef.current.delete(threadId)
+    // The failed entry stays visible, with the error and the parts received so far, until the next
+    // start()/retry() on this thread replaces it or stop() dismisses it.
+    const failedParts = messageLanded ? [] : parts
     setRuns((prev) => {
-      if (!prev.has(threadId)) return prev
       const next = new Map(prev)
-      next.delete(threadId)
+      next.set(threadId, { status: 'error', parts: failedParts, error: agentError })
       return next
     })
+    emit(
+      buildTurnEvent({
+        threadId,
+        startedAt,
+        firstContentAt,
+        partCount: parts.length,
+        status: onFailureStatus,
+        failure: { error: err, agentError },
+      }),
+    )
     onError?.({ threadId, error: err })
+  } finally {
+    committer.cancel()
   }
 }
 
@@ -332,15 +431,17 @@ async function consumeAndFinalize<TPart extends PartLike>(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.
+ * called; the caller has already ended the run's record and aborted its controller before
+ * invoking this. `alreadyAppended` is read by the caller (stop()) off the record's `appended` flag
+ * — an explicit marker rather than an inferred comparison. `outcomeInFlight` is the record's
+ * `resolving` flag: `consumeAndFinalize`'s own `resolveOutcome` is pending and records the
+ * outcome, so this function must not resolve a second time.
  *
  * Ordering / the append-failure guard: the append is attempted FIRST (so a successful stop still
  * reads as 'done' with its partial content intact — this is the common case and the one that
  * matters most), but it is wrapped in its own try/catch that CANNOT prevent the terminal
  * transition below it. This is deliberate, not incidental: by the time this function runs, `stop()`
- * has already deleted `threadId` from `controllersRef` and `appendedRef` (see `stop()`'s own doc),
+ * has already ended the run's record (see `stop()`'s own doc),
  * so a second `stop()` call is unconditionally a no-op regardless of what happens here — if the
  * append (or `mintMessageId`, which now also throws on rung 3 — see `./id.ts`) throws and nothing
  * downstream ran, the thread would be wedged at 'streaming' FOREVER with no way for the user to
@@ -358,12 +459,12 @@ async function consumeAndFinalize<TPart extends PartLike>(args: {
  * distilling into an outcome when the turn's own final message never made it into the store.
  *
  * `setStatus`/`setResumeToken` are guarded for the SAME reason, and this is not belt-and-braces:
- * they are consumer code exactly as `appendMessage` is (a `createThreadsStore` adapter over a
+ * they are consumer code exactly as `appendMessage` is (an adapter over a
  * remote backend, a store that rejects a threadId removed mid-stream), and guarding only the
  * append leaves the identical wedge one line further down. The single thing that must ALWAYS run
  * is the `setRuns` teardown — that entry is the HOOK'S OWN state, it is what `runs.get(threadId)`
- * reports to the UI as "a turn is in flight", and by this point `stop()` has already deleted the
- * thread from `controllersRef`, so no later `stop()` can ever reach here again to clean it up. A
+ * reports to the UI as "a turn is in flight", and by this point `stop()` has already ENDED the
+ * run's record, so no later `stop()` can ever reach here again to clean it up. A
  * throw above it therefore strands a phantom run for the lifetime of the hook. Each store call
  * gets its OWN try so a failing `setStatus` cannot also skip clearing the resume token — a
  * surviving token is separately harmful (it is what a later resume replays from).
@@ -372,11 +473,26 @@ async function finalizeStop<TPart extends PartLike>(args: {
   threadId: string
   parts: TPart[]
   alreadyAppended: boolean
+  /** `consumeAndFinalize`'s own `resolveOutcome` is pending and will record the outcome. */
+  outcomeInFlight: boolean
+  /** The stopped run's record: held `resolving` while this function's own resolver is pending. */
+  record: RunRecord<TPart>
   storeRef: MutableRefObject<ThreadsStore<TPart>>
   resolveOutcome: OutcomeResolver<TPart>
   setRuns: Dispatch<SetStateAction<Map<string, ThreadRunState<TPart>>>>
+  onError?: (info: { readonly threadId: string; readonly error: unknown }) => void
 }): Promise<void> {
-  const { threadId, parts, alreadyAppended, storeRef, resolveOutcome, setRuns } = args
+  const {
+    threadId,
+    parts,
+    alreadyAppended,
+    outcomeInFlight,
+    record,
+    onError,
+    storeRef,
+    resolveOutcome,
+    setRuns,
+  } = args
 
   let appendFailed = false
   if (!alreadyAppended && parts.length > 0) {
@@ -420,12 +536,57 @@ async function finalizeStop<TPart extends PartLike>(args: {
 
   // No outcome to resolve for a turn whose own terminal message never landed, or whose settle
   // never took — see this function's doc on why this mirrors consumeAndFinalize's catch path.
-  if (settleFailed) return
+  if (settleFailed || outcomeInFlight) return
 
   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)
+  // Held `resolving` like consumeAndFinalize's own call: `sweepFlushed` keeps the record while the
+  // resolver is pending, so a later start() still supersedes it and a stale outcome is dropped.
+  record.resolving = true
+  try {
+    const outcome: AgentOutcome = await resolveOutcome(snapshot)
+    if (isLatestRun(record)) storeRef.current.setOutcome(threadId, outcome)
+  } catch (error) {
+    // `stop()` calls this with `void`: a rejection must reach the caller, not become unhandled.
+    // The stopped turn stays 'done'.
+    onError?.({ threadId, error })
+  } finally {
+    record.resolving = false
+  }
+}
+
+/** The `chat.turn` event for a turn that completed (`failure` absent) or failed. */
+function buildTurnEvent(args: {
+  threadId: string
+  startedAt: number
+  firstContentAt: number | undefined
+  partCount: number
+  status: ThreadStatus
+  failure?: { readonly error: unknown; readonly agentError: AgentError }
+}): BasaltEvent {
+  const { threadId, startedAt, firstContentAt, partCount, status, failure } = args
+  const endedAt = now()
+  const base = {
+    start: startedAt,
+    duration: endedAt - startedAt,
+  }
+  const attributes = {
+    'basalt.chat.thread_id': threadId,
+    'basalt.chat.ttft_ms': (firstContentAt ?? endedAt) - startedAt,
+    'basalt.chat.parts': partCount,
+    'basalt.chat.status': status,
+  }
+  if (failure === undefined) return { ...base, type: 'chat.turn', failed: false, attributes }
+  return {
+    ...base,
+    type: 'chat.turn',
+    failed: true,
+    attributes: {
+      ...attributes,
+      'exception.type': errorName(failure.error),
+      'basalt.error.kind': failure.agentError.kind,
+    },
+  }
 }
 
 // ── useAgentThreadRuns ────────────────────────────────────────────────────────
@@ -447,6 +608,8 @@ export function useAgentThreadRuns<TPart extends PartLike = AgentPart>({
   resolveOutcome,
   toUserParts,
   onError,
+  throttle = 100,
+  telemetry,
 }: 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
@@ -458,31 +621,16 @@ export function useAgentThreadRuns<TPart extends PartLike = AgentPart>({
   // closure from an earlier render never fires instead of the consumer's current callback.
   const onErrorRef = useRef(onError)
   onErrorRef.current = onError
-
-  // 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())
+  // Same for the telemetry sink, read at emit time so an inline function never re-subscribes.
+  const providerSink = useContext(TelemetryContext)
+  const telemetryRef = useRef(telemetry ?? providerSink)
+  telemetryRef.current = telemetry ?? providerSink
+  const throttleRef = useRef(throttle)
+  throttleRef.current = throttle
+  // One record per thread id holds the run's lifecycle — controller, unthrottled parts, whether its
+  // terminal message landed, how it ended — written together through `./run-records` (see there for
+  // why these are not separate maps). A run is live while its record's `ended` is undefined.
+  const recordsRef = useRef<RunRecords<TPart>>(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())
@@ -505,6 +653,12 @@ export function useAgentThreadRuns<TPart extends PartLike = AgentPart>({
   const toUserPartsRef = useRef(resolvedToUserParts)
   toUserPartsRef.current = resolvedToUserParts
 
+  // Stable over the sink ref, so an inline `telemetry` function never changes what `start` closes over.
+  const emitTelemetry = useMemo<Telemetry>(
+    () => createEmitter((event) => telemetryRef.current?.(event)),
+    [],
+  )
+
   // Resolves the transport for `threadId`: the shared object as-is for the plain-object form
   // (unchanged behavior), or the factory's result — resolved once per thread id and cached in
   // transportsRef thereafter — for the factory form. Not itself memoized (cheap to recreate each
@@ -520,21 +674,21 @@ export function useAgentThreadRuns<TPart extends PartLike = AgentPart>({
   }
 
   // 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,
+  // leaving aborted records behind would make the mount-reconcile effect below see a live run
+  // 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.
   //
   // Also tears down the matching `runs` entries — the F3 fix above stopped this from wedging
-  // `controllersRef`/the *persisted* thread status, but left `runs` (this hook's own transient
+  // the run records/the *persisted* thread status, but left `runs` (this hook's own transient
   // state) untouched, and on a re-run-without-unmount the component (and its `runs` state) survive
   // this cleanup. Without this, the entry the aborted controller was updating stays in `runs`
   // reporting `status: 'streaming'` forever: the mount-reconcile effect below DOES correctly settle
   // the persisted thread (to a resumed run, or to 'interrupted' if not resumable), but a consumer
   // deriving "is this thread live" from `runs.has(id)` — the whole reason `runs` exists — keeps
   // seeing a phantom in-flight turn no controller is driving anymore, and `stop()` on it was a
-  // permanent no-op (nothing left in `controllersRef` to abort) — see `stop()`'s own doc. Scoped to
+  // permanent no-op (no live record left to abort) — see `stop()`'s own doc. Scoped to
   // exactly the threadIds this pass is aborting (not a blind `runs.clear()`): the mount-reconcile
   // effect below runs AFTER this cleanup completes, in the same synchronous commit — StrictMode's
   // dev-only double-invoke and `<Activity>` hide/show both destroy-then-recreate EVERY mount effect
@@ -548,10 +702,13 @@ export function useAgentThreadRuns<TPart extends PartLike = AgentPart>({
   // itself aborting is exact, not merely defensive.
   useEffect(
     () => () => {
-      const abortedThreadIds = Array.from(controllersRef.current.keys())
-      controllersRef.current.forEach((controller) => controller.abort())
-      controllersRef.current.clear()
-      appendedRef.current.clear()
+      const abortedThreadIds: string[] = []
+      for (const [threadId, record] of recordsRef.current) {
+        if (record.ended !== undefined) continue
+        abortedThreadIds.push(threadId)
+        record.controller.abort()
+      }
+      recordsRef.current.clear()
       if (abortedThreadIds.length === 0) return
       setRuns((prev) => {
         let next: Map<string, ThreadRunState<TPart>> | undefined
@@ -566,8 +723,14 @@ export function useAgentThreadRuns<TPart extends PartLike = AgentPart>({
     [],
   )
 
+  // Once a render shows a run's outcome, its terminal record has done its job (covering the window
+  // before that render); drop it so thread ids are not retained for the life of the hook.
+  useEffect(() => {
+    sweepFlushed(recordsRef.current, runs)
+  })
+
   // Reconcile orphaned in-flight threads once the store is HYDRATED: a persisted thread can be
-  // stuck 'pending' or 'streaming' after a reload/remount, since controllersRef and `runs` both
+  // stuck 'pending' or 'streaming' after a reload/remount, since the run records and `runs` both
   // start empty — nothing would otherwise resolve that skeleton. If the transport supports
   // resumption and the thread has a resumeToken (from a StartPart emitted before the disconnect)
   // plus a user message to resume from, attempt to reconnect the run instead. Any other case — no
@@ -600,7 +763,7 @@ export function useAgentThreadRuns<TPart extends PartLike = AgentPart>({
     for (const thread of storeRef.current.threads) {
       const orphaned =
         (thread.status === 'pending' || thread.status === 'streaming') &&
-        !controllersRef.current.has(thread.id)
+        !hasLiveRun(recordsRef.current, thread.id)
       if (!orphaned) continue
 
       const resumeToken = thread.resumeToken
@@ -620,16 +783,16 @@ export function useAgentThreadRuns<TPart extends PartLike = AgentPart>({
       const resume = resolvedTransport.resume
 
       const controller = new AbortController()
-      controllersRef.current.set(thread.id, controller)
+      const record = beginRun(recordsRef.current, thread.id, controller)
       setRuns((prev) => {
         const next = new Map(prev)
-        next.set(thread.id, { status: 'streaming', parts: [] })
+        next.set(thread.id, { status: 'submitted', parts: [] })
         return next
       })
 
       void consumeAndFinalize({
         threadId: thread.id,
-        controller,
+        record,
         // 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
@@ -639,12 +802,13 @@ export function useAgentThreadRuns<TPart extends PartLike = AgentPart>({
         // providing that safety.
         generator: withPartIds(thread.id, resume(resumeToken, controller.signal)),
         userMessage: lastUserMessage,
-        controllersRef,
-        appendedRef,
+        recordsRef,
         storeRef,
         resolveOutcome,
         setRuns,
         onFailureStatus: 'interrupted',
+        throttle: throttleRef.current,
+        emit: emitTelemetry,
         onError: (info) => onErrorRef.current?.(info),
       })
     }
@@ -657,7 +821,7 @@ export function useAgentThreadRuns<TPart extends PartLike = AgentPart>({
   const start = useCallback(
     (threadId: string, input: string): void => {
       // Ignore a second concurrent turn on the SAME thread; different threads run concurrently.
-      if (controllersRef.current.has(threadId)) return
+      if (hasLiveRun(recordsRef.current, threadId)) return
 
       lastInputRef.current.set(threadId, input)
 
@@ -672,19 +836,19 @@ export function useAgentThreadRuns<TPart extends PartLike = AgentPart>({
       storeRef.current.setStatus(threadId, 'streaming')
       setRuns((prev) => {
         const next = new Map(prev)
-        next.set(threadId, { status: 'streaming', parts: [] })
+        next.set(threadId, { status: 'submitted', parts: [] })
         return next
       })
 
       const controller = new AbortController()
-      controllersRef.current.set(threadId, controller)
+      const record = beginRun(recordsRef.current, threadId, controller)
       const resolvedTransport = resolveTransport(threadId)
 
       // Non-awaited: this consumer runs in the background so start() returns immediately and
       // multiple threads can stream at once.
       void consumeAndFinalize({
         threadId,
-        controller,
+        record,
         // Namespaced by threadId — same choice, same caveat, as the mount-time resume call above.
         // ctx.messageId is this turn's OWN idempotency key (userMessage.id, just minted above) —
         // a transport that accepts it (aiSdkTransport) mints its wire-level message with the SAME
@@ -694,16 +858,17 @@ export function useAgentThreadRuns<TPart extends PartLike = AgentPart>({
           resolvedTransport.stream(input, controller.signal, { messageId: userMessage.id }),
         ),
         userMessage,
-        controllersRef,
-        appendedRef,
+        recordsRef,
         storeRef,
         resolveOutcome,
         setRuns,
         onFailureStatus: 'error',
+        throttle: throttleRef.current,
+        emit: emitTelemetry,
         onError: (info) => onErrorRef.current?.(info),
       })
     },
-    [resolveOutcome],
+    [emitTelemetry, resolveOutcome],
   )
 
   const retry = useCallback(
@@ -715,61 +880,61 @@ export function useAgentThreadRuns<TPart extends PartLike = AgentPart>({
     [start],
   )
 
+  const dismiss = useCallback((threadId: string): void => {
+    dismissRun(recordsRef.current, threadId)
+    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) {
-        // No controller — but if `runs` still reports this thread as live, that's a phantom entry
-        // (see this hook's `stop()` JSDoc): nothing is driving it, and with no controller to key
-        // off of, this is the only remaining path that can ever settle it. Not reachable via any
-        // path in THIS file today (the unmount-cleanup effect and finalizeStop both tear down
-        // `controllersRef` and `runs` in the same synchronous step — see their docs), but a true
-        // no-op here would mean "the UI shows this thread streaming forever, and Stop can never
-        // clear it" the instant that invariant is ever broken by a future change. Settle it via the
-        // same finalizeStop() the normal path uses, so there is still exactly one teardown routine
-        // for "a run is ending" regardless of how it got here.
-        if (!runsRef.current.has(threadId)) return
-        const parts = runsRef.current.get(threadId)?.parts ?? []
-        const alreadyAppended = appendedRef.current.has(threadId)
-        appendedRef.current.delete(threadId)
-        void finalizeStop({ threadId, parts, alreadyAppended, storeRef, resolveOutcome, setRuns })
+      // Decided from the run's record, which start() writes synchronously — NOT from `runsRef`,
+      // which only mirrors the last flushed render. `onClick={() => { start(id, text); stop(id) }}`
+      // has a live record but no rendered entry yet, and a settle's `setRuns` leaves the entry
+      // visible to `runsRef` until the next render; reading `runs` here stranded the first and
+      // double-appended the second. `planStop` falls back to the rendered entry only when no
+      // record exists.
+      const plan = planStopWithTombstone(
+        recordsRef.current,
+        threadId,
+        runsRef.current.get(threadId),
+      )
+      if (plan.kind === 'noop') return
+      if (plan.kind === 'dismiss') {
+        dismiss(threadId)
         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 })
+      const { record, parts } = plan
+      // Capture before endRun empties the record.
+      const { appended, resolving } = record
+      endRun(record, 'stopped')
+      record.controller.abort()
+      void finalizeStop({
+        threadId,
+        parts,
+        alreadyAppended: appended,
+        outcomeInFlight: resolving,
+        record,
+        storeRef,
+        resolveOutcome,
+        setRuns,
+        onError: (info) => onErrorRef.current?.(info),
+      })
     },
-    [resolveOutcome],
+    [dismiss, resolveOutcome],
   )
 
   const stopAll = useCallback((): void => {
-    for (const threadId of Array.from(controllersRef.current.keys())) {
-      stop(threadId)
+    for (const [threadId, record] of Array.from(recordsRef.current)) {
+      if (record.ended === undefined) stop(threadId)
     }
+    // Failed entries have no live run. Sweep the records AND what `runs` shows: an unmount re-run
+    // (StrictMode, `<Activity>`) clears the records while the failed entries survive.
+    for (const threadId of failedThreadIds(recordsRef.current, runsRef.current)) stop(threadId)
   }, [stop])
 
   return { runs, start, retry, stop, stopAll }