basalt-ui 1.10.0 → 1.11.0

package/src/agent/foreign.test.ts

@@ -0,0 +1,47 @@
+/**
+ * foreign.ts — runtime coverage for `narrowAgentPart` (the cheap discriminator, distinct from the
+ * validating `parseAgentPart`) and `definePartRenderers` (identity passthrough, the canonical
+ * const-generic factory contract). Compile-time coverage for the `PartRenderers`/`ConsumerPart`
+ * exhaustiveness contract lives in the playground fixture
+ * (`apps/playground/src/demo/agent-part-registry.type-guard.ts`), not here.
+ */
+import { describe, expect, test } from 'bun:test'
+import { definePartRenderers, narrowAgentPart } from './foreign'
+import type { TranscriptPart } from './foreign'
+
+describe('narrowAgentPart', () => {
+  const BUILT_IN_SAMPLES: TranscriptPart[] = [
+    { id: 'p1', type: 'start', runId: 'r1' },
+    { id: 'p2', type: 'text', text: 'hi' },
+    { id: 'p3', type: 'reasoning', text: 'thinking' },
+    {
+      id: 'p4',
+      type: 'tool',
+      toolCallId: 'c1',
+      toolName: 'search',
+      state: 'input-available',
+      input: {},
+    },
+    { id: 'p5', type: 'source', url: 'https://example.com' },
+    { id: 'p6', type: 'error', message: 'boom' },
+  ]
+
+  for (const part of BUILT_IN_SAMPLES) {
+    test(`narrows a built-in '${part.type}' part`, () => {
+      expect(narrowAgentPart(part)).toBe(part)
+    })
+  }
+
+  test('returns null for a foreign part type', () => {
+    const foreign: TranscriptPart = { id: 'p7', type: 'data-chart', spec: {} }
+    expect(narrowAgentPart(foreign)).toBeNull()
+  })
+})
+
+describe('definePartRenderers', () => {
+  test('identity passthrough — returns the exact map it was given', () => {
+    const renderChart = (): null => null
+    const map = { 'data-chart': renderChart }
+    expect(definePartRenderers(map)).toBe(map)
+  })
+})

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,71 @@
+/**
+ * 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'
+
+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 () => {
+    const drafts = [
+      { 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 = [{ 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,43 @@
+/**
+ * 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'

package/src/agent/merge.test.ts

@@ -0,0 +1,119 @@
+/**
+ * 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 })))
+  })
+
+  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' }])
+  })
+})

package/src/agent/merge.ts

@@ -0,0 +1,67 @@
+/**
+ * mergePart — identity-addressed accumulator over a part array.
+ *
+ * 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.
+ *
+ * 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
+ * it. Splicing a full-length delta at offset 0 overwrites the existing text in place (the
+ * trailing slice covers nothing once the incoming text's length matches what's already there),
+ * so a resumed/replayed stream converges instead of duplicating content.
+ *
+ * Constrained on `PartLike` (structural: `id` + `type`), NOT `AgentPart` — a widened, backward-
+ * compatible relaxation so `TranscriptPart` (`AgentPart | ForeignPart`, ./foreign) flows through
+ * the same accumulator a transport-streamed foreign part must pass through on its way from the
+ * transport into `useAgentThreadRuns`'s `runs` map. `AgentPart`'s closed union is untouched —
+ * only the constraint widens, never the union itself.
+ *
+ * @example
+ * let parts: AgentPart[] = []
+ * parts = mergePart(parts, { id: 'p1', type: 'text', text: 'Hel' })
+ * parts = mergePart(parts, { id: 'p1', type: 'text', text: 'lo' }) // splices at the tail
+ * // parts === [{ id: 'p1', type: 'text', text: 'Hello' }]
+ */
+import type { ReasoningPart, TextPart } from './parts'
+
+type TextLike = TextPart | ReasoningPart
+
+/** The structural bound `mergePart` (and the hooks that call it) actually need — an `AgentPart` or
+ * a `ForeignPart` both satisfy it, so this is the widened constraint, not a new closed union. */
+export type PartLike = { readonly id: string; readonly type: string }
+
+// Widened from `AgentPart['type']` to `string`: a plain type-predicate narrowing, so accepting a
+// wider input (any string, including a ForeignPart's) is safe — it still only returns true for the
+// two text-like literals, and a ForeignPart's type string always falls through it to the
+// wholesale-replace path below.
+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)
+}
+
+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 = parts[index] as TPart
+  const spliceable = existing.type === next.type && isTextLikeType(next.type)
+
+  const merged: TPart = spliceable
+    ? ({
+        ...next,
+        text: spliceText(existing as unknown as TextLike, next as unknown as TextLike),
+      } as TPart)
+    : next
+
+  const out = parts.slice()
+  out[index] = merged
+  return out
+}

