basalt-ui 1.10.0 → 1.12.0

package/src/agent/coalesce.test.ts

@@ -0,0 +1,387 @@
+/**
+ * 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' },
+    }
+    // `toolName` keeps its own empty-string convention for "omitted" (unlike toolCallId, whose
+    // absence is now modelled in the type) — the strict type still requires the field, hence the cast.
+    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')
+  })
+
+  // The SDK's raw approval-responded chunk arrives without its own toolCallId — one of the four
+  // SETTLED states whose id is optional in the type (parts.ts, MaybeIdentified), so every fixture
+  // below builds a legal wire shape directly, with no cast.
+
+  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' },
+    }
+    const approvalResponded: ToolCallPart = {
+      id: 'p2',
+      type: 'tool',
+      toolName: 'delete_file',
+      state: 'approval-responded',
+      input: { path: '/etc/passwd' },
+      approval: { id: 'appr-1', approved: true },
+    }
+
+    const out = coalesceParts([approvalRequested, approvalResponded])
+    expect(out).toHaveLength(1)
+    const merged = out[0] as ToolCallPart
+    expect(merged.state).toBe('approval-responded')
+    // The resolved call keeps the identity the request supplied — the response had none.
+    expect(merged.toolCallId).toBe('call-1')
+  })
+
+  test('a tool part unresolvable by either toolCallId or approvalId is kept as-is, never dropped', () => {
+    const orphan: ToolCallPart = {
+      id: 'p1',
+      type: 'tool',
+      toolName: 'mystery',
+      state: 'approval-responded',
+      input: {},
+      approval: { id: 'unknown-approval', approved: true },
+    }
+
+    const out = coalesceParts([orphan])
+    expect(out).toEqual([orphan])
+  })
+
+  test('an approval-responded seen BEFORE its request stays its own block — the fold never backtracks', () => {
+    // The approvalId side index only holds ids seen so far, so a response arriving first cannot
+    // resolve. Deliberate: reconciling backwards would let the request (the LATER arrival) win
+    // under "later state wins" and re-render an already-answered call as still pending.
+    const respondedFirst: ToolCallPart = {
+      id: 'p1',
+      type: 'tool',
+      toolName: 'delete_file',
+      state: 'approval-responded',
+      input: { path: '/etc/passwd' },
+      approval: { id: 'appr-1', approved: true },
+    }
+    const requestedLater: ToolCallPart = {
+      id: 'p2',
+      type: 'tool',
+      toolCallId: 'call-1',
+      toolName: 'delete_file',
+      state: 'approval-requested',
+      input: { path: '/etc/passwd' },
+      approval: { id: 'appr-1' },
+    }
+    const outputAvailable: ToolCallPart = {
+      id: 'p3',
+      type: 'tool',
+      toolCallId: 'call-1',
+      toolName: 'delete_file',
+      state: 'output-available',
+      input: { path: '/etc/passwd' },
+      output: { deleted: true },
+    }
+
+    const out = coalesceParts([respondedFirst, requestedLater, outputAvailable])
+    expect(out).toHaveLength(2)
+    // The orphan survives untouched at its original position — never dropped, never rewritten.
+    expect(out[0]).toEqual(respondedFirst)
+    // Everything from the request onward folds into ONE second block, not a third.
+    expect((out[1] as ToolCallPart).state).toBe('output-available')
+  })
+
+  test('a failed call keeps NO stale output from the preliminary result it replaces', () => {
+    // The defect a blind `{ ...existing, ...next }` spread produced: output-error has no `output`
+    // key, so a spread let the preliminary result's `output`/`preliminary` ride along and any
+    // consumer branching on `output` before `errorText` rendered a failed call as successful.
+    const preliminaryResult: ToolCallPart = {
+      id: 'p1',
+      type: 'tool',
+      toolCallId: 'call-1',
+      toolName: 'search',
+      state: 'output-available',
+      input: { q: 'x' },
+      output: { hits: 1, partial: true },
+      preliminary: true,
+    }
+    const failed: ToolCallPart = {
+      id: 'p2',
+      type: 'tool',
+      toolCallId: 'call-1',
+      toolName: 'search',
+      state: 'output-error',
+      errorText: 'upstream timed out',
+      durationMs: 900,
+    }
+
+    const out = coalesceParts([preliminaryResult, failed])
+    expect(out).toHaveLength(1)
+    const merged = out[0] as ToolCallPart
+    expect(merged.state).toBe('output-error')
+    expect(Object.hasOwn(merged, 'output')).toBe(false)
+    expect(Object.hasOwn(merged, 'preliminary')).toBe(false)
+    expect(merged).toEqual({
+      id: 'p2',
+      type: 'tool',
+      toolCallId: 'call-1',
+      toolName: 'search',
+      durationMs: 900,
+      state: 'output-error',
+      errorText: 'upstream timed out',
+      // input is the one thing legitimately carried across the transition.
+      input: { q: 'x' },
+    })
+  })
+
+  test('a SETTLED part that arrived unidentified keeps the identity an earlier state supplied', () => {
+    // `toolCallId` is optional on the four settled states (parts.ts, MaybeIdentified). A terminal
+    // part that resolved only through the approvalId side index must come out of the merge WITH the
+    // id the request carried — losing it here would unfold the block on the next pass.
+    const approvalRequested: ToolCallPart = {
+      id: 'p1',
+      type: 'tool',
+      toolCallId: 'call-1',
+      toolName: 'transfer_funds',
+      state: 'approval-requested',
+      input: { amount: 250 },
+      approval: { id: 'appr-1' },
+    }
+    const unidentifiedResult: ToolCallPart = {
+      id: 'p2',
+      type: 'tool',
+      toolName: 'transfer_funds',
+      state: 'output-available',
+      input: { amount: 250 },
+      output: { ok: true },
+      approval: { id: 'appr-1', approved: true },
+    }
+
+    const out = coalesceParts([approvalRequested, unidentifiedResult])
+    expect(out).toHaveLength(1)
+    const merged = out[0] as ToolCallPart
+    expect(merged.state).toBe('output-available')
+    expect(merged.toolCallId).toBe('call-1')
+  })
+
+  // ── never throws ───────────────────────────────────────────────────────────
+  // The tool-state switch is exhaustive at COMPILE time only. coalesceParts is public, runs on the
+  // render path, and folds wire data — an unrecognized state must degrade, not abort the render.
+
+  test('an unrecognized tool state does not throw and yields a sensible merged part', () => {
+    const inputAvailable: ToolCallPart = {
+      id: 'p1',
+      type: 'tool',
+      toolCallId: 'call-1',
+      toolName: 'search',
+      state: 'input-available',
+      input: { q: 'x' },
+    }
+    // A state no version of the union declares — what a newer server would send to an older client.
+    const futureState = {
+      id: 'p2',
+      type: 'tool',
+      toolCallId: 'call-1',
+      toolName: '',
+      state: 'output-streaming',
+      output: { partial: true },
+    } as unknown as ToolCallPart
+
+    const warnings: string[] = []
+    const original = console.warn
+    console.warn = (...args: unknown[]) => void warnings.push(String(args[0]))
+    let out: ToolCallPart[]
+    try {
+      out = coalesceParts([inputAvailable, futureState]) as ToolCallPart[]
+    } finally {
+      console.warn = original
+    }
+
+    expect(out).toHaveLength(1)
+    // `state` widened to `string` — the whole point of this test is a state value the
+    // `ToolCallState` union does NOT declare (a future server sending an unknown state to an
+    // older client), so the real, narrower type would reject the very literal being asserted.
+    const merged = out[0] as Omit<ToolCallPart, 'state'> & { output?: unknown; state: string }
+    // The incoming part survives intact…
+    expect(merged.state).toBe('output-streaming')
+    expect(merged.output).toEqual({ partial: true })
+    // …with the whitelisted carry-over fields folded in, exactly as a known state would get.
+    expect(merged.toolName).toBe('search')
+    expect(merged.toolCallId).toBe('call-1')
+    // …and the anomaly is announced in dev rather than thrown.
+    expect(warnings).toHaveLength(1)
+    expect(warnings[0]).toContain('unrecognized tool state')
+  })
+
+  test('an approval-requested that later succeeds does not carry its pending approval onto the result', () => {
+    const approvalRequested: ToolCallPart = {
+      id: 'p1',
+      type: 'tool',
+      toolCallId: 'call-1',
+      toolName: 'transfer_funds',
+      state: 'approval-requested',
+      input: { amount: 250 },
+      approval: { id: 'appr-1' },
+    }
+    const outputAvailable: ToolCallPart = {
+      id: 'p2',
+      type: 'tool',
+      toolCallId: 'call-1',
+      toolName: 'transfer_funds',
+      state: 'output-available',
+      input: { amount: 250 },
+      output: { ok: true },
+    }
+
+    const out = coalesceParts([approvalRequested, outputAvailable])
+    expect(out).toHaveLength(1)
+    // `approval` comes from `next` alone: a pending request envelope (no verdict) must not surface
+    // on a settled result, where the type only admits `{ approved?: true }`.
+    expect(Object.hasOwn(out[0] as object, 'approval')).toBe(false)
+  })
+})

package/src/agent/coalesce.ts

@@ -0,0 +1,229 @@
+/**
+ * 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.
+ *
+ * A settled tool part can arrive without a `toolCallId` at all — `approval-responded` plus the
+ * three terminal states all carry it as optional (see `MaybeIdentified` in `parts.ts`).
+ * `approval-responded` is where the WIRE itself omits it: the SDK's `tool-approval-response` chunk
+ * carries no `toolCallId`, only `approval.id`, so it is resolved 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.
+ *
+ * The fold is strictly LEFT-TO-RIGHT with no backtracking: the side index only holds ids seen so
+ * far, so an unidentified `approval-responded` arriving BEFORE its `approval-requested` stays its
+ * own block and the later request opens a second one. That is deliberate, not an oversight —
+ * reconciling backwards would let the request (the later arrival) win under the "later state wins"
+ * rule and render an already-answered call as still pending, which is worse than two blocks in an
+ * ordering the wire never produces.
+ *
+ * **This function never throws.** It is public, it runs on the render path, and it folds data that
+ * came off a wire — so every anomaly (an unrecognized tool state, an unresolvable id) degrades to
+ * "keep the part as it arrived", announced in dev, rather than aborting the render. A throw here
+ * would turn one malformed chunk into a permanently dead transcript. Exhaustiveness over the tool
+ * states is still enforced, but at COMPILE time only (see `mergeToolPart`'s default branch).
+ *
+ * @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 (part.toolCallId !== undefined) 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 (part.toolCallId === undefined) return
+  toolCallIdByApprovalId.set(approval.id, part.toolCallId)
+}
+
+/**
+ * The later state always wins; `toolCallId`/`toolName`/`durationMs`/`providerExecuted` and `input`
+ * from the earlier state survive a later state that omits them.
+ *
+ * The result is RECONSTRUCTED per `next.state`, building only the fields that state legally has —
+ * never a blind `{ ...existing, ...next }` spread. A spread lets any field the next state does not
+ * redeclare survive onto it: an `output-available` (with `output`, possibly `preliminary`) that
+ * fails to `output-error` (which has no `output` key) would keep a stale `output` alongside
+ * `errorText`, and a consumer branching on `output` before `errorText` renders a failed call as
+ * successful. Only the fields listed above are carried; `output`, `errorText`, `rawInput`,
+ * `preliminary` and `approval` come from `next` alone, so nothing from a prior state can leak into
+ * a member that has no room for it. Reconstruction is exact enough that tsc proves each returned
+ * member valid — there is deliberately no cast here.
+ */
+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 durationMs = next.durationMs ?? existing.durationMs
+  const providerExecuted = next.providerExecuted ?? existing.providerExecuted
+  // `toolCallId` is optional on the four settled states (see `MaybeIdentified` in parts.ts), so a
+  // later part that arrived unidentified — resolved here through the approvalId side index — keeps
+  // the identity an earlier state supplied instead of losing it on the way through the merge.
+  const settledToolCallId = next.toolCallId ?? existing.toolCallId
+
+  const common = {
+    id: next.id,
+    type: 'tool' as const,
+    toolName: next.toolName.length > 0 ? next.toolName : existing.toolName,
+    ...(durationMs !== undefined ? { durationMs } : {}),
+    ...(providerExecuted !== undefined ? { providerExecuted } : {}),
+  }
+
+  switch (next.state) {
+    case 'input-streaming':
+      return {
+        ...common,
+        toolCallId: next.toolCallId,
+        state: 'input-streaming',
+        ...(input !== undefined ? { input } : {}),
+      }
+    case 'input-available':
+      return { ...common, toolCallId: next.toolCallId, state: 'input-available', input }
+    case 'approval-requested':
+      return {
+        ...common,
+        toolCallId: next.toolCallId,
+        state: 'approval-requested',
+        input,
+        approval: next.approval,
+      }
+    case 'approval-responded':
+      return {
+        ...common,
+        ...(settledToolCallId !== undefined ? { toolCallId: settledToolCallId } : {}),
+        state: 'approval-responded',
+        input,
+        approval: next.approval,
+      }
+    case 'output-available':
+      return {
+        ...common,
+        ...(settledToolCallId !== undefined ? { toolCallId: settledToolCallId } : {}),
+        state: 'output-available',
+        input,
+        output: next.output,
+        ...(next.preliminary !== undefined ? { preliminary: next.preliminary } : {}),
+        ...(next.approval !== undefined ? { approval: next.approval } : {}),
+      }
+    case 'output-error':
+      return {
+        ...common,
+        ...(settledToolCallId !== undefined ? { toolCallId: settledToolCallId } : {}),
+        state: 'output-error',
+        errorText: next.errorText,
+        ...(input !== undefined ? { input } : {}),
+        ...(next.rawInput !== undefined ? { rawInput: next.rawInput } : {}),
+        ...(next.approval !== undefined ? { approval: next.approval } : {}),
+      }
+    case 'output-denied':
+      return {
+        ...common,
+        ...(settledToolCallId !== undefined ? { toolCallId: settledToolCallId } : {}),
+        state: 'output-denied',
+        input,
+        approval: next.approval,
+      }
+    default: {
+      // Exhaustive at COMPILE time, defensive at RUNTIME. Binding `next` at `never` keeps tsc's
+      // guarantee — add a state to `ToolCallPart` without a case above and this line stops
+      // compiling — but this branch must NOT throw. `coalesceParts` is public, runs on the render
+      // path, and folds wire data: a throw would turn one transient wire anomaly into a
+      // permanently dead transcript (the same trade `spliceText` makes in merge.ts, where an
+      // out-of-range offset is clamped rather than thrown on). An unrecognized state therefore
+      // falls back to the incoming part with only the whitelisted carry-over fields folded in —
+      // nothing state-specific from `existing` can leak, because `common` is all that is merged.
+      const unhandled: never = next
+      // Widened back deliberately: control-flow analysis would keep an annotated const at `never`
+      // and make every field read below a compile error, so the assertion is what makes the
+      // runtime value usable. It asserts nothing tsc has not already proved on the line above.
+      const fallback = unhandled as ToolCallPart
+      if (process.env['NODE_ENV'] !== 'production') {
+        console.warn(
+          `[basalt] coalesceParts: unrecognized tool state ${JSON.stringify(fallback.state)} — kept, merged best-effort`,
+        )
+      }
+      return { ...fallback, ...common }
+    }
+  }
+}
+
+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
+}

