basalt-ui 1.9.0 → 1.11.0

package/src/agent/parts.ts

@@ -9,6 +9,11 @@
  * explicitly and carry NO t.Object/t.Union response schema. Validate at yield-time. See
  * agent/rules/basalt-agent.md for the full doctrine.
  *
+ * Part identity: every variant carries a stable `id` (see `PartBase`). Transports are permitted to
+ * yield a DRAFT — `id` omitted — via `AgentPartDraft`; the consuming hooks (or `withPartIds`)
+ * normalize a draft into a fully-identified part before it is ever accumulated. `parseAgentPart`
+ * validates the FULL (identified) shape — a draft is a separate, narrower concern.
+ *
  * @example
  * import type { AgentPart } from 'basalt-ui/agent'
  * function describe(p: AgentPart): string {
@@ -24,6 +29,11 @@
  * }
  */
 
+// ── Part identity ─────────────────────────────────────────────────────────────
+
+/** Every AgentPart variant carries a stable id — the addressing key for `mergePart`/`coalesceParts`. */
+type PartBase = { readonly id: string }
+
 // ── AgentPart discriminated union ────────────────────────────────────────────
 
 /**
@@ -31,53 +41,144 @@
  * resume this run after a disconnect. Not renderable content — UI code should treat it as a
  * no-op signal, not conversation content.
  */
