basalt-ui 1.12.0 → 1.13.0

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

@@ -40,7 +40,7 @@
 import { useCallback, useEffect, useRef, useState } from 'react'
 import type { Dispatch, MutableRefObject, SetStateAction } from 'react'
 import type { ChatMessage } from './history'
-import { withPartIds } from './id'
+import { mintMessageId, mintThreadId, withPartIds } from './id'
 import { mergePart } from './merge'
 import type { PartLike } from './merge'
 import type { AgentOutcome, OutcomeResolver } from './outcome'
@@ -103,18 +103,39 @@ export type UseAgentThreadRunsArgs<TPart = AgentPart> = {
 export type UseAgentThreadRunsReturn<TPart = AgentPart> = {
   /** Live stream state per thread id, for threads with a run in progress or just completed. */
   readonly runs: ReadonlyMap<string, ThreadRunState<TPart>>
-  /** Start a new turn on `threadId`. No-op if that thread already has a stream in flight. */
+  /**
+   * Start a new turn on `threadId`. No-op if that thread already has a stream in flight.
+   *
+   * @throws {Error} synchronously, before any state is touched, on a host with no usable
+   * `crypto` at all (see `mintMessageId` in `./id.ts` — the id it mints here is the new user
+   * ChatMessage's idempotency key, so it degrades to a throw rather than a silent collision).
+   * This throw is a true no-op: it happens before `appendMessage`/`setStatus`/the run's
+   * controller are registered, so nothing is left half-started — the thread is exactly as it was
+   * before the call. A caller invoking `start` from an event handler on a target that must
+   * tolerate this (very old WebViews, non-DOM SSR shims) should wrap the call in its own
+   * try/catch; this rung is vanishingly rare in practice (see `mintMessageId`'s own doc).
+   */
   readonly start: (threadId: string, input: string) => void
   /**
    * Replay the last user input sent on `threadId` (same code path as `start`). No-op if
    * `threadId` has never had a turn started, or already has one in flight.
+   *
+   * @throws {Error} same condition and same true-no-op guarantee as `start` — see its doc.
    */
   readonly retry: (threadId: string) => void
   /**
-   * 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
+   * 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
+   * 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.
    */
   readonly stop: (threadId: string) => void
   /** Abort every in-flight stream across all threads, settling each the same way stop() would. */
@@ -123,9 +144,14 @@ export type UseAgentThreadRunsReturn<TPart = AgentPart> = {
 
 // ── defaults ──────────────────────────────────────────────────────────────────
 
-/** Default toUserParts: wraps raw input in a single text part. */
+/**
+ * Default toUserParts: wraps raw input in a single text part. This part's id is a display/merge
+ * identity WITHIN a message's own `parts` array — it is never the value `appendMessage` idempotes
+ * on (that's the enclosing `ChatMessage.id`, minted separately by the caller) — so `mintThreadId`
+ * is the right low-collision-cost helper here, not `mintMessageId`.
+ */
 function defaultToUserParts(input: string): AgentPart[] {
-  return [{ id: crypto.randomUUID(), type: 'text', text: input }]
+  return [{ id: mintThreadId(), type: 'text', text: input }]
 }
 
 /**
@@ -199,6 +225,18 @@ async function consumeAndFinalize<TPart extends PartLike>(args: {
     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
       if (isStartPart(part)) {
@@ -221,7 +259,9 @@ async function consumeAndFinalize<TPart extends PartLike>(args: {
     }
 
     const assistantMessage: ChatMessage<TPart> = {
-      id: crypto.randomUUID(),
+      // appendMessage's idempotency key — mintMessageId, never mintThreadId (see that helper's
+      // doc): a collided id here would silently drop this message, not merge a duplicate thread.
+      id: mintMessageId(),
       role: 'assistant',
       parts,
       createdAt: Date.now(),
@@ -285,11 +325,37 @@ async function consumeAndFinalize<TPart extends PartLike>(args: {
  * 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.
+ * 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),
+ * 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
+ * clear it. That is exactly the standing invariant this layer forbids (see this hook's module
+ * doc / the render-path degrade rule), so it must not depend on the append succeeding. The
+ * alternative ordering — set status/teardown first, append after — was considered and rejected:
+ * it would mark the thread 'done' before the content the user is about to lose is even attempted,
+ * which is a strictly worse failure mode for the (overwhelmingly common) success path than this
+ * try/catch is for the (vanishingly rare) failure path.
+ *
+ * On an append failure, status becomes 'error' instead of 'done' — mirroring
+ * `consumeAndFinalize`'s own catch path (`onFailureStatus`), which is the existing precedent for
+ * "the persist step failed, tell the user" in this file — and `resolveOutcome` is skipped
+ * entirely, again matching that catch path: there is no complete/consistent snapshot worth
+ * 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
+ * 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
+ * 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).
  */
 async function finalizeStop<TPart extends PartLike>(args: {
   threadId: string
@@ -301,19 +367,39 @@ async function finalizeStop<TPart extends PartLike>(args: {
 }): Promise<void> {
   const { threadId, parts, alreadyAppended, storeRef, resolveOutcome, setRuns } = args
 
+  let appendFailed = false
   if (!alreadyAppended && parts.length > 0) {
-    const stoppedMessage: ChatMessage<TPart> = {
-      id: crypto.randomUUID(),
-      role: 'assistant',
-      parts,
-      createdAt: Date.now(),
-      finish: 'stopped',
+    try {
+      const stoppedMessage: ChatMessage<TPart> = {
+        // Same idempotency-key reasoning as consumeAndFinalize's assistantMessage — mintMessageId.
+        // This can throw on rung 3 (no usable crypto — see ./id.ts) just like appendMessage
+        // (consumer code) can throw for its own reasons; both are caught below so neither can
+        // wedge the thread — see this function's doc.
+        id: mintMessageId(),
+        role: 'assistant',
+        parts,
+        createdAt: Date.now(),
+        finish: 'stopped',
+      }
+      storeRef.current.appendMessage(threadId, stoppedMessage)
+    } catch {
+      appendFailed = true
     }
-    storeRef.current.appendMessage(threadId, stoppedMessage)
   }
 
-  storeRef.current.setStatus(threadId, 'done')
-  storeRef.current.setResumeToken(threadId, undefined)
+  let settleFailed = appendFailed
+  try {
+    storeRef.current.setStatus(threadId, appendFailed ? 'error' : 'done')
+  } catch {
+    settleFailed = true
+  }
+  try {
+    storeRef.current.setResumeToken(threadId, undefined)
+  } catch {
+    settleFailed = true
+  }
+
+  // Unconditional — the one step that cannot be allowed to be skipped. See this function's doc.
   setRuns((prev) => {
     if (!prev.has(threadId)) return prev
     const next = new Map(prev)
@@ -321,6 +407,10 @@ async function finalizeStop<TPart extends PartLike>(args: {
     return next
   })
 
+  // 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
+
   const snapshot = storeRef.current.threads.find((thread) => thread.id === threadId)
   if (snapshot === undefined) return
   const outcome: AgentOutcome = await resolveOutcome(snapshot)
@@ -419,11 +509,40 @@ export function useAgentThreadRuns<TPart extends PartLike = AgentPart>({
   // 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
+  // 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
+  // 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 (both are
+  // `[]`-dep effects on this same fiber, so StrictMode/`<Activity>` destroy-then-recreate both
+  // together, in declaration order) — a resumable thread's reconcile pass registers a FRESH
+  // controller and a fresh `runs` entry there, and this teardown must never clobber that. It
+  // can't: by the time this cleanup runs, nothing has created a NEW entry for these threadIds yet
+  // (that only happens in the reconcile effect, still to come), so scoping to the ids this pass is
+  // 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()
+      if (abortedThreadIds.length === 0) return
+      setRuns((prev) => {
+        let next: Map<string, ThreadRunState<TPart>> | undefined
+        for (const threadId of abortedThreadIds) {
+          if (!prev.has(threadId)) continue
+          next ??= new Map(prev)
+          next.delete(threadId)
+        }
+        return next ?? prev
+      })
     },
     [],
   )
@@ -500,7 +619,8 @@ export function useAgentThreadRuns<TPart extends PartLike = AgentPart>({
       lastInputRef.current.set(threadId, input)
 
       const userMessage: ChatMessage<TPart> = {
-        id: crypto.randomUUID(),
+        // Same idempotency-key reasoning as consumeAndFinalize's assistantMessage — mintMessageId.
+        id: mintMessageId(),
         role: 'user',
         parts: toUserPartsRef.current(input),
         createdAt: Date.now(),
@@ -557,7 +677,23 @@ export function useAgentThreadRuns<TPart extends PartLike = AgentPart>({
       // 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
+      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 })
+        return
+      }
 
       controllersRef.current.delete(threadId)
       // Read the accumulated parts straight out of the live run entry (runsRef mirrors `runs` as of

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

@@ -48,6 +48,17 @@
  * 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.
+ *
+ * (d) is a SEPARATE, later-release defect discovered in the same family: the F3 fix above made the
+ * PERSISTED thread settle correctly (to a resume, or to 'interrupted'), but left the hook's OWN
+ * `runs` state untouched by the unmount-cleanup effect — so on a fiber that survives (StrictMode
+ * double-invoke, `<Activity>` hide/show), `runs` kept reporting the aborted run as `'streaming'`
+ * forever, even once the persisted thread had already settled. Unlike (b)/(c) (which use a
+ * RESUMABLE transport, so a fresh `runs` entry gets created by the surviving resume), (d) uses a
+ * NON-resumable transport — the case where nothing ever replaces the phantom entry, and `stop()`
+ * on it was a permanent no-op (see this hook's `stop()` JSDoc). Verified manually: reverting the
+ * `runs` teardown in the unmount-cleanup effect makes (d) fail — `runs.has(threadId)` stays `true`
+ * after the thread settles to `'interrupted'` — while (a)/(b)/(c) are unaffected by that revert.
  */
 import { describe, expect, test } from 'bun:test'
 import type { JSX } from 'react'
@@ -304,4 +315,73 @@ describe('useAgentThreadRuns — F3 mount-reconcile / unmount-cleanup wedge', ()
     })
     expect(resumeCalls).toBe(2)
   })
+
+  test('(d) BLOCKING regression: a non-resumable run aborted by an <Activity> hide/show cycle leaves no phantom `runs` entry, and stop() still reaches a terminal state', async () => {
+    const store = createTestThreadsStore()
+
+    // No `resume` at all — unlike (c), this transport cannot be resumed. Hangs until aborted;
+    // never resolves on its own (matching the real playground repro this test pins).
+    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))
+        })
+      },
+    }
+
+    let externalSetMode: ((mode: 'visible' | 'hidden') => void) | undefined
+    let hookResult: ReturnType<typeof useAgentThreadRuns<AgentPart>> | undefined
+
+    function Probe(): null {
+      hookResult = 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 />)
+    })
+
+    const threadId = store.create()
+    act(() => {
+      hookResult?.start(threadId, 'hello')
+    })
+    expect(hookResult?.runs.get(threadId)?.status).toBe('streaming')
+
+    // Hide then show — the cleanup-without-unmount path. The fiber (and its refs/state) survive;
+    // only its effects are destroyed and recreated, exactly as React 19.2's <Activity> does in
+    // PRODUCTION (see the file doc above) or as StrictMode does on every dev mount.
+    await act(async () => {
+      externalSetMode?.('hidden')
+    })
+    await act(async () => {
+      externalSetMode?.('visible')
+    })
+
+    await waitFor(() => {
+      expect(store.threads.find((t) => t.id === threadId)?.status).toBe('interrupted')
+    })
+
+    // The BLOCKING defect this test pins: `runs` must not still report this thread as 'streaming'
+    // once the persisted thread has settled to 'interrupted' — that phantom entry is what made
+    // stop() a permanent no-op.
+    expect(hookResult?.runs.has(threadId)).toBe(false)
+
+    // stop() on the now-settled thread reaches (stays at) a terminal state — not a wedge.
+    act(() => {
+      hookResult?.stop(threadId)
+    })
+    expect(store.threads.find((t) => t.id === threadId)?.status).toBe('interrupted')
+    expect(hookResult?.runs.has(threadId)).toBe(false)
+  })
 })

