basalt-ui 1.11.0 → 1.13.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'))
@@ -565,3 +592,67 @@ describe('aiSdkTransport — deterministic ids and replay idempotency', () => {
     )
   })
 })
+
+describe('aiSdkTransport — id minting under degraded crypto', () => {
+  test('the fixed chatId (mintThreadId, low collision cost) mints fine with no usable crypto at all — construction never throws', () => {
+    const originalCrypto = globalThis.crypto
+    Object.defineProperty(globalThis, 'crypto', { value: undefined, configurable: true })
+    try {
+      expect(() =>
+        aiSdkTransport({
+          api: '/api/chat',
+          fetch: mockFetch(() => {
+            throw new Error('must not be called')
+          }),
+        }),
+      ).not.toThrow()
+    } finally {
+      Object.defineProperty(globalThis, 'crypto', { value: originalCrypto, configurable: true })
+    }
+  })
+
+  test('the outbound user message id (mintMessageId, an idempotency key on the AI SDK backend) works via getRandomValues when randomUUID is unavailable', async () => {
+    const chunks: UIMessageChunk[] = [
+      { type: 'text-start', id: 't1' },
+      { type: 'text-end', id: 't1' },
+    ]
+    const transport = aiSdkTransport({
+      api: '/api/chat',
+      fetch: mockFetch(async () => scriptedResponse(chunks)),
+    })
+
+    const originalCrypto = globalThis.crypto
+    Object.defineProperty(globalThis, 'crypto', {
+      value: { getRandomValues: originalCrypto.getRandomValues.bind(originalCrypto) },
+      configurable: true,
+    })
+    try {
+      const parts = await collect(transport.stream('hi'))
+      expect(parts[0]?.type).toBe('start')
+    } finally {
+      Object.defineProperty(globalThis, 'crypto', { value: originalCrypto, configurable: true })
+    }
+  })
+
+  test('the outbound user message id THROWS on a host with no usable crypto at all, rather than silently colliding', async () => {
+    const transport = aiSdkTransport({
+      api: '/api/chat',
+      fetch: mockFetch(() => {
+        throw new Error('must not be called — must throw before any network call')
+      }),
+    })
+    const gen = transport.stream('hi')
+
+    // The synthesized StartPart is yielded first, before mintMessageId is ever reached.
+    const start = await gen.next()
+    expect(start.value).toMatchObject({ type: 'start' })
+
+    const originalCrypto = globalThis.crypto
+    Object.defineProperty(globalThis, 'crypto', { value: undefined, configurable: true })
+    try {
+      await expect(gen.next()).rejects.toThrow(/idempotency key/)
+    } finally {
+      Object.defineProperty(globalThis, 'crypto', { value: originalCrypto, configurable: true })
+    }
+  })
+})

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

@@ -48,6 +48,7 @@
  * })
  */
 import { assertNever } from '../register'
+import { mintMessageId, mintThreadId } from './id'
 import { TERMINAL_TOOL_STATES } from './parts'
 import type { AgentPart, AgentPartDraft } from './parts'
 import type { ResumableAgentTransport } from './transport'
@@ -401,7 +402,10 @@ export function aiSdkTransport<TPart = AgentPart>(
 
         const { httpTransport, readUIMessageStream: readStream } = await resolveAiSdk()
         const userMessage: UIMessage = {
-          id: crypto.randomUUID(),
+          // This id is what AI SDK's own backend persistence/dedup keys turns hang off — the same
+          // idempotency-key cost as basalt's own ChatMessage.id (see mintMessageId's doc), so
+          // mintMessageId, not mintThreadId, is the right helper here.
+          id: mintMessageId(),
           role: 'user',
           parts: [{ type: 'text', text: input }],
         }
@@ -425,7 +429,9 @@ export function aiSdkTransport<TPart = AgentPart>(
     }
   }
 
-  const fixedChatId = crypto.randomUUID()
+  // Client-side conversation namespace, not an idempotency key — a collision here would merge two
+  // conversations' index-addressed part ids, the same low collision cost `mintThreadId` covers.
+  const fixedChatId = mintThreadId()
   return {
     ...makeTransport(fixedChatId),
     forThread: (chatId: string) => makeTransport(chatId),

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)
+  })
 })