package/src/agent/part-list.test.tsx

@@ -0,0 +1,82 @@
+/**
+ * PartList's headless default tool-call renderer — a failed/denied call must stay visible.
+ *
+ * Regression coverage: after the seven-state ToolCallPart split, `output-error` carries no
+ * `output` field, so the old `part.state === 'output-available'`-only body left a failed call
+ * rendering as name+input and nothing else — the failure was silently invisible. Same gap for
+ * `output-denied`, indistinguishable from a still-pending call.
+ */
+import { cleanup, render, screen } from '@testing-library/react'
+import { afterEach, describe, expect, test } from 'bun:test'
+import { PartList } from './part-list'
+import type { ToolCallPart } from './parts'
+
+afterEach(cleanup)
+
+const BASE = { id: 'p1', type: 'tool' as const, toolCallId: 'c1', toolName: 'search' }
+
+describe('DefaultToolCall — terminal states stay visible', () => {
+  test('output-error renders the errorText', () => {
+    const part: ToolCallPart = { ...BASE, state: 'output-error', errorText: 'boom' }
+    render(<PartList parts={[part]} />)
+    expect(screen.getByText('boom')).not.toBeNull()
+  })
+
+  test('output-error with no validated input falls back to rendering rawInput', () => {
+    const part: ToolCallPart = {
+      ...BASE,
+      state: 'output-error',
+      errorText: 'boom',
+      rawInput: { q: 'x' },
+    }
+    render(<PartList parts={[part]} />)
+    expect(screen.getByText(/"q": "x"/)).not.toBeNull()
+  })
+
+  test('output-error with validated input present does not also render rawInput', () => {
+    const part: ToolCallPart = {
+      ...BASE,
+      state: 'output-error',
+      errorText: 'boom',
+      input: { q: 'x' },
+      rawInput: { q: 'stale' },
+    }
+    render(<PartList parts={[part]} />)
+    expect(screen.queryByText(/stale/)).toBeNull()
+  })
+
+  test('output-denied is visibly denied, not indistinguishable from a pending call', () => {
+    const part: ToolCallPart = {
+      ...BASE,
+      state: 'output-denied',
+      input: { q: 'x' },
+      approval: { id: 'a1', approved: false, reason: 'too risky' },
+    }
+    render(<PartList parts={[part]} />)
+    expect(screen.getByText(/Denied/)).not.toBeNull()
+    expect(screen.getByText(/too risky/)).not.toBeNull()
+  })
+
+  test('output-denied with no reason still renders a visible denial', () => {
+    const part: ToolCallPart = {
+      ...BASE,
+      state: 'output-denied',
+      input: { q: 'x' },
+      approval: { id: 'a1', approved: false },
+    }
+    render(<PartList parts={[part]} />)
+    expect(screen.getByText('Denied')).not.toBeNull()
+  })
+
+  test('output-available is unaffected — still renders output, no error/denied line', () => {
+    const part: ToolCallPart = {
+      ...BASE,
+      state: 'output-available',
+      input: { q: 'x' },
+      output: { hits: 3 },
+    }
+    render(<PartList parts={[part]} />)
+    expect(screen.getByText(/"hits": 3/)).not.toBeNull()
+    expect(screen.queryByText(/Denied/)).toBeNull()
+  })
+})