basalt-ui 1.9.0 → 1.11.0

package/src/agent/transport.ts

@@ -29,7 +29,7 @@
  *   api.chat.post({ body: { message: input }, fetch: { signal } }),
  * )
  */
-import type { AgentPart } from './parts'
+import type { AgentPart, AgentPartDraft } from './parts'
 
 // ── AgentTransport ────────────────────────────────────────────────────────────
 
@@ -37,6 +37,11 @@ import type { AgentPart } from './parts'
  * The injected transport seam. `stream(input, signal)` returns an async generator of parts.
  * Implement this interface for any backend — Eden, fetch-based SSE, AI SDK, or a mock.
  *
+ * The default `TPart` is `AgentPartDraft` (not `AgentPart`): transports yield DRAFTS — `id`
+ * optional — and the consuming hooks (or `withPartIds`) normalize a draft into a fully-identified
+ * part before it is ever accumulated. Pass an explicit `AgentPart` generic when a transport mints
+ * its own ids directly (as `aiSdkTransport` does).
+ *
  * @example
  * // Minimal mock transport for tests / playground:
  * const mockTransport: AgentTransport = {
@@ -45,12 +50,48 @@ import type { AgentPart } from './parts'
  *   },
  * }
  */
-export type AgentTransport<TPart = AgentPart, TInput = string> = {
+export type AgentTransport<TPart = AgentPartDraft, TInput = string> = {
   stream: (input: TInput, signal?: AbortSignal) => AsyncGenerator<TPart>
   /** Optional: resume a previously-started run from its resumeToken (see StartPart). Transports that don't support resumption simply omit this. */
   resume?: (resumeToken: string, signal?: AbortSignal) => AsyncGenerator<TPart>
 }
 
+// ── ResumableAgentTransport ───────────────────────────────────────────────────
+
+/**
+ * A transport whose replay is safe to run over an already-rendered turn. Implementing `resume`
+ * alone is no longer enough: `idempotentReplay: true` is a literal-typed assertion that every
+ * text/reasoning part this transport emits carries an authoritative `offset`, so mergePart
+ * rewrites instead of appending.
+ */
+export type ResumableAgentTransport<TPart = AgentPartDraft, TInput = string> = AgentTransport<
+  TPart,
+  TInput
+> & {
+  readonly resume: (resumeToken: string, signal?: AbortSignal) => AsyncGenerator<TPart>
+  readonly idempotentReplay: true
+}
+
+/**
+ * Type guard: true when `t` both implements `resume` AND has explicitly asserted
+ * `idempotentReplay: true`. A transport with `resume` but no `idempotentReplay` is NOT resumable
+ * — the mount-time reconcile in `useAgentThreadRuns` falls back to `'interrupted'` for it rather
+ * than risk duplicating already-rendered content.
+ *
+ * @example
+ * if (isResumable(transport)) {
+ *   for await (const part of transport.resume(resumeToken)) { ... }
+ * }
+ */
+export function isResumable<TPart, TInput>(
+  t: AgentTransport<TPart, TInput>,
+): t is ResumableAgentTransport<TPart, TInput> {
+  return (
+    typeof t.resume === 'function' &&
+    (t as Partial<ResumableAgentTransport<TPart, TInput>>).idempotentReplay === true
+  )
+}
+
 // ── edenTransport ─────────────────────────────────────────────────────────────
 
 /**
@@ -70,6 +111,12 @@ export type AgentTransport<TPart = AgentPart, TInput = string> = {
  * object has NO `resume` key at all (not `resume: undefined`) — consumers that don't wire a
  * resumable backend get a transport that behaves exactly as before.
  *
+ * `resumeCall` alone does NOT make the transport resumable per `isResumable` — pass
+ * `{ idempotentReplay: true }` as the third argument to opt in EXPLICITLY once the server-side
+ * `resumeCall` route is verified to re-emit every text/reasoning delta with an authoritative
+ * `offset` (never a bare append). This is an opt-in, not an inference: a `resumeCall` whose deltas
+ * aren't offset-accurate would double-render on replay if treated as resumable.
+ *
  * @example
  * import { edenTransport, type AgentPart } from 'basalt-ui/agent'
  *
@@ -78,6 +125,7 @@ export type AgentTransport<TPart = AgentPart, TInput = string> = {
  * const transport = edenTransport<AgentPart>(
  *   (input, signal) => api.chat.post({ body: { message: input }, fetch: { signal } }),
  *   (resumeToken, signal) => api.chat.resume.post({ body: { resumeToken }, fetch: { signal } }),
+ *   { idempotentReplay: true },
  * )
  *
  * // Wire into useAgentStream:
@@ -92,23 +140,27 @@ export function edenTransport<TPart = AgentPart, TInput = string>(
     resumeToken: string,
     signal?: AbortSignal,
   ) => Promise<{ data: AsyncGenerator<TPart> | null; error: unknown }>,
-): AgentTransport<TPart, TInput> {
-  return {
-    async *stream(input: TInput, signal?: AbortSignal): AsyncGenerator<TPart> {
-      const { data, error } = await call(input, signal)
-      if (error) throw error
-      if (data === null) return
-      yield* data
-    },
-    ...(resumeCall !== undefined
-      ? {
-          async *resume(resumeToken: string, signal?: AbortSignal): AsyncGenerator<TPart> {
-            const { data, error } = await resumeCall(resumeToken, signal)
-            if (error) throw error
-            if (data === null) return
-            yield* data
-          },
-        }
-      : {}),
+  options?: { readonly idempotentReplay?: true },
+): AgentTransport<TPart, TInput> | ResumableAgentTransport<TPart, TInput> {
+  const stream = async function* (input: TInput, signal?: AbortSignal): AsyncGenerator<TPart> {
+    const { data, error } = await call(input, signal)
+    if (error) throw error
+    if (data === null) return
+    yield* data
+  }
+
+  if (resumeCall === undefined) return { stream }
+
+  const resume = async function* (
+    resumeToken: string,
+    signal?: AbortSignal,
+  ): AsyncGenerator<TPart> {
+    const { data, error } = await resumeCall(resumeToken, signal)
+    if (error) throw error
+    if (data === null) return
+    yield* data
   }
+
+  if (options?.idempotentReplay !== true) return { stream, resume }
+  return { stream, resume, idempotentReplay: true }
 }

package/src/agent/use-agent-stream.test.tsx

@@ -0,0 +1,261 @@
+/**
+ * useAgentStream — single in-flight-turn lifecycle: abort, supersede, error, AbortError handling,
+ * unmount cleanup, and StrictMode double-invoke of a "send on mount" consumer effect.
+ *
+ * Scope: the API AS IT EXISTS TODAY (B1) — no stop-preserves-the-partial-turn semantics, no
+ * `ChatMessage.finish`; those are later-release surface (see the sibling `use-agent-thread-runs.*`
+ * test files' scope note).
+ */
+import { describe, expect, test } from 'bun:test'
+import { StrictMode, useEffect } from 'react'
+import { act, render, renderHook, waitFor } from '@testing-library/react'
+import { useAgentStream } from './use-agent-stream'
+import type { AgentTransport } from './transport'
+import type { AgentPart } from './parts'
+
+function deferred<T>(): { promise: Promise<T>; resolve: (value: T) => void } {
+  let resolve!: (value: T) => void
+  const promise = new Promise<T>((r) => {
+    resolve = r
+  })
+  return { promise, resolve }
+}
+
+describe('useAgentStream', () => {
+  test('stop() mid-stream sets status "done" and discards any parts that arrive after the abort', async () => {
+    const gate = deferred<void>()
+    const transport: AgentTransport<AgentPart, string> = {
+      async *stream() {
+        yield { id: 'p1', type: 'text', text: 'a' }
+        await gate.promise
+        // Must never be observed — the consumer's guard should discard this once aborted.
+        yield { id: 'p2', type: 'text', text: 'b' }
+      },
+    }
+
+    const { result } = renderHook(() => useAgentStream({ transport }))
+
+    act(() => {
+      void result.current.send('hi')
+    })
+    await waitFor(() => {
+      expect(result.current.parts).toEqual([{ id: 'p1', type: 'text', text: 'a' }])
+    })
+    expect(result.current.status).toBe('streaming')
+
+    act(() => {
+      result.current.stop()
+    })
+    // stop() sets 'done' synchronously — never 'error', even for an in-flight stream.
+    expect(result.current.status).toBe('done')
+
+    gate.resolve(undefined)
+    await waitFor(() => {
+      expect(result.current.status).toBe('done')
+    })
+    expect(result.current.parts).toEqual([{ id: 'p1', type: 'text', text: 'a' }])
+  })
+
+  test("a second send() supersedes an in-flight one — the first stream's later parts are discarded", async () => {
+    const gateFirst = deferred<void>()
+    const transport: AgentTransport<AgentPart, string> = {
+      async *stream(input) {
+        if (input === 'first') {
+          yield { id: 'f1', type: 'text', text: 'first-1' }
+          await gateFirst.promise
+          // Must never be observed — 'second' has already superseded this controller.
+          yield { id: 'f2', type: 'text', text: 'first-2' }
+        } else {
+          yield { id: 's1', type: 'text', text: 'second-1' }
+        }
+      },
+    }
+
+    const { result } = renderHook(() => useAgentStream({ transport }))
+
+    act(() => {
+      void result.current.send('first')
+    })
+    await waitFor(() => {
+      expect(result.current.parts).toEqual([{ id: 'f1', type: 'text', text: 'first-1' }])
+    })
+
+    act(() => {
+      void result.current.send('second')
+    })
+    await waitFor(() => {
+      expect(result.current.parts).toEqual([{ id: 's1', type: 'text', text: 'second-1' }])
+    })
+    expect(result.current.status).toBe('done')
+
+    gateFirst.resolve(undefined)
+    await waitFor(() => {
+      expect(result.current.status).toBe('done')
+    })
+    expect(result.current.parts).toEqual([{ id: 's1', type: 'text', text: 'second-1' }])
+  })
+
+  test('F1 regression: id-less drafts of different types within one send() do not destroy each other', async () => {
+    const transport: AgentTransport<AgentPart, string> = {
+      async *stream() {
+        yield { type: 'text', text: 'Hi' }
+        yield {
+          type: 'tool',
+          toolCallId: 'c1',
+          toolName: 'search',
+          state: 'input-available',
+          input: { q: 'x' },
+        }
+        yield { type: 'text', text: 'Bye' }
+      },
+    }
+
+    const { result } = renderHook(() => useAgentStream({ transport }))
+
+    await act(async () => {
+      await result.current.send('hi')
+    })
+
+    // Pre-fix: mergePart matched all three drafts on `undefined === undefined`, so text→tool→text
+    // collapsed to a single (wrong-typed) entry instead of three. withPartIds stamping a distinct
+    // id per draft is what keeps them apart.
+    expect(result.current.parts).toHaveLength(3)
+    expect(result.current.parts.map((part) => part.type)).toEqual(['text', 'tool', 'text'])
+    const ids = result.current.parts.map((part) => (part as { id: string }).id)
+    expect(new Set(ids).size).toBe(3)
+  })
+
+  test('a thrown (non-abort) error sets status "error" and captures the error', async () => {
+    const boom = new Error('boom')
+    const transport: AgentTransport<AgentPart, string> = {
+      async *stream() {
+        throw boom
+        // eslint-disable-next-line no-unreachable
+        yield { type: 'text', text: 'unreachable' }
+      },
+    }
+
+    const { result } = renderHook(() => useAgentStream({ transport }))
+
+    await act(async () => {
+      await result.current.send('hi')
+    })
+
+    expect(result.current.status).toBe('error')
+    expect(result.current.error).toBe(boom)
+  })
+
+  test('an AbortError thrown by the transport is ignored — it never overwrites status with "error"', async () => {
+    const gate = deferred<void>()
+    const transport: AgentTransport<AgentPart, string> = {
+      async *stream(_input, signal) {
+        yield { id: 'p1', type: 'text', text: 'a' }
+        await gate.promise
+        if (signal?.aborted) throw new DOMException('The operation was aborted.', 'AbortError')
+        yield { id: 'p2', type: 'text', text: 'b' }
+      },
+    }
+
+    const { result } = renderHook(() => useAgentStream({ transport }))
+
+    act(() => {
+      void result.current.send('hi')
+    })
+    await waitFor(() => {
+      expect(result.current.parts).toEqual([{ id: 'p1', type: 'text', text: 'a' }])
+    })
+
+    // stop() aborts the signal AND sets 'done' synchronously.
+    act(() => {
+      result.current.stop()
+    })
+    expect(result.current.status).toBe('done')
+
+    // The transport now throws AbortError (asynchronously, after 'done' is already set) — this
+    // must be swallowed by the catch's `err.name === 'AbortError'` guard, never flip to 'error'.
+    gate.resolve(undefined)
+    await waitFor(() => {
+      expect(result.current.status).toBe('done')
+    })
+    expect(result.current.error).toBeUndefined()
+  })
+
+  test('unmount aborts the in-flight stream', async () => {
+    let observedAbortedOnResume = false
+    const gate = deferred<void>()
+    const transport: AgentTransport<AgentPart, string> = {
+      async *stream(_input, signal) {
+        yield { id: 'p1', type: 'text', text: 'a' }
+        await gate.promise
+        observedAbortedOnResume = signal?.aborted ?? false
+      },
+    }
+
+    const { result, unmount } = renderHook(() => useAgentStream({ transport }))
+
+    act(() => {
+      void result.current.send('hi')
+    })
+    await waitFor(() => {
+      expect(result.current.parts).toEqual([{ id: 'p1', type: 'text', text: 'a' }])
+    })
+
+    unmount()
+
+    gate.resolve(undefined)
+    // Let the generator's resumed step run and observe the signal.
+    await new Promise((resolveTick) => setTimeout(resolveTick, 0))
+    expect(observedAbortedOnResume).toBe(true)
+  })
+
+  test('StrictMode double-invoke of a "send on mount" consumer effect: the surviving stream is the only one reflected in final state', async () => {
+    // useAgentStream itself never calls transport.stream() from an effect — only send() does, and
+    // send() is consumer-invoked. The realistic StrictMode hazard is therefore a consumer's own
+    // `useEffect(() => { void send(x) }, [])` "send the first turn on mount" pattern, which
+    // StrictMode's dev-only double-invoke runs twice against the SAME fiber. Verified empirically
+    // (reported alongside this suite): transport.stream() IS called twice in that scenario — the
+    // first pass's controller is aborted (both by useAgentStream's own unmount-cleanup effect
+    // during the simulated unmount, and redundantly by send()'s own
+    // `controllerRef.current?.abort()` at the top of the second call) — so exactly ONE stream's
+    // output is ever reflected in the hook's observable state, even though the transport function
+    // itself was invoked twice. That is the invariant this test pins, not a literal single
+    // `transport.stream()` call count.
+    let streamCalls = 0
+    let capturedParts: AgentPart[] = []
+    let capturedStatus = ''
+
+    const transport: AgentTransport<AgentPart, string> = {
+      async *stream() {
+        streamCalls++
+        yield { id: `call-${streamCalls}`, type: 'text', text: `call-${streamCalls}` }
+      },
+    }
+
+    function Consumer(): null {
+      const { send, parts, status } = useAgentStream({ transport })
+      capturedParts = parts
+      capturedStatus = status
+      useEffect(() => {
+        void send('initial')
+        // eslint-disable-next-line react-hooks/exhaustive-deps
+      }, [])
+      return null
+    }
+
+    await act(async () => {
+      render(
+        <StrictMode>
+          <Consumer />
+        </StrictMode>,
+      )
+    })
+
+    await waitFor(() => {
+      expect(capturedStatus).toBe('done')
+    })
+
+    expect(streamCalls).toBe(2)
+    // Only the SECOND (surviving) call's part made it into final state — the first is discarded.
+    expect(capturedParts).toEqual([{ id: 'call-2', type: 'text', text: 'call-2' }])
+  })
+})

package/src/agent/use-agent-stream.ts

@@ -27,7 +27,10 @@
  * }
  */
 import { useCallback, useEffect, useRef, useState } from 'react'
