basalt-ui 1.10.0 → 1.12.0

package/src/agent/parts.ts

@@ -3,12 +3,20 @@
  *
  * Exhaustiveness is enforced at every switch via assertNever (imported from '../register').
  * Adding a new variant without a matching case is a tsc error — see the fixture in
- * apps/playground/src/demo/agent-part.type-guard.ts.
+ * apps/playground/src/demo/agent-part.type-guard.ts. One caveat for code that folds WIRE data on
+ * the render path (`coalesceParts`): keep the compile-time guarantee — bind the value at `never` —
+ * but do NOT let the runtime throw, or one malformed chunk kills the whole transcript. See
+ * `mergeToolPart`'s default branch for that shape.
  *
  * Eden #231 doctrine: the server-side Elysia route MUST declare `: AsyncGenerator<AgentPart>`
  * 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 +32,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 +44,179 @@
  * 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 }
+/**
+ * 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 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
+}
 
-/** An internal reasoning/thinking fragment (may be hidden in the UI). */
-export type ReasoningPart = { readonly type: 'reasoning'; readonly text: string }
+// ── 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.
+//
+// `toolCallId` is required on the three IN-FLIGHT states and OPTIONAL on the four SETTLED ones —
+// see `Identified` / `MaybeIdentified` below. The absence is modelled in the type, never as a
+// sentinel value.
+
+/** 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'
+  readonly toolName: string
+  /** Wall-clock time from first sighting of this toolCallId to its terminal state. */
+  readonly durationMs?: number
+  readonly providerExecuted?: boolean
+}
 
 /**
- * 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.
+ * The three IN-FLIGHT states (`input-streaming`, `input-available`, `approval-requested`) carry an
+ * authoritative `toolCallId` — the merge key, and for them it is structural. An in-flight part
+ * exists only to be superseded by the settled part for the same call; with no merge key it can
+ * never be closed, so it would render as a forever-pending chip standing beside the real result.
+ * Nothing is lost by rejecting an unidentified one either: the `toolName` and `input` it carries
+ * are re-supplied on the settled part. `parseToolCallPart` therefore rejects these when the id is
+ * missing or empty.
+ */
+type Identified = ToolCallBase & { readonly toolCallId: string }
+
+/**
+ * The four SETTLED states (`approval-responded` plus the three terminal ones) may legitimately
+ * arrive without a `toolCallId`, for two different reasons.
+ *
+ * `approval-responded` is where the WIRE omits it: the SDK's `tool-approval-response` chunk
+ * carries none, and it is resolved by reverse lookup on `approval.id` (coalesce.ts keeps the
+ * approvalId -> toolCallId side index that does it).
+ *
+ * The three terminal states admit the absence for a different reason — tolerance, not wire shape.
+ * They are self-contained: each carries the OUTCOME of the call, so a missing id costs only the
+ * fold (`coalesceParts` keeps an unresolvable part as its own block and never discards it).
+ * Rejecting one instead would delete the only record of how the call ended — silent data loss in a
+ * transcript, strictly worse than an unfolded block.
  *
- * `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.
+ * The absence is modelled here rather than smuggled through an empty-string sentinel: the union
+ * previously declared an always-meaningful `string` that the `approval-responded` wire shape
+ * cannot supply, which forced a `''` sentinel into the type and an `as unknown as` cast into every
+ * test that built one. A `''` toolCallId is not a value any state accepts; `parseToolCallPart`
+ * normalizes one to absent at the wire boundary, so it never reaches the type or a consumer.
  */
