@kitn.ai/ui 0.20.1 → 0.22.0

package/src/state/index.ts

@@ -1,6 +1,32 @@
 // Framework-neutral state core for @kitn.ai/ui. Pure functions over ChatMessage[]
 // + a typed streaming handle. No React/Solid runtime — drives a consumer setter.
-export { appendMessage, upsertMessage, updateMessage, removeMessage, appendContent } from './messages';
+export { appendMessage, upsertMessage, updateMessage, removeMessage, appendText, textMessage, partsToText } from './messages';
 export { addSuggestion, removeSuggestion } from './suggestions';
 export { createAssistantStream, onStreamSettled } from './stream';
 export type { SetMessages, AssistantStream } from './stream';
+export { appendTextPart, appendReasoningPart, upsertToolPart, upsertCardPart, fingerprint } from './parts';
+export type { ReasoningOpts } from './parts';
+
+// The zero-config mock. Produces SSE frames rather than folding parts directly,
+// so the no-backend preview runs through the SAME parser a real provider does —
+// and is deliberately impossible to mistake for one. See ./mock.
+export { createMockResponder, DEFAULT_MOCK_REPLIES, MOCK_BANNER, MOCK_MARKER, MOCK_MARKER_KEY, MOCK_MODEL_ID } from './mock';
+export type { MockResponder, MockResponderOptions } from './mock';
+
+// The content-model types every signature above mentions. Without these a
+// consumer importing only from '@kitn.ai/ui/state' cannot annotate the very
+// values these helpers take and return (the missing-annotation gap that made an
+// un-annotated `const history = [...]` widen to `string` and fail TS2322).
+export type {
+  ChatMessage, ChatMessageAction, CustomAction, AvatarData, FeedbackVote, MessagePart,
+  MessageSource, RawOrigin,
+} from '../elements/chat-types';
+export type { ToolPart } from '../components/tool-types';
+export type { ToolKind } from '../components/tool-classify';
+// upsertToolPart defaults `kind` to classifyTool(type) and reverts it on a type
+// change (see ./parts), and ToolPart.kind's doc comment names the function, so a
+// consumer computing `kind` itself needs the identical classifier — not a
+// hand-rolled copy that drifts from ours.
+export { classifyTool } from '../components/tool-classify';
+export type { CardEnvelope } from '../primitives/card-contract';
+export type { AttachmentData } from '../components/attachment-types';

package/src/state/messages.ts

