basalt-ui 1.9.0 → 1.11.0

package/configs/oxlint-plugin.test.ts

@@ -8,7 +8,7 @@
  * binary and returns the parsed set of `basalt/<rule>` diagnostics it printed.
  */
 import { afterEach, beforeEach, describe, expect, it } from 'bun:test'
-import { mkdirSync, mkdtempSync, rmSync, writeFileSync } from 'node:fs'
+import { mkdirSync, mkdtempSync, readFileSync, rmSync, writeFileSync } from 'node:fs'
 import { tmpdir } from 'node:os'
 import { dirname, resolve } from 'node:path'
 
@@ -31,6 +31,9 @@ beforeEach(() => {
         'basalt/visx-boundary': 'error',
         'basalt/visx-tooltip': 'error',
         'basalt/token-layer-boundary': 'error',
+        'basalt/agent-resume-guard': 'error',
+        'basalt/agent-no-raw-usechat': 'error',
+        'basalt/ai-sdk-major': 'error',
       },
     }),
   )
@@ -232,3 +235,215 @@ describe('rule independence', () => {
     expect(rules).toContain('visx-tooltip')
   })
 })
+
+// ── agent-resume-guard ───────────────────────────────────────────────────────
+// The two agent rules honour a SEPARATE escape token, `basalt-agent-allow`, not `theme-allow` — a
+// color exemption must never be able to switch off a streaming guard. The `theme-allow` fixture
+// below proves the wrong token does not suppress the finding.
+
+describe('basalt/agent-resume-guard', () => {
+  it('flags useChat({ resume: true })', () => {
+    const { code, rules } = run(`const c = useChat({ id, resume: true })\n`)
+    expect(code).toBe(1)
+    expect(rules).toContain('agent-resume-guard')
+  })
+
+  it('does NOT flag useChat({ resume: false })', () => {
+    const { code, rules } = run(`const c = useChat({ id, resume: false })\n`)
+    expect(code).toBe(0)
+    expect(rules).not.toContain('agent-resume-guard')
+  })
+
+  it('does NOT flag a bare useChat({ id }) with no resume key', () => {
+    const { code, rules } = run(`const c = useChat({ id })\n`)
+    expect(code).toBe(0)
+    expect(rules).not.toContain('agent-resume-guard')
+  })
+
+  it('flags chat.resumeStream() called from an effect', () => {
+    const { code, rules } = run(`useEffect(() => { chat.resumeStream() }, [])\n`)
+    expect(code).toBe(1)
+    expect(rules).toContain('agent-resume-guard')
+  })
+
+  it('does NOT flag chat.resumeStream() marked basalt-agent-allow', () => {
+    const { code, rules } = run(`// basalt-agent-allow\nchat.resumeStream()\n`)
+    expect(code).toBe(0)
+    expect(rules).not.toContain('agent-resume-guard')
+  })
+
+  it('STILL flags chat.resumeStream() marked only theme-allow (wrong escape token)', () => {
+    const { code, rules } = run(`// theme-allow\nchat.resumeStream()\n`)
+    expect(code).toBe(1)
+    expect(rules).toContain('agent-resume-guard')
+  })
+
+  it('does NOT flag an unrelated call like runs.start(id, text)', () => {
+    const { code, rules } = run(`runs.start(id, text)\n`)
+    expect(code).toBe(0)
+    expect(rules).not.toContain('agent-resume-guard')
+  })
+})
+
+// ── agent-no-raw-usechat ─────────────────────────────────────────────────────
+
+describe('basalt/agent-no-raw-usechat', () => {
+  it('flags importing useChat from @ai-sdk/react', () => {
+    const { code, rules } = run(`import { useChat } from '@ai-sdk/react'\n`, 'lib.ts')
+    expect(code).toBe(1)
+    expect(rules).toContain('agent-no-raw-usechat')
+  })
+
+  it('flags importing useCompletion from @ai-sdk/react', () => {
+    const { code, rules } = run(`import { useCompletion } from '@ai-sdk/react'\n`, 'lib.ts')
+    expect(code).toBe(1)
+    expect(rules).toContain('agent-no-raw-usechat')
+  })
+
+  it('does NOT flag a type-only import of UIMessage from the same module', () => {
+    const { code, rules } = run(`import type { UIMessage } from '@ai-sdk/react'\n`, 'lib.ts')
+    expect(code).toBe(0)
+    expect(rules).not.toContain('agent-no-raw-usechat')
+  })
+
+  it('does NOT flag an unrelated import from ai', () => {
+    const { code, rules } = run(`import { DefaultChatTransport } from 'ai'\n`, 'lib.ts')
+    expect(code).toBe(0)
+    expect(rules).not.toContain('agent-no-raw-usechat')
+  })
+
+  it('does NOT flag useChat imported from a local module', () => {
+    const { code, rules } = run(`import { useChat } from './my-hooks'\n`, 'lib.ts')
+    expect(code).toBe(0)
+    expect(rules).not.toContain('agent-no-raw-usechat')
+  })
+
+  // The matcher covers TWO source specifiers (RAW_USE_CHAT_SOURCES: '@ai-sdk/react' AND
+  // 'ai/react') — every fixture above only exercises '@ai-sdk/react'; this pins the other half.
+  it("flags importing useChat from 'ai/react' (the other matched source)", () => {
+    const { code, rules } = run(`import { useChat } from 'ai/react'\n`, 'lib.ts')
+    expect(code).toBe(1)
+    expect(rules).toContain('agent-no-raw-usechat')
+  })
+
+  it('does NOT flag an import marked basalt-agent-allow', () => {
+    const { code, rules } = run(
+      `// basalt-agent-allow\nimport { useChat } from '@ai-sdk/react'\n`,
+      'lib.ts',
+    )
+    expect(code).toBe(0)
+    expect(rules).not.toContain('agent-no-raw-usechat')
+  })
+
+  it('STILL flags an import marked only theme-allow (wrong escape token)', () => {
+    const { code, rules } = run(
+      `// theme-allow\nimport { useChat } from '@ai-sdk/react'\n`,
+      'lib.ts',
+    )
+    expect(code).toBe(1)
+    expect(rules).toContain('agent-no-raw-usechat')
+  })
+})
+
+// ── ai-sdk-major ─────────────────────────────────────────────────────────────
+// The lint rule compares the LINTED FILE's nearest package.json against basalt-ui's own declared
+// `ai` peer major (read from packages/basalt-ui/package.json — the real file, since the plugin
+// resolves it relative to its own module location regardless of where it's invoked from). basalt-ui
+// declares "ai": "^7.0.15" (major 7) in both devDependencies and peerDependencies.
+
+describe('basalt/ai-sdk-major', () => {
+  it("flags when the nearest package.json declares a different ai major (5 vs basalt's 7)", () => {
+    writeFileSync(resolve(dir, 'package.json'), JSON.stringify({ dependencies: { ai: '5.0.196' } }))
+    const { code, rules } = run(`import { streamText } from 'ai'\n`, 'lib.ts')
+    expect(code).toBe(1)
+    expect(rules).toContain('ai-sdk-major')
+  })
+
+  it('does NOT flag when the nearest package.json declares the same major (^7.0.18)', () => {
+    writeFileSync(resolve(dir, 'package.json'), JSON.stringify({ dependencies: { ai: '^7.0.18' } }))
+    const { code, rules } = run(`import { streamText } from 'ai'\n`, 'lib.ts')
+    expect(code).toBe(0)
+    expect(rules).not.toContain('ai-sdk-major')
+  })
+
+  it('does NOT flag when there is no ai in the nearest package.json', () => {
+    writeFileSync(resolve(dir, 'package.json'), JSON.stringify({ dependencies: {} }))
+    const { code, rules } = run(`import { streamText } from 'ai'\n`, 'lib.ts')
+    expect(code).toBe(0)
+    expect(rules).not.toContain('ai-sdk-major')
+  })
+
+  it('does NOT flag an unrelated import even with a skewed nearest package.json', () => {
+    writeFileSync(resolve(dir, 'package.json'), JSON.stringify({ dependencies: { ai: '5.0.196' } }))
+    const { code, rules } = run(`import { useState } from 'react'\n`, 'lib.ts')
+    expect(code).toBe(0)
+    expect(rules).not.toContain('ai-sdk-major')
+  })
+
+  // The matcher covers TWO forms (source === 'ai' OR source.startsWith('@ai-sdk/')) — every
+  // fixture above only exercises the bare 'ai' specifier; this pins the scoped-package half.
+  it("flags a scoped '@ai-sdk/*' import when the nearest package.json declares a different ai major", () => {
+    writeFileSync(resolve(dir, 'package.json'), JSON.stringify({ dependencies: { ai: '5.0.196' } }))
+    const { code, rules } = run(`import { openai } from '@ai-sdk/openai'\n`, 'lib.ts')
+    expect(code).toBe(1)
+    expect(rules).toContain('ai-sdk-major')
+  })
+
+  it("does NOT flag a scoped '@ai-sdk/*' import when the nearest package.json declares the same major", () => {
+    writeFileSync(resolve(dir, 'package.json'), JSON.stringify({ dependencies: { ai: '^7.0.18' } }))
+    const { code, rules } = run(`import { openai } from '@ai-sdk/openai'\n`, 'lib.ts')
+    expect(code).toBe(0)
+    expect(rules).not.toContain('ai-sdk-major')
+  })
+
+  // Unlike the other rules in this file, ai-sdk-major honours `basalt-agent-allow` — the SAME
+  // token as its two agent-chat siblings above — not `theme-allow`. A skewed producer/consumer
+  // import that is genuinely intentional (see doctor's `aiMajorSkewReason`) can mark the line.
+  it('does NOT flag an import marked basalt-agent-allow, even with a skewed nearest package.json', () => {
+    writeFileSync(resolve(dir, 'package.json'), JSON.stringify({ dependencies: { ai: '5.0.196' } }))
+    const { code, rules } = run(
+      `// basalt-agent-allow\nimport { streamText } from 'ai'\n`,
+      'lib.ts',
+    )
+    expect(code).toBe(0)
+    expect(rules).not.toContain('ai-sdk-major')
+  })
+
+  it('STILL flags an import marked only theme-allow (wrong escape token)', () => {
+    writeFileSync(resolve(dir, 'package.json'), JSON.stringify({ dependencies: { ai: '5.0.196' } }))
+    const { code, rules } = run(`// theme-allow\nimport { streamText } from 'ai'\n`, 'lib.ts')
+    expect(code).toBe(1)
+    expect(rules).toContain('ai-sdk-major')
+  })
+})
+
+// ── raw-scroll-container — promotion (off → warn shipped) ────────────────────
+
+describe('basalt/raw-scroll-container promotion', () => {
+  it('ships "warn" (not "off") in the consumer preset', () => {
+    const shipped = JSON.parse(
+      readFileSync(resolve(import.meta.dirname, 'oxlint.json'), 'utf8'),
+    ) as { rules: Record<string, unknown> }
+    expect(shipped.rules['basalt/raw-scroll-container']).toBe('warn')
+  })
+
+  it('stays "warn" repo-local', () => {
+    const repoLocal = JSON.parse(
+      readFileSync(resolve(import.meta.dirname, '..', '..', '..', '.oxlintrc.json'), 'utf8'),
+    ) as { rules: Record<string, unknown> }
+    expect(repoLocal.rules['basalt/raw-scroll-container']).toBe('warn')
+  })
+
+  it('still flags a raw overflow:auto style property at the shipped level', () => {
+    writeFileSync(
+      resolve(dir, '.oxlintrc.json'),
+      JSON.stringify({
+        plugins: [],
+        jsPlugins: [PLUGIN_PATH],
+        rules: { 'basalt/raw-scroll-container': 'warn' },
+      }),
+    )
+    const { rules } = run(`const s = { overflowY: 'auto' }\n`, 'lib.ts')
+    expect(rules).toContain('raw-scroll-container')
+  })
+})