-export type ToolCallPart = {
-  readonly type: 'tool'
-  readonly toolName: string
-  readonly input: unknown
-  readonly output?: unknown
-  readonly toolCallId?: string
+type MaybeIdentified = ToolCallBase & { readonly toolCallId?: string }
+
+export type ToolCallPart =
+  | (Identified & { readonly state: 'input-streaming'; readonly input?: unknown })
+  | (Identified & { readonly state: 'input-available'; readonly input: unknown })
+  | (Identified & {
+      readonly state: 'approval-requested'
+      readonly input: unknown
+      readonly approval: ToolApproval & { readonly approved?: never; readonly reason?: never }
+    })
+  | (MaybeIdentified & {
+      readonly state: 'approval-responded'
+      readonly input: unknown
+      readonly approval: ToolApproval & { readonly approved: boolean }
+    })
+  | (MaybeIdentified & {
+      readonly state: 'output-available'
+      readonly input: unknown
+      readonly output: unknown
+      readonly preliminary?: boolean
+      readonly approval?: ToolApproval & { readonly approved?: true }
+    })
+  | (MaybeIdentified & {
+      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 }
+    })
+  | (MaybeIdentified & {
+      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 +227,198 @@ 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.
+ *
+ * An empty-string `toolCallId` is normalized to absent here — the one place the wire's degenerate
+ * shape is decoded — so `''` never reaches the type or any consumer of it. What an ABSENT id then
+ * means is decided per state, exactly as the union declares it (`Identified` /
+ * `MaybeIdentified`): fatal on the three in-flight states, which exist only to be closed by a
+ * later one and are re-supplied by it; survivable on the four settled states, which carry the
+ * outcome and are kept UNIDENTIFIED rather than dropped. Dropping a settled part would be silent
+ * data loss — the transcript would simply forget how the call ended. */
+function parseToolCallPart(id: string, obj: Record<string, unknown>): ToolCallPart | null {
+  if (typeof obj['toolName'] !== 'string') return null
+  if (typeof obj['state'] !== 'string') return null
+
+  const rawToolCallId = obj['toolCallId']
+  if (rawToolCallId !== undefined && typeof rawToolCallId !== 'string') return null
+  const toolCallId =
+    typeof rawToolCallId === 'string' && rawToolCallId.length > 0 ? rawToolCallId : undefined
+
+  const toolName = obj['toolName']
+  const common = {
+    id,
+    type: 'tool' as const,
+    toolName,
+    ...(typeof obj['durationMs'] === 'number' ? { durationMs: obj['durationMs'] } : {}),
+    ...(typeof obj['providerExecuted'] === 'boolean'
+      ? { providerExecuted: obj['providerExecuted'] }
+      : {}),
+  }
+  // The three in-flight states below require an identified call; the four settled ones spread
+  // `identity` instead, which is simply empty when the wire supplied no usable id.
+  const identified = toolCallId !== undefined ? { ...common, toolCallId } : null
+  const identity = toolCallId !== undefined ? { toolCallId } : {}
+
+  switch (obj['state']) {
+    case 'input-streaming':
+      if (identified === null) return null
+      return {
+        ...identified,
+        state: 'input-streaming',
+        ...('input' in obj ? { input: obj['input'] } : {}),
+      }
+    case 'input-available':
+      if (identified === null) return null
+      if (!('input' in obj)) return null
+      return { ...identified, state: 'input-available', input: obj['input'] }
+    case 'approval-requested': {
+      if (identified === null) return null
+      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 {
+        ...identified,
+        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
+      // The state the WIRE ships unidentified — `approval.id` is then its only addressing key.
+      return {
+        ...common,
+        ...identity,
+        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,
+        ...identity,
+        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,
+        ...identity,
+        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,
+        ...identity,
+        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

@@ -1,6 +1,7 @@
 /**
  * createThreadsStore — ring-buffer caps (maxThreads/maxMessagesPerThread), newest-first ordering,
- * setResumeToken's delete-the-key-on-undefined semantics, and same-tick action accumulation.
+ * setResumeToken's delete-the-key-on-undefined semantics, same-tick action accumulation, and the
+ * constant hydrated/error pair the async sibling store (./adapter) actually varies.
  *
  * Uses the REAL localStorage-backed store (happy-dom provides `window.localStorage`), so every
  * test uses its own unique `key` — the same convention as
@@ -13,7 +14,12 @@ 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() }
+  return {
+    id,
+    role: 'user',
+    parts: [{ id: `${id}-p0`, type: 'text', text: id }],
+    createdAt: Date.now(),
+  }
 }
 
 describe('createThreadsStore', () => {
@@ -144,4 +150,71 @@ describe('createThreadsStore', () => {
     expect(thread?.status).toBe('streaming')
     expect(thread?.resumeToken).toBe('tok-accum')
   })
+
+  test('hydrated is always true and error always undefined — localStorage resolves synchronously', () => {
+    const useThreads = createThreadsStore({ key: 'thread-hydrated-a', version: 1 })
+    const { result } = renderHook(() => useThreads())
+
+    // Pinned because these two exist for the async adapter store (./adapter); the localStorage
+    // store must fill them with the "nothing to wait for, nothing to report" constants on the
+    // very first render, before any action has run.
+    expect(result.current.hydrated).toBe(true)
+    expect(result.current.error).toBeUndefined()
+
+    act(() => {
+      result.current.create()
+    })
+
+    expect(result.current.hydrated).toBe(true)
+    expect(result.current.error).toBeUndefined()
+  })
+
+  test('create() mints distinct ids via crypto.getRandomValues when randomUUID is unavailable', () => {
+    const originalCrypto = globalThis.crypto
+    Object.defineProperty(globalThis, 'crypto', {
+      value: { getRandomValues: originalCrypto.getRandomValues.bind(originalCrypto) },
+      configurable: true,
+    })
+    try {
+      const useThreads = createThreadsStore({ key: 'thread-crypto-a', version: 1 })
+      const { result } = renderHook(() => useThreads())
+
+      let first = ''
+      let second = ''
+      act(() => {
+        first = result.current.create()
+        second = result.current.create()
+      })
+
+      expect(first).not.toBe('')
+      expect(second).not.toBe('')
+      expect(first).not.toBe(second)
+    } finally {
+      // Restore the real crypto so no later test in the process is affected.
+      Object.defineProperty(globalThis, 'crypto', { value: originalCrypto, configurable: true })
+    }
+  })
+
+  test('create() still mints distinct ids with no usable crypto at all (randomUUID and getRandomValues both absent)', () => {
+    const originalCrypto = globalThis.crypto
+    Object.defineProperty(globalThis, 'crypto', { value: undefined, configurable: true })
+    try {
+      const useThreads = createThreadsStore({ key: 'thread-crypto-b', version: 1 })
+      const { result } = renderHook(() => useThreads())
+
+      let first = ''
+      let second = ''
+      act(() => {
+        first = result.current.create()
+        second = result.current.create()
+      })
+
+      expect(first).not.toBe('')
+      expect(second).not.toBe('')
+      expect(first).not.toBe(second)
+    } finally {
+      // Restore the real crypto so no later test in the process is affected.
+      Object.defineProperty(globalThis, 'crypto', { value: originalCrypto, configurable: true })
+    }
+  })
 })

package/src/agent/thread.ts

@@ -24,6 +24,7 @@
 import { useCallback, useRef } from 'react'
 import { createPersistedState } from '../state'
 import type { ChatMessage } from './history'
+import { mintThreadId } from './id'
 import type { AgentOutcome } from './outcome'
 import type { AgentPart } from './parts'
 
@@ -138,6 +139,20 @@ export type ThreadsStore<TPart = AgentPart> = {
   readonly remove: (id: string) => void
   /** Remove all threads and clear the active selection. */
   readonly clear: () => void
+  /**
+   * Whether `threads` reflects the backing store yet. Always `true` for the localStorage store
+   * (createPersistedState resolves synchronously); meaningful only for an async, server-backed
+   * store built with `createAdapterThreadsStore` (./adapter), where it stays `false` until the
+   * first `listThreads` SUCCEEDS. Pair it with `error` — `!hydrated && error !== undefined` is a
+   * failed load, `!hydrated && error === undefined` is still loading.
+   */
+  readonly hydrated: boolean
+  /**
+   * The most recent persistence failure, or `undefined`. Always `undefined` for the localStorage
+   * store, which has no failure the caller can act on. An async store surfaces the rejected
+   * load/write here after rolling its optimistic edit back.
+   */
+  readonly error: unknown
 }
 
 // ── createThreadsStore ────────────────────────────────────────────────────────
@@ -198,7 +213,7 @@ export function createThreadsStore<TPart = AgentPart>(
 
     const create = useCallback(
       (createOpts?: { readonly meta?: Record<string, unknown> }): string => {
-        const id = crypto.randomUUID()
+        const id = mintThreadId()
         const now = Date.now()
         const thread: AgentThread<TPart> = {
           id,
@@ -307,6 +322,11 @@ export function createThreadsStore<TPart = AgentPart>(
       markRead,
       remove,
       clear,
+      // localStorage resolves synchronously and swallows its own quota errors, so there is never
+      // a pending load to await nor a failure a caller could act on. See ./adapter for the async
+      // store where these two carry real information.
+      hydrated: true,
+      error: undefined,
     }
   }
 }

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