package/src/agent/foreign.test.ts

@@ -0,0 +1,51 @@
+/**
+ * foreign.ts — runtime coverage for `narrowAgentPart` (the cheap discriminator, distinct from the
+ * validating `parseAgentPart`) and `definePartRenderers` (identity passthrough, the canonical
+ * const-generic factory contract). Compile-time coverage for the `PartRenderers`/`ConsumerPart`
+ * exhaustiveness contract lives in the playground fixture
+ * (`apps/playground/src/demo/agent-part-registry.type-guard.ts`), not here.
+ */
+import { describe, expect, test } from 'bun:test'
+import { definePartRenderers, narrowAgentPart } from './foreign'
+import type { TranscriptPart } from './foreign'
+import type { AgentPart } from './parts'
+
+describe('narrowAgentPart', () => {
+  // Typed AgentPart[], not TranscriptPart[]: every literal here IS a built-in variant (the whole
+  // point of this fixture), and narrowAgentPart's return type is AgentPart | null — comparing it
+  // against a TranscriptPart-typed element (which also admits ForeignPart) doesn't type-check.
+  const BUILT_IN_SAMPLES: AgentPart[] = [
+    { id: 'p1', type: 'start', runId: 'r1' },
+    { id: 'p2', type: 'text', text: 'hi' },
+    { id: 'p3', type: 'reasoning', text: 'thinking' },
+    {
+      id: 'p4',
+      type: 'tool',
+      toolCallId: 'c1',
+      toolName: 'search',
+      state: 'input-available',
+      input: {},
+    },
+    { id: 'p5', type: 'source', url: 'https://example.com' },
+    { id: 'p6', type: 'error', message: 'boom' },
+  ]
+
+  for (const part of BUILT_IN_SAMPLES) {
+    test(`narrows a built-in '${part.type}' part`, () => {
+      expect(narrowAgentPart(part)).toBe(part)
+    })
+  }
+
+  test('returns null for a foreign part type', () => {
+    const foreign: TranscriptPart = { id: 'p7', type: 'data-chart', spec: {} }
+    expect(narrowAgentPart(foreign)).toBeNull()
+  })
+})
+
+describe('definePartRenderers', () => {
+  test('identity passthrough — returns the exact map it was given', () => {
+    const renderChart = (): null => null
+    const map = { 'data-chart': renderChart }
+    expect(definePartRenderers(map)).toBe(map)
+  })
+})