basalt-ui 1.11.0 → 1.12.0

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

@@ -23,7 +23,7 @@ import { aiSdkTransport } from './ai-sdk-transport'
 import { withPartIds } from './id'
 import { mergePart } from './merge'
 import type { UIMessageChunk } from 'ai'
-import type { AgentPart } from './parts'
+import type { AgentPart, ToolCallPart } from './parts'
 
 /**
  * Builds a fetch-compatible Response whose body is the given low-level UIMessageChunks, SSE-
@@ -43,6 +43,16 @@ function scriptedResponse(chunks: UIMessageChunk[]): Response {
   return new Response(body, { status: 200, headers: { 'content-type': 'text/event-stream' } })
 }
 
+/**
+ * Casts a scripted fetch stub into `aiSdkTransport`'s `fetch: typeof globalThis.fetch` option.
+ * The DOM lib's `typeof fetch` type also demands a static `preconnect` method (a real
+ * browser/undici API these scripted mocks never call and don't need to implement) — the cast
+ * documents that the only structural gap is that one, unused static member.
+ */
+function mockFetch(impl: () => Promise<Response>): typeof fetch {
+  return impl as unknown as typeof fetch
+}
+
 /** Drains an aiSdkTransport `.stream()`/`.resume()` async generator into a plain array. */
 async function collect(gen: AsyncGenerator<AgentPart>): Promise<AgentPart[]> {
   const parts: AgentPart[] = []
@@ -50,11 +60,24 @@ async function collect(gen: AsyncGenerator<AgentPart>): Promise<AgentPart[]> {
   return parts
 }
 
+/**
+ * `Omit<T, K>` does not distribute over a union — `keyof T` on a union collapses to only the
+ * KEYS COMMON to every member, so `Omit<ToolCallPart, 'durationMs'>` would silently drop each
+ * state's own fields (`input`, `output`, …) rather than just `durationMs`. This variant forces
+ * distribution via a naked conditional type parameter.
+ */
+type DistributiveOmit<T, K extends PropertyKey> = T extends unknown ? Omit<T, K> : never
+
 /** Strips a non-deterministic `durationMs` (wall-clock, so never equality-comparable) before an
- * exact `toEqual`, and separately asserts its type. */
-function withoutDurationMs<T extends { durationMs?: number }>(part: T): Omit<T, 'durationMs'> {
+ * exact `toEqual`, and separately asserts its type. Constrained to `Record<string, unknown>`
+ * rather than `{ durationMs?: number }` because ErrorPart (uniquely among AgentPart variants)
+ * carries no `durationMs` field at all — that stricter constraint trips TS's weak-type check
+ * ("no properties in common") the moment this is called with the full AgentPart union. */
+function withoutDurationMs<T extends Record<string, unknown>>(
+  part: T,
+): DistributiveOmit<T, 'durationMs'> {
   const { durationMs: _durationMs, ...rest } = part
-  return rest
+  return rest as DistributiveOmit<T, 'durationMs'>
 }
 
 describe('aiSdkTransport — snapshot→delta diffing', () => {
@@ -67,7 +90,7 @@ describe('aiSdkTransport — snapshot→delta diffing', () => {
     ]
     const transport = aiSdkTransport({
       api: '/api/chat',
-      fetch: async () => scriptedResponse(chunks),
+      fetch: mockFetch(async () => scriptedResponse(chunks)),
     })
     const parts = await collect(transport.stream('hi'))
 
@@ -107,7 +130,7 @@ describe('aiSdkTransport — snapshot→delta diffing', () => {
     // trivially fail to match on that alone, masking whether withPartIds itself changed anything.
     const transport = aiSdkTransport({
       api: '/api/chat',
-      fetch: async () => scriptedResponse(chunks),
+      fetch: mockFetch(async () => scriptedResponse(chunks)),
     })
     const direct = await collect(transport.stream('hi'))
     const wrapped = await collect(withPartIds('unrelated-run-id', transport.stream('hi')))
@@ -126,7 +149,7 @@ describe('aiSdkTransport — snapshot→delta diffing', () => {
     ]
     const transport = aiSdkTransport({
       api: '/api/chat',
-      fetch: async () => scriptedResponse(chunks),
+      fetch: mockFetch(async () => scriptedResponse(chunks)),
     })
     const parts = await collect(transport.stream('hi'))
 
@@ -146,7 +169,7 @@ describe('aiSdkTransport — snapshot→delta diffing', () => {
     ]
     const transport = aiSdkTransport({
       api: '/api/chat',
-      fetch: async () => scriptedResponse(chunks),
+      fetch: mockFetch(async () => scriptedResponse(chunks)),
     })
     const parts = await collect(transport.stream('hi'))
 
@@ -168,13 +191,16 @@ describe('aiSdkTransport — snapshot→delta diffing', () => {
     ]
     const transport = aiSdkTransport({
       api: '/api/chat',
-      fetch: async () => scriptedResponse(chunks),
+      fetch: mockFetch(async () => scriptedResponse(chunks)),
     })
     const parts = await collect(transport.stream('hi'))
 
     const toolParts = parts.filter((p) => p.type === 'tool')
     expect(toolParts.every((p) => (p as { id: string }).id === 'tool#call-1')).toBe(true)
-    expect(toolParts.map(withoutDurationMs)).toEqual([
+    // Annotated so each element is checked individually against the ToolCallPart union — passed
+    // inline, TS collapses the array's contextual element type and rejects the settled states'
+    // extra `input`/`output` fields against the first (narrowest) member it picks.
+    const expectedToolParts: DistributiveOmit<ToolCallPart, 'durationMs'>[] = [
       {
         id: 'tool#call-1',
         type: 'tool',
@@ -199,7 +225,8 @@ describe('aiSdkTransport — snapshot→delta diffing', () => {
         input: { q: 'x' },
         output: { hits: 3 },
       },
-    ])
+    ]
+    expect(toolParts.map(withoutDurationMs)).toEqual(expectedToolParts)
     // durationMs is only set once the call reaches a terminal state (output-available here).
     expect((toolParts[0] as { durationMs?: number }).durationMs).toBeUndefined()
     expect(typeof (toolParts.at(-1) as { durationMs?: number }).durationMs).toBe('number')
@@ -215,7 +242,7 @@ describe('aiSdkTransport — snapshot→delta diffing', () => {
     ]
     const transport = aiSdkTransport({
       api: '/api/chat',
-      fetch: async () => scriptedResponse(chunks),
+      fetch: mockFetch(async () => scriptedResponse(chunks)),
     })
     const parts = await collect(transport.stream('hi'))
 
@@ -245,7 +272,7 @@ describe('aiSdkTransport — snapshot→delta diffing', () => {
     ]
     const transport = aiSdkTransport({
       api: '/api/chat',
-      fetch: async () => scriptedResponse(chunks),
+      fetch: mockFetch(async () => scriptedResponse(chunks)),
     })
     const parts = await collect(transport.stream('hi'))
 
@@ -282,7 +309,7 @@ describe('aiSdkTransport — snapshot→delta diffing', () => {
     ]
     const transport = aiSdkTransport({
       api: '/api/chat',
-      fetch: async () => scriptedResponse(chunks),
+      fetch: mockFetch(async () => scriptedResponse(chunks)),
     })
     const parts = await collect(transport.stream('hi'))
 
@@ -330,7 +357,7 @@ describe('aiSdkTransport — snapshot→delta diffing', () => {
     ]
     const transport = aiSdkTransport({
       api: '/api/chat',
-      fetch: async () => scriptedResponse(chunks),
+      fetch: mockFetch(async () => scriptedResponse(chunks)),
     })
     const parts = await collect(transport.stream('hi'))
 
@@ -362,7 +389,7 @@ describe('aiSdkTransport — snapshot→delta diffing', () => {
     ]
     const transport = aiSdkTransport({
       api: '/api/chat',
-      fetch: async () => scriptedResponse(chunks),
+      fetch: mockFetch(async () => scriptedResponse(chunks)),
     })
     const parts = await collect(transport.stream('hi'))
 
@@ -394,7 +421,7 @@ describe('aiSdkTransport — snapshot→delta diffing', () => {
     ]
     const transport = aiSdkTransport({
       api: '/api/chat',
-      fetch: async () => scriptedResponse(chunks),
+      fetch: mockFetch(async () => scriptedResponse(chunks)),
     })
     const parts = await collect(transport.stream('hi'))
 
@@ -415,7 +442,7 @@ describe('aiSdkTransport — signal.aborted stops the yield', () => {
     ]
     const transport = aiSdkTransport({
       api: '/api/chat',
-      fetch: async () => scriptedResponse(chunks),
+      fetch: mockFetch(async () => scriptedResponse(chunks)),
     })
     const controller = new AbortController()
     const gen = transport.stream('hi', controller.signal)
@@ -446,9 +473,9 @@ describe('aiSdkTransport — deterministic chat-id binding', () => {
     // generator that never advances past its first `.next()` never touches the network.
     const transport = aiSdkTransport({
       api: '/api/chat',
-      fetch: () => {
+      fetch: mockFetch(() => {
         throw new Error('must not be called — only the first, pre-network yield is read')
-      },
+      }),
     })
 
     const first = await transport.stream('a').next()
@@ -460,9 +487,9 @@ describe('aiSdkTransport — deterministic chat-id binding', () => {
   test('.forThread(id) binds the StartPart runId/resumeToken/id deterministically to the given id', async () => {
     const transport = aiSdkTransport({
       api: '/api/chat',
-      fetch: () => {
+      fetch: mockFetch(() => {
         throw new Error('must not be called — only the first, pre-network yield is read')
-      },
+      }),
     })
     const bound = transport.forThread('caller-supplied-thread-id')
 
@@ -482,9 +509,9 @@ describe('aiSdkTransport — deterministic chat-id binding', () => {
   test('two different .forThread() ids produce two different StartPart runIds/ids', async () => {
     const transport = aiSdkTransport({
       api: '/api/chat',
-      fetch: () => {
+      fetch: mockFetch(() => {
         throw new Error('must not be called — only the first, pre-network yield is read')
-      },
+      }),
     })
 
     const a = await transport.forThread('thread-a').stream('hi').next()
@@ -516,7 +543,7 @@ describe('aiSdkTransport — deterministic ids and replay idempotency', () => {
     ]
     const transport = aiSdkTransport({
       api: '/api/chat',
-      fetch: async () => scriptedResponse(chunks),
+      fetch: mockFetch(async () => scriptedResponse(chunks)),
     }).forThread('thread-x')
 
     const firstIds = (await collect(transport.stream('hi'))).map((p) => (p as { id: string }).id)
@@ -535,7 +562,7 @@ describe('aiSdkTransport — deterministic ids and replay idempotency', () => {
     ]
     const transport = aiSdkTransport({
       api: '/api/chat',
-      fetch: async () => scriptedResponse(chunks),
+      fetch: mockFetch(async () => scriptedResponse(chunks)),
     }).forThread('thread-x')
 
     const firstPass = await collect(transport.stream('hi'))

package/src/agent/coalesce.test.ts

@@ -136,6 +136,8 @@ describe('coalesceParts', () => {
       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',
@@ -150,6 +152,10 @@ describe('coalesceParts', () => {
     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',
@@ -160,35 +166,222 @@ describe('coalesceParts', () => {
       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 = {
+    const approvalResponded: ToolCallPart = {
       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')
+    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 = {
+    const orphan: ToolCallPart = {
       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])
   })
+
+  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

@@ -12,10 +12,26 @@
  * 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.
+ * 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'
@@ -35,7 +51,7 @@ function resolveToolCallId(
   part: ToolCallPart,
   toolCallIdByApprovalId: Map<string, string>,
 ): string | undefined {
-  if (typeof part.toolCallId === 'string' && part.toolCallId.length > 0) return part.toolCallId
+  if (part.toolCallId !== undefined) return part.toolCallId
   const approval = 'approval' in part ? part.approval : undefined
   return approval !== undefined ? toolCallIdByApprovalId.get(approval.id) : undefined
 }
@@ -48,24 +64,119 @@ function registerApprovalIndex(
 ): void {
   const approval = 'approval' in part ? part.approval : undefined
   if (approval === undefined) return
-  if (typeof part.toolCallId !== 'string' || part.toolCallId.length === 0) return
+  if (part.toolCallId === undefined) 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. */
+/**
+ * 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 toolName = next.toolName.length > 0 ? next.toolName : existing.toolName
+  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 } : {}),
+  }
 
-  return {
-    ...existing,
-    ...next,
-    toolName,
-    ...(input !== undefined ? { input } : {}),
-  } as ToolCallPart
+  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[] {

package/src/agent/foreign.test.ts

@@ -8,9 +8,13 @@
 import { describe, expect, test } from 'bun:test'
 import { definePartRenderers, narrowAgentPart } from './foreign'
 import type { TranscriptPart } from './foreign'
+import type { AgentPart } from './parts'
 
 describe('narrowAgentPart', () => {
-  const BUILT_IN_SAMPLES: TranscriptPart[] = [
+  // 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' },