basalt-ui 1.10.0 → 1.12.0

package/src/agent/foreign.ts

@@ -0,0 +1,140 @@
+/**
+ * foreign.ts — the open half of the transcript's part-rendering registry.
+ *
+ * `AgentPart` (`./parts`) is a closed, exhaustively-switched union — adding a variant without
+ * updating every consuming switch is a tsc error (`PartList`'s `assertNever` gate). A transport
+ * that streams app-specific structured data (a chart spec, a progress ping) needs a part type
+ * `AgentPart` will never carry — closing the union around it would defeat the whole point of the
+ * gate. This file is the seam: `ForeignPart` describes what basalt does NOT know, `ConsumerPart`
+ * resolves the augmented union a consumer registers via `declare module 'basalt-ui'`, and
+ * `definePartRenderers` types an exhaustive renderer map against it. See
+ * `agent-chat/thread-message.tsx`'s three-step resolution order for how this plugs into
+ * `ThreadTranscript`: a consumer renderer wins first, `narrowAgentPart` routes the built-in six to
+ * `PartList`'s own exhaustive switch second, and `fallbackRenderer` catches anything left.
+ *
+ * @example
+ * // app-side: src/features/chat/parts.ts
+ * type ChartPart = { type: 'data-chart'; id: string; spec: ChartSpec }
+ * declare module 'basalt-ui' {
+ *   interface BasaltRegister { parts: ChartPart }
+ * }
+ * export const chatRenderers = definePartRenderers({
+ *   'data-chart': ({ part, settled }) => (settled ? <Chart spec={part.spec} /> : <ChartSkeleton />),
+ * })
+ */
+import type { ReactNode } from 'react'
+import type { BasaltRegister } from '../register'
+import type { ChatMessage } from './history'
+import type { AgentPart } from './parts'
+
+// ── ForeignPart / TranscriptPart ──────────────────────────────────────────────
+
+/** A part basalt does not know. NOT a member of AgentPart — the built-in union stays closed. */
+export type ForeignPart = {
+  readonly type: string
+  readonly id: string
+  readonly [k: string]: unknown
+}
+
+/** What a transcript actually holds — basalt's own six variants plus anything a consumer registers. */
+export type TranscriptPart = AgentPart | ForeignPart
+
+// ── ConsumerPart ───────────────────────────────────────────────────────────────
+//
+// JUDGMENT POINT — this is a sibling conditional, NOT a reuse of `register.ts`'s `Slot<K,
+// Constraint>`, and deliberately so:
+//
+// `Slot<K, Constraint>` is built for MAP-shaped slots (series, commands, overlays,
+// notifications): its un-augmented fallback is the never-keyed empty object `{}`, which is the
+// correct zero for a MAP (`keyof {}` is `never`, so the derived key-union — e.g. `SeriesKey` — is
+// `never` too). `parts` is UNION-shaped, not map-shaped: there is no key to look anything up by,
+// the type itself IS the legal value set. So the un-augmented fallback here has to be `never`
+// (the empty union), not `{}`.
+//
+// Concretely, reusing `Slot<'parts', ForeignPart>` would hand back `{}` when un-augmented (an
+// empty object does not itself satisfy `ForeignPart`'s `{ type: string; id: string }` shape, but
+// `Slot`'s fallback branch returns it unconditionally regardless of `Constraint`), and then
+// `PartRenderers` below — which reads `ConsumerPart['type']` on the augmented branch and checks
+// `[ConsumerPart] extends [never]` to pick between the two branches — would see a non-`never`,
+// property-less `{}` and take the WRONG branch (or fail to compile the indexed access) even with
+// zero augmentation, exactly the case that must compile cleanly. `Slot`'s fallback isn't a
+// parameter (nor should it be — every existing map slot wants `{}`), so this is a sibling
+// conditional purpose-built for a union slot, not a gap in `Slot` itself.
+/** The consumer's registered foreign-part union, or `never` when un-augmented. */
+export type ConsumerPart = BasaltRegister extends { parts: infer P extends ForeignPart } ? P : never
+
+// ── PartRenderers ────────────────────────────────────────────────────────────
+
+/**
+ * Un-augmented: a loose string-keyed map (any renderer, any key — there is nothing to check
+ * against). Augmented: a MISSING key is a tsc error (`definePartRenderers` requires the full
+ * registered union), and each renderer's `part` is narrowed to exactly its variant. Same
+ * bound-check mechanism as `SeriesKey` (`register.ts:26-58`), applied to a union instead of a map.
+ *
+ * NOT caught: a STALE (extra, unregistered) key. `<const T extends Constraint>` inference does
+ * not excess-property-check an object-literal argument the way a direct assignment to a fixed
+ * target type would (verified against this repo's tsc — see
+ * `apps/playground/src/demo/agent-part-registry.type-guard.ts`'s Fixture 3) — an extra key
+ * compiles as dead code rather than erroring. Catching it would need an `Exact<T, Shape>`-style
+ * wrapper that departs from the `spec: T` "canonical token-factory contract" every other `defineX`
+ * in this codebase follows verbatim; that trade was left as a documented gap rather than a one-off
+ * factory shape.
+ */
+export type PartRenderers = [ConsumerPart] extends [never]
+  ? Readonly<Record<string, PartRenderer<ForeignPart>>>
+  : { readonly [K in ConsumerPart['type']]: PartRenderer<Extract<ConsumerPart, { type: K }>> }
+
+/** Everything a foreign-part renderer needs beyond the part itself. */
+export type PartRenderContext<TPart = ForeignPart> = {
+  readonly part: TPart
+  readonly messageId: string
+  readonly partId: string
+  /** false while this part belongs to the in-flight tail of a streaming turn. */
+  readonly settled: boolean
+  readonly role: ChatMessage['role']
+}
+
+export type PartRenderer<TPart = ForeignPart> = (ctx: PartRenderContext<TPart>) => ReactNode
+
+/**
+ * Canonical const-generic factory (`packages/basalt-ui/CLAUDE.md`, "Canonical token-factory
+ * contract") — identity passthrough, exact-keyed return, no builder, no config bag. Mirrors
+ * `defineSeries` (`tokens/index.ts:648-650`) and `defineNotifications`
+ * (`notifications/define-notifications.ts:112-115`).
+ *
+ * @example
+ * const chatRenderers = definePartRenderers({
+ *   'data-chart': ({ part }) => <Chart spec={part.spec} />,
+ * })
+ */
+export function definePartRenderers<const T extends PartRenderers>(map: T): T {
+  return map
+}
+
+// ── narrowAgentPart ──────────────────────────────────────────────────────────
+
+const AGENT_PART_TYPES: ReadonlySet<string> = new Set([
+  'start',
+  'text',
+  'reasoning',
+  'tool',
+  'source',
+  'error',
+])
+
+/**
+ * Returns `part` as an `AgentPart` when its `type` is one of the six built-in variants, else
+ * `null`. Deliberately NOT routed through `parseAgentPart`: that function is a VALIDATING parser
+ * for untrusted wire data — it checks every field a variant requires (`runId`, `toolCallId`,
+ * `approval`, ...) and would reject an already-well-typed in-memory `AgentPart` on shape grounds
+ * if it doesn't happen to match the wire representation byte-for-byte. `narrowAgentPart` is the
+ * cheap complement: a plain discriminator check on a value already known to be a `TranscriptPart`,
+ * used purely to route rendering — it trusts the caller's typing rather than re-validating it.
+ *
+ * @example
+ * const agentPart = narrowAgentPart(part)
+ * if (agentPart !== null) return <PartList parts={[agentPart]} />
+ */
+export function narrowAgentPart(part: TranscriptPart): AgentPart | null {
+  return AGENT_PART_TYPES.has(part.type) ? (part as AgentPart) : null
+}