@@ -1,4 +1,21 @@
-import type { ChatMessage } from '../elements/chat-types';
+import type { ChatMessage, MessagePart } from '../elements/chat-types';
+import { appendTextPart } from './parts';
+
+function newId(): string {
+  if (typeof crypto !== 'undefined' && crypto.randomUUID) return crypto.randomUUID();
+  return 'kai-' + Math.random().toString(36).slice(2);
+}
+
+/** Convenience for the common single-text-part message. */
+export function textMessage(role: ChatMessage['role'], text: string, init: Partial<ChatMessage> = {}): ChatMessage {
+  return { id: init.id ?? newId(), role, parts: [{ type: 'text', text }], ...init };
+}
+
+/** Concatenates every text part. Use where a plain string is genuinely needed
+ *  (copy-to-clipboard, TTS, a length check). Do NOT use it for rendering. */
+export function partsToText(parts: MessagePart[]): string {
+  return parts.filter((p) => p.type === 'text').map((p) => p.text).join('');
+}
 
 /** Append a message; returns a new array. */
 export function appendMessage(messages: ChatMessage[], msg: ChatMessage): ChatMessage[] {
@@ -30,7 +47,7 @@ export function removeMessage(messages: ChatMessage[], id: string): ChatMessage[
   return messages.filter((x) => x.id !== id);
 }
 
-/** Streaming primitive: concatenate `delta` onto the matched message's content. */
-export function appendContent(messages: ChatMessage[], id: string, delta: string): ChatMessage[] {
-  return messages.map((x) => (x.id === id ? { ...x, content: x.content + delta } : x));
+/** Streaming primitive: append `delta` onto the matched message's trailing text part. */
+export function appendText(messages: ChatMessage[], id: string, delta: string): ChatMessage[] {
+  return messages.map((x) => (x.id === id ? { ...x, parts: appendTextPart(x.parts, delta) } : x));
 }

package/src/state/mock.ts

@@ -0,0 +1,211 @@
+// The mock responder: the zero-config first win, standardized.
+//
+// WHAT IT IS
+// ----------
+// `createMockResponder()` returns a function that produces a STREAM SOURCE —
+// SSE text frames in the OpenAI chat-completions shape — which the caller hands
+// to `readOpenAIStream` from `@kitn.ai/ui/wire` exactly as it would hand over a
+// `fetch()` Response. There is no network, no key and no provider.
+//
+// WHY IT PRODUCES A WIRE INSTEAD OF FOLDING PARTS DIRECTLY
+// -------------------------------------------------------
+// The obvious cheaper design is to yield text deltas and let the caller fold
+// them onto `parts` with `appendTextPart`. That is what the scaffolder and all
+// five composed starters used to do, in seven separate copies, and it is worse
+// on every axis that matters:
+//
+//   · It BYPASSES the kit's own parser. The zero-config default is the code path
+//     every new developer runs first, and under the folding design it exercised
+//     none of `sseDataFrames` / `sseJson` / `openaiChatFormat` /
+//     `consumeModelStream`. Producing a wire makes the first-run path a live
+//     regression test of the thing every real integration depends on.
+//   · It makes the mock scaffold and the real scaffold STRUCTURALLY DIFFERENT,
+//     so "swap the mock for a real backend" is a rewrite of the submit handler
+//     rather than a one-expression change. With a wire, the only difference
+//     between the two emitted scaffolds is `mockResponse(value)` vs
+//     `await fetch('/api/chat', …)`; `createAssistantStream`, `readOpenAIStream`,
+//     the try/catch/finally and the abort handling are byte-identical.
+//   · The hand-rolled folds drifted. One of them replaced `parts` wholesale,
+//     which silently deleted any reasoning/tool parts already on the message.
+//
+// The frames are the OpenAI chat-completions shape because the mock stands in
+// for the consumer's `/api/chat` ROUTE, not for a provider: every integration in
+// the kit's catalog except this one re-frames its provider to that shape
+// server-side (see `readOpenAIStream`), so matching it is what keeps the swap to
+// a real backend a one-line change.
+//
+// WHY YOU CAN TELL IT IS A MOCK — READ THIS BEFORE CHANGING ANY STRING BELOW
+// -------------------------------------------------------------------------
+// A mock that is indistinguishable from a real response is how a fabricated turn
+// gets believed. This repo has already shipped that bug once: a scaffold seeded a
+// tool call from fixture data, the panel rendered "search Completed", and the
+// fabricated turn was POSTed to the provider AHEAD of the user's own message. A
+// human demoing it saw success; only an assertion on the round-2 answer failed.
+//
+// Choosing a real provider's frame SHAPE (above) means shape alone can no longer
+// distinguish the mock, so the tells are deliberate and layered. Each is visible
+// at a different altitude, so whichever one a developer happens to be looking at,
+// something says "no provider was contacted":
+//
+//   1. RAW STREAM — the first bytes are an SSE comment banner (`: kai-mock …`).
+//      Comment lines are dropped by `sseDataFrames`, so this is free
+//      semantically and unmissable to anyone reading the stream or a capture.
+//   2. EVERY FRAME — carries `_kai_mock`, a full sentence naming this function.
+//      The OpenAI reader ignores fields it does not know, so it costs nothing
+//      and it survives JSON parsing: logging any single frame shows it.
+//   3. FIELD LEVEL — `model` is `kai-mock`, which is not a model any provider
+//      serves. If a mock frame were ever echoed back upstream it would be
+//      REJECTED rather than quietly accepted, which is the specific failure the
+//      fabricated-tool-call bug needed and did not get.
+//   4. TURN LEVEL — usage is all zeros. A real turn that produced text cannot
+//      report zero completion tokens, so `turn.usage` disambiguates in the app,
+//      not merely in the bytes.
+//   5. UI LEVEL — the reply says so in words. The WEAKEST tell and the only one
+//      a real model could imitate, which is exactly why it is not the only one.
+//
+// CONSTRAINTS
+// -----------
+// Zero dependencies, no DOM, no Solid, no network, and nothing that is not a
+// global in both Node and the browser (`setTimeout`, `JSON`). This module is
+// part of `@kitn.ai/ui/state`, which is import-safe on a server — see
+// `verify:ssr`. It deliberately does NOT import from `@kitn.ai/ui/wire`: it
+// yields `AsyncIterable<string>`, which is structurally a `StreamSource`, so the
+// dependency runs one way (a caller pairs them) and `state` keeps its charter of
+// owning no wire format.
+
+/** The `model` every mock frame reports. Not a model any provider serves — see
+ *  tell 3 in the header. */
+export const MOCK_MODEL_ID = 'kai-mock';
+
+/** The marker field carried by every mock frame. Tell 2. */
+export const MOCK_MARKER_KEY = '_kai_mock';
+
+/** The value of that marker: a whole sentence, because it is read by a human
+ *  staring at a logged frame and wondering where the reply came from. */
+export const MOCK_MARKER =
+  'no provider was contacted — this reply was generated locally by createMockResponder() from @kitn.ai/ui/state';
+
+/** The SSE comment that opens every mock stream. Tell 1. */
+export const MOCK_BANNER = `: kai-mock — NO PROVIDER WAS CONTACTED. ${MOCK_MARKER}.`;
+
+/** The default canned replies, cycled per turn so a multi-turn preview stays
+ *  coherent instead of repeating one line forever. */
+export const DEFAULT_MOCK_REPLIES: readonly string[] = [
+  "Hi! I'm a local mock — no backend, no API key, no provider was contacted. I'm streaming through the same parser a real model would, so what you're seeing is the real rendering path with a canned reply.",
+  "Still the mock. Swap `createMockResponder()` for a `fetch('/api/chat', …)` and nothing else in this handler changes — that's the whole point of the seam.",
+  'Mock again. Every frame I send is tagged `_kai_mock` and my usage reports zero tokens, so nothing here can be mistaken for a real turn.',
+];
+
+export interface MockResponderOptions {
+  /** Canned replies, cycled one per turn. Defaults to `DEFAULT_MOCK_REPLIES`. */
+  replies?: readonly string[];
+  /** Delay between chunks, in ms. Defaults to 24 — fast enough to feel alive,
+   *  slow enough that the streaming is visible. `0` streams as fast as the
+   *  event loop allows, which is what tests want. */
+  delayMs?: number;
+  /** How many whitespace-delimited tokens ride in each frame. Defaults to 1
+   *  (token by token). Larger values coarsen the cadence. */
+  chunkSize?: number;
+  /** Log a one-time notice on the first turn. Defaults to `true`: the point of
+   *  this module is that a mock reply is hard to mistake for a real one, and a
+   *  console line is the fastest way for a human to notice. Pass `false` in
+   *  tests, or wherever the banner and the frame markers are tell enough. */
+  announce?: boolean;
+}
+
+/** Produces one turn's worth of SSE frames. Structurally a `StreamSource`, so it
+ *  goes straight into `readOpenAIStream(responder(text), stream)`. */
+export type MockResponder = (prompt?: string) => AsyncIterable<string>;
+
+/** Split into whitespace-preserving tokens, so re-joining the deltas reproduces
+ *  the reply exactly (the separators are tokens too). */
+function tokenize(reply: string, chunkSize: number): string[] {
+  const parts = reply.split(/(\s+)/).filter((t) => t !== '');
+  if (chunkSize <= 1) return parts;
+  const out: string[] = [];
+  for (let i = 0; i < parts.length; i += chunkSize) {
+    out.push(parts.slice(i, i + chunkSize).join(''));
+  }
+  return out;
+}
+
+function frame(id: string, body: Record<string, unknown>): string {
+  // The marker goes FIRST so it is the first thing visible in a logged or
+  // captured frame, before the payload a reader would skim for.
+  return `data: ${JSON.stringify({
+    [MOCK_MARKER_KEY]: MOCK_MARKER,
+    id,
+    object: 'chat.completion.chunk',
+    model: MOCK_MODEL_ID,
+    ...body,
+  })}\n\n`;
+}
+
+const delay = (ms: number): Promise<void> =>
+  ms > 0 ? new Promise((r) => setTimeout(r, ms)) : Promise.resolve();
+
+/**
+ * Build a mock responder.
+ *
+ * ```ts
+ * import { createAssistantStream, createMockResponder } from '@kitn.ai/ui/state';
+ * import { readOpenAIStream } from '@kitn.ai/ui/wire';
+ *
+ * const mockResponse = createMockResponder();
+ * const stream = createAssistantStream(setMessages);
+ * await readOpenAIStream(mockResponse(value), stream);   // <- swap for fetch()
+ * stream.done();
+ * ```
+ */
+export function createMockResponder(options: MockResponderOptions = {}): MockResponder {
+  const {
+    replies = DEFAULT_MOCK_REPLIES,
+    delayMs = 24,
+    chunkSize = 1,
+    announce = true,
+  } = options;
+
+  const pool = replies.length > 0 ? replies : DEFAULT_MOCK_REPLIES;
+  let turn = 0;
+  let announced = false;
+
+  return function respond(_prompt?: string): AsyncIterable<string> {
+    const reply = pool[turn % pool.length];
+    const id = `kai-mock-${turn + 1}`;
+    turn += 1;
+
+    return {
+      async *[Symbol.asyncIterator]() {
+        if (announce && !announced) {
+          announced = true;
+          // Not console.warn: nothing is wrong. This is the mock announcing
+          // itself so a developer never has to wonder whether the reply they
+          // are looking at came from a model.
+          console.info(`[kai] ${MOCK_BANNER.slice(2)}`);
+        }
+
+        // Tell 1. Dropped by the parser (`sseDataFrames` skips ':' lines), so it
+        // costs nothing semantically — and it exercises that comment-skipping
+        // path, which real providers use for keep-alives.
+        yield `${MOCK_BANNER}\n\n`;
+
+        // The role frame a real OpenAI stream opens with: no content, so it also
+        // exercises the reader's empty-delta path.
+        yield frame(id, { choices: [{ index: 0, delta: { role: 'assistant' }, finish_reason: null }] });
+
+        for (const token of tokenize(reply, chunkSize)) {
+          await delay(delayMs);
+          yield frame(id, { choices: [{ index: 0, delta: { content: token }, finish_reason: null }] });
+        }
+
+        // Tell 4: zero usage. A real turn that produced this much text cannot
+        // report zero completion tokens.
+        yield frame(id, {
+          choices: [{ index: 0, delta: {}, finish_reason: 'stop' }],
+          usage: { prompt_tokens: 0, completion_tokens: 0, total_tokens: 0 },
+        });
+        yield 'data: [DONE]\n\n';
+      },
+    };
+  };
+}

package/src/state/parts.ts

@@ -0,0 +1,295 @@
+import type { MessagePart, RawOrigin } from '../elements/chat-types';
+import type { ToolPart } from '../components/tool-types';
+import type { CardEnvelope } from '../primitives/card-contract';
+import { classifyTool } from '../components/tool-classify';
+
+/** Stable structural fingerprint. Key order independent, so an identical snapshot
+ *  arriving twice compares equal and can be skipped. */
+export function fingerprint(value: unknown): string {
+  const seen = new WeakSet<object>();
+  const walk = (v: unknown): unknown => {
+    if (v === null || typeof v !== 'object') return v;
+    if (seen.has(v as object)) return '[circular]';
+    seen.add(v as object);
+    const o = v as Record<string, unknown>;
+    const out = Array.isArray(v)
+      ? v.map(walk)
+      : Object.fromEntries(Object.keys(o).sort().map((k) => [k, walk(o[k])]));
+    seen.delete(v as object);
+    return out;
+  };
+  return JSON.stringify(walk(value)) ?? '';
+}
+
+/** Appends to the trailing text part, or OPENS A NEW ONE if the last part is not
+ *  text. This is what stops a post-tool answer being glued onto the pre-tool text. */
+export function appendTextPart(parts: MessagePart[], delta: string): MessagePart[] {
+  const last = parts[parts.length - 1];
+  if (last?.type === 'text') {
+    return [...parts.slice(0, -1), { ...last, text: last.text + delta }];
+  }
+  return [...parts, { type: 'text', text: delta }];
+}
+
+export interface ReasoningOpts {
+  index?: number;
+  /** Namespaces `index` to one provider response stream. Producers that read more
+   *  than one stream into the SAME message must set it. See `appendReasoningPart`. */
+  streamId?: string;
+  label?: string;
+  signature?: string;
+  raw?: RawOrigin;
+}
+
+type ReasoningPart = Extract<MessagePart, { type: 'reasoning' }>;
+
+/** Keyed by `(streamId, index)` so parallel reasoning blocks stay distinct.
+ *
+ *  WHY THE KEY IS A PAIR. A block index alone is NOT unique inside one `parts`
+ *  array. Anthropic numbers content blocks per MESSAGE and restarts at 0 on the
+ *  next one, while a tool loop folds every round into a single assistant turn.
+ *  Keyed on index alone, round 2's thinking block (index 0) merges into round 1's
+ *  part: the text concatenates and `raw: opts.raw ?? cur.raw` OVERWRITES round 1's
+ *  verbatim provider payload with round 2's. `toAnthropicMessages` then emits one
+ *  thinking block where two belong, carrying round 2's signature in round 1's
+ *  position -- a modified-and-filtered thinking block, which is exactly the 400
+ *  the verbatim `raw` channel exists to prevent.
+ *
+ *  `streamId` is the namespace: one value per provider response stream, attached
+ *  by `consumeModelStream`. Two rounds are two streams, so their index 0s are two
+ *  parts. Producers that drive a sink from a single stream can omit it; `undefined`
+ *  is its own namespace and behaves exactly as before.
+ *
+ *  Returns the SAME array reference when the merge produces an identical part,
+ *  for the same reason `upsertToolPart` does: a new `parts` array is the
+ *  re-render signal, so handing one back for a delta that changed nothing is a
+ *  spurious render.
+ *
+ *  An EMPTY delta is not a no-op and must still reach here: it is how a redacted
+ *  reasoning block, a `signature_delta` and an assembled `content_block_stop`
+ *  block arrive, and how a format opens a block at the right position so block
+ *  ORDER survives into `parts`. Those carry a new `raw`/`signature`/index and so
+ *  compare unequal and DO rebuild. What the check absorbs is the other empty
+ *  frame: one carrying nothing new, which a provider is free to send repeatedly.
+ *
+ *  `signature` and `raw` resolve with `??`, so an explicit `undefined` from a
+ *  later delta never blanks a value an earlier one established. Pass a DEFINED
+ *  value to replace either; there is no way to clear them. */
+export function appendReasoningPart(
+  parts: MessagePart[],
+  delta: string,
+  opts: ReasoningOpts = {},
+): MessagePart[] {
+  const index = opts.index ?? 0;
+  const streamId = opts.streamId;
+  const i = parts.findIndex(
+    (p) => p.type === 'reasoning' && (p.index ?? 0) === index && p.streamId === streamId,
+  );
+  if (i < 0) {
+    return [...parts, { type: 'reasoning', text: delta, index, streamId, label: opts.label, signature: opts.signature, raw: opts.raw }];
+  }
+  const cur = parts[i] as ReasoningPart;
+  const next: ReasoningPart = {
+    ...cur,
+    text: cur.text + delta,
+    label: opts.label ?? cur.label,
+    signature: opts.signature ?? cur.signature,
+    raw: opts.raw ?? cur.raw,
+  };
+  if (reasoningEqual(cur, next)) return parts;
+  return [...parts.slice(0, i), next, ...parts.slice(i + 1)];
+}
+
+/** Every `ReasoningPart` key, in the order `reasoningEqual` checks them. Same
+ *  exhaustive-by-construction contract as `TOOL_KEYS` below: adding a field to
+ *  the `reasoning` variant of `MessagePart` fails the build until it is listed
+ *  here AND given a comparator, so a new field can never be silently ignored by
+ *  the dedupe check and strand a stale array reference. */
+const REASONING_KEYS = [
+  'type', 'text', 'index', 'streamId', 'label', 'signature', 'raw',
+] as const satisfies readonly (keyof ReasoningPart)[];
+
+type _ReasoningKeysExhaustive = Exclude<
+  keyof ReasoningPart,
+  (typeof REASONING_KEYS)[number]
+> extends never
+  ? true
+  : ['MessagePart reasoning variant has a key missing from REASONING_KEYS', Exclude<keyof ReasoningPart, (typeof REASONING_KEYS)[number]>];
+const _reasoningKeysExhaustive: _ReasoningKeysExhaustive = true;
+void _reasoningKeysExhaustive;
+
+/** One comparator per key in `REASONING_KEYS`. The mapped type means a key added
+ *  to that list with no comparator here is ALSO a compile error.
+ *
+ *  `raw` compares by REFERENCE, exactly as `TOOL_COMPARATORS.raw` does: it is the
+ *  untranslated provider payload, a producer attaches it once, and
+ *  `appendReasoningPart` itself carries it forward when a delta omits it, so
+ *  reference equality holds on every real path. Hashing it would walk the whole
+ *  payload on every empty keep-alive frame, which is the cost this check exists
+ *  to avoid. Worst case is a producer handing over a fresh-but-equal `raw`: one
+ *  extra re-render, never a wrong render. */
+const REASONING_COMPARATORS: {
+  [K in (typeof REASONING_KEYS)[number]]: (a: ReasoningPart, b: ReasoningPart) => boolean;
+} = {
+  type: (a, b) => a.type === b.type,
+  text: (a, b) => a.text === b.text,
+  index: (a, b) => a.index === b.index,
+  streamId: (a, b) => a.streamId === b.streamId,
+  label: (a, b) => a.label === b.label,
+  signature: (a, b) => a.signature === b.signature,
+  raw: (a, b) => a.raw === b.raw,
+};
+
+function reasoningEqual(a: ReasoningPart, b: ReasoningPart): boolean {
+  return REASONING_KEYS.every((key) => REASONING_COMPARATORS[key](a, b));
+}
+
+type CardPart = Extract<MessagePart, { type: 'card' }>;
+
+/** Creates or REPLACES a card part, keyed on `envelope.id`. Returns the SAME array
+ *  reference when the incoming envelope is structurally identical to the current
+ *  one, for the same reason `upsertToolPart` does: a new `parts` array is the
+ *  re-render signal, so handing one back for a revision that changed nothing is a
+ *  spurious render.
+ *
+ *  WHY THIS REPLACES WHERE `upsertToolPart` MERGES. A tool part is patched
+ *  fragment-by-fragment as its arguments stream in, which is why that function
+ *  needs carry-forward rules for `raw` and `kind` — a later patch that omits a
+ *  field is not asserting the field is gone. A card envelope is the opposite: it
+ *  arrives WHOLE, as one complete tool result, so an omitted field IS an
+ *  assertion. Last-write-wins is both simpler and the only semantics under which
+ *  a host can CLEAR `resolution` to re-open a dismissed card — a field-by-field
+ *  merge can only ever set that field, never unset it, so `CardPolicy.onReopen`
+ *  (see `primitives/card-contract.ts`) would have no way to express its result.
+ *
+ *  The PART-level `raw` is preserved across a revision. It is a different field
+ *  from anything inside the envelope: the untranslated provider payload the part
+ *  was built from, attached once by the producer, which a fresh envelope carries
+ *  no opinion about.
+ *
+ *  Position is preserved: a revised card stays where it first appeared in the
+ *  thread rather than jumping past the text that followed it. */
+export function upsertCardPart(parts: MessagePart[], envelope: CardEnvelope): MessagePart[] {
+  const i = parts.findIndex((p) => p.type === 'card' && p.envelope.id === envelope.id);
+  if (i < 0) return [...parts, { type: 'card', envelope }];
+  const cur = parts[i] as CardPart;
+  if (fingerprint(cur.envelope) === fingerprint(envelope)) return parts;
+  return [...parts.slice(0, i), { ...cur, envelope }, ...parts.slice(i + 1)];
+}
+
+/** Creates or merges a tool part. Returns the SAME array reference when the merge
+ *  produces an identical tool, so repeated snapshots do not trigger a re-render.
+ *
+ *  Two fields do NOT follow plain spread semantics, because a streaming provider
+ *  hands them over on one fragment and then keeps patching the rest:
+ *  - `kind`: a value the consumer set is preserved across later patches instead
+ *    of being reverted to `classifyTool(type)` (see `resolveKind`).
+ *  - `raw`: an explicit `raw: undefined` never blanks a `raw` an earlier patch
+ *    established. Pass a DEFINED `raw` to replace it; there is no way to clear it. */
+export function upsertToolPart(
+  parts: MessagePart[],
+  toolCallId: string,
+  patch: Partial<ToolPart>,
+): MessagePart[] {
+  const i = parts.findIndex((p) => p.type === 'tool' && p.tool.toolCallId === toolCallId);
+  if (i < 0) {
+    const tool: ToolPart = {
+      type: patch.type ?? 'unknown',
+      state: patch.state ?? 'input-streaming',
+      ...patch,
+      toolCallId,
+    };
+    tool.kind = tool.kind ?? classifyTool(tool.type);
+    return [...parts, { type: 'tool', tool }];
+  }
+  const cur = (parts[i] as Extract<MessagePart, { type: 'tool' }>).tool;
+  const merged: ToolPart = { ...cur, ...patch, toolCallId };
+  merged.kind = resolveKind(cur, patch, merged.type);
+  if (merged.raw === undefined && cur.raw !== undefined) merged.raw = cur.raw;
+  if (toolsEqual(cur, merged)) return parts;
+  return [...parts.slice(0, i), { type: 'tool', tool: merged }, ...parts.slice(i + 1)];
+}
+
+/** `kind` precedence on an update, in order:
+ *  1. an explicit `patch.kind` always wins;
+ *  2. a `kind` the consumer set that is NOT merely the auto-derivation of the
+ *     current `type` is preserved. Create honors `patch.kind`, so an update must
+ *     not silently revert a custom classification mid-stream (a tool created as
+ *     `{ type: 'my_widget_tool', kind: 'mcp' }` stays `mcp` after a plain
+ *     `{ state: 'output-available' }` patch);
+ *  3. otherwise re-derive from the merged `type`, so a tool whose real name only
+ *     arrives in a later fragment still classifies (the streaming path: created
+ *     as `unknown`/`generic`, patched to `web_search` -> `search`).
+ *
+ *  A consumer `kind` that happens to equal `classifyTool(type)` is
+ *  indistinguishable from the derived one, which is harmless: they agree until
+ *  the `type` changes, and then re-deriving is the better answer anyway. */
+function resolveKind(cur: ToolPart, patch: Partial<ToolPart>, nextType: string): ToolPart['kind'] {
+  if (patch.kind !== undefined) return patch.kind;
+  const derived = cur.kind === undefined || cur.kind === classifyTool(cur.type);
+  return derived ? classifyTool(nextType) : cur.kind;
+}
+
+/** Every `ToolPart` key, in the order `toolsEqual` checks them (cheap identity
+ *  checks first, the two fingerprint-based checks last). See `ToolPart` in
+ *  `components/tool-types.ts`, which points back here.
+ *
+ *  This is not just documentation: `_toolKeysExhaustive` below fails to compile
+ *  if `ToolPart` gains a key that is not listed here, and `TOOL_COMPARATORS`
+ *  fails to compile if this list gains a key with no comparator. Adding a field
+ *  to `ToolPart` without wiring it into both is a BUILD failure, not a silently
+ *  stale array reference. */
+const TOOL_KEYS = [
+  'type', 'state', 'kind', 'toolCallId', 'errorText', 'rawInput', 'raw', 'input', 'output',
+] as const satisfies readonly (keyof ToolPart)[];
+
+// If `ToolPart` gains a key absent from `TOOL_KEYS`, `Exclude<...>` stops being
+// `never`, the assigned literal type no longer matches `true`, and `tsc` reports
+// the offending key name right here.
+type _ToolKeysExhaustive = Exclude<keyof ToolPart, (typeof TOOL_KEYS)[number]> extends never
+  ? true
+  : ['ToolPart has a key missing from TOOL_KEYS', Exclude<keyof ToolPart, (typeof TOOL_KEYS)[number]>];
+const _toolKeysExhaustive: _ToolKeysExhaustive = true;
+void _toolKeysExhaustive;
+
+/** One comparator per key in `TOOL_KEYS`. The mapped type over
+ *  `(typeof TOOL_KEYS)[number]` means a key added to `TOOL_KEYS` with no
+ *  comparator here is ALSO a compile error ("Property 'x' is missing"), so the
+ *  guard reaches the actual comparison, not just the key list.
+ *
+ *  Semantics are unchanged from before this table existed:
+ *  - `raw` compares by REFERENCE on purpose. It is the untranslated provider
+ *    payload; a producer attaches it once and never rebuilds it (upsertToolPart
+ *    itself carries `cur.raw` forward when a patch omits it), so reference
+ *    equality holds on every real path. Hashing it would walk the accumulated
+ *    argument string a second time, which is the cost this table exists to
+ *    remove. The worst case is a producer handing over a fresh-but-equal `raw`,
+ *    which costs one extra re-render and never a wrong render.
+ *  - `input` and `output` are the two fields that are genuinely object-shaped:
+ *    reference equality first, then `fingerprint()` as a structural fallback so
+ *    a fresh-but-identical object still dedupes.
+ *  - everything else, including `rawInput`, compares with `===`. `rawInput`
+ *    against `!==` is exactly the test we want (did the accumulated text
+ *    change?) and it is cheap: two strings of different lengths are unequal
+ *    after the length check, so it never walks the full string.
+ *
+ *  This replaces `fingerprint(merged) === fingerprint(cur)`, which serialized
+ *  the ENTIRE ToolPart on every patch. A streaming tool call is patched once
+ *  per argument fragment while `rawInput` grows toward the full argument JSON,
+ *  so hashing the whole part per fragment is quadratic in the argument size:
+ *  fine at 4 KB, not at 200 KB. */
+const TOOL_COMPARATORS: { [K in (typeof TOOL_KEYS)[number]]: (a: ToolPart, b: ToolPart) => boolean } = {
+  type: (a, b) => a.type === b.type,
+  state: (a, b) => a.state === b.state,
+  kind: (a, b) => a.kind === b.kind,
+  toolCallId: (a, b) => a.toolCallId === b.toolCallId,
+  errorText: (a, b) => a.errorText === b.errorText,
+  rawInput: (a, b) => a.rawInput === b.rawInput,
+  raw: (a, b) => a.raw === b.raw,
+  input: (a, b) => a.input === b.input || fingerprint(a.input) === fingerprint(b.input),
+  output: (a, b) => a.output === b.output || fingerprint(a.output) === fingerprint(b.output),
+};
+
+function toolsEqual(a: ToolPart, b: ToolPart): boolean {
+  return TOOL_KEYS.every((key) => TOOL_COMPARATORS[key](a, b));
+}