basalt-ui 1.10.0 → 1.11.0

package/src/agent/ai-sdk-transport.ts

@@ -47,13 +47,22 @@
  *   resolveOutcome: heuristicOutcome,
  * })
  */
-import type { AgentPart, SourcePart, ToolCallPart } from './parts'
-import type { AgentTransport } from './transport'
+import { assertNever } from '../register'
+import { TERMINAL_TOOL_STATES } from './parts'
+import type { AgentPart, AgentPartDraft } from './parts'
+import type { ResumableAgentTransport } from './transport'
 
 // ── ai (optional peer) — TYPE-ONLY imports, erased at runtime ────────────────
 // verbatimModuleSyntax-safe: these never trigger a runtime resolution of 'ai'. The actual runtime
 // access goes through the memoized `import('ai')` inside resolveAiSdk() below.
-import type { DefaultChatTransport, UIMessage, UIMessageChunk, readUIMessageStream } from 'ai'
+import type {
+  DefaultChatTransport,
+  DynamicToolUIPart,
+  ToolUIPart,
+  UIMessage,
+  UIMessageChunk,
+  readUIMessageStream,
+} from 'ai'
 
 /** The element type of an AI SDK UIMessage's `parts` array (defaults applied). */
 type AiPart = UIMessage['parts'][number]