package/src/agent/history.ts

@@ -43,6 +43,8 @@ export type ChatMessage<TPart = AgentPart> = {
   readonly role: 'user' | 'assistant'
   readonly parts: TPart[]
   readonly createdAt: number
+  /** How the turn ended. Absent on user messages and on pre-1.11 persisted assistant messages. */
+  readonly finish?: 'complete' | 'stopped' | 'error'
 }
 
 // ── createChatHistoryStore options ────────────────────────────────────────────

package/src/agent/id.test.ts

@@ -0,0 +1,75 @@
+/**
+ * withPartIds — stamps `${runId}#${n}` onto any draft part arriving without an id; idempotent for
+ * drafts that already have one (untouched, and doesn't advance the counter).
+ */
+import { describe, expect, test } from 'bun:test'
+import { withPartIds } from './id'
+import type { AgentPartDraft } from './parts'
+
+async function* gen<T>(values: T[]): AsyncGenerator<T> {
+  for (const value of values) yield value
+}
+
+async function collect<T>(source: AsyncGenerator<T>): Promise<T[]> {
+  const out: T[] = []
+  for await (const value of source) out.push(value)
+  return out
+}
+
+describe('withPartIds', () => {
+  test('stamps a sequential id on every draft missing one', async () => {
+    // Annotated: all three literals uniformly omit `id`, so without this TS infers an `id`-less
+    // element type that has no properties in common with withPartIds' `{ id?: string }`
+    // constraint — a weak-type check failure, not a real shape mismatch.
+    const drafts: AgentPartDraft[] = [
+      { type: 'text', text: 'a' },
+      { type: 'text', text: 'b' },
+      { type: 'text', text: 'c' },
+    ]
+    const result = await collect(withPartIds('run-1', gen(drafts)))
+    expect(result).toEqual([
+      { type: 'text', text: 'a', id: 'run-1#0' },
+      { type: 'text', text: 'b', id: 'run-1#1' },
+      { type: 'text', text: 'c', id: 'run-1#2' },
+    ])
+  })
+
+  test('leaves a part that already has an id untouched', async () => {
+    const drafts = [{ type: 'text', text: 'a', id: 'custom-id' }]
+    const result = await collect(withPartIds('run-1', gen(drafts)))
+    expect(result).toEqual([{ type: 'text', text: 'a', id: 'custom-id' }])
+  })
+
+  test('is idempotent: re-running withPartIds over already-identified parts changes nothing', async () => {
+    const drafts: AgentPartDraft[] = [{ type: 'text', text: 'a' }]
+    const once = await collect(withPartIds('run-1', gen(drafts)))
+    const twice = await collect(withPartIds('run-1', gen(once)))
+    expect(twice).toEqual(once)
+  })
+
+  test('does not advance the counter for parts that already carry an id', async () => {
+    const drafts = [
+      { type: 'text', text: 'a', id: 'preset' },
+      { type: 'text', text: 'b' },
+    ]
+    const result = await collect(withPartIds('run-1', gen(drafts)))
+    expect(result).toEqual([
+      { type: 'text', text: 'a', id: 'preset' },
+      { type: 'text', text: 'b', id: 'run-1#0' },
+    ])
+  })
+
+  test('mixed run: only missing ids are stamped, sequentially among themselves', async () => {
+    const drafts = [
+      { type: 'text', text: 'a' },
+      { type: 'text', text: 'b', id: 'preset' },
+      { type: 'text', text: 'c' },
+    ]
+    const result = await collect(withPartIds('run-42', gen(drafts)))
+    expect(result).toEqual([
+      { type: 'text', text: 'a', id: 'run-42#0' },
+      { type: 'text', text: 'b', id: 'preset' },
+      { type: 'text', text: 'c', id: 'run-42#1' },
+    ])
+  })
+})