package/configs/oxlint.json

@@ -20,9 +20,12 @@
     "basalt/raw-size-literal": "warn",
     "basalt/card-inset": "error",
     "basalt/chart-in-raw-surface": "error",
-    "basalt/raw-scroll-container": "off",
+    "basalt/raw-scroll-container": "warn",
     "basalt/visx-boundary": "error",
-    "basalt/visx-tooltip": "error"
+    "basalt/visx-tooltip": "error",
+    "basalt/agent-resume-guard": "warn",
+    "basalt/agent-no-raw-usechat": "warn",
+    "basalt/ai-sdk-major": "warn"
   },
   "overrides": [
     {

package/dist/agent/ai-sdk-transport.d.ts

@@ -1,54 +1,5 @@
-/**
- * aiSdkTransport — an AgentTransport backed by Vercel AI SDK's native streaming + resumption
- * primitives (the `ai` npm package). This is the RECOMMENDED DEFAULT transport for LLM chat use
- * cases — edenTransport remains the zero-extra-dependency alternative (see agent/rules/basalt-agent.md).
- *
- * OPTIONAL PEER: `ai` is not a required dependency. Importing 'basalt-ui/agent' (and calling this
- * factory) does NOT eagerly resolve it — the package is loaded via a memoized dynamic import()
- * only when the first stream()/resume() call actually runs, mirroring the lazy-optional-peer
- * contract used by BasaltStickToBottom. Unlike that, there is no meaningful "plain text" fallback
- * for a missing transport: if 'ai' is not installed, the dynamic import
- * rejects and the error propagates through the async generator to the consumer's EXISTING error
- * handling (useAgentStream sets status: 'error'; useAgentThreadRuns falls back to its
- * onFailureStatus) — no separate crash path is introduced.
- *
- * Install the optional peer:
- *   bun add ai
- *
- * WHY DIFFING IS NEEDED: AI SDK's `readUIMessageStream` yields the FULL accumulated `UIMessage`
- * snapshot (a growing `parts` array, with existing parts' content growing in place) on every
- * update — it is not itself a delta stream. basalt-ui's whole part-accumulation model
- * (useAgentStream / useAgentThreadRuns, and every consumer's own coalescing) is delta-based: many
- * small parts merged at render time. This module diffs consecutive snapshots and yields only the
- * new deltas as AgentParts, so nothing is double-rendered.
- *
- * CHAT ID BINDING: AI SDK's convention is that the chat id is known client-side before the
- * request (unlike a river/server-minted id) — `aiSdkTransport(options)` mints ONE stable chat id
- * at construction time, so the returned object is immediately usable with useAgentStream (a single
- * ongoing conversation). `.forThread(threadId)` returns a transport bound to an arbitrary
- * caller-supplied id instead — pass a basalt-ui thread id here to plug into
- * useAgentThreadRuns's per-thread transport-factory form, so a thread's turns (and its mount-time
- * resume) share one continuous AI SDK chat session:
- *
- * @example
- * import { useAgentStream, aiSdkTransport } from 'basalt-ui/agent'
- *
- * const transport = aiSdkTransport({ api: '/api/chat' })
- * const { parts, status, send } = useAgentStream({ transport })
- *
- * @example
- * import { useAgentThreadRuns, aiSdkTransport, createThreadsStore, heuristicOutcome } from 'basalt-ui/agent'
- *
- * const useThreads = createThreadsStore({ key: 'main-threads', version: 1 })
- * const transport = aiSdkTransport({ api: '/api/chat' })
- * const { runs, start } = useAgentThreadRuns({
- *   transport: (threadId) => transport.forThread(threadId),
- *   store: useThreads(),
- *   resolveOutcome: heuristicOutcome,
- * })
- */
 import type { AgentPart } from './parts.js';
-import type { AgentTransport } from './transport.js';
+import type { ResumableAgentTransport } from './transport.js';
 export type AiSdkTransportOptions = {
     /** The API URL AI SDK's transport POSTs new turns to and GETs reconnects from. */
     readonly api: string;
@@ -62,13 +13,13 @@ export type AiSdkTransportOptions = {
      */
     readonly fetch?: typeof globalThis.fetch;
 };
-export type AiSdkTransport<TPart = AgentPart> = AgentTransport<TPart, string> & {
+export type AiSdkTransport<TPart = AgentPart> = ResumableAgentTransport<TPart, string> & {
     /**
      * Returns an AgentTransport bound to a stable chat id (e.g. a basalt-ui thread id) instead of
      * this transport's own fixed one. Use this for useAgentThreadRuns's per-thread transport-factory
      * form so each thread's turns share one continuous AI SDK chat session.
      */
-    readonly forThread: (chatId: string) => AgentTransport<TPart, string>;
+    readonly forThread: (chatId: string) => ResumableAgentTransport<TPart, string>;
 };
 /**
  * Wraps AI SDK's `DefaultChatTransport` + `readUIMessageStream` into an AgentTransport.

package/dist/agent/ai-sdk-transport.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"ai-sdk-transport.d.ts","sourceRoot":"","sources":["../../src/agent/ai-sdk-transport.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAgDG;AACH,OAAO,KAAK,EAAE,SAAS,EAA4B,MAAM,SAAS,CAAA;AAClE,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,aAAa,CAAA;AAYjD,MAAM,MAAM,qBAAqB,GAAG;IAClC,kFAAkF;IAClF,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAA;IACpB,+CAA+C;IAC/C,QAAQ,CAAC,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,GAAG,OAAO,CAAA;IACnD,oFAAoF;IACpF,QAAQ,CAAC,WAAW,CAAC,EAAE,kBAAkB,CAAA;IACzC;;;OAGG;IACH,QAAQ,CAAC,KAAK,CAAC,EAAE,OAAO,UAAU,CAAC,KAAK,CAAA;CACzC,CAAA;AAID,MAAM,MAAM,cAAc,CAAC,KAAK,GAAG,SAAS,IAAI,cAAc,CAAC,KAAK,EAAE,MAAM,CAAC,GAAG;IAC9E;;;;OAIG;IACH,QAAQ,CAAC,SAAS,EAAE,CAAC,MAAM,EAAE,MAAM,KAAK,cAAc,CAAC,KAAK,EAAE,MAAM,CAAC,CAAA;CACtE,CAAA;AA8ID;;;;;;;;;;GAUG;AACH,wBAAgB,cAAc,CAAC,KAAK,GAAG,SAAS,EAC9C,OAAO,EAAE,qBAAqB,GAC7B,cAAc,CAAC,KAAK,CAAC,CAuCvB"}
+{"version":3,"file":"ai-sdk-transport.d.ts","sourceRoot":"","sources":["../../src/agent/ai-sdk-transport.ts"],"names":[],"mappings":"AAmDA,OAAO,KAAK,EAAE,SAAS,EAAkB,MAAM,SAAS,CAAA;AACxD,OAAO,KAAK,EAAE,uBAAuB,EAAE,MAAM,aAAa,CAAA;AAmB1D,MAAM,MAAM,qBAAqB,GAAG;IAClC,kFAAkF;IAClF,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAA;IACpB,+CAA+C;IAC/C,QAAQ,CAAC,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,GAAG,OAAO,CAAA;IACnD,oFAAoF;IACpF,QAAQ,CAAC,WAAW,CAAC,EAAE,kBAAkB,CAAA;IACzC;;;OAGG;IACH,QAAQ,CAAC,KAAK,CAAC,EAAE,OAAO,UAAU,CAAC,KAAK,CAAA;CACzC,CAAA;AAID,MAAM,MAAM,cAAc,CAAC,KAAK,GAAG,SAAS,IAAI,uBAAuB,CAAC,KAAK,EAAE,MAAM,CAAC,GAAG;IACvF;;;;OAIG;IACH,QAAQ,CAAC,SAAS,EAAE,CAAC,MAAM,EAAE,MAAM,KAAK,uBAAuB,CAAC,KAAK,EAAE,MAAM,CAAC,CAAA;CAC/E,CAAA;AAwRD;;;;;;;;;;GAUG;AACH,wBAAgB,cAAc,CAAC,KAAK,GAAG,SAAS,EAC9C,OAAO,EAAE,qBAAqB,GAC7B,cAAc,CAAC,KAAK,CAAC,CA6CvB"}

package/dist/agent/ai-sdk-transport.js

@@ -1,3 +1,5 @@
+import { assertNever } from "../register.js";
+import { TERMINAL_TOOL_STATES } from "./parts.js";
 function createAiSdkResolver(options) {
   let resolved;
   return function resolveAiSdk() {
@@ -15,55 +17,133 @@ function createAiSdkResolver(options) {
     return resolved;
   };
 }
-function diffPart(prevPart, currPart) {
+function diffPart(chatId, index, prevPart, currPart, toolStartTimes) {
   switch (currPart.type) {
     case "text": {
       const prevText = prevPart?.type === "text" ? prevPart.text : "";
       const delta = currPart.text.slice(prevText.length);
-      return delta.length === 0 ? [] : [{ type: "text", text: delta }];
+      return delta.length === 0 ? [] : [{ id: `${chatId}#${index}`, type: "text", text: delta, offset: prevText.length }];
     }
     case "reasoning": {
       const prevText = prevPart?.type === "reasoning" ? prevPart.text : "";
       const delta = currPart.text.slice(prevText.length);
-      return delta.length === 0 ? [] : [{ type: "reasoning", text: delta }];
+      return delta.length === 0 ? [] : [{ id: `${chatId}#${index}`, type: "reasoning", text: delta, offset: prevText.length }];
     }
     case "source-url": {
       if (prevPart !== void 0) return [];
-      const source = { type: "source", url: currPart.url };
+      const source = { id: `${chatId}#${index}`, type: "source", url: currPart.url };
       return [currPart.title !== void 0 ? { ...source, title: currPart.title } : source];
     }
     default:
-      return currPart.type.startsWith("tool-") ? diffToolPart(prevPart, currPart) : [];
+      return isToolLikePart(currPart) ? diffToolPart(prevPart, currPart, toolStartTimes) : [];
   }
 }
-function diffToolPart(prevPart, currPart) {
-  const curr = currPart;
-  if (curr.state === "input-streaming") return [];
-  const prev = prevPart !== void 0 && prevPart.type === currPart.type ? prevPart : void 0;
-  if (prev?.state === curr.state) return [];
-  const toolName = curr.type.slice("tool-".length);
+function isToolLikePart(part) {
+  return part.type === "dynamic-tool" || part.type.startsWith("tool-");
+}
+function deriveToolName(part) {
+  return part.type === "dynamic-tool" ? part.toolName : part.type.split("-").slice(1).join("-");
+}
+function outputSnapshot(part) {
+  return part.state === "output-available" ? { output: part.output, preliminary: part.preliminary } : void 0;
+}
+function isSameToolState(prev, curr) {
+  if (prev.state !== curr.state) return false;
+  const prevOutput = outputSnapshot(prev);
+  const currOutput = outputSnapshot(curr);
+  if (prevOutput === void 0 || currOutput === void 0) return true;
+  return JSON.stringify(prevOutput.output) === JSON.stringify(currOutput.output) && prevOutput.preliminary === currOutput.preliminary;
+}
+function diffToolPart(prevPart, currPart, toolStartTimes) {
+  if (!toolStartTimes.has(currPart.toolCallId)) {
+    toolStartTimes.set(currPart.toolCallId, Date.now());
+  }
+  const prev = prevPart !== void 0 && isToolLikePart(prevPart) ? prevPart : void 0;
+  if (prev !== void 0 && isSameToolState(prev, currPart)) return [];
+  const settled = TERMINAL_TOOL_STATES.includes(currPart.state);
+  const durationMs = settled ? Date.now() - (toolStartTimes.get(currPart.toolCallId) ?? Date.now()) : void 0;
   const base = {
+    id: `tool#${currPart.toolCallId}`,
     type: "tool",
-    toolName,
-    toolCallId: curr.toolCallId,
-    input: curr.input
+    toolCallId: currPart.toolCallId,
+    toolName: deriveToolName(currPart),
+    ...currPart.providerExecuted !== void 0 ? { providerExecuted: currPart.providerExecuted } : {},
+    ...durationMs !== void 0 ? { durationMs } : {}
   };
-  if (curr.state === "output-available") return [{ ...base, output: curr.output }];
-  if (curr.state === "output-error") return [{ ...base, output: { error: curr.errorText } }];
-  return [base];
+  switch (currPart.state) {
+    case "input-streaming":
+      return [
+        {
+          ...base,
+          state: "input-streaming",
+          ...currPart.input !== void 0 ? { input: currPart.input } : {}
+        }
+      ];
+    case "input-available":
+      return [{ ...base, state: "input-available", input: currPart.input }];
+    case "approval-requested":
+      return [
+        {
+          ...base,
+          state: "approval-requested",
+          input: currPart.input,
+          approval: currPart.approval
+        }
+      ];
+    case "approval-responded":
+      return [
+        {
+          ...base,
+          state: "approval-responded",
+          input: currPart.input,
+          approval: currPart.approval
+        }
+      ];
+    case "output-available":
+      return [
+        {
+          ...base,
+          state: "output-available",
+          input: currPart.input,
+          output: currPart.output,
+          ...currPart.preliminary !== void 0 ? { preliminary: currPart.preliminary } : {},
+          ...currPart.approval !== void 0 ? { approval: currPart.approval } : {}
+        }
+      ];
+    case "output-error": {
+      const rawInput = currPart.type === "dynamic-tool" ? void 0 : currPart.rawInput;
+      return [
+        {
+          ...base,
+          state: "output-error",
+          ...currPart.input !== void 0 ? { input: currPart.input } : {},
+          errorText: currPart.errorText,
+          ...rawInput !== void 0 ? { rawInput } : {},
+          ...currPart.approval !== void 0 ? { approval: currPart.approval } : {}
+        }
+      ];
+    }
+    case "output-denied":
+      return [
+        { ...base, state: "output-denied", input: currPart.input, approval: currPart.approval }
+      ];
+    default:
+      return assertNever(currPart);
+  }
 }
-function diffMessage(prev, curr) {
+function diffMessage(chatId, prev, curr, toolStartTimes) {
   const deltas = [];
   curr.parts.forEach((part, i) => {
-    deltas.push(...diffPart(prev?.parts[i], part));
+    deltas.push(...diffPart(chatId, i, prev?.parts[i], part, toolStartTimes));
   });
   return deltas;
 }
-async function* diffChunkStream(chunkStream, readStream, signal) {
+async function* diffChunkStream(chatId, chunkStream, readStream, signal) {
   let prev;
+  const toolStartTimes = /* @__PURE__ */ new Map();
   for await (const curr of readStream({ stream: chunkStream })) {
     if (signal?.aborted) return;
-    for (const part of diffMessage(prev, curr)) {
+    for (const part of diffMessage(chatId, prev, curr, toolStartTimes)) {
       yield part;
     }
     prev = curr;
@@ -73,8 +153,12 @@ function aiSdkTransport(options) {
   const resolveAiSdk = createAiSdkResolver(options);
   function makeTransport(chatId) {
     return {
+      // Every text/reasoning delta this transport emits carries an authoritative `offset` (see
+      // diffPart), so a replayed run rewrites in place instead of duplicating — the literal
+      // condition this assertion stands for.
+      idempotentReplay: true,
       async *stream(input, signal) {
-        yield { type: "start", runId: chatId, resumeToken: chatId };
+        yield { id: `${chatId}#start`, type: "start", runId: chatId, resumeToken: chatId };
         const { httpTransport, readUIMessageStream: readStream } = await resolveAiSdk();
         const userMessage = {
           id: crypto.randomUUID(),
@@ -88,13 +172,13 @@ function aiSdkTransport(options) {
           messageId: void 0,
           abortSignal: signal
         });
-        yield* diffChunkStream(chunkStream, readStream, signal);
+        yield* diffChunkStream(chatId, chunkStream, readStream, signal);
       },
       async *resume(resumeToken, signal) {
         const { httpTransport, readUIMessageStream: readStream } = await resolveAiSdk();
         const chunkStream = await httpTransport.reconnectToStream({ chatId: resumeToken });
         if (chunkStream === null) return;
-        yield* diffChunkStream(chunkStream, readStream, signal);
+        yield* diffChunkStream(resumeToken, chunkStream, readStream, signal);
       }
     };
   }

package/dist/agent/coalesce.d.ts

@@ -0,0 +1,26 @@
+/**
+ * coalesceParts — merges a rendered-turn's parts array for display.
+ *
+ * Merges consecutive `text`+`text` and `reasoning`+`reasoning` parts (streamed answers arrive as
+ * many small fragments; this renders a streaming reply as one flowing block instead of a stack of
+ * fragments). Merges `tool` parts BY `toolCallId` regardless of adjacency — the AI SDK re-emits a
+ * tool call's `input-available` then `output-available` as two separate parts, not necessarily
+ * adjacent once other parts interleave; without this rule a UI renders two stacked tool blocks for
+ * one call. The later state always wins; the merged part keeps the position of its FIRST
+ * occurrence (stable ordering); and an `input` (or `toolName`) supplied by an earlier state
+ * survives a later state that omits it — `tool-output-available` carries only `output` on the
+ * 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.
+ *
+ * @example
+ * import { coalesceParts } from 'basalt-ui/agent'
+ * <PartList parts={coalesceParts(parts)} />
+ */
+import type { AgentPart } from './parts.js';
+export declare function coalesceParts<TPart extends AgentPart>(parts: readonly TPart[]): TPart[];
+//# sourceMappingURL=coalesce.d.ts.map

package/dist/agent/coalesce.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"coalesce.d.ts","sourceRoot":"","sources":["../../src/agent/coalesce.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH,OAAO,KAAK,EAAE,SAAS,EAAyC,MAAM,SAAS,CAAA;AA+C/E,wBAAgB,aAAa,CAAC,KAAK,SAAS,SAAS,EAAE,KAAK,EAAE,SAAS,KAAK,EAAE,GAAG,KAAK,EAAE,CA+CvF"}

package/dist/agent/coalesce.js

@@ -0,0 +1,69 @@
+function isTextLikeType(type) {
+  return type === "text" || type === "reasoning";
+}
+function resolveToolCallId(part, toolCallIdByApprovalId) {
+  if (typeof part.toolCallId === "string" && part.toolCallId.length > 0) return part.toolCallId;
+  const approval = "approval" in part ? part.approval : void 0;
+  return approval !== void 0 ? toolCallIdByApprovalId.get(approval.id) : void 0;
+}
+function registerApprovalIndex(part, toolCallIdByApprovalId) {
+  const approval = "approval" in part ? part.approval : void 0;
+  if (approval === void 0) return;
+  if (typeof part.toolCallId !== "string" || part.toolCallId.length === 0) return;
+  toolCallIdByApprovalId.set(approval.id, part.toolCallId);
+}
+function mergeToolPart(existing, next) {
+  const existingInput = "input" in existing ? existing.input : void 0;
+  const nextInput = "input" in next ? next.input : void 0;
+  const input = nextInput !== void 0 ? nextInput : existingInput;
+  const toolName = next.toolName.length > 0 ? next.toolName : existing.toolName;
+  return {
+    ...existing,
+    ...next,
+    toolName,
+    ...input !== void 0 ? { input } : {}
+  };
+}
+function coalesceParts(parts) {
+  const out = [];
+  const toolIndexByCallId = /* @__PURE__ */ new Map();
+  const toolCallIdByApprovalId = /* @__PURE__ */ new Map();
+  for (const part of parts) {
+    if (isTextLikeType(part.type)) {
+      const last = out[out.length - 1];
+      if (last !== void 0 && last.type === part.type) {
+        const merged = {
+          ...part,
+          text: last.text + part.text
+        };
+        out[out.length - 1] = merged;
+        continue;
+      }
+      out.push(part);
+      continue;
+    }
+    if (part.type === "tool") {
+      const toolPart = part;
+      registerApprovalIndex(toolPart, toolCallIdByApprovalId);
+      const resolvedCallId = resolveToolCallId(toolPart, toolCallIdByApprovalId);
+      if (resolvedCallId === void 0) {
+        out.push(part);
+        continue;
+      }
+      const existingIndex = toolIndexByCallId.get(resolvedCallId);
+      if (existingIndex === void 0) {
+        toolIndexByCallId.set(resolvedCallId, out.length);
+        out.push(part);
+        continue;
+      }
+      const existing = out[existingIndex];
+      out[existingIndex] = mergeToolPart(existing, toolPart);
+      continue;
+    }
+    out.push(part);
+  }
+  return out;
+}
+export {
+  coalesceParts
+};