-export type StartPart = {
+export type StartPart = PartBase & {
   readonly type: 'start'
   readonly runId: string
   readonly resumeToken?: string
 }
 
-/** A streamed text fragment from the assistant. */
-export type TextPart = { readonly type: 'text'; readonly text: string }
-
-/** An internal reasoning/thinking fragment (may be hidden in the UI). */
-export type ReasoningPart = { readonly type: 'reasoning'; readonly text: string }
-
 /**
- * A tool invocation — input is the parameters sent, output (optional) is the result once
- * the tool has completed. Streams arrive with output undefined; it may be appended later.
- *
- * `toolCallId` (optional) identifies the specific invocation when a transport's wire format
- * carries one (e.g. AI SDK's `ToolUIPart`) — useful for consumer-side coalescing of a tool call's
- * input/output pair by id rather than by array position.
+ * A streamed text fragment from the assistant. `offset` is the character position of this delta
+ * inside its part (undefined = append at the tail) — the mechanism `mergePart` uses to splice a
+ * replayed delta in place rather than duplicating it.
  */
-export type ToolCallPart = {
+export type TextPart = PartBase & {
+  readonly type: 'text'
+  readonly text: string
+  readonly offset?: number
+}
+
+/** An internal reasoning/thinking fragment (may be hidden in the UI). Same `offset` mechanism as TextPart. */
+export type ReasoningPart = PartBase & {
+  readonly type: 'reasoning'
+  readonly text: string
+  readonly offset?: number
+}
+
+// ── ToolCallPart — mirrors AI SDK v7's UIToolInvocation ─────────────────────
+//
+// Verified against installed ai@7.0.16 / 7.0.18 (byte-identical .d.ts). Seven states, no
+// 'running' ('input-available' IS the running state — input complete, no output yet).
+//
+// The nested `approval` shape mirrors the SDK exactly (`{ id, approved?, reason?, isAutomatic?,
+// signature? }`) rather than flattening to `approvalId`/`approved`/`reason` — flattening would
+// silently drop `isAutomatic`/`signature`.
+//
+// `toolName` is NOT a field on the SDK's UIToolInvocation — for static tools it lives in the part
+// discriminator `tool-${NAME}`. It IS a required field here (ours, not the SDK's) because the chip
+// needs it; a transport mapping from the SDK must DERIVE it from the discriminator, not read it off
+// the invocation.
+
+/** The nested approval envelope — mirrors the SDK's shape verbatim, never flattened. */
+type ToolApproval = {
+  readonly id: string
+  readonly approved?: boolean
+  readonly reason?: string
+  readonly isAutomatic?: boolean
+  readonly signature?: string
+}
+
+type ToolCallBase = PartBase & {
   readonly type: 'tool'
+  /** Required on all seven states (was optional — see parts.ts history). */
+  readonly toolCallId: string
   readonly toolName: string
-  readonly input: unknown
-  readonly output?: unknown
-  readonly toolCallId?: string
+  /** Wall-clock time from first sighting of this toolCallId to its terminal state. */
+  readonly durationMs?: number
+  readonly providerExecuted?: boolean
+}
+
+export type ToolCallPart =
+  | (ToolCallBase & { readonly state: 'input-streaming'; readonly input?: unknown })
+  | (ToolCallBase & { readonly state: 'input-available'; readonly input: unknown })
+  | (ToolCallBase & {
+      readonly state: 'approval-requested'
+      readonly input: unknown
+      readonly approval: ToolApproval & { readonly approved?: never; readonly reason?: never }
+    })
+  | (ToolCallBase & {
+      readonly state: 'approval-responded'
+      readonly input: unknown
+      readonly approval: ToolApproval & { readonly approved: boolean }
+    })
+  | (ToolCallBase & {
+      readonly state: 'output-available'
+      readonly input: unknown
+      readonly output: unknown
+      readonly preliminary?: boolean
+      readonly approval?: ToolApproval & { readonly approved?: true }
+    })
+  | (ToolCallBase & {
+      readonly state: 'output-error'
+      readonly input?: unknown
+      /** The SDK's field name — there is no field named `error` anywhere in the union. */
+      readonly errorText: string
+      /** The only place the raw, un-parsed input survives — what lets a UI render a call whose input never validated. */
+      readonly rawInput?: unknown
+      readonly approval?: ToolApproval & { readonly approved?: true }
+    })
+  | (ToolCallBase & {
+      readonly state: 'output-denied'
+      readonly input: unknown
+      readonly approval: ToolApproval & { readonly approved: false }
+    })
+
+export type ToolCallState = ToolCallPart['state']
+
+/** The three states a tool call can never leave — see `isToolCallSettled`. */
+export const TERMINAL_TOOL_STATES = ['output-available', 'output-error', 'output-denied'] as const
+
+/** True once a tool call has reached one of `TERMINAL_TOOL_STATES` — no further state transition. */
+export function isToolCallSettled(part: ToolCallPart): boolean {
+  return (TERMINAL_TOOL_STATES as readonly ToolCallState[]).includes(part.state)
 }
 
 /** A cited source URL referenced by the assistant. */
-export type SourcePart = { readonly type: 'source'; readonly url: string; readonly title?: string }
+export type SourcePart = PartBase & {
+  readonly type: 'source'
+  readonly url: string
+  readonly title?: string
+}
 
 /** A fatal or recoverable error emitted in-stream by the agent. */
-export type ErrorPart = { readonly type: 'error'; readonly message: string }
+export type ErrorPart = PartBase & { readonly type: 'error'; readonly message: string }
 
 /**
  * The complete discriminated union of all structured agent stream parts.
  *
  * @example
- * const part: AgentPart = { type: 'text', text: 'Hello' }
+ * const part: AgentPart = { id: 'p1', type: 'text', text: 'Hello' }
  */
 export type AgentPart = StartPart | TextPart | ReasoningPart | ToolCallPart | SourcePart | ErrorPart
 
+// ── AgentPartDraft — what a transport is allowed to yield ────────────────────
+
+/**
+ * An AgentPart with `id` optional — the shape a transport is allowed to yield. The naked type
+ * parameter (not `AgentPart extends unknown ? ... : never` written some other way) is deliberate:
+ * it makes the conditional type distribute over the AgentPart union member-by-member, so
+ * `Drafted<AgentPart>` is `Drafted<StartPart> | Drafted<TextPart> | ...` rather than one flattened
+ * (and wrong) shape.
+ */
+export type Drafted<T> = T extends unknown ? Omit<T, 'id'> & { readonly id?: string } : never
+export type AgentPartDraft = Drafted<AgentPart>
+
 // ── parseAgentPart ───────────────────────────────────────────────────────────
 
 /**
  * Runtime type-narrowing guard: validates an unknown value against the AgentPart discriminated
- * union and returns the narrowed type or null when validation fails.
+ * union and returns the narrowed type or null when validation fails. Validates the FULL
+ * (identified) shape — an `id`-less draft is a separate concern handled by `withPartIds`.
  *
  * @example
  * const raw = JSON.parse(line)
@@ -88,46 +189,175 @@ export function parseAgentPart(raw: unknown): AgentPart | null {
   if (raw === null || typeof raw !== 'object') return null
   const obj = raw as Record<string, unknown>
   if (typeof obj['type'] !== 'string') return null
+  if (typeof obj['id'] !== 'string') return null
+  const id = obj['id']
 
   switch (obj['type']) {
     case 'start':
       if (typeof obj['runId'] !== 'string') return null
       return {
+        id,
         type: 'start',
         runId: obj['runId'],
         ...(typeof obj['resumeToken'] === 'string' ? { resumeToken: obj['resumeToken'] } : {}),
       }
     case 'text':
       if (typeof obj['text'] !== 'string') return null
-      return { type: 'text', text: obj['text'] }
+      return {
+        id,
+        type: 'text',
+        text: obj['text'],
+        ...(typeof obj['offset'] === 'number' ? { offset: obj['offset'] } : {}),
+      }
     case 'reasoning':
       if (typeof obj['text'] !== 'string') return null
-      return { type: 'reasoning', text: obj['text'] }
-    case 'tool':
-      if (typeof obj['toolName'] !== 'string') return null
-      if (!('input' in obj)) return null
       return {
-        type: 'tool',
-        toolName: obj['toolName'],
-        input: obj['input'],
-        ...(obj['output'] !== undefined ? { output: obj['output'] } : {}),
-        ...(typeof obj['toolCallId'] === 'string' ? { toolCallId: obj['toolCallId'] } : {}),
+        id,
+        type: 'reasoning',
+        text: obj['text'],
+        ...(typeof obj['offset'] === 'number' ? { offset: obj['offset'] } : {}),
       }
+    case 'tool':
+      return parseToolCallPart(id, obj)
     case 'source':
       if (typeof obj['url'] !== 'string') return null
       return {
+        id,
         type: 'source',
         url: obj['url'],
         ...(typeof obj['title'] === 'string' ? { title: obj['title'] } : {}),
       }
     case 'error':
       if (typeof obj['message'] !== 'string') return null
-      return { type: 'error', message: obj['message'] }
+      return { id, type: 'error', message: obj['message'] }
+    default:
+      return null
+  }
+}
+
+/** Validates the state-discriminated `tool` part shape. Rejects the pre-1.11.0 flat shape
+ * (`{type:'tool', output}` with no `state`) and any unrecognized `state` value. */
+function parseToolCallPart(id: string, obj: Record<string, unknown>): ToolCallPart | null {
+  if (typeof obj['toolCallId'] !== 'string') return null
+  if (typeof obj['toolName'] !== 'string') return null
+  if (typeof obj['state'] !== 'string') return null
+
+  const { toolCallId, toolName } = obj as { toolCallId: string; toolName: string }
+  const common = {
+    id,
+    type: 'tool' as const,
+    toolCallId,
+    toolName,
+    ...(typeof obj['durationMs'] === 'number' ? { durationMs: obj['durationMs'] } : {}),
+    ...(typeof obj['providerExecuted'] === 'boolean'
+      ? { providerExecuted: obj['providerExecuted'] }
+      : {}),
+  }
+
+  switch (obj['state']) {
+    case 'input-streaming':
+      return {
+        ...common,
+        state: 'input-streaming',
+        ...('input' in obj ? { input: obj['input'] } : {}),
+      }
+    case 'input-available':
+      if (!('input' in obj)) return null
+      return { ...common, state: 'input-available', input: obj['input'] }
+    case 'approval-requested': {
+      if (!('input' in obj)) return null
+      const approval = parseApproval(obj['approval'])
+      // The type declares this state's approval as `{ approved?: never; reason?: never }` — a
+      // request that already carries a verdict or a reason is a contradiction, not a pending
+      // request, so reject it rather than silently casting past the invariant.
+      if (approval === null || approval.approved !== undefined || approval.reason !== undefined) {
+        return null
+      }
+      return {
+        ...common,
+        state: 'approval-requested',
+        input: obj['input'],
+        approval: approval as ToolApproval & { approved?: never; reason?: never },
+      }
+    }
+    case 'approval-responded': {
+      if (!('input' in obj)) return null
+      const approval = parseApproval(obj['approval'])
+      if (approval === null || typeof approval.approved !== 'boolean') return null
+      return {
+        ...common,
+        state: 'approval-responded',
+        input: obj['input'],
+        approval: approval as ToolApproval & { approved: boolean },
+      }
+    }
+    case 'output-denied': {
+      if (!('input' in obj)) return null
+      const approval = parseApproval(obj['approval'])
+      if (approval === null || approval.approved !== false) return null
+      return {
+        ...common,
+        state: 'output-denied',
+        input: obj['input'],
+        approval: approval as ToolApproval & { approved: false },
+      }
+    }
+    case 'output-available': {
+      if (!('input' in obj)) return null
+      if (!('output' in obj)) return null
+      const approval = obj['approval'] === undefined ? null : parseApproval(obj['approval'])
+      // The type declares this state's approval as `{ approved?: true }` — output present
+      // alongside `approved: false` is a denial masquerading as a result, not a valid "approved"
+      // carry-through. A present-but-malformed approval is rejected the same way (not silently
+      // dropped), matching output-denied/approval-responded's precedent above.
+      if (obj['approval'] !== undefined && (approval === null || approval.approved === false)) {
+        return null
+      }
+      return {
+        ...common,
+        state: 'output-available',
+        input: obj['input'],
+        output: obj['output'],
+        ...(typeof obj['preliminary'] === 'boolean' ? { preliminary: obj['preliminary'] } : {}),
+        ...(approval !== null ? { approval: approval as ToolApproval & { approved?: true } } : {}),
+      }
+    }
+    case 'output-error': {
+      if (typeof obj['errorText'] !== 'string') return null
+      const approval = obj['approval'] === undefined ? null : parseApproval(obj['approval'])
+      // Same invariant as output-available above: an error carrying `approved: false` is a
+      // denial, not an error whose approval "happens to carry through".
+      if (obj['approval'] !== undefined && (approval === null || approval.approved === false)) {
+        return null
+      }
+      return {
+        ...common,
+        state: 'output-error',
+        errorText: obj['errorText'],
+        ...('input' in obj ? { input: obj['input'] } : {}),
+        ...('rawInput' in obj ? { rawInput: obj['rawInput'] } : {}),
+        ...(approval !== null ? { approval: approval as ToolApproval & { approved?: true } } : {}),
+      }
+    }
     default:
       return null
   }
 }
 
+/** Validates the nested `approval` envelope. Returns null when absent/malformed. */
+function parseApproval(raw: unknown): ToolApproval | null {
+  if (raw === null || typeof raw !== 'object') return null
+  const obj = raw as Record<string, unknown>
+  if (typeof obj['id'] !== 'string') return null
+  return {
+    id: obj['id'],
+    ...(typeof obj['approved'] === 'boolean' ? { approved: obj['approved'] } : {}),
+    ...(typeof obj['reason'] === 'string' ? { reason: obj['reason'] } : {}),
+    ...(typeof obj['isAutomatic'] === 'boolean' ? { isAutomatic: obj['isAutomatic'] } : {}),
+    ...(typeof obj['signature'] === 'string' ? { signature: obj['signature'] } : {}),
+  }
+}
+
 // ── isStartPart ──────────────────────────────────────────────────────────────
 
 /** Type guard: narrows an unknown value to StartPart. */

package/src/agent/thread.test.ts

@@ -0,0 +1,147 @@
+/**
+ * createThreadsStore — ring-buffer caps (maxThreads/maxMessagesPerThread), newest-first ordering,
+ * setResumeToken's delete-the-key-on-undefined semantics, and same-tick action accumulation.
+ *
+ * Uses the REAL localStorage-backed store (happy-dom provides `window.localStorage`), so every
+ * test uses its own unique `key` — the same convention as
+ * `router-tanstack/multi-search-param-store.test.ts` — to avoid cross-test bleed through the
+ * shared localStorage instance the process-wide DOM registration provides.
+ */
+import { describe, expect, test } from 'bun:test'
+import { act, renderHook } from '@testing-library/react'
+import { createThreadsStore } from './thread'
+import type { ChatMessage } from './history'
+
+function makeMessage(id: string): ChatMessage {
+  return { id, role: 'user', parts: [{ type: 'text', text: id }], createdAt: Date.now() }
+}
+
+describe('createThreadsStore', () => {
+  test('caps at 50 threads, dropping the oldest (tail) when exceeded', () => {
+    const useThreads = createThreadsStore({ key: 'thread-cap-a', version: 1 })
+    const { result } = renderHook(() => useThreads())
+
+    const ids: string[] = []
+    act(() => {
+      for (let i = 0; i < 51; i++) {
+        ids.push(result.current.create())
+      }
+    })
+
+    expect(result.current.threads).toHaveLength(50)
+    // The very first created thread is the oldest — it must have been dropped.
+    expect(result.current.threads.some((t) => t.id === ids[0])).toBe(false)
+    // The very last created thread is the newest — it must be retained, at index 0.
+    expect(result.current.threads[0]?.id).toBe(ids[50])
+  })
+
+  test('caps at 100 messages per thread, dropping the oldest first', () => {
+    const useThreads = createThreadsStore({ key: 'thread-cap-b', version: 1 })
+    const { result } = renderHook(() => useThreads())
+
+    let threadId = ''
+    act(() => {
+      threadId = result.current.create()
+    })
+
+    act(() => {
+      for (let i = 0; i < 101; i++) {
+        result.current.appendMessage(threadId, makeMessage(`m${i}`))
+      }
+    })
+
+    const thread = result.current.threads.find((t) => t.id === threadId)
+    expect(thread?.messages).toHaveLength(100)
+    // m0 (the oldest) must have been dropped; m1..m100 survive.
+    expect(thread?.messages[0]?.id).toBe('m1')
+    expect(thread?.messages.at(-1)?.id).toBe('m100')
+  })
+
+  test('threads are stored newest-first: the most recently created thread is always index 0', () => {
+    const useThreads = createThreadsStore({ key: 'thread-order-a', version: 1 })
+    const { result } = renderHook(() => useThreads())
+
+    let idA = ''
+    let idB = ''
+    let idC = ''
+    act(() => {
+      idA = result.current.create()
+    })
+    act(() => {
+      idB = result.current.create()
+    })
+    act(() => {
+      idC = result.current.create()
+    })
+
+    expect(result.current.threads.map((t) => t.id)).toEqual([idC, idB, idA])
+  })
+
+  test('setResumeToken(id, undefined) deletes the key rather than assigning undefined', () => {
+    const useThreads = createThreadsStore({ key: 'thread-resume-a', version: 1 })
+    const { result } = renderHook(() => useThreads())
+
+    let threadId = ''
+    act(() => {
+      threadId = result.current.create()
+    })
+
+    act(() => {
+      result.current.setResumeToken(threadId, 'token-1')
+    })
+    const withToken = result.current.threads.find((t) => t.id === threadId)
+    expect(withToken?.resumeToken).toBe('token-1')
+    expect('resumeToken' in (withToken ?? {})).toBe(true)
+    // JSON round-trip: the key is present and serialized.
+    expect(JSON.parse(JSON.stringify(withToken)).resumeToken).toBe('token-1')
+
+    act(() => {
+      result.current.setResumeToken(threadId, undefined)
+    })
+    const cleared = result.current.threads.find((t) => t.id === threadId)
+    // The distinction this test pins: the key is ABSENT, not present-with-value-undefined —
+    // observable via `in` (survives a plain assignment of `undefined`) and via JSON round-trip
+    // (an `undefined`-valued key would also vanish from JSON, so `in` is the load-bearing check).
+    expect('resumeToken' in (cleared ?? {})).toBe(false)
+    expect(cleared?.resumeToken).toBeUndefined()
+    expect(JSON.stringify(cleared)).not.toContain('resumeToken')
+  })
+
+  test('two synchronous actions called in the same tick accumulate rather than one clobbering the other', () => {
+    const useThreads = createThreadsStore({ key: 'thread-accumulate-a', version: 1 })
+    const { result } = renderHook(() => useThreads())
+
+    let threadId = ''
+    act(() => {
+      // Both calls happen before React re-renders and hands back a fresh `result.current` — the
+      // second call must still observe the first's effect via the ref mirror (thread.ts:178-190),
+      // not the stale pre-render `state` closure.
+      threadId = result.current.create()
+      result.current.appendMessage(threadId, makeMessage('accumulated'))
+    })
+
+    const thread = result.current.threads.find((t) => t.id === threadId)
+    expect(thread).toBeDefined()
+    expect(thread?.messages).toHaveLength(1)
+    expect(thread?.messages[0]?.id).toBe('accumulated')
+  })
+
+  test('two synchronous setStatus + setResumeToken calls in one tick both land, not just the last', () => {
+    const useThreads = createThreadsStore({ key: 'thread-accumulate-b', version: 1 })
+    const { result } = renderHook(() => useThreads())
+
+    let threadId = ''
+    act(() => {
+      threadId = result.current.create()
+    })
+
+    act(() => {
+      result.current.setStatus(threadId, 'streaming')
+      result.current.setResumeToken(threadId, 'tok-accum')
+    })
+
+    const thread = result.current.threads.find((t) => t.id === threadId)
+    expect(thread?.status).toBe('streaming')
+    expect(thread?.resumeToken).toBe('tok-accum')
+  })
+})

package/src/agent/transport.test.ts

@@ -0,0 +1,70 @@
+/**
+ * transport — `isResumable` and `edenTransport`'s opt-in `idempotentReplay` flag.
+ *
+ * `resume` alone is NOT enough for a transport to be treated as resumable: `isResumable` also
+ * requires the literal `idempotentReplay: true` assertion, and `edenTransport` only sets it when
+ * the caller opts in explicitly via a third argument — never inferred from `resumeCall` alone.
+ */
+import { describe, expect, test } from 'bun:test'
+import { edenTransport, isResumable } from './transport'
+import type { AgentTransport } from './transport'
+import type { AgentPart } from './parts'
+
+describe('isResumable', () => {
+  test('false for a transport with no resume() at all', () => {
+    const transport: AgentTransport<AgentPart, string> = {
+      async *stream() {},
+    }
+    expect(isResumable(transport)).toBe(false)
+  })
+
+  test('false for a transport with resume() but WITHOUT idempotentReplay — resume alone is not enough', () => {
+    const transport: AgentTransport<AgentPart, string> = {
+      async *stream() {},
+      async *resume() {
+        yield { id: 'p1', type: 'text', text: 'resumed' }
+      },
+    }
+    expect(isResumable(transport)).toBe(false)
+  })
+
+  test('true only once BOTH resume() and idempotentReplay: true are present', () => {
+    const transport = {
+      async *stream() {},
+      async *resume() {
+        yield { id: 'p1', type: 'text', text: 'resumed' }
+      },
+      idempotentReplay: true as const,
+    }
+    expect(isResumable(transport)).toBe(true)
+  })
+})
+
+describe('edenTransport — idempotentReplay is opt-in, never inferred', () => {
+  test('no resumeCall at all → the returned object has NO resume key', () => {
+    const transport = edenTransport<AgentPart>(async () => ({
+      data: (async function* () {})(),
+      error: null,
+    }))
+    expect('resume' in transport).toBe(false)
+    expect(isResumable(transport)).toBe(false)
+  })
+
+  test('resumeCall supplied but NO options → resume() exists but isResumable is still false', () => {
+    const transport = edenTransport<AgentPart>(
+      async () => ({ data: (async function* () {})(), error: null }),
+      async () => ({ data: (async function* () {})(), error: null }),
+    )
+    expect(typeof transport.resume).toBe('function')
+    expect(isResumable(transport)).toBe(false)
+  })
+
+  test('resumeCall + { idempotentReplay: true } → isResumable is true', () => {
+    const transport = edenTransport<AgentPart>(
+      async () => ({ data: (async function* () {})(), error: null }),
+      async () => ({ data: (async function* () {})(), error: null }),
+      { idempotentReplay: true },
+    )
+    expect(isResumable(transport)).toBe(true)
+  })
+})