package/src/agent/id.ts

@@ -0,0 +1,91 @@
+/**
+ * Id-minting helpers shared by the thread stores: `mintThreadId` (a client-side thread id, used by
+ * both `./thread`'s `createThreadsStore` and `./adapter`'s `createAdapterThreadsStore`) and
+ * `withPartIds` (stamps sequence ids onto streamed parts). Related in theme — both mint an id a
+ * store needs — unrelated in mechanism; grouped here because they're the two id-minting leaves the
+ * two thread stores both sit above.
+ */
+
+/**
+ * Mints a client-side thread id. `crypto.randomUUID()` exists only in SECURE CONTEXTS (HTTPS or
+ * localhost) — a consumer served over plain HTTP on a LAN hostname (a homelab dashboard on a bare
+ * IP, a staging box) would otherwise have `create()`, about the most basic user action a thread
+ * store has, throw a plain TypeError. A store used from a browser must not throw on a user gesture
+ * — the same principle already applied twice this release (`spliceText` clamps rather than throws,
+ * `coalesceParts` degrades rather than throws).
+ *
+ * Fallback chain, each rung reached only when the one above it is unavailable:
+ *   1. `crypto.randomUUID()` — cryptographically random, RFC 4122 UUID. The normal path.
+ *   2. `crypto.getRandomValues()` — still cryptographically random; hand-assembled into a UUIDv4
+ *      (the version/variant bits are set per RFC 4122, since this rung hands back raw bytes, not a
+ *      formatted UUID).
+ *   3. No usable `crypto` at all (missing entirely, or missing both methods above — an old WebView,
+ *      an SSR shim). NOT cryptographically random and NOT collision-resistant in general. This rung
+ *      exists solely so `create()` never throws on such a host. It is acceptable ONLY because this
+ *      id is minted a handful of times per client session and is not the idempotency key any write
+ *      here depends on — `ThreadsStoreAdapter.appendMessage`'s idempotency key is the MESSAGE id,
+ *      not this thread id, so a collision on this rung costs a locally merged/duplicated thread, not
+ *      silent data loss on the append path. Do not reuse this rung for anything with a higher
+ *      collision cost than that.
+ */
+export function mintThreadId(): string {
+  if (typeof crypto !== 'undefined' && typeof crypto.randomUUID === 'function') {
+    return crypto.randomUUID()
+  }
+  if (typeof crypto !== 'undefined' && typeof crypto.getRandomValues === 'function') {
+    const bytes = crypto.getRandomValues(new Uint8Array(16))
+    const hex = Array.from({ length: 16 }, (_, i) => {
+      const raw = bytes.at(i) ?? 0
+      // Version 4 (bits 12-15 of time_hi_and_version) and variant 10 (bits 6-7 of
+      // clock_seq_hi_and_reserved) — the only structure a UUIDv4 promises over raw random bytes.
+      const byte = i === 6 ? (raw & 0x0f) | 0x40 : i === 8 ? (raw & 0x3f) | 0x80 : raw
+      return byte.toString(16).padStart(2, '0')
+    }).join('')
+    return `${hex.slice(0, 8)}-${hex.slice(8, 12)}-${hex.slice(12, 16)}-${hex.slice(16, 20)}-${hex.slice(20)}`
+  }
+  return `id-${Date.now().toString(36)}-${Math.random().toString(36).slice(2)}`
+}
+
+/**
+ * withPartIds — stamps a stable id onto every draft part arriving without one.
+ *
+ * A transport is allowed to yield a draft (`AgentPartDraft` — `id` optional); this wraps such a
+ * generator and normalizes it into a fully-identified stream, minting `${runId}#${n}` for any
+ * part that arrives without an `id`. A part that already carries an id passes through untouched
+ * (idempotent) and does not advance the counter.
+ *
+ * NOT a replay-convergence mechanism. The minted id is a bare per-call sequence number with no
+ * relationship to content or offset — it identifies "the nth id-less part THIS invocation saw",
+ * nothing more. Calling `withPartIds` again over a resumed/replayed stream restarts its counter at
+ * 0, so the resumed stream's first delta mints the SAME id as the original run's first delta
+ * (`${runId}#0`) regardless of whether it carries the same content — if the resumed transport
+ * re-sends the full text as one chunk while the original sent it as several deltas, mergePart's
+ * tail-splice will corrupt the accumulated text rather than converge it. A transport that needs
+ * genuine replay convergence (one asserting `ResumableAgentTransport`'s `idempotentReplay: true`)
+ * MUST mint its own content-stable ids — e.g. `aiSdkTransport`'s `${chatId}#${index}` /
+ * `tool#${toolCallId}` — and must not rely on this helper for that guarantee. Combining
+ * `withPartIds` with a transport that asserts `idempotentReplay: true` is only safe when that
+ * transport already mints stable ids itself, in which case every part already carries an `id` and
+ * `withPartIds` is a no-op passthrough (see the idempotent behavior above) — it is never the thing
+ * providing replay safety.
+ *
+ * @example
+ * const identified = withPartIds(runId, transport.stream(input, signal))
+ * for await (const part of identified) {
+ *   // part.id is always defined here
+ * }
+ */
+export async function* withPartIds<TPart extends { id?: string }>(
+  runId: string,
+  source: AsyncGenerator<TPart>,
+): AsyncGenerator<TPart & { id: string }> {
+  let n = 0
+  for await (const part of source) {
+    if (part.id !== undefined) {
+      yield part as TPart & { id: string }
+      continue
+    }
+    yield { ...part, id: `${runId}#${n}` }
+    n += 1
+  }
+}