package/src/agent-chat/index.ts

@@ -19,6 +19,18 @@ export type { ThreadWorkspaceProps } from './thread-workspace'
 export { ThreadFeed } from './thread-feed'
 export type { ThreadFeedProps } from './thread-feed'
 
+// ── ThreadFeedRow ─────────────────────────────────────────────────────────────
+export { ThreadFeedRow } from './thread-feed-row'
+export type { ThreadFeedRowProps } from './thread-feed-row'
+
+// ── Shared transcript/row contracts ───────────────────────────────────────────
+// Type-only. Both are named in the PUBLIC props of components exported above
+// (`ThreadTranscriptProps.affordances`, `ThreadFeedRowProps`'s virtualize union), so a consumer
+// that wants to hold one in a typed variable needs to be able to name it. No runtime export here —
+// the resolution/defaults live inside the components.
+export type { MessageAffordances } from './message-affordances'
+export type { VirtualizeOptions, VirtualizeProps } from './virtualize'
+
 // ── ThreadOutcomeCard ─────────────────────────────────────────────────────────
 export { ThreadOutcomeCard } from './thread-outcome-card'
 export type { ThreadOutcomeCardProps } from './thread-outcome-card'

package/src/agent-chat/message-affordances.ts

@@ -0,0 +1,61 @@
+/**
+ * MessageAffordances — the per-message hover-row/action contract shared by `ThreadTranscript` and
+ * a virtualized `ThreadFeedRow` (both render `MessageBlock`, so the affordance surface lives here
+ * rather than being redeclared on each consumer).
+ *
+ * Type-only module — the rendering (the actual hover row, copy button, regenerate button) lives in
+ * `thread-message.tsx`. `MessageAffordances` itself IS public (re-exported, type-only, from the
+ * agent-chat barrel and the root): it is named in `ThreadTranscriptProps.affordances` and
+ * `ThreadFeedRowProps.affordances`, so a consumer has to be able to name it. `DEFAULT_AFFORDANCES`
+ * stays internal — resolving unset fields is the components' job, not the consumer's.
+ */
+import type { ReactNode } from 'react'
+import type { ChatMessage, TranscriptPart } from '../agent'
+
+export type MessageAffordances = {
+  /**
+   * How the per-message timestamp renders.
+   * @default 'relative'
+   */
+  readonly timestamp?: 'relative' | 'absolute' | 'none'
+  /**
+   * Whether a copy action is offered on the hover row. Copies the message's COALESCED text (the
+   * same merged/de-duplicated text `coalesceParts` produces for display), not the raw `parts`
+   * array — a message can accumulate multiple adjacent/by-id text parts while streaming, and
+   * copying the raw parts would either duplicate text or copy fragments the user never saw
+   * assembled.
+   * @default true
+   */
+  readonly copy?: boolean
+  /**
+   * Regenerate action, shown on the LAST ASSISTANT message only (never on earlier turns, never on
+   * user messages). Receives that message's `id`. `useAgentThreadRuns`'s `retry` is
+   * THREAD-keyed (`retry: (threadId: string) => void`), replaying the last user input for the
+   * whole thread — the consumer bridges this messageId-keyed callback to that thread-keyed retry;
+   * the framework only ever hands back the messageId, it does not know about threads.
+   */
+  readonly onRegenerate?: (messageId: string) => void
+  /**
+   * Extra actions appended to the hover row, after the built-in copy/regenerate actions.
+   *
+   * This is a RENDER prop, not an event handler — it is called during render, once per message,
+   * and its return value is rendered. That means it is treated differently from `onRegenerate`:
+   * `onRegenerate` is identity-stabilized internally (a fresh inline literal every render costs
+   * nothing), while `actions` is compared by REFERENCE, because its reference is the only signal
+   * that its output may have changed. A fresh inline `actions={() => …}` literal therefore
+   * re-renders every message block on every render of the transcript. That is correct — an action
+   * whose output depends on consumer state (a pin/star toggle) must be allowed to update — but on
+   * a long thread it is worth avoiding: wrap `actions` in the consumer's own `useCallback`, keyed
+   * on whatever state it actually reads.
+   */
+  readonly actions?: (ctx: { readonly message: ChatMessage<TranscriptPart> }) => ReactNode
+}
+
+/**
+ * Resolved defaults for the optional {@link MessageAffordances} fields — one place, so
+ * `ThreadTranscript` and a virtualized `ThreadFeedRow` cannot drift on what "unset" means.
+ */
+export const DEFAULT_AFFORDANCES: Required<Pick<MessageAffordances, 'timestamp' | 'copy'>> = {
+  timestamp: 'relative',
+  copy: true,
+}

