basalt-ui 1.9.0 → 1.10.0

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

@@ -0,0 +1,231 @@
+/**
+ * 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 { type: 'text', text: 'a' }
+        await gate.promise
+        // Must never be observed — the consumer's guard should discard this once aborted.
+        yield { type: 'text', text: 'b' }
+      },
+    }
+
+    const { result } = renderHook(() => useAgentStream({ transport }))
+
+    act(() => {
+      void result.current.send('hi')
+    })
+    await waitFor(() => {
+      expect(result.current.parts).toEqual([{ 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([{ 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 { type: 'text', text: 'first-1' }
+          await gateFirst.promise
+          // Must never be observed — 'second' has already superseded this controller.
+          yield { type: 'text', text: 'first-2' }
+        } else {
+          yield { type: 'text', text: 'second-1' }
+        }
+      },
+    }
+
+    const { result } = renderHook(() => useAgentStream({ transport }))
+
+    act(() => {
+      void result.current.send('first')
+    })
+    await waitFor(() => {
+      expect(result.current.parts).toEqual([{ type: 'text', text: 'first-1' }])
+    })
+
+    act(() => {
+      void result.current.send('second')
+    })
+    await waitFor(() => {
+      expect(result.current.parts).toEqual([{ 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([{ type: 'text', text: 'second-1' }])
+  })
+
+  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 { type: 'text', text: 'a' }
+        await gate.promise
+        if (signal?.aborted) throw new DOMException('The operation was aborted.', 'AbortError')
+        yield { type: 'text', text: 'b' }
+      },
+    }
+
+    const { result } = renderHook(() => useAgentStream({ transport }))
+
+    act(() => {
+      void result.current.send('hi')
+    })
+    await waitFor(() => {
+      expect(result.current.parts).toEqual([{ 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 { 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([{ 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 { 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([{ type: 'text', text: 'call-2' }])
+  })
+})

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

@@ -0,0 +1,261 @@
+/**
+ * useAgentThreadRuns — mount-time reconcile ("resume orphaned threads after a reload") coverage.
+ *
+ * The mount-reconcile effect (empty deps — a one-time sweep of whatever the store held when this
+ * manager first attaches) treats any persisted 'pending' or 'streaming' thread with no live
+ * controller as orphaned, and either attempts `transport.resume(resumeToken, signal)` (when the
+ * transport supports it, a resumeToken is present, and there's a last user message to attribute
+ * the resumed turn to) or falls back straight to 'interrupted'.
+ *
+ * The F3 wedge (StrictMode/`<Activity>` re-running this same effect on the SAME fiber) has its
+ * own file: `use-agent-thread-runs.wedge.test.tsx`.
+ */
+import { describe, expect, test } from 'bun:test'
+import { 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 { AgentPart } from './parts'
+import type { ChatMessage } from './history'
+import type { AgentOutcome } from './outcome'
+
+// ── test-only ThreadsStore double — see use-agent-thread-runs.wedge.test.tsx for the rationale ──
+function createTestThreadsStore(initial: AgentThread<AgentPart>[]): ThreadsStore<AgentPart> {
+  let threads = initial
+  let activeId: string | null = null
+  return {
+    get threads() {
+      return threads
+    },
+    get activeId() {
+      return activeId
+    },
+    select(id) {
+      activeId = id
+    },
+    create(opts) {
+      const id = crypto.randomUUID()
+      const now = Date.now()
+      const thread: AgentThread<AgentPart> = {
+        id,
+        messages: [],
+        outcome: null,
+        status: 'pending',
+        read: false,
+        createdAt: now,
+        updatedAt: now,
+        ...(opts?.meta !== undefined ? { meta: opts.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
+    },
+  }
+}
+
+function makeStreamingThread(
+  overrides: Partial<AgentThread<AgentPart>> = {},
+): AgentThread<AgentPart> {
+  const now = Date.now()
+  const userMessage: ChatMessage<AgentPart> = {
+    id: crypto.randomUUID(),
+    role: 'user',
+    parts: [{ type: 'text', text: 'hello' }],
+    createdAt: now,
+  }
+  return {
+    id: crypto.randomUUID(),
+    messages: [userMessage],
+    outcome: null,
+    status: 'streaming',
+    read: false,
+    createdAt: now,
+    updatedAt: now,
+    resumeToken: 'resume-token',
+    ...overrides,
+  }
+}
+
+const resolveOutcome = (): AgentOutcome => ({ title: 'title', summary: 'summary', status: 'done' })
+
+describe('useAgentThreadRuns — mount-time reconcile', () => {
+  test('no resume() on the transport → falls back to interrupted', async () => {
+    const thread = makeStreamingThread()
+    const store = createTestThreadsStore([thread])
+
+    const transport: AgentTransport<AgentPart, string> = {
+      async *stream() {},
+      // no `resume` key at all
+    }
+
+    renderHook(() => useAgentThreadRuns({ transport, store, resolveOutcome }))
+
+    await waitFor(() => {
+      expect(store.threads.find((t) => t.id === thread.id)?.status).toBe('interrupted')
+    })
+  })
+
+  test('no resumeToken on the persisted thread → falls back to interrupted, even with a resumable transport', async () => {
+    // exactOptionalPropertyTypes forbids `resumeToken: undefined` as an override — build the
+    // thread directly, simply omitting the key, to represent "never had a resumeToken".
+    const now = Date.now()
+    const userMessage: ChatMessage<AgentPart> = {
+      id: crypto.randomUUID(),
+      role: 'user',
+      parts: [{ type: 'text', text: 'hello' }],
+      createdAt: now,
+    }
+    const thread: AgentThread<AgentPart> = {
+      id: crypto.randomUUID(),
+      messages: [userMessage],
+      outcome: null,
+      status: 'streaming',
+      read: false,
+      createdAt: now,
+      updatedAt: now,
+    }
+    const store = createTestThreadsStore([thread])
+
+    let resumeCalls = 0
+    const transport: AgentTransport<AgentPart, string> = {
+      async *stream() {},
+      async *resume() {
+        resumeCalls++
+        yield { type: 'text', text: 'resumed' }
+      },
+    }
+
+    renderHook(() => useAgentThreadRuns({ transport, store, resolveOutcome }))
+
+    await waitFor(() => {
+      expect(store.threads.find((t) => t.id === thread.id)?.status).toBe('interrupted')
+    })
+    expect(resumeCalls).toBe(0)
+  })
+
+  test('no last user message on the persisted thread → falls back to interrupted, even with a resumable transport + token', async () => {
+    const thread = makeStreamingThread({ messages: [] })
+    const store = createTestThreadsStore([thread])
+
+    let resumeCalls = 0
+    const transport: AgentTransport<AgentPart, string> = {
+      async *stream() {},
+      async *resume() {
+        resumeCalls++
+        yield { type: 'text', text: 'resumed' }
+      },
+    }
+
+    renderHook(() => useAgentThreadRuns({ transport, store, resolveOutcome }))
+
+    await waitFor(() => {
+      expect(store.threads.find((t) => t.id === thread.id)?.status).toBe('interrupted')
+    })
+    expect(resumeCalls).toBe(0)
+  })
+
+  test('resumable transport + token + last user message → resume() is called exactly once, with that token', async () => {
+    const thread = makeStreamingThread({ resumeToken: 'the-exact-token' })
+    const store = createTestThreadsStore([thread])
+
+    const resumeArgs: string[] = []
+    const transport: AgentTransport<AgentPart, string> = {
+      async *stream() {},
+      async *resume(token) {
+        resumeArgs.push(token)
+        yield { type: 'text', text: 'resumed' }
+      },
+    }
+
+    renderHook(() => useAgentThreadRuns({ transport, store, resolveOutcome }))
+
+    await waitFor(() => {
+      expect(store.threads.find((t) => t.id === thread.id)?.status).toBe('done')
+    })
+    expect(resumeArgs).toEqual(['the-exact-token'])
+  })
+
+  test('a failed resume() falls back to interrupted via onFailureStatus, not error', async () => {
+    const thread = makeStreamingThread()
+    const store = createTestThreadsStore([thread])
+
+    const transport: AgentTransport<AgentPart, string> = {
+      async *stream() {},
+      // oxlint-disable-next-line require-yield
+      async *resume() {
+        throw new Error('resume failed')
+      },
+    }
+
+    renderHook(() => useAgentThreadRuns({ transport, store, resolveOutcome }))
+
+    await waitFor(() => {
+      expect(store.threads.find((t) => t.id === thread.id)?.status).toBe('interrupted')
+    })
+  })
+
+  test('a "pending" (never-started) thread with no live controller is also swept by reconcile', async () => {
+    // Not covered by "streaming" scenarios above: reconcile's orphan check is
+    // `status === 'pending' || status === 'streaming'`, so a thread that was created but never
+    // started is reconciled the same way on the very next mount.
+    const now = Date.now()
+    const pendingThread: AgentThread<AgentPart> = {
+      id: crypto.randomUUID(),
+      messages: [],
+      outcome: null,
+      status: 'pending',
+      read: false,
+      createdAt: now,
+      updatedAt: now,
+    }
+    const store = createTestThreadsStore([pendingThread])
+
+    const transport: AgentTransport<AgentPart, string> = {
+      async *stream() {},
+    }
+
+    renderHook(() => useAgentThreadRuns({ transport, store, resolveOutcome }))
+
+    await waitFor(() => {
+      expect(store.threads.find((t) => t.id === pendingThread.id)?.status).toBe('interrupted')
+    })
+  })
+})