package/src/agent/index.ts

@@ -34,18 +34,41 @@
 // ── AgentPart discriminated union ─────────────────────────────────────────────
 export type {
   AgentPart,
+  AgentPartDraft,
+  Drafted,
   StartPart,
   TextPart,
   ReasoningPart,
   ToolCallPart,
+  ToolCallState,
   SourcePart,
   ErrorPart,
 } from './parts'
-export { parseAgentPart, isStartPart } from './parts'
+export { parseAgentPart, isStartPart, isToolCallSettled, TERMINAL_TOOL_STATES } from './parts'
+
+// ── mergePart (identity-addressed accumulator) ───────────────────────────────
+export { mergePart } from './merge'
+
+// ── withPartIds (drafts → identified parts) ──────────────────────────────────
+export { withPartIds } from './id'
+
+// ── coalesceParts (adjacent + by-id merge for display) ───────────────────────
+export { coalesceParts } from './coalesce'
+
+// ── foreign parts (the open half of the part-renderer registry) ──────────────
+export { definePartRenderers, narrowAgentPart } from './foreign'
+export type {
+  ForeignPart,
+  TranscriptPart,
+  ConsumerPart,
+  PartRenderers,
+  PartRenderContext,
+  PartRenderer,
+} from './foreign'
 
 // ── AgentTransport + edenTransport ───────────────────────────────────────────