+import { withPartIds } from './id'
 import { isStartPart } from './parts'
+import { mergePart } from './merge'
+import type { PartLike } from './merge'
 import type { AgentPart } from './parts'
 import type { AgentTransport } from './transport'
 
@@ -67,7 +70,7 @@ export type UseAgentStreamReturn<TPart, TInput> = {
  * // parts accumulates as the stream arrives
  * // status: 'idle' → 'streaming' → 'done' (or 'error')
  */
-export function useAgentStream<TPart = AgentPart, TInput = string>({
+export function useAgentStream<TPart extends PartLike = AgentPart, TInput = string>({
   transport,
 }: {
   transport: AgentTransport<TPart, TInput>
@@ -100,15 +103,22 @@ export function useAgentStream<TPart = AgentPart, TInput = string>({
       setError(undefined)
       setStatus('streaming')
 
+      // Per-send namespace: this hook has no thread/session id to key off, and each send() call
+      // fully resets `parts` anyway, so a fresh id per call is enough to keep two id-less drafts
+      // ARRIVING WITHIN THE SAME SEND from colliding on `undefined === undefined` in mergePart (the
+      // F1 bug — text→tool→text destroying each other). Not a replay mechanism — this hook has no
+      // resume() path — see withPartIds' own doc for why it can't be one anyway.
+      const runId = crypto.randomUUID()
+
       try {
-        for await (const part of transport.stream(input, controller.signal)) {
+        for await (const part of withPartIds(runId, transport.stream(input, controller.signal))) {
           // Guard: if a newer send() has superseded this stream, stop updating state.
           if (controllerRef.current !== controller) return
           if (controller.signal.aborted) break
           // StartPart is a no-op signal (run id + resume token), not renderable content — this
           // hook has no persistence layer to resume across, so just skip it.
           if (isStartPart(part)) continue
-          setParts((prev) => [...prev, part])
+          setParts((prev) => mergePart(prev, part))
         }
         // Only mark done if this stream is still the current one and wasn't aborted.
         if (controllerRef.current === controller && !controller.signal.aborted) setStatus('done')

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

@@ -0,0 +1,133 @@
+/**
+ * useAgentThreadRuns — foreign-part round trip (B2 convergence fix).
+ *
+ * The open part registry (./foreign) only serves its headline purpose — a transport streaming an
+ * app-specific part type (`data-toolProgress`, `data-chart`, …) reaching `ThreadTranscript` — if a
+ * ForeignPart can flow all the way through this hook's mergePart accumulator: transport →
+ * consumeAndFinalize → runs.get(id).parts → the persisted assistant ChatMessage. This file proves
+ * that path end to end with `useAgentThreadRuns<TranscriptPart>`, which was a tsc error before
+ * mergePart's constraint was widened from `AgentPart` to the structural `PartLike`.
+ */
+import { describe, expect, test } from 'bun:test'
+import { act, renderHook, waitFor } from '@testing-library/react'
+import { useAgentThreadRuns } from './use-agent-thread-runs'
+import type { AgentThread, ThreadsStore } from './thread'
+import type { AgentTransport } from './transport'
+import type { TranscriptPart } from './foreign'
+import type { AgentOutcome, OutcomeResolver } from './outcome'
+
+// ── test-only ThreadsStore double, typed over TranscriptPart ─────────────────────────────────────
+function createTestThreadsStore(): ThreadsStore<TranscriptPart> {
+  let threads: AgentThread<TranscriptPart>[] = []
+  let activeId: string | null = null
+
+  return {
+    get threads() {
+      return threads
+    },
+    get activeId() {
+      return activeId
+    },
+    select(id) {
+      activeId = id
+    },
+    create(createOpts) {
+      const id = crypto.randomUUID()
+      const now = Date.now()
+      const thread: AgentThread<TranscriptPart> = {
+        id,
+        messages: [],
+        outcome: null,
+        status: 'pending',
+        read: false,
+        createdAt: now,
+        updatedAt: now,
+        ...(createOpts?.meta !== undefined ? { meta: createOpts.meta } : {}),
+      }
+      threads = [thread, ...threads]
+      return id
+    },
+    appendMessage(id, message) {
+      threads = threads.map((thread) =>
+        thread.id === id
+          ? { ...thread, messages: [...thread.messages, message], updatedAt: Date.now() }
+          : thread,
+      )
+    },
+    setOutcome(id, outcome) {
+      threads = threads.map((thread) =>
+        thread.id === id ? { ...thread, outcome, updatedAt: Date.now() } : thread,
+      )
+    },
+    setStatus(id, status) {
+      threads = threads.map((thread) =>
+        thread.id === id ? { ...thread, status, updatedAt: Date.now() } : thread,
+      )
+    },
+    setResumeToken(id, token) {
+      threads = threads.map((thread) => {
+        if (thread.id !== id) return thread
+        const { resumeToken: _resumeToken, ...rest } = thread
+        return {
+          ...rest,
+          ...(token !== undefined ? { resumeToken: token } : {}),
+          updatedAt: Date.now(),
+        }
+      })
+    },
+    markRead(id) {
+      threads = threads.map((thread) => (thread.id === id ? { ...thread, read: true } : thread))
+    },
+    remove(id) {
+      threads = threads.filter((thread) => thread.id !== id)
+      if (activeId === id) activeId = null
+    },
+    clear() {
+      threads = []
+      activeId = null
+    },
+  }
+}
+
+const resolveOutcome: OutcomeResolver<TranscriptPart> = (): AgentOutcome => ({
+  title: 'title',
+  summary: 'summary',
+  status: 'done',
+})
+
+describe('useAgentThreadRuns<TranscriptPart> — foreign part round trip', () => {
+  test('a foreign part survives accumulation and a replay replaces rather than duplicates', async () => {
+    const store = createTestThreadsStore()
+    const threadId = store.create()
+
+    const transport: AgentTransport<TranscriptPart, string> = {
+      async *stream() {
+        yield { id: 'progress-1', type: 'data-toolProgress', message: 'searching' }
+        // Same id, second delta — must REPLACE the first entry, not duplicate it.
+        yield { id: 'progress-1', type: 'data-toolProgress', message: 'done' }
+        yield { id: 'text-1', type: 'text', text: 'Found it.' }
+      },
+    }
+
+    const { result } = renderHook(() =>
+      useAgentThreadRuns<TranscriptPart>({ transport, store, resolveOutcome }),
+    )
+
+    act(() => {
+      result.current.start(threadId, 'go find it')
+    })
+
+    await waitFor(() => {
+      expect(store.threads.find((t) => t.id === threadId)?.status).toBe('done')
+    })
+
+    const assistantMessage = store.threads
+      .find((t) => t.id === threadId)
+      ?.messages.find((m) => m.role === 'assistant')
+
+    expect(assistantMessage?.parts).toEqual([
+      { id: 'progress-1', type: 'data-toolProgress', message: 'done' },
+      { id: 'text-1', type: 'text', text: 'Found it.' },
+    ])
+  })
+})