basalt-ui 1.11.0 → 1.13.0

package/src/agent/coalesce.ts

@@ -12,10 +12,26 @@
  * wire, the SDK re-supplies `input` by reading it back off the stored invocation, and a merge that
  * replaces wholesale rather than accumulating would lose it outright.
  *
- * `approval`-bearing responses can arrive without a usable `toolCallId` (the SDK resolves them by
- * reverse lookup on `approval.id` instead) — this maintains an `approvalId -> toolCallId` side
- * index while folding and routes such a part through it. A part resolvable by neither key is kept
- * as-is rather than dropped; never silently discard a part.
+ * A settled tool part can arrive without a `toolCallId` at all — `approval-responded` plus the
+ * three terminal states all carry it as optional (see `MaybeIdentified` in `parts.ts`).
+ * `approval-responded` is where the WIRE itself omits it: the SDK's `tool-approval-response` chunk
+ * carries no `toolCallId`, only `approval.id`, so it is resolved by reverse lookup on `approval.id`
+ * instead — this maintains an `approvalId -> toolCallId` side index while folding and routes such a
+ * part through it. A part resolvable by neither key is kept as-is rather than dropped; never
+ * silently discard a part.
+ *
+ * The fold is strictly LEFT-TO-RIGHT with no backtracking: the side index only holds ids seen so
+ * far, so an unidentified `approval-responded` arriving BEFORE its `approval-requested` stays its
+ * own block and the later request opens a second one. That is deliberate, not an oversight —
+ * reconciling backwards would let the request (the later arrival) win under the "later state wins"
+ * rule and render an already-answered call as still pending, which is worse than two blocks in an
+ * ordering the wire never produces.
+ *
+ * **This function never throws.** It is public, it runs on the render path, and it folds data that
+ * came off a wire — so every anomaly (an unrecognized tool state, an unresolvable id) degrades to
+ * "keep the part as it arrived", announced in dev, rather than aborting the render. A throw here
+ * would turn one malformed chunk into a permanently dead transcript. Exhaustiveness over the tool
+ * states is still enforced, but at COMPILE time only (see `mergeToolPart`'s default branch).
  *
  * @example
  * import { coalesceParts } from 'basalt-ui/agent'
@@ -35,7 +51,7 @@ function resolveToolCallId(
   part: ToolCallPart,
   toolCallIdByApprovalId: Map<string, string>,
 ): string | undefined {
-  if (typeof part.toolCallId === 'string' && part.toolCallId.length > 0) return part.toolCallId
+  if (part.toolCallId !== undefined) return part.toolCallId
   const approval = 'approval' in part ? part.approval : undefined
   return approval !== undefined ? toolCallIdByApprovalId.get(approval.id) : undefined
 }
@@ -48,24 +64,119 @@ function registerApprovalIndex(
 ): void {
   const approval = 'approval' in part ? part.approval : undefined
   if (approval === undefined) return
-  if (typeof part.toolCallId !== 'string' || part.toolCallId.length === 0) return
+  if (part.toolCallId === undefined) return
   toolCallIdByApprovalId.set(approval.id, part.toolCallId)
 }
 
-/** The later state always wins; `input`/`toolName` from the earlier state survive a later state
- * that omits them. */
+/**
+ * The later state always wins; `toolCallId`/`toolName`/`durationMs`/`providerExecuted` and `input`
+ * from the earlier state survive a later state that omits them.
+ *
+ * The result is RECONSTRUCTED per `next.state`, building only the fields that state legally has —
+ * never a blind `{ ...existing, ...next }` spread. A spread lets any field the next state does not
+ * redeclare survive onto it: an `output-available` (with `output`, possibly `preliminary`) that
+ * fails to `output-error` (which has no `output` key) would keep a stale `output` alongside
+ * `errorText`, and a consumer branching on `output` before `errorText` renders a failed call as
+ * successful. Only the fields listed above are carried; `output`, `errorText`, `rawInput`,
+ * `preliminary` and `approval` come from `next` alone, so nothing from a prior state can leak into
+ * a member that has no room for it. Reconstruction is exact enough that tsc proves each returned
+ * member valid — there is deliberately no cast here.
+ */
 function mergeToolPart(existing: ToolCallPart, next: ToolCallPart): ToolCallPart {
   const existingInput = 'input' in existing ? existing.input : undefined
   const nextInput = 'input' in next ? next.input : undefined
   const input = nextInput !== undefined ? nextInput : existingInput
-  const toolName = next.toolName.length > 0 ? next.toolName : existing.toolName
+  const durationMs = next.durationMs ?? existing.durationMs
+  const providerExecuted = next.providerExecuted ?? existing.providerExecuted
+  // `toolCallId` is optional on the four settled states (see `MaybeIdentified` in parts.ts), so a
+  // later part that arrived unidentified — resolved here through the approvalId side index — keeps
+  // the identity an earlier state supplied instead of losing it on the way through the merge.
+  const settledToolCallId = next.toolCallId ?? existing.toolCallId
+
+  const common = {
+    id: next.id,
+    type: 'tool' as const,
+    toolName: next.toolName.length > 0 ? next.toolName : existing.toolName,
+    ...(durationMs !== undefined ? { durationMs } : {}),
+    ...(providerExecuted !== undefined ? { providerExecuted } : {}),
+  }
 
-  return {
-    ...existing,
-    ...next,
-    toolName,
-    ...(input !== undefined ? { input } : {}),
-  } as ToolCallPart
+  switch (next.state) {
+    case 'input-streaming':
+      return {
+        ...common,
+        toolCallId: next.toolCallId,
+        state: 'input-streaming',
+        ...(input !== undefined ? { input } : {}),
+      }
+    case 'input-available':
+      return { ...common, toolCallId: next.toolCallId, state: 'input-available', input }
+    case 'approval-requested':
+      return {
+        ...common,
+        toolCallId: next.toolCallId,
+        state: 'approval-requested',
+        input,
+        approval: next.approval,
+      }
+    case 'approval-responded':
+      return {
+        ...common,
+        ...(settledToolCallId !== undefined ? { toolCallId: settledToolCallId } : {}),
+        state: 'approval-responded',
+        input,
+        approval: next.approval,
+      }
+    case 'output-available':
+      return {
+        ...common,
+        ...(settledToolCallId !== undefined ? { toolCallId: settledToolCallId } : {}),
+        state: 'output-available',
+        input,
+        output: next.output,
+        ...(next.preliminary !== undefined ? { preliminary: next.preliminary } : {}),
+        ...(next.approval !== undefined ? { approval: next.approval } : {}),
+      }
+    case 'output-error':
+      return {
+        ...common,
+        ...(settledToolCallId !== undefined ? { toolCallId: settledToolCallId } : {}),
+        state: 'output-error',
+        errorText: next.errorText,
+        ...(input !== undefined ? { input } : {}),
+        ...(next.rawInput !== undefined ? { rawInput: next.rawInput } : {}),
+        ...(next.approval !== undefined ? { approval: next.approval } : {}),
+      }
+    case 'output-denied':
+      return {
+        ...common,
+        ...(settledToolCallId !== undefined ? { toolCallId: settledToolCallId } : {}),
+        state: 'output-denied',
+        input,
+        approval: next.approval,
+      }
+    default: {
+      // Exhaustive at COMPILE time, defensive at RUNTIME. Binding `next` at `never` keeps tsc's
+      // guarantee — add a state to `ToolCallPart` without a case above and this line stops
+      // compiling — but this branch must NOT throw. `coalesceParts` is public, runs on the render
+      // path, and folds wire data: a throw would turn one transient wire anomaly into a
+      // permanently dead transcript (the same trade `spliceText` makes in merge.ts, where an
+      // out-of-range offset is clamped rather than thrown on). An unrecognized state therefore
+      // falls back to the incoming part with only the whitelisted carry-over fields folded in —
+      // nothing state-specific from `existing` can leak, because `common` is all that is merged.
+      const unhandled: never = next
+      // Widened back deliberately: control-flow analysis would keep an annotated const at `never`
+      // and make every field read below a compile error, so the assertion is what makes the
+      // runtime value usable. It asserts nothing tsc has not already proved on the line above.
+      const fallback = unhandled as ToolCallPart
+      if (process.env['NODE_ENV'] !== 'production') {
+        console.warn(
+          `[basalt] coalesceParts: unrecognized tool state ${JSON.stringify(fallback.state)} — kept, merged best-effort`,
+        )
+      }
+      return { ...fallback, ...common }
+    }
+  }
 }
 
 export function coalesceParts<TPart extends AgentPart>(parts: readonly TPart[]): TPart[] {

package/src/agent/foreign.test.ts

@@ -8,9 +8,13 @@
 import { describe, expect, test } from 'bun:test'
 import { definePartRenderers, narrowAgentPart } from './foreign'
 import type { TranscriptPart } from './foreign'
+import type { AgentPart } from './parts'
 
 describe('narrowAgentPart', () => {
-  const BUILT_IN_SAMPLES: TranscriptPart[] = [
+  // Typed AgentPart[], not TranscriptPart[]: every literal here IS a built-in variant (the whole
+  // point of this fixture), and narrowAgentPart's return type is AgentPart | null — comparing it
+  // against a TranscriptPart-typed element (which also admits ForeignPart) doesn't type-check.
+  const BUILT_IN_SAMPLES: AgentPart[] = [
     { id: 'p1', type: 'start', runId: 'r1' },
     { id: 'p2', type: 'text', text: 'hi' },
     { id: 'p3', type: 'reasoning', text: 'thinking' },

package/src/agent/id.test.ts

@@ -1,9 +1,16 @@
 /**
  * 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).
+ *
+ * mintThreadId/mintMessageId — the two id-minting helpers behind every unguarded
+ * `crypto.randomUUID()` call site this file's siblings used to have. Both share rungs 1
+ * (`crypto.randomUUID`) and 2 (`crypto.getRandomValues`, hand-assembled into a UUIDv4); they
+ * deliberately diverge on rung 3 (no crypto at all) — `mintThreadId` degrades, `mintMessageId`
+ * throws. See each function's own doc for why.
  */
 import { describe, expect, test } from 'bun:test'
-import { withPartIds } from './id'
+import { mintMessageId, mintThreadId, withPartIds } from './id'
+import type { AgentPartDraft } from './parts'
 
 async function* gen<T>(values: T[]): AsyncGenerator<T> {
   for (const value of values) yield value
@@ -15,9 +22,39 @@ async function collect<T>(source: AsyncGenerator<T>): Promise<T[]> {
   return out
 }
 
+const UUID_V4_RE = /^[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/i
+
+/** Rung 2: randomUUID absent, getRandomValues present (a real, non-secure-context host). */
+function withRung2Crypto<T>(run: () => T): T {
+  const originalCrypto = globalThis.crypto
+  Object.defineProperty(globalThis, 'crypto', {
+    value: { getRandomValues: originalCrypto.getRandomValues.bind(originalCrypto) },
+    configurable: true,
+  })
+  try {
+    return run()
+  } finally {
+    Object.defineProperty(globalThis, 'crypto', { value: originalCrypto, configurable: true })
+  }
+}
+
+/** Rung 3: no usable crypto at all. */
+function withRung3Crypto<T>(run: () => T): T {
+  const originalCrypto = globalThis.crypto
+  Object.defineProperty(globalThis, 'crypto', { value: undefined, configurable: true })
+  try {
+    return run()
+  } finally {
+    Object.defineProperty(globalThis, 'crypto', { value: originalCrypto, configurable: true })
+  }
+}
+
 describe('withPartIds', () => {
   test('stamps a sequential id on every draft missing one', async () => {
-    const drafts = [
+    // 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' },
@@ -37,7 +74,7 @@ describe('withPartIds', () => {
   })
 
   test('is idempotent: re-running withPartIds over already-identified parts changes nothing', async () => {
-    const drafts = [{ type: 'text', text: 'a' }]
+    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)
@@ -69,3 +106,64 @@ describe('withPartIds', () => {
     ])
   })
 })
+
+describe('mintThreadId', () => {
+  test('rung 1 (crypto.randomUUID): returns a valid UUIDv4 string', () => {
+    const id = mintThreadId()
+    expect(id).toMatch(UUID_V4_RE)
+  })
+
+  test('rung 1: many mints are distinct', () => {
+    const ids = Array.from({ length: 1000 }, () => mintThreadId())
+    expect(new Set(ids).size).toBe(1000)
+  })
+
+  test('rung 2 (getRandomValues only): assembles a valid UUIDv4 — version/variant bits set', () => {
+    const id = withRung2Crypto(() => mintThreadId())
+    expect(id).toMatch(UUID_V4_RE)
+  })
+
+  test('rung 2: many mints are distinct', () => {
+    const ids = withRung2Crypto(() => Array.from({ length: 1000 }, () => mintThreadId()))
+    expect(new Set(ids).size).toBe(1000)
+  })
+
+  test('rung 3 (no usable crypto at all): does NOT throw, still returns distinct non-empty strings', () => {
+    const ids = withRung3Crypto(() => Array.from({ length: 50 }, () => mintThreadId()))
+    for (const id of ids) {
+      expect(typeof id).toBe('string')
+      expect(id.length).toBeGreaterThan(0)
+    }
+    // Weak (Date.now() + Math.random()), not cryptographically random — but still distinct across
+    // this many mints in one tick, since Math.random() varies even when Date.now() doesn't.
+    expect(new Set(ids).size).toBe(50)
+  })
+})
+
+describe('mintMessageId', () => {
+  test('rung 1 (crypto.randomUUID): returns a valid UUIDv4 string', () => {
+    const id = mintMessageId()
+    expect(id).toMatch(UUID_V4_RE)
+  })
+
+  test('rung 1: many mints are distinct', () => {
+    const ids = Array.from({ length: 1000 }, () => mintMessageId())
+    expect(new Set(ids).size).toBe(1000)
+  })
+
+  test('rung 2 (getRandomValues only): assembles a valid UUIDv4 — version/variant bits set', () => {
+    const id = withRung2Crypto(() => mintMessageId())
+    expect(id).toMatch(UUID_V4_RE)
+  })
+
+  test('rung 2: many mints are distinct', () => {
+    const ids = withRung2Crypto(() => Array.from({ length: 1000 }, () => mintMessageId()))
+    expect(new Set(ids).size).toBe(1000)
+  })
+
+  test('rung 3 (no usable crypto at all): THROWS rather than minting a non-random id', () => {
+    // Diverges from mintThreadId's rung 3 on purpose — appendMessage's idempotency key must never
+    // silently degrade to a non-collision-resistant id. See mintMessageId's own doc.
+    expect(() => withRung3Crypto(() => mintMessageId())).toThrow(/idempotency key/)
+  })
+})

package/src/agent/id.ts

@@ -1,3 +1,121 @@
+/**
+ * Id-minting helpers shared across the agent layer: `mintThreadId` (a low-stakes client-side id —
+ * threads, run/chat namespaces — used by `./thread`'s `createThreadsStore`, `./adapter`'s
+ * `createAdapterThreadsStore`/`threadsStoreAdapterContract`, `./use-agent-stream`'s per-send run
+ * id, and `aiSdkTransport`'s fixed chat id), `mintMessageId` (the higher-stakes id `appendMessage`
+ * treats as its only idempotency key), and `withPartIds` (stamps sequence ids onto streamed
+ * parts). Grouped here because they're the id-minting leaves every store/hook/transport in this
+ * layer sits above — not because they share a mechanism (`mintMessageId` deliberately diverges
+ * from `mintThreadId` on rung 3; see its own doc).
+ */
+
+/**
+ * Hand-assembles a UUIDv4 string from 16 random bytes — the shared rung-2 mechanism both
+ * `mintThreadId` and `mintMessageId` use once `crypto.randomUUID` is unavailable but
+ * `crypto.getRandomValues` still is. The version/variant bits are set per RFC 4122, since this
+ * rung hands back raw bytes, not a formatted UUID.
+ */
+function assembleUuidV4(bytes: Uint8Array): string {
+  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)}`
+}
+
+/**
+ * Mints a client-side id for a LOW-COLLISION-COST use: a thread id, a per-send run-id namespace, a
+ * fixed chat id — anything minted client-side that is NOT the idempotency key some write depends
+ * on. `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
+ *      via `assembleUuidV4`.
+ *   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 a caller never throws on such a host. It is acceptable ONLY because an id
+ *      minted here is minted a handful of times per client session and is not the idempotency key
+ *      any write depends on — `ThreadsStoreAdapter.appendMessage`'s idempotency key is the MESSAGE
+ *      id (see `mintMessageId`), not this one, so a collision on this rung costs a locally
+ *      merged/duplicated thread (or two runs sharing a part-id namespace), not silent data loss on
+ *      the append path. Do not reuse this rung for anything with a higher collision cost than that
+ *      — see `mintMessageId` for the id that needs one.
+ */
+export function mintThreadId(): string {
+  if (typeof crypto !== 'undefined' && typeof crypto.randomUUID === 'function') {
+    return crypto.randomUUID()
+  }
+  if (typeof crypto !== 'undefined' && typeof crypto.getRandomValues === 'function') {
+    return assembleUuidV4(crypto.getRandomValues(new Uint8Array(16)))
+  }
+  return `id-${Date.now().toString(36)}-${Math.random().toString(36).slice(2)}`
+}
+
+/**
+ * Mints a message id — the value `ThreadsStoreAdapter.appendMessage` treats as its ONLY
+ * idempotency key (see that method's contract doc in `./adapter`). Shares `mintThreadId`'s rungs
+ * 1-2 (`crypto.randomUUID()`, then `crypto.getRandomValues()` assembled into a UUIDv4) — both are
+ * cryptographically random and collision-resistant, and rung 2 is the fix that actually matters in
+ * practice (a plain-HTTP/LAN host still has `getRandomValues`; only `randomUUID` is secure-context-
+ * gated).
+ *
+ * Rung 3 deliberately DIVERGES from `mintThreadId`: it THROWS instead of degrading to a
+ * non-random fallback. A thread id's rung-3 collision costs a locally merged/duplicated thread —
+ * annoying, recoverable, visible. A message id's collision cost is different IN KIND, not degree:
+ * `appendMessage` is idempotent on this id, so two messages that collide are not two rows, they
+ * are ONE — the second write silently no-ops and its content is gone, with nothing downstream able
+ * to tell. Degrading here would trade a loud, debuggable failure for silent, permanent data loss.
+ *
+ * This deliberately diverges from this layer's other standing rule — render-path code degrades,
+ * never throws (`spliceText` clamps, `coalesceParts` degrades, a consumer fence renderer must not
+ * take the message down) — because minting a message id is NOT render-path code. It runs once, in
+ * the write path that constructs a message before handing it to a store (`start()`,
+ * `consumeAndFinalize`'s finalize step, `finalizeStop`, `aiSdkTransport`'s per-turn user message),
+ * never inside the per-chunk accumulation/render loop those functions guard. A host with no usable
+ * `crypto` at all (missing both `randomUUID` and `getRandomValues`) is vanishingly rare — no
+ * runtime with a DOM/fetch surface worth targeting ships without a Crypto object — and an uncaught
+ * throw here is a loud, debuggable failure rather than a message silently vanishing with no trace,
+ * but WHERE it surfaces differs by call site (audited, not assumed — this paragraph previously
+ * claimed a single shared catch handled all of them, which was false):
+ *   - `consumeAndFinalize`'s own assistantMessage mint runs inside that function's try/catch, so a
+ *     throw there is correctly turned into `onFailureStatus` ('error' from `start()`, 'interrupted'
+ *     from the mount-time resume) — a visibly stuck-then-settled run, as originally claimed.
+ *   - `useAgentThreadRuns.start()`'s userMessage mint runs BEFORE any state is touched
+ *     (`appendMessage`/`setStatus`/the controller registration all come after it), so a throw there
+ *     is a true no-op that propagates synchronously out of `start()` itself — not a stuck run at
+ *     all, since nothing ever started. See `UseAgentThreadRunsReturn.start`'s `@throws` doc.
+ *   - `finalizeStop`'s stoppedMessage mint is wrapped in its own try/catch precisely so a throw
+ *     here cannot wedge the thread at 'streaming' forever (stop() has already torn down this run's
+ *     bookkeeping by the time finalizeStop runs, so a second stop() is always a no-op) — see
+ *     `finalizeStop`'s doc for the guarded behavior and the resulting 'error' status.
+ * A stuck spinner is debuggable; silently discarded chat history is not — that half of the
+ * original claim stands regardless of which of the three paths above catches it.
+ *
+ * @throws {Error} when neither `crypto.randomUUID` nor `crypto.getRandomValues` is available.
+ */
+export function mintMessageId(): string {
+  if (typeof crypto !== 'undefined' && typeof crypto.randomUUID === 'function') {
+    return crypto.randomUUID()
+  }
+  if (typeof crypto !== 'undefined' && typeof crypto.getRandomValues === 'function') {
+    return assembleUuidV4(crypto.getRandomValues(new Uint8Array(16)))
+  }
+  throw new Error(
+    'mintMessageId: no usable crypto (both randomUUID and getRandomValues are unavailable) — ' +
+      'refusing to mint a non-random message id, since ThreadsStoreAdapter.appendMessage treats ' +
+      'this id as its only idempotency key and a collision would silently drop a message.',
+  )
+}
+
 /**
  * withPartIds — stamps a stable id onto every draft part arriving without one.
  *

package/src/agent/index.ts

@@ -113,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

@@ -57,6 +57,93 @@ describe('mergePart', () => {
     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[] = [
       {

package/src/agent/merge.ts

@@ -4,8 +4,11 @@
  * Appending a part whose `id` is already present in `parts` REWRITES that entry in place rather
  * than pushing a duplicate — ordering stays stable (a rewritten part keeps its original position).
  * `text`/`reasoning` splice the incoming delta into the existing text at `next.offset` (an
- * undefined offset means "append at the tail"); every other variant — including any `ForeignPart`,
- * which is never text-like — replaces wholesale.
+ * undefined offset means "append at the tail", and an out-of-range one is clamped rather than
+ * honoured — see `spliceText` for the exact supported shapes); every other variant — including any
+ * `ForeignPart`, which is never text-like — replaces wholesale. A FIRST insertion of a text-like
+ * part goes through the same splice against an empty text, so an offset that claims a prefix this
+ * accumulator never saw is clamped and warned about there too — never honoured, never padded.
  *
  * The invariant this holds, and the reason `offset` exists at all: replaying a whole run from
  * character 0 rebuilds the identical parts array it produced the first time — it cannot double
@@ -41,26 +44,70 @@ function isTextLikeType(type: string): type is TextLike['type'] {
   return type === 'text' || type === 'reasoning'
 }
 
-/** Splices `next`'s text into `existing`'s text at `next.offset` (tail-append when undefined). */
-function spliceText(existing: TextLike, next: TextLike): string {
-  const offset = next.offset ?? existing.text.length
-  return existing.text.slice(0, offset) + next.text + existing.text.slice(offset + next.text.length)
+/**
+ * Splices `next`'s text into `existingText` at `next.offset`. Exactly two shapes are supported,
+ * and they are the only two any basalt transport emits (`diffPart` always sets
+ * `offset = prevText.length`; `diffChunkStream` restarts its accumulator per call):
+ *
+ * 1. **append at the end** — `offset` undefined, or equal to `existingText.length`;
+ * 2. **in-range replace** — `0 <= offset <= existingText.length`, overwriting the span the
+ *    incoming text covers (this is what makes an offset-0 full replay converge instead of double).
+ *
+ * An offset outside that range — negative, past the current length, or non-finite — is **clamped**
+ * into `[0, existingText.length]`, not honoured and not thrown on. A throw here would turn a
+ * transient wire anomaly into a permanently dead transcript; this is stream-reduction code on the
+ * render path. Each clamp is announced in dev.
+ *
+ * A FIRST insertion (no entry with this id yet) runs through here too, against an empty
+ * `existingText`: the stored text is the incoming text either way, but a nonzero offset — the wire
+ * claiming text this accumulator never saw — is clamped to 0 and announced like any other
+ * out-of-range value rather than passing silently. `mergePart` never invents the missing prefix.
+ *
+ * Note what is NOT special-cased: an out-of-order delta whose offset is still in range is an
+ * ordinary in-range replace, so it overwrites whatever already occupies that span. `mergePart`
+ * has no way to tell a stale delta from a deliberate rewrite, and inventing one would break the
+ * offset-0 replay convergence this whole mechanism exists for.
+ */
+function spliceText(existingText: string, next: TextLike): string {
+  const offset = clampOffset(next.offset ?? existingText.length, existingText.length)
+  return existingText.slice(0, offset) + next.text + existingText.slice(offset + next.text.length)
+}
+
+/** Clamps a wire offset into `[0, length]`, warning in dev when the raw value was out of range. */
+function clampOffset(offset: number, length: number): number {
+  // A non-finite offset would make every slice() return '' and blank the part outright — it is
+  // out of range like any other, and appending is the safe reading of "position unknown".
+  const clamped = Number.isFinite(offset) ? Math.min(Math.max(offset, 0), length) : length
+  if (clamped !== offset && process.env['NODE_ENV'] !== 'production') {
+    console.warn(
+      `[basalt] mergePart: text offset ${offset} out of range [0, ${length}] — clamped to ${clamped}`,
+    )
+  }
+  return clamped
 }
 
 export function mergePart<TPart extends PartLike>(parts: readonly TPart[], next: TPart): TPart[] {
   const index = parts.findIndex((part) => part.id === next.id)
-  if (index === -1) return [...parts, next]
+  const existing = index === -1 ? undefined : (parts[index] as TPart)
 
-  const existing = parts[index] as TPart
-  const spliceable = existing.type === next.type && isTextLikeType(next.type)
+  // A first insertion of a text-like part is spliced too — against an empty existing text — so the
+  // offset contract is one path with one set of rules: same clamp, same dev warning, and the same
+  // stored result (`'' + next.text`) an unconditional append would have produced.
+  const spliceable =
+    isTextLikeType(next.type) && (existing === undefined || existing.type === next.type)
 
   const merged: TPart = spliceable
     ? ({
         ...next,
-        text: spliceText(existing as unknown as TextLike, next as unknown as TextLike),
+        text: spliceText(
+          existing === undefined ? '' : (existing as unknown as TextLike).text,
+          next as unknown as TextLike,
+        ),
       } as TPart)
     : next
 
+  if (existing === undefined) return [...parts, merged]
+
   const out = parts.slice()
   out[index] = merged
   return out