-export type { AgentTransport } from './transport'
-export { edenTransport } from './transport'
+export type { AgentTransport, ResumableAgentTransport } from './transport'
+export { edenTransport, isResumable } from './transport'
 
 // ── aiSdkTransport (recommended default, optional peer: ai) ──────────────────
 export { aiSdkTransport } from './ai-sdk-transport'
@@ -90,3 +113,11 @@ export type { AgentThread, ThreadStatus, ThreadsStore, ThreadsStoreOptions } fro
 // ── AgentOutcome + heuristicOutcome ────────────────────────────────────────────
 export { heuristicOutcome } from './outcome'
 export type { AgentOutcome, OutcomeResolver } from './outcome'
+
+// ── createAdapterThreadsStore + threadsStoreAdapterContract ──────────────────
+export { createAdapterThreadsStore, threadsStoreAdapterContract } from './adapter'
+export type {
+  AdapterThreadsStoreOptions,
+  ThreadsStoreAdapter,
+  ThreadsStoreAdapterContractCase,
+} from './adapter'

package/src/agent/merge.test.ts

@@ -0,0 +1,206 @@
+/**
+ * mergePart — the identity-addressed accumulator. The behaviour under test that matters most:
+ * replaying a whole run from character offset 0 rebuilds the identical parts array it produced
+ * the first time — it cannot double the content.
+ */
+import { describe, expect, test } from 'bun:test'
+import { mergePart } from './merge'
+import type { TranscriptPart } from './foreign'
+import type { AgentPart, TextPart, ToolCallPart } from './parts'
+
+describe('mergePart', () => {
+  test('appends a part whose id is not yet present', () => {
+    const parts: AgentPart[] = [{ id: 'p1', type: 'text', text: 'Hi' }]
+    const next: AgentPart = { id: 'p2', type: 'text', text: 'there' }
+    expect(mergePart(parts, next)).toEqual([
+      { id: 'p1', type: 'text', text: 'Hi' },
+      { id: 'p2', type: 'text', text: 'there' },
+    ])
+  })
+
+  test('an undefined offset splices at the tail (append)', () => {
+    const parts: TextPart[] = [{ id: 'p1', type: 'text', text: 'Hel' }]
+    const next: TextPart = { id: 'p1', type: 'text', text: 'lo' }
+    const [merged] = mergePart(parts, next)
+    expect(merged?.text).toBe('Hello')
+  })
+
+  test('splices an explicit offset into the middle of the existing text', () => {
+    const parts: TextPart[] = [{ id: 'p1', type: 'text', text: 'Hello world' }]
+    // Replace the 5-char span starting at offset 6 ("world") with "there"
+    const next: TextPart = { id: 'p1', type: 'text', text: 'there', offset: 6 }
+    const [merged] = mergePart(parts, next)
+    expect(merged?.text).toBe('Hello there')
+  })
+
+  test('reasoning splices the same way as text', () => {
+    const parts = [{ id: 'p1', type: 'reasoning' as const, text: 'thinking' }]
+    const next = { id: 'p1', type: 'reasoning' as const, text: ' more' }
+    const [merged] = mergePart(parts, next)
+    expect(merged?.text).toBe('thinking more')
+  })
+
+  test('offset-0 full replay rebuilds an identical array — it does not double the content', () => {
+    // First pass: two deltas building "Hello world" from nothing.
+    let parts: TextPart[] = []
+    parts = mergePart(parts, { id: 'p1', type: 'text', text: 'Hello' })
+    parts = mergePart(parts, { id: 'p1', type: 'text', text: ' world', offset: 5 })
+    expect(parts).toHaveLength(1)
+    expect(parts[0]?.text).toBe('Hello world')
+    const firstPassResult = parts
+
+    // Replay from character 0: the whole run resent as one delta at offset 0.
+    const replayed = mergePart(parts, { id: 'p1', type: 'text', text: 'Hello world', offset: 0 })
+
+    expect(replayed).toHaveLength(1)
+    expect(replayed[0]?.text).toBe('Hello world')
+    expect(replayed).toEqual(firstPassResult.map((p) => ({ ...p, offset: 0 })))
+  })
+
+  // ── out-of-range offsets ───────────────────────────────────────────────────
+  // spliceText supports exactly two shapes (append at the end, in-range replace). Everything else
+  // is CLAMPED into [0, existing.text.length] with a dev warning — never thrown on, because a
+  // throw on the render path turns a transient wire anomaly into a permanently dead transcript.
+
+  test('an offset past the end of the existing text clamps to the tail (appends, leaves no hole)', () => {
+    const parts: TextPart[] = [{ id: 'p1', type: 'text', text: 'Hi' }]
+    const [merged] = mergePart(parts, { id: 'p1', type: 'text', text: '!', offset: 10 })
+    expect(merged?.text).toBe('Hi!')
+  })
+
+  test('a negative offset clamps to 0 rather than slicing from the end', () => {
+    const parts: TextPart[] = [{ id: 'p1', type: 'text', text: 'Hello world' }]
+    const [merged] = mergePart(parts, { id: 'p1', type: 'text', text: 'Hey', offset: -3 })
+    expect(merged?.text).toBe('Heylo world')
+  })
+
+  test('an out-of-order (already-covered) offset replaces in place — it never re-appends', () => {
+    // 'Hello world' is fully accumulated; a straggler delta for offset 6 arrives after the tail
+    // has moved past it. In-range, so it is honoured as a replace, not clamped.
+    const parts: TextPart[] = [{ id: 'p1', type: 'text', text: 'Hello world' }]
+    const [merged] = mergePart(parts, { id: 'p1', type: 'text', text: 'WORLD', offset: 6 })
+    expect(merged?.text).toBe('Hello WORLD')
+  })
+
+  test('a non-finite offset clamps to the tail rather than blanking the part', () => {
+    const parts: TextPart[] = [{ id: 'p1', type: 'text', text: 'Hi' }]
+    const [merged] = mergePart(parts, { id: 'p1', type: 'text', text: '!', offset: Number.NaN })
+    expect(merged?.text).toBe('Hi!')
+  })
+
+  test('a FIRST insertion with a nonzero offset clamps and warns like any other out-of-range one', () => {
+    // A first insertion splices against an EMPTY existing text, so the offset is out of range
+    // [0, 0]: mergePart never invents the 2 missing characters, it stores what arrived — but the
+    // anomaly is announced, exactly as it is for an existing part. One contract, one code path.
+    const warnings: string[] = []
+    const original = console.warn
+    console.warn = (...args: unknown[]) => void warnings.push(String(args[0]))
+    let first: TextPart[]
+    try {
+      first = mergePart<TextPart>([], { id: 'p1', type: 'text', text: 'llo', offset: 2 })
+    } finally {
+      console.warn = original
+    }
+    expect(warnings).toHaveLength(1)
+    expect(warnings[0]).toContain('out of range [0, 0]')
+    expect(first).toEqual([{ id: 'p1', type: 'text', text: 'llo', offset: 2 }])
+
+    // The offset rides along inert; the next delta for this id splices relative to the STORED text.
+    const [merged] = mergePart(first, { id: 'p1', type: 'text', text: ' there' })
+    expect(merged?.text).toBe('llo there')
+  })
+
+  test('a FIRST insertion with an in-range (0 or undefined) offset stays silent and stores the text as-is', () => {
+    const warnings: string[] = []
+    const original = console.warn
+    console.warn = (...args: unknown[]) => void warnings.push(String(args[0]))
+    try {
+      expect(mergePart<TextPart>([], { id: 'p1', type: 'text', text: 'Hello', offset: 0 })).toEqual(
+        [{ id: 'p1', type: 'text', text: 'Hello', offset: 0 }],
+      )
+      expect(mergePart<TextPart>([], { id: 'p2', type: 'text', text: 'Hello' })).toEqual([
+        { id: 'p2', type: 'text', text: 'Hello' },
+      ])
+    } finally {
+      console.warn = original
+    }
+    expect(warnings).toHaveLength(0)
+  })
+
+  test('warns in dev on an out-of-range offset, and stays silent on an in-range one', () => {
+    const warnings: string[] = []
+    const original = console.warn
+    console.warn = (...args: unknown[]) => void warnings.push(String(args[0]))
+    try {
+      const parts: TextPart[] = [{ id: 'p1', type: 'text', text: 'Hi' }]
+      mergePart(parts, { id: 'p1', type: 'text', text: '!', offset: 1 })
+      expect(warnings).toHaveLength(0)
+
+      mergePart(parts, { id: 'p1', type: 'text', text: '!', offset: 10 })
+      expect(warnings).toHaveLength(1)
+      expect(warnings[0]).toContain('out of range')
+    } finally {
+      console.warn = original
+    }
+  })
+
+  test('non-text/reasoning variants replace wholesale rather than merging fields', () => {
+    const parts: ToolCallPart[] = [
+      {
+        id: 'p1',
+        type: 'tool',
+        toolCallId: 'call-1',
+        toolName: 'search',
+        state: 'input-available',
+        input: { q: 'x' },
+      },
+    ]
+    const next: ToolCallPart = {
+      id: 'p1',
+      type: 'tool',
+      toolCallId: 'call-1',
+      toolName: 'search',
+      state: 'output-available',
+      input: { q: 'x' },
+      output: { hits: 3 },
+    }
+    expect(mergePart(parts, next)).toEqual([next])
+  })
+
+  test('a rewrite keeps the original position — ordering is stable', () => {
+    const parts: AgentPart[] = [
+      { id: 'a', type: 'text', text: 'first' },
+      { id: 'b', type: 'text', text: 'second' },
+      { id: 'c', type: 'text', text: 'third' },
+    ]
+    const next: AgentPart = { id: 'b', type: 'text', text: '!!', offset: 6 }
+    const merged = mergePart(parts, next)
+    expect(merged.map((p) => p.id)).toEqual(['a', 'b', 'c'])
+    expect((merged[1] as TextPart).text).toBe('second!!')
+  })
+
+  // B2 convergence fix: mergePart is constrained on PartLike (structural `id` + `type`), not the
+  // closed AgentPart union, precisely so a ForeignPart (never text-like) flows through the same
+  // accumulator. This is the compile-time contract `useAgentThreadRuns<TranscriptPart>` depends on.
+  test('a foreign part (never text-like) survives a round trip unchanged', () => {
+    const parts: TranscriptPart[] = []
+    const first = mergePart(parts, {
+      id: 'f1',
+      type: 'data-toolProgress',
+      tool: 'search',
+      message: 'searching',
+    })
+    expect(first).toEqual([
+      { id: 'f1', type: 'data-toolProgress', tool: 'search', message: 'searching' },
+    ])
+  })
+
+  test('a replayed foreign part (same id) replaces wholesale rather than duplicating', () => {
+    let parts: TranscriptPart[] = []
+    parts = mergePart(parts, { id: 'f1', type: 'data-toolProgress', message: 'searching' })
+    parts = mergePart(parts, { id: 'f1', type: 'data-toolProgress', message: 'done' })
+
+    expect(parts).toHaveLength(1)
+    expect(parts).toEqual([{ id: 'f1', type: 'data-toolProgress', message: 'done' }])
+  })
+})