package/src/agent-chat/relative-time.test.ts

@@ -0,0 +1,95 @@
+import { describe, expect, test } from 'bun:test'
+import { formatRelativeTime } from './relative-time'
+
+// Unit boundaries (ms) mirrored from relative-time.ts — kept in sync deliberately rather than
+// importing the private table, so a drift between the two shows up as a test failure.
+const YEAR_MS = 31_536_000_000
+const MONTH_MS = 2_628_000_000
+const WEEK_MS = 604_800_000
+const DAY_MS = 86_400_000
+const HOUR_MS = 3_600_000
+const MINUTE_MS = 60_000
+
+describe('formatRelativeTime', () => {
+  test('sub-minute past → "just now"', () => {
+    expect(formatRelativeTime(Date.now() - 1)).toBe('just now')
+    expect(formatRelativeTime(Date.now() - 30_000)).toBe('just now')
+    expect(formatRelativeTime(Date.now() - (MINUTE_MS - 1_000))).toBe('just now')
+  })
+
+  test('sub-minute future → "just now" (the threshold is symmetric on |diff|)', () => {
+    expect(formatRelativeTime(Date.now() + 1)).toBe('just now')
+    expect(formatRelativeTime(Date.now() + (MINUTE_MS - 1))).toBe('just now')
+  })
+
+  test('minute boundary', () => {
+    expect(formatRelativeTime(Date.now() - MINUTE_MS)).toBe('1 minute ago')
+  })
+
+  test('hour boundary', () => {
+    expect(formatRelativeTime(Date.now() - HOUR_MS)).toBe('1 hour ago')
+  })
+
+  test('day boundary', () => {
+    expect(formatRelativeTime(Date.now() - DAY_MS)).toBe('yesterday')
+  })
+
+  test('week boundary', () => {
+    expect(formatRelativeTime(Date.now() - WEEK_MS)).toBe('last week')
+  })
+
+  test('month boundary', () => {
+    expect(formatRelativeTime(Date.now() - MONTH_MS)).toBe('last month')
+  })
+
+  test('year boundary', () => {
+    expect(formatRelativeTime(Date.now() - YEAR_MS)).toBe('last year')
+  })
+
+  test('future timestamp: the function handles negative diffMs (diff = timestamp - Date.now())', () => {
+    // diffMs is positive here (timestamp is ahead of "now"), so Math.round(diffMs / unit.ms) is
+    // positive too, and Intl.RelativeTimeFormat's 'auto' numeric mode renders the "in X" / "next
+    // X" / "tomorrow" forms rather than the "X ago" / "last X" forms used for the past.
+    expect(formatRelativeTime(Date.now() + HOUR_MS)).toBe('in 1 hour')
+    expect(formatRelativeTime(Date.now() + DAY_MS)).toBe('tomorrow')
+    expect(formatRelativeTime(Date.now() + WEEK_MS)).toBe('next week')
+  })
+
+  test('non-finite/wrong-type inputs degrade to empty string instead of throwing', () => {
+    // Intl.RelativeTimeFormat.format throws a RangeError on any of these. The pre-fix code called
+    // it unguarded, so each of the following would have thrown out of formatRelativeTime — except
+    // `null`, which coerces to 0 via `timestamp - Date.now()` and produced a nonsense-but-non-
+    // throwing "X years ago" string. The guard now normalizes all six to the same '' result.
+    expect(formatRelativeTime(NaN)).toBe('')
+    expect(formatRelativeTime(Infinity)).toBe('')
+    expect(formatRelativeTime(-Infinity)).toBe('')
+    // @ts-expect-error — runtime type violation (undefined at a `number`-typed call site), the exact
+    // shape a `ThreadsStoreAdapter` bug or corrupted localStorage JSON would produce.
+    expect(formatRelativeTime(undefined)).toBe('')
+    // @ts-expect-error — runtime type violation (ISO string), the single most likely real-world
+    // adapter mistake (a server returning `created_at` as a string).
+    expect(formatRelativeTime('2024-01-01T00:00:00Z')).toBe('')
+    // @ts-expect-error — runtime type violation (null); previously coerced to 0 rather than
+    // throwing, now normalized to the same '' as every other non-finite input.
+    expect(formatRelativeTime(null)).toBe('')
+  })
+
+  test('finite-but-absurd timestamps still format instead of throwing', () => {
+    // Number.isFinite is true for both, so these fall through the new guard unchanged — the guard
+    // must not over-trigger on merely-extreme (but valid) input.
+    expect(() => formatRelativeTime(8_640_000_000_000_000)).not.toThrow() // year 275760, JS Date max
+    expect(() => formatRelativeTime(-8_640_000_000_000_000)).not.toThrow() // symmetric min
+    expect(() => formatRelativeTime(-1_000_000_000_000)).not.toThrow() // pre-1970 epoch
+  })
+
+  test('"at(-1)!" fallback path — documented as effectively unreachable', () => {
+    // RELATIVE_TIME_UNITS.find(...) ?? RELATIVE_TIME_UNITS.at(-1)! only falls through to the
+    // fallback when .find returns undefined. The array's last (smallest) entry is 'minute' at
+    // 60_000ms, exactly the threshold the "just now" early-return already guards below — so for
+    // every absMs that reaches the .find call (absMs >= 60_000), 'minute' itself always matches
+    // first-or-later, and the ?? branch is defensive dead code under the current threshold table.
+    // This test exercises the boundary that the fallback would produce if it were ever reachable
+    // (it currently is not, verified by construction): the same 'minute' unit as the last table row.
+    expect(formatRelativeTime(Date.now() - MINUTE_MS)).toBe('1 minute ago')
+  })
+})