@@ -76,13 +85,13 @@ export type AiSdkTransportOptions = {
 
 // ── AiSdkTransport ─────────────────────────────────────────────────────────────
 
-export type AiSdkTransport<TPart = AgentPart> = AgentTransport<TPart, string> & {
+export type AiSdkTransport<TPart = AgentPart> = ResumableAgentTransport<TPart, string> & {
   /**
    * Returns an AgentTransport bound to a stable chat id (e.g. a basalt-ui thread id) instead of
    * this transport's own fixed one. Use this for useAgentThreadRuns's per-thread transport-factory
    * form so each thread's turns share one continuous AI SDK chat session.
    */
-  readonly forThread: (chatId: string) => AgentTransport<TPart, string>
+  readonly forThread: (chatId: string) => ResumableAgentTransport<TPart, string>
 }
 
 // ── Lazy, memoized 'ai' resolution ────────────────────────────────────────────
@@ -120,80 +129,209 @@ function createAiSdkResolver(options: AiSdkTransportOptions): () => Promise<Reso
 
 /**
  * Diffs one AI SDK part (by array index) against its previous snapshot at that same index,
- * returning zero or more new AgentPart deltas.
+ * returning zero or more new AgentPart drafts, each carrying a deterministic id.
  *
- * source-document, file, reasoning-file, data-*, step-start, custom, and dynamic-tool parts have
- * no AgentPart equivalent yet — deliberate v1 gap, skipped rather than inventing new variants.
+ * Index-addressed parts (text, reasoning, source) get `${chatId}#${index}` — stable across
+ * replays of the same snapshot sequence, which is what lets `mergePart` rewrite instead of
+ * duplicate on a resumed/replayed stream. text/reasoning also carry an authoritative `offset`
+ * (the length of the previously-seen text for that part) so a full-length resend at offset 0
+ * splices over the existing content instead of appending — the literal mechanism
+ * `idempotentReplay: true` asserts.
+ *
+ * source-document, file, reasoning-file, data-*, step-start, and custom parts have no AgentPart
+ * equivalent yet — deliberate v1 gap, skipped rather than inventing new variants.
  */
-function diffPart(prevPart: AiPart | undefined, currPart: AiPart): AgentPart[] {
+function diffPart(
+  chatId: string,
+  index: number,
+  prevPart: AiPart | undefined,
+  currPart: AiPart,
+  toolStartTimes: Map<string, number>,
+): AgentPartDraft[] {
   switch (currPart.type) {
     case 'text': {
       const prevText = prevPart?.type === 'text' ? prevPart.text : ''
       const delta = currPart.text.slice(prevText.length)
-      return delta.length === 0 ? [] : [{ type: 'text', text: delta }]
+      return delta.length === 0
+        ? []
+        : [{ id: `${chatId}#${index}`, type: 'text', text: delta, offset: prevText.length }]
     }
     case 'reasoning': {
       const prevText = prevPart?.type === 'reasoning' ? prevPart.text : ''
       const delta = currPart.text.slice(prevText.length)
-      return delta.length === 0 ? [] : [{ type: 'reasoning', text: delta }]
+      return delta.length === 0
+        ? []
+        : [{ id: `${chatId}#${index}`, type: 'reasoning', text: delta, offset: prevText.length }]
     }
     case 'source-url': {
       // Emit once, the first time this part appears at this index.
       if (prevPart !== undefined) return []
-      const source: SourcePart = { type: 'source', url: currPart.url }
+      const source: AgentPartDraft = { id: `${chatId}#${index}`, type: 'source', url: currPart.url }
       return [currPart.title !== undefined ? { ...source, title: currPart.title } : source]
     }
     default:
-      return currPart.type.startsWith('tool-') ? diffToolPart(prevPart, currPart) : []
+      return isToolLikePart(currPart) ? diffToolPart(prevPart, currPart, toolStartTimes) : []
   }
 }
 
+/** True for a `tool-${name}` static part OR a `dynamic-tool` part — the two AI SDK shapes basalt
+ * models as one `ToolCallPart`. `'dynamic-tool'` does NOT start with `'tool-'`, so this must be
+ * its own check, not a `.startsWith('tool-')` alone (that silently drops every dynamic tool call). */
+function isToolLikePart(part: AiPart): part is ToolUIPart | DynamicToolUIPart {
+  return part.type === 'dynamic-tool' || part.type.startsWith('tool-')
+}
+
+/** Derives the tool's display name — mirrors AI SDK's own `getToolName`/`getStaticToolName`
+ * runtime (reimplemented locally rather than value-imported, so this module never resolves 'ai'
+ * at runtime; see the module docblock). Static tools carry their name only in the `tool-${name}`
+ * discriminator; dynamic tools carry it in `toolName`. */
+function deriveToolName(part: ToolUIPart | DynamicToolUIPart): string {
+  return part.type === 'dynamic-tool' ? part.toolName : part.type.split('-').slice(1).join('-')
+}
+
+/** The `{ output, preliminary }` snapshot of an `output-available` tool part, or undefined for
+ * any other state. */
+function outputSnapshot(
+  part: ToolUIPart | DynamicToolUIPart,
+): { readonly output: unknown; readonly preliminary: boolean | undefined } | undefined {
+  return part.state === 'output-available'
+    ? { output: part.output, preliminary: part.preliminary }
+    : undefined
+}
+
 /**
- * Minimal structural shape read off a `tool-${name}` UIMessagePart. Cast to this (rather than
- * AI SDK's own generic ToolUIPart<TOOLS>) because we diff by raw `type`/`state` string comparison,
- * not by a caller-supplied tool registry.
+ * True when `curr` reports nothing new relative to `prev` — same state AND (for output-available)
+ * the same output/preliminary content. A `preliminary: true` result streams several
+ * output-available snapshots with the SAME `state` but a MUTATING `output`; naive state-equality
+ * would freeze on the first snapshot and drop every refinement. Content (not reference) equality:
+ * each snapshot from `readUIMessageStream` is a fresh `structuredClone`, so `===` on nested output
+ * objects would never match even when genuinely unchanged.
  */
-type ToolLike = {
-  readonly type: string
-  readonly toolCallId: string
-  readonly state: string
-  readonly input?: unknown
-  readonly output?: unknown
-  readonly errorText?: string
+function isSameToolState(
+  prev: ToolUIPart | DynamicToolUIPart,
+  curr: ToolUIPart | DynamicToolUIPart,
+): boolean {
+  if (prev.state !== curr.state) return false
+  const prevOutput = outputSnapshot(prev)
+  const currOutput = outputSnapshot(curr)
+  if (prevOutput === undefined || currOutput === undefined) return true
+  return (
+    JSON.stringify(prevOutput.output) === JSON.stringify(currOutput.output) &&
+    prevOutput.preliminary === currOutput.preliminary
+  )
 }
 
-function diffToolPart(prevPart: AiPart | undefined, currPart: AiPart): AgentPart[] {
-  const curr = currPart as unknown as ToolLike
-  // Deliberate v1 simplification: never emit on 'input-streaming' (partial/DeepPartial input) —
-  // wait for at least 'input-available' so the consumer isn't flooded with incomplete fragments.
-  if (curr.state === 'input-streaming') return []
+/**
+ * Diffs one tool part across the seven-state `UIToolInvocation` union into a `ToolCallPart` draft,
+ * addressed by `tool#${toolCallId}` — stable across every state transition of one call, so
+ * `mergePart` rewrites the same part in place rather than stacking one entry per state.
+ *
+ * `durationMs` is basalt's own field (the SDK doesn't provide one): wall-clock from this
+ * toolCallId's first sighting (recorded in `toolStartTimes`, scoped to ONE stream() / resume()
+ * call — never module-global, so two concurrent threads never share timings) to a terminal state.
+ */
+function diffToolPart(
+  prevPart: AiPart | undefined,
+  currPart: ToolUIPart | DynamicToolUIPart,
+  toolStartTimes: Map<string, number>,
+): AgentPartDraft[] {
+  if (!toolStartTimes.has(currPart.toolCallId)) {
+    toolStartTimes.set(currPart.toolCallId, Date.now())
+  }
+
+  const prev = prevPart !== undefined && isToolLikePart(prevPart) ? prevPart : undefined
+  if (prev !== undefined && isSameToolState(prev, currPart)) return []
 
-  const prev =
-    prevPart !== undefined && prevPart.type === currPart.type
-      ? (prevPart as unknown as ToolLike)
-      : undefined
-  // Already emitted this exact state for this tool call index — nothing new to report.
-  if (prev?.state === curr.state) return []
+  const settled = (TERMINAL_TOOL_STATES as readonly string[]).includes(currPart.state)
+  const durationMs = settled
+    ? Date.now() - (toolStartTimes.get(currPart.toolCallId) ?? Date.now())
+    : undefined
 
-  const toolName = curr.type.slice('tool-'.length)
-  const base: ToolCallPart = {
-    type: 'tool',
-    toolName,
-    toolCallId: curr.toolCallId,
-    input: curr.input,
+  const base = {
+    id: `tool#${currPart.toolCallId}`,
+    type: 'tool' as const,
+    toolCallId: currPart.toolCallId,
+    toolName: deriveToolName(currPart),
+    ...(currPart.providerExecuted !== undefined
+      ? { providerExecuted: currPart.providerExecuted }
+      : {}),
+    ...(durationMs !== undefined ? { durationMs } : {}),
+  }
+
+  switch (currPart.state) {
+    case 'input-streaming':
+      return [
+        {
+          ...base,
+          state: 'input-streaming',
+          ...(currPart.input !== undefined ? { input: currPart.input } : {}),
+        },
+      ]
+    case 'input-available':
+      return [{ ...base, state: 'input-available', input: currPart.input }]
+    case 'approval-requested':
+      return [
+        {
+          ...base,
+          state: 'approval-requested',
+          input: currPart.input,
+          approval: currPart.approval,
+        },
+      ]
+    case 'approval-responded':
+      return [
+        {
+          ...base,
+          state: 'approval-responded',
+          input: currPart.input,
+          approval: currPart.approval,
+        },
+      ]
+    case 'output-available':
+      return [
+        {
+          ...base,
+          state: 'output-available',
+          input: currPart.input,
+          output: currPart.output,
+          ...(currPart.preliminary !== undefined ? { preliminary: currPart.preliminary } : {}),
+          ...(currPart.approval !== undefined ? { approval: currPart.approval } : {}),
+        },
+      ]
+    case 'output-error': {
+      // rawInput only exists on the static ToolUIPart variant — a DynamicToolUIPart's output-error
+      // has no such field at all, so this must be read defensively behind the type discriminant.
+      const rawInput = currPart.type === 'dynamic-tool' ? undefined : currPart.rawInput
+      return [
+        {
+          ...base,
+          state: 'output-error',
+          ...(currPart.input !== undefined ? { input: currPart.input } : {}),
+          errorText: currPart.errorText,
+          ...(rawInput !== undefined ? { rawInput } : {}),
+          ...(currPart.approval !== undefined ? { approval: currPart.approval } : {}),
+        },
+      ]
+    }
+    case 'output-denied':
+      return [
+        { ...base, state: 'output-denied', input: currPart.input, approval: currPart.approval },
+      ]
+    default:
+      return assertNever(currPart)
   }
-  if (curr.state === 'output-available') return [{ ...base, output: curr.output }]
-  // output-error: still surface it as a tool part rather than silently dropping the failure — the
-  // error text becomes the output payload since ToolCallPart has no dedicated error field.
-  if (curr.state === 'output-error') return [{ ...base, output: { error: curr.errorText } }]
-  return [base]
 }
 
 /** Diffs every index of one UIMessage snapshot against the previous snapshot. */
-function diffMessage(prev: UIMessage | undefined, curr: UIMessage): AgentPart[] {
-  const deltas: AgentPart[] = []
+function diffMessage(
+  chatId: string,
+  prev: UIMessage | undefined,
+  curr: UIMessage,
+  toolStartTimes: Map<string, number>,
+): AgentPartDraft[] {
+  const deltas: AgentPartDraft[] = []
   curr.parts.forEach((part, i) => {
-    deltas.push(...diffPart(prev?.parts[i], part))
+    deltas.push(...diffPart(chatId, i, prev?.parts[i], part, toolStartTimes))
   })
   return deltas
 }
@@ -204,19 +342,28 @@ function diffMessage(prev: UIMessage | undefined, curr: UIMessage): AgentPart[]
  * built-in AgentPart variants, so TPart must be — or be assignable from — AgentPart for a
  * meaningful result; same documented-cast convention as useAgentThreadRuns' defaultToUserParts).
  *
+ * `chatId` is the id-namespace for this diff pass — the caller's chat id on stream(), the
+ * resumeToken (which IS the chat id, see the module docblock's CHAT ID BINDING note) on resume() —
+ * so index-addressed ids line up with the original run's ids across a reconnect.
+ *
+ * A fresh `toolStartTimes` map is scoped to ONE diffChunkStream call (one stream()/resume()
+ * invocation), never shared across calls or threads.
+ *
  * `resume()`'s underlying reconnectToStream call has no AbortSignal parameter in the current AI
  * SDK API (unlike sendMessages), so we can't cancel the in-flight fetch directly — checking
  * `signal.aborted` here at least stops yielding further deltas to an aborted caller promptly.
  */
 async function* diffChunkStream<TPart>(
+  chatId: string,
   chunkStream: ReadableStream<UIMessageChunk>,
   readStream: typeof readUIMessageStream,
   signal?: AbortSignal,
 ): AsyncGenerator<TPart> {
   let prev: UIMessage | undefined
+  const toolStartTimes = new Map<string, number>()
   for await (const curr of readStream<UIMessage>({ stream: chunkStream })) {
     if (signal?.aborted) return
-    for (const part of diffMessage(prev, curr)) {
+    for (const part of diffMessage(chatId, prev, curr, toolStartTimes)) {
       yield part as TPart
     }
     prev = curr
@@ -241,12 +388,16 @@ export function aiSdkTransport<TPart = AgentPart>(
 ): AiSdkTransport<TPart> {
   const resolveAiSdk = createAiSdkResolver(options)
 
-  function makeTransport(chatId: string): AgentTransport<TPart, string> {
+  function makeTransport(chatId: string): ResumableAgentTransport<TPart, string> {
     return {
+      // Every text/reasoning delta this transport emits carries an authoritative `offset` (see
+      // diffPart), so a replayed run rewrites in place instead of duplicating — the literal
+      // condition this assertion stands for.
+      idempotentReplay: true,
       async *stream(input: string, signal?: AbortSignal): AsyncGenerator<TPart> {
         // Synthesized locally, first — we already know the chat id client-side, so there is no
         // need to wait on the server to hand us a run id (unlike a river-style protocol).
-        yield { type: 'start', runId: chatId, resumeToken: chatId } as TPart
+        yield { id: `${chatId}#start`, type: 'start', runId: chatId, resumeToken: chatId } as TPart
 
         const { httpTransport, readUIMessageStream: readStream } = await resolveAiSdk()
         const userMessage: UIMessage = {
@@ -261,13 +412,15 @@ export function aiSdkTransport<TPart = AgentPart>(
           messageId: undefined,
           abortSignal: signal,
         })
-        yield* diffChunkStream<TPart>(chunkStream, readStream, signal)
+        yield* diffChunkStream<TPart>(chatId, chunkStream, readStream, signal)
       },
       async *resume(resumeToken: string, signal?: AbortSignal): AsyncGenerator<TPart> {
         const { httpTransport, readUIMessageStream: readStream } = await resolveAiSdk()
         const chunkStream = await httpTransport.reconnectToStream({ chatId: resumeToken })
         if (chunkStream === null) return
-        yield* diffChunkStream<TPart>(chunkStream, readStream, signal)
+        // resumeToken IS the chat id (see CHAT ID BINDING above) — reusing it as the id-namespace
+        // here keeps replayed index-addressed ids identical to the ones the original run minted.
+        yield* diffChunkStream<TPart>(resumeToken, chunkStream, readStream, signal)
       },
     }
   }

package/src/agent/coalesce.test.ts

@@ -0,0 +1,194 @@
+/**
+ * coalesceParts — merges a rendered turn's parts for display: consecutive text/reasoning runs,
+ * and tool parts by toolCallId regardless of adjacency (later state wins, input/toolName from an
+ * earlier state survive a later state that omits them, first-occurrence position is kept). An
+ * approval-bearing part with no directly usable toolCallId resolves via the approvalId side index.
+ */
+import { describe, expect, test } from 'bun:test'
+import { coalesceParts } from './coalesce'
+import type { AgentPart, ToolCallPart } from './parts'
+
+describe('coalesceParts', () => {
+  test('merges consecutive text parts into one', () => {
+    const parts: AgentPart[] = [
+      { id: 'p1', type: 'text', text: 'Hel' },
+      { id: 'p2', type: 'text', text: 'lo' },
+    ]
+    expect(coalesceParts(parts)).toEqual([{ id: 'p2', type: 'text', text: 'Hello' }])
+  })
+
+  test('merges consecutive reasoning parts into one', () => {
+    const parts: AgentPart[] = [
+      { id: 'p1', type: 'reasoning', text: 'thinking' },
+      { id: 'p2', type: 'reasoning', text: ' more' },
+    ]
+    expect(coalesceParts(parts)).toEqual([{ id: 'p2', type: 'reasoning', text: 'thinking more' }])
+  })
+
+  test('does not merge text across a non-text part (a tool call interleaved)', () => {
+    const parts: AgentPart[] = [
+      { id: 'p1', type: 'text', text: 'a' },
+      {
+        id: 'p2',
+        type: 'tool',
+        toolCallId: 'call-1',
+        toolName: 'search',
+        state: 'input-available',
+        input: {},
+      },
+      { id: 'p3', type: 'text', text: 'b' },
+    ]
+    const out = coalesceParts(parts)
+    expect(out).toHaveLength(3)
+    expect(out[0]?.type).toBe('text')
+    expect(out[2]?.type).toBe('text')
+  })
+
+  test('merges tool parts by toolCallId across NON-ADJACENT positions', () => {
+    const inputAvailable: ToolCallPart = {
+      id: 'p1',
+      type: 'tool',
+      toolCallId: 'call-1',
+      toolName: 'search',
+      state: 'input-available',
+      input: { q: 'x' },
+    }
+    const outputAvailable: ToolCallPart = {
+      id: 'p3',
+      type: 'tool',
+      toolCallId: 'call-1',
+      toolName: 'search',
+      state: 'output-available',
+      input: { q: 'x' },
+      output: { hits: 3 },
+    }
+    const parts: AgentPart[] = [
+      inputAvailable,
+      { id: 'p2', type: 'text', text: 'meanwhile...' },
+      outputAvailable,
+    ]
+
+    const out = coalesceParts(parts)
+    expect(out).toHaveLength(2)
+    // The merged tool part keeps the position of its FIRST occurrence.
+    expect(out[0]?.type).toBe('tool')
+    expect((out[0] as ToolCallPart).state).toBe('output-available')
+    expect(out[1]?.type).toBe('text')
+  })
+
+  test('the later terminal state wins over an earlier one for the same toolCallId', () => {
+    const outputAvailable: ToolCallPart = {
+      id: 'p1',
+      type: 'tool',
+      toolCallId: 'call-1',
+      toolName: 'search',
+      state: 'output-available',
+      input: { q: 'x' },
+      output: { hits: 3 },
+    }
+    const outputError: ToolCallPart = {
+      id: 'p2',
+      type: 'tool',
+      toolCallId: 'call-1',
+      toolName: 'search',
+      state: 'output-error',
+      errorText: 'timed out',
+    }
+    const out = coalesceParts([outputAvailable, outputError])
+    expect(out).toHaveLength(1)
+    expect((out[0] as ToolCallPart).state).toBe('output-error')
+  })
+
+  test('input from an earlier state survives a later state that omits it', () => {
+    const inputAvailable: ToolCallPart = {
+      id: 'p1',
+      type: 'tool',
+      toolCallId: 'call-1',
+      toolName: 'search',
+      state: 'input-available',
+      input: { q: 'x' },
+    }
+    // Simulates the wire shape where `tool-output-available` carries only `output` — a raw
+    // pre-normalization shape our strict type doesn't allow, hence the cast.
+    const outputAvailableNoInput = {
+      id: 'p2',
+      type: 'tool',
+      toolCallId: 'call-1',
+      toolName: 'search',
+      state: 'output-available',
+      output: { hits: 3 },
+    } as unknown as ToolCallPart
+
+    const out = coalesceParts([inputAvailable, outputAvailableNoInput])
+    expect(out).toHaveLength(1)
+    const merged = out[0] as ToolCallPart & { output: unknown }
+    expect(merged.state).toBe('output-available')
+    expect(merged.input).toEqual({ q: 'x' })
+    expect(merged.output).toEqual({ hits: 3 })
+  })
+
+  test('toolName from an earlier state survives a later state that omits it', () => {
+    const inputAvailable: ToolCallPart = {
+      id: 'p1',
+      type: 'tool',
+      toolCallId: 'call-1',
+      toolName: 'search',
+      state: 'input-available',
+      input: { q: 'x' },
+    }
+    const outputAvailableNoToolName = {
+      id: 'p2',
+      type: 'tool',
+      toolCallId: 'call-1',
+      toolName: '',
+      state: 'output-available',
+      input: { q: 'x' },
+      output: { hits: 3 },
+    } as unknown as ToolCallPart
+
+    const out = coalesceParts([inputAvailable, outputAvailableNoToolName])
+    expect((out[0] as ToolCallPart).toolName).toBe('search')
+  })
+
+  test('an approval-responded part with no toolCallId is resolved via the approvalId side index', () => {
+    const approvalRequested: ToolCallPart = {
+      id: 'p1',
+      type: 'tool',
+      toolCallId: 'call-1',
+      toolName: 'delete_file',
+      state: 'approval-requested',
+      input: { path: '/etc/passwd' },
+      approval: { id: 'appr-1' },
+    }
+    // The SDK's raw approval-responded chunk arrives without its own toolCallId — resolved by
+    // reverse lookup on approval.id instead.
+    const approvalResponded = {
+      id: 'p2',
+      type: 'tool',
+      toolCallId: '',
+      toolName: 'delete_file',
+      state: 'approval-responded',
+      input: { path: '/etc/passwd' },
+      approval: { id: 'appr-1', approved: true },
+    } as unknown as ToolCallPart
+
+    const out = coalesceParts([approvalRequested, approvalResponded])
+    expect(out).toHaveLength(1)
+    expect((out[0] as ToolCallPart).state).toBe('approval-responded')
+  })
+
+  test('a tool part unresolvable by either toolCallId or approvalId is kept as-is, never dropped', () => {
+    const orphan = {
+      id: 'p1',
+      type: 'tool',
+      toolCallId: '',
+      toolName: 'mystery',
+      state: 'approval-responded',
+      input: {},
+      approval: { id: 'unknown-approval', approved: true },
+    } as unknown as ToolCallPart
+
+    const out = coalesceParts([orphan])
+    expect(out).toEqual([orphan])
+  })
+})

package/src/agent/coalesce.ts

@@ -0,0 +1,118 @@
+/**
+ * coalesceParts — merges a rendered-turn's parts array for display.
+ *
+ * Merges consecutive `text`+`text` and `reasoning`+`reasoning` parts (streamed answers arrive as
+ * many small fragments; this renders a streaming reply as one flowing block instead of a stack of
+ * fragments). Merges `tool` parts BY `toolCallId` regardless of adjacency — the AI SDK re-emits a
+ * tool call's `input-available` then `output-available` as two separate parts, not necessarily
+ * adjacent once other parts interleave; without this rule a UI renders two stacked tool blocks for
+ * one call. The later state always wins; the merged part keeps the position of its FIRST
+ * occurrence (stable ordering); and an `input` (or `toolName`) supplied by an earlier state
+ * survives a later state that omits it — `tool-output-available` carries only `output` on the
+ * wire, the SDK re-supplies `input` by reading it back off the stored invocation, and a merge that
+ * replaces wholesale rather than accumulating would lose it outright.
+ *
+ * `approval`-bearing responses can arrive without a usable `toolCallId` (the SDK resolves them by
+ * reverse lookup on `approval.id` instead) — this maintains an `approvalId -> toolCallId` side
+ * index while folding and routes such a part through it. A part resolvable by neither key is kept
+ * as-is rather than dropped; never silently discard a part.
+ *
+ * @example
+ * import { coalesceParts } from 'basalt-ui/agent'
+ * <PartList parts={coalesceParts(parts)} />
+ */
+import type { AgentPart, ReasoningPart, TextPart, ToolCallPart } from './parts'
+
+type TextLike = TextPart | ReasoningPart
+
+function isTextLikeType(type: AgentPart['type']): type is TextLike['type'] {
+  return type === 'text' || type === 'reasoning'
+}
+
+/** Resolves a usable toolCallId for `part`, either off the part itself or (for an approval-bearing
+ * part missing one) via the approvalId -> toolCallId side index built while folding. */
+function resolveToolCallId(
+  part: ToolCallPart,
+  toolCallIdByApprovalId: Map<string, string>,
+): string | undefined {
+  if (typeof part.toolCallId === 'string' && part.toolCallId.length > 0) return part.toolCallId
+  const approval = 'approval' in part ? part.approval : undefined
+  return approval !== undefined ? toolCallIdByApprovalId.get(approval.id) : undefined
+}
+
+/** Registers this part's approval.id -> toolCallId mapping (when both are known) so a later
+ * approval-bearing part missing its own toolCallId can still resolve to the right tool call. */
+function registerApprovalIndex(
+  part: ToolCallPart,
+  toolCallIdByApprovalId: Map<string, string>,
+): void {
+  const approval = 'approval' in part ? part.approval : undefined
+  if (approval === undefined) return
+  if (typeof part.toolCallId !== 'string' || part.toolCallId.length === 0) return
+  toolCallIdByApprovalId.set(approval.id, part.toolCallId)
+}
+
+/** The later state always wins; `input`/`toolName` from the earlier state survive a later state
+ * that omits them. */
+function mergeToolPart(existing: ToolCallPart, next: ToolCallPart): ToolCallPart {
+  const existingInput = 'input' in existing ? existing.input : undefined
+  const nextInput = 'input' in next ? next.input : undefined
+  const input = nextInput !== undefined ? nextInput : existingInput
+  const toolName = next.toolName.length > 0 ? next.toolName : existing.toolName
+
+  return {
+    ...existing,
+    ...next,
+    toolName,
+    ...(input !== undefined ? { input } : {}),
+  } as ToolCallPart
+}
+
+export function coalesceParts<TPart extends AgentPart>(parts: readonly TPart[]): TPart[] {
+  const out: TPart[] = []
+  const toolIndexByCallId = new Map<string, number>()
+  const toolCallIdByApprovalId = new Map<string, string>()
+
+  for (const part of parts) {
+    if (isTextLikeType(part.type)) {
+      const last = out[out.length - 1]
+      if (last !== undefined && last.type === part.type) {
+        const merged = {
+          ...part,
+          text: (last as unknown as TextLike).text + (part as unknown as TextLike).text,
+        }
+        out[out.length - 1] = merged as TPart
+        continue
+      }
+      out.push(part)
+      continue
+    }
+
+    if (part.type === 'tool') {
+      const toolPart = part as unknown as ToolCallPart
+      registerApprovalIndex(toolPart, toolCallIdByApprovalId)
+      const resolvedCallId = resolveToolCallId(toolPart, toolCallIdByApprovalId)
+
+      if (resolvedCallId === undefined) {
+        // Unresolvable by either key — never silently discard.
+        out.push(part)
+        continue
+      }
+
+      const existingIndex = toolIndexByCallId.get(resolvedCallId)
+      if (existingIndex === undefined) {
+        toolIndexByCallId.set(resolvedCallId, out.length)
+        out.push(part)
+        continue
+      }
+
+      const existing = out[existingIndex] as unknown as ToolCallPart
+      out[existingIndex] = mergeToolPart(existing, toolPart) as unknown as TPart
+      continue
+    }
+
+    out.push(part)
+  }
+
+  return out
+}