basalt-ui 1.12.0 → 1.14.0

package/src/agent/id.test.ts

@@ -1,9 +1,15 @@
 /**
  * withPartIds — stamps `${runId}#${n}` onto any draft part arriving without an id; idempotent for
  * drafts that already have one (untouched, and doesn't advance the counter).
+ *
+ * mintThreadId/mintMessageId — the two id-minting helpers behind every unguarded
+ * `crypto.randomUUID()` call site this file's siblings used to have. Both share rungs 1
+ * (`crypto.randomUUID`) and 2 (`crypto.getRandomValues`, hand-assembled into a UUIDv4); they
+ * deliberately diverge on rung 3 (no crypto at all) — `mintThreadId` degrades, `mintMessageId`
+ * throws. See each function's own doc for why.
  */
 import { describe, expect, test } from 'bun:test'
-import { withPartIds } from './id'
+import { mintMessageId, mintThreadId, withPartIds } from './id'
 import type { AgentPartDraft } from './parts'
 
 async function* gen<T>(values: T[]): AsyncGenerator<T> {
@@ -16,6 +22,33 @@ async function collect<T>(source: AsyncGenerator<T>): Promise<T[]> {
   return out
 }
 
+const UUID_V4_RE = /^[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/i
+
+/** Rung 2: randomUUID absent, getRandomValues present (a real, non-secure-context host). */
+function withRung2Crypto<T>(run: () => T): T {
+  const originalCrypto = globalThis.crypto
+  Object.defineProperty(globalThis, 'crypto', {
+    value: { getRandomValues: originalCrypto.getRandomValues.bind(originalCrypto) },
+    configurable: true,
+  })
+  try {
+    return run()
+  } finally {
+    Object.defineProperty(globalThis, 'crypto', { value: originalCrypto, configurable: true })
+  }
+}
+
+/** Rung 3: no usable crypto at all. */
+function withRung3Crypto<T>(run: () => T): T {
+  const originalCrypto = globalThis.crypto
+  Object.defineProperty(globalThis, 'crypto', { value: undefined, configurable: true })
+  try {
+    return run()
+  } finally {
+    Object.defineProperty(globalThis, 'crypto', { value: originalCrypto, configurable: true })
+  }
+}
+
 describe('withPartIds', () => {
   test('stamps a sequential id on every draft missing one', async () => {
     // Annotated: all three literals uniformly omit `id`, so without this TS infers an `id`-less
@@ -73,3 +106,64 @@ describe('withPartIds', () => {
     ])
   })
 })
+
+describe('mintThreadId', () => {
+  test('rung 1 (crypto.randomUUID): returns a valid UUIDv4 string', () => {
+    const id = mintThreadId()
+    expect(id).toMatch(UUID_V4_RE)
+  })
+
+  test('rung 1: many mints are distinct', () => {
+    const ids = Array.from({ length: 1000 }, () => mintThreadId())
+    expect(new Set(ids).size).toBe(1000)
+  })
+
+  test('rung 2 (getRandomValues only): assembles a valid UUIDv4 — version/variant bits set', () => {
+    const id = withRung2Crypto(() => mintThreadId())
+    expect(id).toMatch(UUID_V4_RE)
+  })
+
+  test('rung 2: many mints are distinct', () => {
+    const ids = withRung2Crypto(() => Array.from({ length: 1000 }, () => mintThreadId()))
+    expect(new Set(ids).size).toBe(1000)
+  })
+
+  test('rung 3 (no usable crypto at all): does NOT throw, still returns distinct non-empty strings', () => {
+    const ids = withRung3Crypto(() => Array.from({ length: 50 }, () => mintThreadId()))
+    for (const id of ids) {
+      expect(typeof id).toBe('string')
+      expect(id.length).toBeGreaterThan(0)
+    }
+    // Weak (Date.now() + Math.random()), not cryptographically random — but still distinct across
+    // this many mints in one tick, since Math.random() varies even when Date.now() doesn't.
+    expect(new Set(ids).size).toBe(50)
+  })
+})
+
+describe('mintMessageId', () => {
+  test('rung 1 (crypto.randomUUID): returns a valid UUIDv4 string', () => {
+    const id = mintMessageId()
+    expect(id).toMatch(UUID_V4_RE)
+  })
+
+  test('rung 1: many mints are distinct', () => {
+    const ids = Array.from({ length: 1000 }, () => mintMessageId())
+    expect(new Set(ids).size).toBe(1000)
+  })
+
+  test('rung 2 (getRandomValues only): assembles a valid UUIDv4 — version/variant bits set', () => {
+    const id = withRung2Crypto(() => mintMessageId())
+    expect(id).toMatch(UUID_V4_RE)
+  })
+
+  test('rung 2: many mints are distinct', () => {
+    const ids = withRung2Crypto(() => Array.from({ length: 1000 }, () => mintMessageId()))
+    expect(new Set(ids).size).toBe(1000)
+  })
+
+  test('rung 3 (no usable crypto at all): THROWS rather than minting a non-random id', () => {
+    // Diverges from mintThreadId's rung 3 on purpose — appendMessage's idempotency key must never
+    // silently degrade to a non-collision-resistant id. See mintMessageId's own doc.
+    expect(() => withRung3Crypto(() => mintMessageId())).toThrow(/idempotency key/)
+  })
+})

package/src/agent/id.ts

@@ -1,51 +1,121 @@
 /**
- * Id-minting helpers shared by the thread stores: `mintThreadId` (a client-side thread id, used by
- * both `./thread`'s `createThreadsStore` and `./adapter`'s `createAdapterThreadsStore`) and
- * `withPartIds` (stamps sequence ids onto streamed parts). Related in theme — both mint an id a
- * store needs — unrelated in mechanism; grouped here because they're the two id-minting leaves the
- * two thread stores both sit above.
+ * Id-minting helpers shared across the agent layer: `mintThreadId` (a low-stakes client-side id —
+ * threads, run/chat namespaces — used by `./thread`'s `createThreadsStore`, `./adapter`'s
+ * `createAdapterThreadsStore`/`threadsStoreAdapterContract`, `./use-agent-stream`'s per-send run
+ * id, and `aiSdkTransport`'s fixed chat id), `mintMessageId` (the higher-stakes id `appendMessage`
+ * treats as its only idempotency key), and `withPartIds` (stamps sequence ids onto streamed
+ * parts). Grouped here because they're the id-minting leaves every store/hook/transport in this
+ * layer sits above — not because they share a mechanism (`mintMessageId` deliberately diverges
+ * from `mintThreadId` on rung 3; see its own doc).
  */
 
 /**
- * Mints a client-side thread id. `crypto.randomUUID()` exists only in SECURE CONTEXTS (HTTPS or
- * localhost) — a consumer served over plain HTTP on a LAN hostname (a homelab dashboard on a bare
- * IP, a staging box) would otherwise have `create()`, about the most basic user action a thread
- * store has, throw a plain TypeError. A store used from a browser must not throw on a user gesture
- * — the same principle already applied twice this release (`spliceText` clamps rather than throws,
- * `coalesceParts` degrades rather than throws).
+ * Hand-assembles a UUIDv4 string from 16 random bytes — the shared rung-2 mechanism both
+ * `mintThreadId` and `mintMessageId` use once `crypto.randomUUID` is unavailable but
+ * `crypto.getRandomValues` still is. The version/variant bits are set per RFC 4122, since this
+ * rung hands back raw bytes, not a formatted UUID.
+ */
+function assembleUuidV4(bytes: Uint8Array): string {
+  const hex = Array.from({ length: 16 }, (_, i) => {
+    const raw = bytes.at(i) ?? 0
+    // Version 4 (bits 12-15 of time_hi_and_version) and variant 10 (bits 6-7 of
+    // clock_seq_hi_and_reserved) — the only structure a UUIDv4 promises over raw random bytes.
+    const byte = i === 6 ? (raw & 0x0f) | 0x40 : i === 8 ? (raw & 0x3f) | 0x80 : raw
+    return byte.toString(16).padStart(2, '0')
+  }).join('')
+  return `${hex.slice(0, 8)}-${hex.slice(8, 12)}-${hex.slice(12, 16)}-${hex.slice(16, 20)}-${hex.slice(20)}`
+}
+
+/**
+ * Mints a client-side id for a LOW-COLLISION-COST use: a thread id, a per-send run-id namespace, a
+ * fixed chat id — anything minted client-side that is NOT the idempotency key some write depends
+ * on. `crypto.randomUUID()` exists only in SECURE CONTEXTS (HTTPS or localhost) — a consumer served
+ * over plain HTTP on a LAN hostname (a homelab dashboard on a bare IP, a staging box) would
+ * otherwise have `create()`, about the most basic user action a thread store has, throw a plain
+ * TypeError. A store used from a browser must not throw on a user gesture — the same principle
+ * already applied twice this release (`spliceText` clamps rather than throws, `coalesceParts`
+ * degrades rather than throws).
  *
  * Fallback chain, each rung reached only when the one above it is unavailable:
  *   1. `crypto.randomUUID()` — cryptographically random, RFC 4122 UUID. The normal path.
  *   2. `crypto.getRandomValues()` — still cryptographically random; hand-assembled into a UUIDv4
- *      (the version/variant bits are set per RFC 4122, since this rung hands back raw bytes, not a
- *      formatted UUID).
+ *      via `assembleUuidV4`.
  *   3. No usable `crypto` at all (missing entirely, or missing both methods above — an old WebView,
  *      an SSR shim). NOT cryptographically random and NOT collision-resistant in general. This rung
- *      exists solely so `create()` never throws on such a host. It is acceptable ONLY because this
- *      id is minted a handful of times per client session and is not the idempotency key any write
- *      here depends on — `ThreadsStoreAdapter.appendMessage`'s idempotency key is the MESSAGE id,
- *      not this thread id, so a collision on this rung costs a locally merged/duplicated thread, not
- *      silent data loss on the append path. Do not reuse this rung for anything with a higher
- *      collision cost than that.
+ *      exists solely so a caller never throws on such a host. It is acceptable ONLY because an id
+ *      minted here is minted a handful of times per client session and is not the idempotency key
+ *      any write depends on — `ThreadsStoreAdapter.appendMessage`'s idempotency key is the MESSAGE
+ *      id (see `mintMessageId`), not this one, so a collision on this rung costs a locally
+ *      merged/duplicated thread (or two runs sharing a part-id namespace), not silent data loss on
+ *      the append path. Do not reuse this rung for anything with a higher collision cost than that
+ *      — see `mintMessageId` for the id that needs one.
  */
 export function mintThreadId(): string {
   if (typeof crypto !== 'undefined' && typeof crypto.randomUUID === 'function') {
     return crypto.randomUUID()
   }
   if (typeof crypto !== 'undefined' && typeof crypto.getRandomValues === 'function') {
-    const bytes = crypto.getRandomValues(new Uint8Array(16))
-    const hex = Array.from({ length: 16 }, (_, i) => {
-      const raw = bytes.at(i) ?? 0
-      // Version 4 (bits 12-15 of time_hi_and_version) and variant 10 (bits 6-7 of
-      // clock_seq_hi_and_reserved) — the only structure a UUIDv4 promises over raw random bytes.
-      const byte = i === 6 ? (raw & 0x0f) | 0x40 : i === 8 ? (raw & 0x3f) | 0x80 : raw
-      return byte.toString(16).padStart(2, '0')
-    }).join('')
-    return `${hex.slice(0, 8)}-${hex.slice(8, 12)}-${hex.slice(12, 16)}-${hex.slice(16, 20)}-${hex.slice(20)}`
+    return assembleUuidV4(crypto.getRandomValues(new Uint8Array(16)))
   }
   return `id-${Date.now().toString(36)}-${Math.random().toString(36).slice(2)}`
 }
 
+/**
+ * Mints a message id — the value `ThreadsStoreAdapter.appendMessage` treats as its ONLY
+ * idempotency key (see that method's contract doc in `./adapter`). Shares `mintThreadId`'s rungs
+ * 1-2 (`crypto.randomUUID()`, then `crypto.getRandomValues()` assembled into a UUIDv4) — both are
+ * cryptographically random and collision-resistant, and rung 2 is the fix that actually matters in
+ * practice (a plain-HTTP/LAN host still has `getRandomValues`; only `randomUUID` is secure-context-
+ * gated).
+ *
+ * Rung 3 deliberately DIVERGES from `mintThreadId`: it THROWS instead of degrading to a
+ * non-random fallback. A thread id's rung-3 collision costs a locally merged/duplicated thread —
+ * annoying, recoverable, visible. A message id's collision cost is different IN KIND, not degree:
+ * `appendMessage` is idempotent on this id, so two messages that collide are not two rows, they
+ * are ONE — the second write silently no-ops and its content is gone, with nothing downstream able
+ * to tell. Degrading here would trade a loud, debuggable failure for silent, permanent data loss.
+ *
+ * This deliberately diverges from this layer's other standing rule — render-path code degrades,
+ * never throws (`spliceText` clamps, `coalesceParts` degrades, a consumer fence renderer must not
+ * take the message down) — because minting a message id is NOT render-path code. It runs once, in
+ * the write path that constructs a message before handing it to a store (`start()`,
+ * `consumeAndFinalize`'s finalize step, `finalizeStop`, `aiSdkTransport`'s per-turn user message),
+ * never inside the per-chunk accumulation/render loop those functions guard. A host with no usable
+ * `crypto` at all (missing both `randomUUID` and `getRandomValues`) is vanishingly rare — no
+ * runtime with a DOM/fetch surface worth targeting ships without a Crypto object — and an uncaught
+ * throw here is a loud, debuggable failure rather than a message silently vanishing with no trace,
+ * but WHERE it surfaces differs by call site (audited, not assumed — this paragraph previously
+ * claimed a single shared catch handled all of them, which was false):
+ *   - `consumeAndFinalize`'s own assistantMessage mint runs inside that function's try/catch, so a
+ *     throw there is correctly turned into `onFailureStatus` ('error' from `start()`, 'interrupted'
+ *     from the mount-time resume) — a visibly stuck-then-settled run, as originally claimed.
+ *   - `useAgentThreadRuns.start()`'s userMessage mint runs BEFORE any state is touched
+ *     (`appendMessage`/`setStatus`/the controller registration all come after it), so a throw there
+ *     is a true no-op that propagates synchronously out of `start()` itself — not a stuck run at
+ *     all, since nothing ever started. See `UseAgentThreadRunsReturn.start`'s `@throws` doc.
+ *   - `finalizeStop`'s stoppedMessage mint is wrapped in its own try/catch precisely so a throw
+ *     here cannot wedge the thread at 'streaming' forever (stop() has already torn down this run's
+ *     bookkeeping by the time finalizeStop runs, so a second stop() is always a no-op) — see
+ *     `finalizeStop`'s doc for the guarded behavior and the resulting 'error' status.
+ * A stuck spinner is debuggable; silently discarded chat history is not — that half of the
+ * original claim stands regardless of which of the three paths above catches it.
+ *
+ * @throws {Error} when neither `crypto.randomUUID` nor `crypto.getRandomValues` is available.
+ */
+export function mintMessageId(): string {
+  if (typeof crypto !== 'undefined' && typeof crypto.randomUUID === 'function') {
+    return crypto.randomUUID()
+  }
+  if (typeof crypto !== 'undefined' && typeof crypto.getRandomValues === 'function') {
+    return assembleUuidV4(crypto.getRandomValues(new Uint8Array(16)))
+  }
+  throw new Error(
+    'mintMessageId: no usable crypto (both randomUUID and getRandomValues are unavailable) — ' +
+      'refusing to mint a non-random message id, since ThreadsStoreAdapter.appendMessage treats ' +
+      'this id as its only idempotency key and a collision would silently drop a message.',
+  )
+}
+
 /**
  * withPartIds — stamps a stable id onto every draft part arriving without one.
  *

package/src/agent/thread.ts

@@ -145,6 +145,10 @@ export type ThreadsStore<TPart = AgentPart> = {
    * store built with `createAdapterThreadsStore` (./adapter), 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.
    */
   readonly hydrated: boolean
   /**

package/src/agent/use-agent-stream.test.tsx

@@ -262,4 +262,26 @@ describe('useAgentStream', () => {
     // Only the SECOND (surviving) call's part made it into final state — the first is discarded.
     expect(capturedParts).toEqual([{ id: 'call-2', type: 'text', text: 'call-2' }])
   })
+
+  test('send() still streams without throwing on a host with no usable crypto at all — its runId is a low-collision-cost mint (mintThreadId), never the message-id one', async () => {
+    const originalCrypto = globalThis.crypto
+    Object.defineProperty(globalThis, 'crypto', { value: undefined, configurable: true })
+    try {
+      const transport: AgentTransport<AgentPart, string> = {
+        async *stream() {
+          yield { type: 'text', text: 'a' } as AgentPartDraft as AgentPart
+        },
+      }
+      const { result } = renderHook(() => useAgentStream({ transport }))
+
+      await act(async () => {
+        await result.current.send('hi')
+      })
+
+      expect(result.current.status).toBe('done')
+      expect(result.current.parts).toHaveLength(1)
+    } finally {
+      Object.defineProperty(globalThis, 'crypto', { value: originalCrypto, configurable: true })
+    }
+  })
 })

package/src/agent/use-agent-stream.ts

@@ -27,7 +27,7 @@
  * }
  */
 import { useCallback, useEffect, useRef, useState } from 'react'
-import { withPartIds } from './id'
+import { mintThreadId, withPartIds } from './id'
 import { isStartPart } from './parts'
 import { mergePart } from './merge'
 import type { PartLike } from './merge'
@@ -107,8 +107,11 @@ export function useAgentStream<TPart extends PartLike = AgentPart, TInput = stri
       // fully resets `parts` anyway, so a fresh id per call is enough to keep two id-less drafts
       // ARRIVING WITHIN THE SAME SEND from colliding on `undefined === undefined` in mergePart (the
       // F1 bug — text→tool→text destroying each other). Not a replay mechanism — this hook has no
-      // resume() path — see withPartIds' own doc for why it can't be one anyway.
-      const runId = crypto.randomUUID()
+      // resume() path — see withPartIds' own doc for why it can't be one anyway. Low collision
+      // cost (this hook persists nothing — `parts` is discarded on the next send()/unmount), so
+      // `mintThreadId` — never `mintMessageId` — is the right rung-3 behavior here: this must not
+      // throw on a host with no usable crypto at all.
+      const runId = mintThreadId()
 
       try {
         for await (const part of withPartIds(runId, transport.stream(input, controller.signal))) {

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

@@ -792,3 +792,329 @@ describe('useAgentThreadRuns — F1 regression: id-less drafts within one run',
     expect(assistantMessage?.parts.map((part) => part.type)).toEqual(['text', 'tool', 'text'])
   })
 })
+
+describe('useAgentThreadRuns — message-id minting under degraded crypto', () => {
+  test('start() mints distinct message ids via crypto.getRandomValues when randomUUID is unavailable', async () => {
+    const store = createTestThreadsStore()
+    const threadA = store.create()
+    const threadB = store.create()
+
+    const transport: AgentTransport<AgentPart, string> = {
+      async *stream(input) {
+        yield { id: 'p1', type: 'text', text: `done:${input}` }
+      },
+    }
+
+    const originalCrypto = globalThis.crypto
+    Object.defineProperty(globalThis, 'crypto', {
+      value: { getRandomValues: originalCrypto.getRandomValues.bind(originalCrypto) },
+      configurable: true,
+    })
+    try {
+      const { result } = renderHook(() => useAgentThreadRuns({ transport, store, resolveOutcome }))
+
+      act(() => {
+        result.current.start(threadA, 'input-a')
+        result.current.start(threadB, 'input-b')
+      })
+
+      await waitFor(() => {
+        expect(store.threads.find((t) => t.id === threadA)?.status).toBe('done')
+        expect(store.threads.find((t) => t.id === threadB)?.status).toBe('done')
+      })
+
+      const allMessageIds = store.threads.flatMap((t) => t.messages.map((m) => m.id))
+      expect(allMessageIds.length).toBeGreaterThan(0)
+      expect(new Set(allMessageIds).size).toBe(allMessageIds.length)
+    } finally {
+      Object.defineProperty(globalThis, 'crypto', { value: originalCrypto, configurable: true })
+    }
+  })
+
+  test('start() THROWS on a host with no usable crypto at all, rather than silently minting a colliding message id', () => {
+    const store = createTestThreadsStore()
+    const threadId = store.create()
+
+    const transport: AgentTransport<AgentPart, string> = {
+      async *stream() {
+        yield { id: 'p1', type: 'text', text: 'unreachable' }
+      },
+    }
+
+    const { result } = renderHook(() => useAgentThreadRuns({ transport, store, resolveOutcome }))
+
+    const originalCrypto = globalThis.crypto
+    Object.defineProperty(globalThis, 'crypto', { value: undefined, configurable: true })
+    try {
+      expect(() => {
+        act(() => {
+          result.current.start(threadId, 'hi')
+        })
+      }).toThrow(/idempotency key/)
+    } finally {
+      Object.defineProperty(globalThis, 'crypto', { value: originalCrypto, configurable: true })
+    }
+
+    // The deliberate divergence documented on mintMessageId: throwing means the write never
+    // happened at all (no half-appended message, no orphaned run entry) rather than silently
+    // dropping content behind a colliding id.
+    expect(store.threads.find((t) => t.id === threadId)?.messages).toHaveLength(0)
+    expect(result.current.runs.has(threadId)).toBe(false)
+  })
+})
+
+// A ThreadsStore double that delegates everything to a real test store EXCEPT appendMessage,
+// which throws for messages matching `shouldThrow` — lets a test simulate consumer-adapter code
+// (appendMessage) throwing without touching the shared createTestThreadsStore factory used by
+// every other test in this file.
+function wrapStoreWithThrowingAppend(
+  store: ThreadsStore<AgentPart>,
+  shouldThrow: (message: AgentThread<AgentPart>['messages'][number]) => boolean,
+): ThreadsStore<AgentPart> {
+  return {
+    get threads() {
+      return store.threads
+    },
+    get activeId() {
+      return store.activeId
+    },
+    select: store.select,
+    create: store.create,
+    appendMessage(id, message) {
+      if (shouldThrow(message)) {
+        throw new Error('consumer appendMessage boom')
+      }
+      store.appendMessage(id, message)
+    },
+    setOutcome: store.setOutcome,
+    setStatus: store.setStatus,
+    setResumeToken: store.setResumeToken,
+    markRead: store.markRead,
+    remove: store.remove,
+    clear: store.clear,
+    hydrated: store.hydrated,
+    error: store.error,
+  }
+}
+
+/** As above, but for the settle half of `finalizeStop` — a consumer store whose `setStatus` throws
+ * (a remote-backed adapter rejecting a thread removed mid-stream is the realistic shape). Narrowed
+ * by `shouldThrow` because the hook ALSO calls `setStatus` from its mount-time orphan sweep, which
+ * is a different call site with a different (non-wedge) failure mode. */
+function wrapStoreWithThrowingSetStatus(
+  store: ThreadsStore<AgentPart>,
+  shouldThrow: (status: AgentThread<AgentPart>['status']) => boolean,
+): ThreadsStore<AgentPart> {
+  return {
+    get threads() {
+      return store.threads
+    },
+    get activeId() {
+      return store.activeId
+    },
+    select: store.select,
+    create: store.create,
+    appendMessage: store.appendMessage,
+    setOutcome: store.setOutcome,
+    setStatus(id, status) {
+      if (shouldThrow(status)) throw new Error('consumer setStatus boom')
+      store.setStatus(id, status)
+    },
+    setResumeToken: store.setResumeToken,
+    markRead: store.markRead,
+    remove: store.remove,
+    clear: store.clear,
+    hydrated: store.hydrated,
+    error: store.error,
+  }
+}
+
+describe('useAgentThreadRuns — finalizeStop must reach a terminal state no matter what', () => {
+  test('stop() on a host with no usable crypto still reaches a terminal status and clears the run entry (was: wedged at "streaming" forever)', async () => {
+    const store = createTestThreadsStore()
+    const threadId = store.create()
+
+    const gate = deferred<void>()
+    const transport: AgentTransport<AgentPart, string> = {
+      async *stream() {
+        yield { id: 'p1', type: 'text', text: 'partial' }
+        await gate.promise
+        yield { id: 'p2', type: 'text', text: 'never arrives' }
+      },
+    }
+
+    const { result } = renderHook(() => useAgentThreadRuns({ transport, store, resolveOutcome }))
+
+    act(() => {
+      result.current.start(threadId, 'hi')
+    })
+
+    await waitFor(() => {
+      expect(result.current.runs.get(threadId)?.parts).toHaveLength(1)
+    })
+
+    const originalCrypto = globalThis.crypto
+    Object.defineProperty(globalThis, 'crypto', { value: undefined, configurable: true })
+    try {
+      act(() => {
+        result.current.stop(threadId)
+      })
+
+      const thread = store.threads.find((t) => t.id === threadId)
+      // Before the fix: mintMessageId's throw escaped finalizeStop entirely, so setStatus/setRuns
+      // never ran and this stayed 'streaming' forever.
+      expect(thread?.status).toBe('error')
+      // The stopped message never minted an id, so appendMessage was never even attempted —
+      // only the original user message is present.
+      expect(thread?.messages).toHaveLength(1)
+      expect(result.current.runs.has(threadId)).toBe(false)
+
+      // A second stop() must not be the user's only recourse — and it isn't: controllersRef
+      // already had this threadId deleted before finalizeStop ever ran, so this is an ordinary
+      // no-op, not a retry of the failed append.
+      act(() => {
+        result.current.stop(threadId)
+      })
+      expect(store.threads.find((t) => t.id === threadId)?.status).toBe('error')
+    } finally {
+      Object.defineProperty(globalThis, 'crypto', { value: originalCrypto, configurable: true })
+    }
+
+    gate.resolve(undefined)
+  })
+
+  test("stop() reaches a terminal status and clears the run entry even when the consumer's appendMessage throws (was: wedged at 'streaming' forever)", async () => {
+    const baseStore = createTestThreadsStore()
+    const threadId = baseStore.create()
+    const store = wrapStoreWithThrowingAppend(
+      baseStore,
+      (message) => message.role === 'assistant' && message.finish === 'stopped',
+    )
+
+    const gate = deferred<void>()
+    const transport: AgentTransport<AgentPart, string> = {
+      async *stream() {
+        yield { id: 'p1', type: 'text', text: 'partial' }
+        await gate.promise
+        yield { id: 'p2', type: 'text', text: 'never arrives' }
+      },
+    }
+
+    const { result } = renderHook(() => useAgentThreadRuns({ transport, store, resolveOutcome }))
+
+    act(() => {
+      result.current.start(threadId, 'hi')
+    })
+
+    await waitFor(() => {
+      expect(result.current.runs.get(threadId)?.parts).toHaveLength(1)
+    })
+
+    act(() => {
+      result.current.stop(threadId)
+    })
+
+    const thread = store.threads.find((t) => t.id === threadId)
+    expect(thread?.status).toBe('error')
+    // Only the user message — the consumer's appendMessage rejected the stopped message.
+    expect(thread?.messages).toHaveLength(1)
+    expect(result.current.runs.has(threadId)).toBe(false)
+
+    // A second stop() remains a true no-op — not the user's only recourse.
+    act(() => {
+      result.current.stop(threadId)
+    })
+    expect(store.threads.find((t) => t.id === threadId)?.status).toBe('error')
+
+    gate.resolve(undefined)
+  })
+
+  test("stop() clears the hook's own run entry even when the consumer's setStatus throws (the second half of the same wedge)", async () => {
+    const baseStore = createTestThreadsStore()
+    const threadId = baseStore.create()
+    const store = wrapStoreWithThrowingSetStatus(baseStore, (status) => status === 'done')
+
+    const gate = deferred<void>()
+    const transport: AgentTransport<AgentPart, string> = {
+      async *stream() {
+        yield { id: 'p1', type: 'text', text: 'partial' }
+        await gate.promise
+        yield { id: 'p2', type: 'text', text: 'never arrives' }
+      },
+    }
+
+    const { result } = renderHook(() => useAgentThreadRuns({ transport, store, resolveOutcome }))
+
+    act(() => {
+      result.current.start(threadId, 'hi')
+    })
+
+    await waitFor(() => {
+      expect(result.current.runs.get(threadId)?.parts).toHaveLength(1)
+    })
+
+    act(() => {
+      result.current.stop(threadId)
+    })
+
+    // The store's own status is whatever the throwing adapter left it as — unrecoverable from
+    // here. What IS this hook's to guarantee is that `runs` no longer reports an in-flight turn:
+    // that entry is the hook's own state and nothing later can ever clear it (stop() already
+    // deleted the thread from controllersRef), so a throw above the teardown stranded it forever.
+    expect(result.current.runs.has(threadId)).toBe(false)
+    // The partial content still landed — the append runs before the settle.
+    expect(store.threads.find((t) => t.id === threadId)?.messages).toHaveLength(2)
+
+    act(() => {
+      result.current.stop(threadId)
+    })
+    expect(result.current.runs.has(threadId)).toBe(false)
+
+    gate.resolve(undefined)
+  })
+
+  test('stop() still succeeds via crypto.getRandomValues when randomUUID is unavailable (rung 2 — the rung that matters in practice)', async () => {
+    const store = createTestThreadsStore()
+    const threadId = store.create()
+
+    const gate = deferred<void>()
+    const transport: AgentTransport<AgentPart, string> = {
+      async *stream() {
+        yield { id: 'p1', type: 'text', text: 'partial' }
+        await gate.promise
+        yield { id: 'p2', type: 'text', text: 'never arrives' }
+      },
+    }
+
+    const originalCrypto = globalThis.crypto
+    Object.defineProperty(globalThis, 'crypto', {
+      value: { getRandomValues: originalCrypto.getRandomValues.bind(originalCrypto) },
+      configurable: true,
+    })
+    try {
+      const { result } = renderHook(() => useAgentThreadRuns({ transport, store, resolveOutcome }))
+
+      act(() => {
+        result.current.start(threadId, 'hi')
+      })
+
+      await waitFor(() => {
+        expect(result.current.runs.get(threadId)?.parts).toHaveLength(1)
+      })
+
+      act(() => {
+        result.current.stop(threadId)
+      })
+
+      const thread = store.threads.find((t) => t.id === threadId)
+      expect(thread?.status).toBe('done')
+      expect(thread?.messages).toHaveLength(2)
+      expect(thread?.messages[1]?.finish).toBe('stopped')
+      expect(result.current.runs.has(threadId)).toBe(false)
+    } finally {
+      Object.defineProperty(globalThis, 'crypto', { value: originalCrypto, configurable: true })
+    }
+
+    gate.resolve(undefined)
+  })
+})