package/src/agent-chat/relative-time.ts

@@ -0,0 +1,55 @@
+/**
+ * formatRelativeTime — dependency-free relative-time formatting (no date-fns).
+ *
+ * Shared between `ThreadOutcomeCard` (inbox row timestamps) and `ThreadTranscript` (per-message
+ * timestamps). 'en'-hardcoded for now — see the module-level note below for the deferred locale
+ * seam.
+ *
+ * Internal to `agent-chat/` — not part of the public barrel.
+ */
+
+const RELATIVE_TIME_FORMAT = new Intl.RelativeTimeFormat('en', { numeric: 'auto' })
+
+const RELATIVE_TIME_UNITS: readonly {
+  readonly unit: Intl.RelativeTimeFormatUnit
+  readonly ms: number
+}[] = [
+  { unit: 'year', ms: 31_536_000_000 },
+  { unit: 'month', ms: 2_628_000_000 },
+  { unit: 'week', ms: 604_800_000 },
+  { unit: 'day', ms: 86_400_000 },
+  { unit: 'hour', ms: 3_600_000 },
+  { unit: 'minute', ms: 60_000 },
+]
+
+/**
+ * Formats an epoch-ms timestamp as a short relative string ("3 hours ago", "just now").
+ *
+ * A non-finite `timestamp` — `NaN`, `±Infinity`, or a non-number value that slipped past the
+ * `ChatMessage.createdAt: number` type at runtime (an ISO string or `undefined`/`null` from a
+ * hand-rolled `ThreadsStoreAdapter`, or from JSON-deserialized `localStorage` state) renders as an
+ * empty string rather than reaching `Intl.RelativeTimeFormat.format`, which throws a `RangeError`
+ * on any non-finite input. This is render-path code — one bad `createdAt` on one message must not
+ * blank the whole transcript (the standing rule `spliceText`/`coalesceParts` already hold) — so it
+ * degrades instead of throwing, and warns in dev, matching `mergePart`'s clamp-and-warn precedent
+ * (`clampOffset` in `../agent/merge.ts`). The warning is NOT deduplicated, also matching that
+ * precedent — but note the call sites differ: `clampOffset` runs once per wire event, whereas this
+ * runs during render, once per message, so a single bad `createdAt` in a long transcript warns
+ * once per message per render. That is loud on purpose (a `createdAt` that isn't a number is an
+ * adapter bug worth fixing, not worth muting), and it costs nothing in production.
+ */
+export function formatRelativeTime(timestamp: number): string {
+  if (!Number.isFinite(timestamp)) {
+    if (process.env['NODE_ENV'] !== 'production') {
+      console.warn(
+        `[basalt] formatRelativeTime: non-finite timestamp ${String(timestamp)} — rendering empty string`,
+      )
+    }
+    return ''
+  }
+  const diffMs = timestamp - Date.now()
+  const absMs = Math.abs(diffMs)
+  if (absMs < 60_000) return 'just now'
+  const unit = RELATIVE_TIME_UNITS.find(({ ms }) => absMs >= ms) ?? RELATIVE_TIME_UNITS.at(-1)!
+  return RELATIVE_TIME_FORMAT.format(Math.round(diffMs / unit.ms), unit.unit)
+}