@djangocfg/widget-chat 0.1.1

package/src/content/response.tsx

@@ -0,0 +1,221 @@
+import { math } from "@streamdown/math";
+import { code } from "@streamdown/code";
+import { DiagramSource, diagramPlugin } from "@djangocfg/widget-media/diagram";
+import { memo, type ComponentProps } from "react";
+import { harden } from "rehype-harden";
+import { Streamdown } from "streamdown";
+
+import { maskIncompleteMath } from "../core/content";
+import { mentionScheme } from "../core/links";
+
+/**
+ * The ONE place a model's markdown becomes DOM.
+ *
+ * Everything below is a decision that was measured rather than assumed, because
+ * each one is invisible when wrong: a half-arrived fence that throws takes the
+ * transcript row down, and a formula typeset from a prefix renders a DIFFERENT
+ * expression than the one being written.
+ *
+ * ## Why the whole string is one block
+ *
+ * `parseMarkdownIntoBlocksFn={(s) => [s]}` disables streamdown's own splitting.
+ * Splitting on blank lines is what breaks reference definitions — `see [x][1]`
+ * and `[1]: https://…` land in different parses, so the link never resolves and
+ * the reader sees a literal `[1]`. Our previous splitter had the same defect
+ * plus a second one (loose ordered lists renumbering from 1), and both follow
+ * from splitting AT ALL, not from how it was done.
+ *
+ * The cost is real and accepted: a token now re-renders the whole message
+ * instead of its last block. `memo` below keeps that to the one message that
+ * changed, and a message is bounded — a transcript is not.
+ *
+ * ## Why these two plugins and not the other two
+ *
+ * streamdown's core carries no math, no highlighting, no diagrams; each is an
+ * opt-in package — streamdown does NOT drag KaTeX in on its own.
+ *
+ * - `math` (katex, ~1 dep tree) — IN. Agent answers carry complexity bounds and
+ *   formulas; rendering them as `$O(n \log n)$` is a worse answer.
+ * - `code` (shiki) — IN. A transcript of an agent that edits files is mostly
+ *   code; unhighlighted code is the single most-read thing here.
+ * - `mermaid` — IN, on OUR renderer rather than the upstream plugin. The cost
+ *   objection stands against `@streamdown/mermaid`, which pulls an 84 MB
+ *   runtime needing a DOM; `@djangocfg/widget-media` draws the same diagrams from a
+ *   2.5 MB parser needing none. The `show_media` tool declares `mermaid` among
+ *   its kinds, so diagrams are produced whether or not this renders them — the
+ *   alternative was not "no diagrams", it was a code block where one belongs.
+ * - `cjk` — OUT until a CJK locale ships. Its job is strikethrough/emphasis
+ *   boundaries in CJK text; nothing today reads those.
+ *
+ * ## Inline math needs `$$`, and that default is KEPT
+ *
+ * `@streamdown/math` ships `singleDollarTextMath: false`. That reads like a
+ * missing feature and is not: a transcript from an agent that runs shells and
+ * quotes prices is FULL of lone dollars — `$PATH`, `$HOME`, `$50/month`, `cd
+ * $DIR` — and enabling single-dollar math turns the text between any two of
+ * them into a formula. The failure is silent and it corrupts the answer, which
+ * is strictly worse than `$x$` staying literal.
+ *
+ * So inline math is written `$$E = mc^2$$` and block math is a fenced `$$` on
+ * its own lines. Pinned by a test, because "turn it on" is a one-word edit that
+ * looks like an improvement.
+ *
+ * ## KaTeX needs its stylesheet
+ *
+ * The plugin emits `<span class="katex">`; without `katex/dist/katex.min.css`
+ * that renders as unstyled fallback glyphs. `math.getStyles()` returns the path
+ * — the HOST imports it, because this package ships no CSS of its own.
+ *
+ * ## Completion stays ON, and math is exempted from it
+ *
+ * streamdown completes half-arrived markdown, which is what makes a bold run
+ * style itself as it is typed. For math that same behaviour typesets a PREFIX —
+ * `$$O(n \log` renders a finished-looking `O(n log` that becomes a different
+ * formula on the next token:
+ *
+ * | unclosed | completion on | off |
+ * |---|---|---|
+ * | `**important` | bold | plain |
+ * | `` `foo( `` | code | plain |
+ * | `[docs](` | link | plain |
+ * | `$$O(n \log` | KATEX ← the defect | plain |
+ *
+ * `parseIncompleteMarkdown: false` fixes the last row by breaking the other
+ * three, so the flag stays on and the one harmful case is neutralised on the
+ * INPUT by `maskIncompleteMath` — see `core/content/incomplete-math.ts`.
+ */
+
+const PLUGINS = { math, code, mermaid: diagramPlugin };
+
+/**
+ * What a fenced diagram shows before it can be drawn.
+ *
+ * Streamdown recomputes the mermaid branch on every token and does NOT pass it
+ * the `isIncomplete` flag it hands the code-block branch, so a diagram arriving
+ * a token at a time reaches the renderer dozens of times unfinished. The plugin
+ * rejects those, and this is what a rejection looks like: the source, not
+ * streamdown's default red error box, which would otherwise flash through the
+ * whole of a streamed diagram before the picture replaced it.
+ */
+const MERMAID_OPTIONS = { errorComponent: DiagramSource } as const;
+
+/**
+ * Link hardening, re-declared so an app scheme survives it.
+ *
+ * The renderer hardens links through `rehype-harden`, whose `allowedProtocols`
+ * defaults to EMPTY. A scheme it does not recognise loses its `href` and the
+ * anchor is replaced by grey text reading `<label> [blocked]`, carrying
+ * `title="Blocked URL: undefined"`. Correct for `javascript:`; wrong for an app
+ * scheme the HOST assigns meaning to — a `<scheme>://user/<id>` mention
+ * rendered as `name [blocked]` mid-sentence, which is what shipped.
+ *
+ * `urlTransform` does NOT fix it: that runs earlier, and harden re-checks the
+ * href afterwards. The plugin is the only place the decision is made.
+ *
+ * Declared here rather than passed by the host because `components` is already
+ * the seam for "this href means something to me" — a host that supplies a link
+ * renderer must not also have to know that a plugin would strip the href before
+ * its renderer ever sees it.
+ */
+/**
+ * Built on FIRST RENDER, not at module load, and cached per scheme.
+ *
+ * A host configures the scheme at startup, which may run after this module is
+ * evaluated. Baking the protocol list in at load time would therefore block
+ * every one of that host's own mentions, with `[blocked]` in the transcript as
+ * the only symptom.
+ */
+let cachedScheme: string | undefined;
+let cachedPlugins: readonly unknown[] | undefined;
+
+function rehypePlugins(): readonly unknown[] {
+  const scheme = mentionScheme();
+  if (cachedPlugins === undefined || cachedScheme !== scheme) {
+    cachedScheme = scheme;
+    cachedPlugins = [
+      [
+        harden,
+        {
+          // `*` for prefixes keeps the default reach; the PROTOCOL list is the
+          // part that was empty, and it is what blocked the app scheme.
+          allowedLinkPrefixes: ["*"],
+          allowedImagePrefixes: ["*"],
+          allowedProtocols: ["http:", "https:", "mailto:", "tel:", `${scheme}:`],
+          allowDataImages: true,
+        },
+      ],
+    ];
+  }
+  return cachedPlugins;
+}
+
+/**
+ * Links are anchors, not confirm buttons.
+ *
+ * `linkSafety` defaults to ON, and an enabled one renders every link as a
+ * `<button>` carrying no `href` — clicking opens an "are you sure" modal first.
+ * That is built for a chat where a STRANGER writes the link. Here the author is
+ * the agent the host put behind this room, and the two threats the modal
+ * guards are already answered upstream: a dangerous scheme cannot survive
+ * the hardened protocol list, and content the agent did not author is
+ * datamarked before it ever reaches a model. What was left was a second click
+ * on every citation.
+ *
+ * Deliberately NOT a domain allowlist of "our" hosts: that is a second source
+ * of truth about which addresses are ours, needing an edit for every new one,
+ * and it is the same thing `allowedLinkPrefixes: ["*"]` above already declined.
+ * The protocol is the class of threat; the domain is not.
+ */
+const LINK_SAFETY = { enabled: false } as const;
+
+/** One block: see the reference-definition rationale above. */
+const wholeString = (source: string) => [source];
+
+export interface ResponseProps {
+  /** Markdown, possibly mid-stream. */
+  readonly children: string;
+  readonly className?: string;
+  /**
+   * Element overrides, passed through to the markdown renderer.
+   *
+   * The seam exists for links whose HREF the host owns a meaning for.
+   * `[@Dana Reyes](<scheme>://user/<id>)` is a MENTION here, and this
+   * package must not learn what a mentionable thing is — so the host overrides `a`,
+   * recognises its own scheme, and renders a chip. An unrecognised href falls
+   * through to the default anchor.
+   *
+   * Without it a mention paints as an ordinary link to a scheme no browser can
+   * follow: visibly a link, inert on click.
+   *
+   * MUST be referentially stable — an inline object is a new reference on every
+   * render, and the comparator below would then re-parse the markdown of every
+   * message on every parent render, which is the cost that comparator exists to
+   * avoid.
+   */
+  readonly components?: ComponentProps<typeof Streamdown>["components"];
+}
+
+export const Response = memo(
+  ({ children, className, components }: ResponseProps) => (
+    <Streamdown
+      className={className}
+      parseMarkdownIntoBlocksFn={wholeString}
+      plugins={PLUGINS}
+      mermaid={MERMAID_OPTIONS}
+      components={components}
+      linkSafety={LINK_SAFETY}
+      rehypePlugins={rehypePlugins() as never}
+    >
+      {maskIncompleteMath(children)}
+    </Streamdown>
+  ),
+  // Vercel's own comparator, and for the same reason: `Streamdown` is the most
+  // expensive node in the transcript, and a parent re-rendering for an unrelated
+  // reason (a scroll flag, a new sibling message) must not re-parse markdown.
+  (prev, next) =>
+    prev.children === next.children &&
+    prev.className === next.className &&
+    prev.components === next.components,
+);
+
+Response.displayName = "Response";

package/src/core/adapter.ts

@@ -0,0 +1,29 @@
+/**
+ * The backend contract. ONE required method.
+ *
+ * Everything optional an adapter might do — mentions, retry — is a
+ * separate capability object, not a field here. That split is what keeps the
+ * root component at seven props: a capability that is absent is a feature that
+ * is off, expressed once, instead of a boolean plus its four companion props.
+ *
+ * A `ReadableStream` rather than a callback bag because backpressure and
+ * cancellation come with it: `AbortSignal` stops the stream and the reducer
+ * needs no "am I still the current turn?" bookkeeping.
+ */
+
+import type { StreamChunk } from "./chunks";
+import type { ChatMessage } from "./parts";
+
+export interface SendRequest {
+  /** The full outbound text, tool markers already appended. */
+  readonly text: string;
+  /** Prior turns, oldest first. The adapter decides how much it forwards. */
+  readonly history: readonly ChatMessage[];
+  /** The message this turn answers, or absent. Opaque — the adapter forwards it. */
+  readonly replyTo?: string;
+  readonly signal: AbortSignal;
+}
+
+export interface ChatAdapter {
+  sendMessage(request: SendRequest): Promise<ReadableStream<StreamChunk>>;
+}

package/src/core/capabilities.ts

@@ -0,0 +1,286 @@
+/**
+ * Capabilities — the answer to 83 props.
+ *
+ * Every optional feature is ONE object. Present means the feature exists;
+ * absent means it does not, and no UI for it renders. There is no boolean to
+ * contradict the object, and no companion props to keep in sync with it — those
+ * two failure modes are what produced a configuration space nobody could
+ * enumerate (`@rules/architecture.md`).
+ *
+ * The rule that keeps it honest: a capability owns the WHOLE feature — its
+ * behaviour, its limits, its callbacks. If adding one still requires a prop on
+ * `<Chat>`, the capability is drawn wrong.
+ */
+
+import type { MediaBlock, MediaGeneration } from "./media/block";
+import type { ToolsCapability } from "./tools/capability";
+import type { VoiceSoundsCapability } from "./voice/earcons";
+
+/**
+ * Re-running a turn.
+ *
+ * Separate from the adapter because not every backend can: a replayed history
+ * transcript has no live turn to retry, and the button must be absent there
+ * rather than present-and-broken.
+ */
+export interface RetryCapability {
+  readonly retry: (messageId: string) => void;
+}
+
+/**
+ * End the turn on the AGENT, not just the local stream.
+ *
+ * Aborting the stream only closes this tab's reader: the run is deliberately
+ * detached from its caller, so the agent keeps working and the button silences
+ * the tab. This carries the explicit stop the host sends instead.
+ *
+ * Absent ⇒ Stop stays local-only, which is correct for a host with no transport
+ * behind it — a replayed transcript has no run to end.
+ */
+export interface CancelRunCapability {
+  /** Rejects on a refusal the host chose to surface; the abort happens either way. */
+  readonly cancel: () => Promise<void>;
+}
+
+/**
+ * Dictation.
+ *
+ * The contract is the smallest one that works: start, stop, and a stream of
+ * text. Which engine, which language and whether audio leaves the device are
+ * product and privacy decisions, and this seam is what keeps them the host's.
+ *
+ * **Absent does NOT mean no microphone here**, unlike every other capability.
+ * The package ships a Web Speech default (`core/voice/web-speech.ts`), so an
+ * absent capability falls back to the browser and only a browser without an
+ * engine yields no button. A host supplying one overrides the default outright.
+ * The exception is deliberate: without it every consumer re-implements the same
+ * engine, which is how a host ends up depending on an external toolkit for a
+ * seam the package could have owned.
+ *
+ * `false` is how a host says NO — the one thing absence cannot express here,
+ * since absence already means "use the default". A phone keyboard has dictation
+ * of its own, so a second microphone in the composer is a duplicate control
+ * spending a tile in the row a thumb reaches.
+ */
+export interface VoiceCapability {
+  /**
+   * Begin dictation.
+   *
+   * `onText` may be called many times. `final: false` is an interim result that
+   * REPLACES the previous interim; `final: true` commits. Without that
+   * distinction an interim "hello wor" and its correction both land in the
+   * draft and the user watches their sentence duplicate itself.
+   */
+  readonly start: (
+    onText: (text: string, final: boolean) => void,
+    signal: AbortSignal,
+  ) => Promise<void>;
+  /**
+   * Stop and discard any uncommitted interim.
+   *
+   * MUST be safe to call synchronously from a send. The archived chat notes
+   * why: on submit, "voice dictation stops recording instead of talking into a
+   * sent message" — a listener that settles asynchronously lets the next words
+   * land in a draft that has already been cleared.
+   */
+  readonly stop: () => void;
+}
+
+/**
+ * Rendering the agent's media blocks.
+ *
+ * Absent ⇒ media blocks render NOTHING. That is the safe default rather than a
+ * degraded one: a media src is a URL the MODEL chose, and displaying it is an
+ * outbound request made on the user's behalf. A host that cannot say which
+ * same-origin paths are legitimately its own cannot gate that request, so it
+ * must not make it.
+ *
+ * The prefixes are the capability's whole content because they are the one part
+ * a package cannot know. `core/media/allowed-src.ts` gates schemes on its own —
+ * `https:`, `app://`, `data:image/` are the same everywhere — but an absolute
+ * path is only safe relative to whoever serves the transcript. Baking one
+ * transport's routes into this package would be the second source of truth its
+ * own header refuses.
+ */
+export interface MediaCapability {
+  /**
+   * Absolute-path prefixes this host serves media from, e.g.
+   * `/api/admin/attachments/`. Case-sensitive, and matched only after the path
+   * is proven already-clean — see `isAllowedSrc`.
+   *
+   * Empty ⇒ only the allowlisted SCHEMES render; no same-origin path does.
+   */
+  readonly sameOriginPrefixes: readonly string[];
+  /**
+   * Draw a playable block (audio, video, map) with the host's own player.
+   *
+   * Absent ⇒ the native `<audio controls>` / `<video controls>`, which cannot
+   * join the shell's player, show embedded artwork, or rewrite a video src
+   * onto a streaming route.
+   *
+   * On MediaCapability rather than its own: a host that can render media is the
+   * same host that decides what a player is. Returning undefined for one kind
+   * falls back per kind.
+   *
+   * `unknown`, not `ReactNode`: `src/core` imports no React. The renderer that
+   * consumes this narrows it.
+   */
+  readonly renderPlayer?: (block: MediaBlock) => unknown;
+  /**
+   * Draw a picture with the host's own viewer.
+   *
+   * Absent ⇒ a plain `<img>`, which is the one thing in a transcript that looks
+   * openable and is not. The seam exists for the same reason `renderPlayer`
+   * does: a lightbox is a heavy dependency belonging to the host's design
+   * system, and a package that shipped one would carry it into every mount.
+   *
+   * Format is never part of the decision — whatever the browser can render,
+   * the host is handed the same src the `<img>` would have used.
+   * `unknown`, not `ReactNode`: `src/core` imports no React.
+   */
+  readonly renderImage?: (image: {
+    readonly src: string;
+    /** The filename, which is also the picture's only description. */
+    readonly title: string;
+    /** What produced it, when a tool authored the picture rather than found it. */
+    readonly generation?: MediaGeneration;
+  }) => unknown;
+}
+
+/**
+ * Starter prompts for an empty room.
+ *
+ * Absent ⇒ an empty transcript shows its one line of text and nothing else, the
+ * same absent-not-stubbed rule as voice. A read-only replay has no agent to
+ * start, so the affordance must be absent rather than inert.
+ *
+ * The CATALOGUE is the host's, and that is load-bearing rather than tidy:
+ * choosing the set needs facts this package cannot hold — which of the agent's
+ * tool families exist on the server behind the transport, and that different
+ * agent engines reach different subsets of them. A list declared here would be
+ * a second source of truth against the one the host generates.
+ *
+ * The stakes are higher than for a menu of verbs the transport can refuse. An
+ * unsupported verb comes back as an error; a suggestion is ordinary prose, so
+ * nothing refuses it — the model answers, improvising about a tool it does not
+ * have. There is no server-side gate behind this list at all.
+ */
+export interface SuggestionsCapability {
+  /** The list to offer, already filtered by the host, in display order. */
+  readonly items: readonly ChatSuggestion[];
+  /**
+   * The language to answer in, named in ENGLISH ("Russian"), appended to the
+   * prompt as one sentence.
+   *
+   * Prompts stay English because they are model-facing; the reply is what the
+   * user reads. The host supplies it: no locale reaches the agent on the ask
+   * path, so this cannot be decided further down.
+   *
+   * Absent ⇒ nothing appended. An English-language host needs no "Reply in
+   * English."
+   */
+  readonly replyLanguage?: string;
+  /**
+   * Observe a pick. The prompt is ALREADY SENT when this runs — this is a
+   * notification, not the send itself.
+   *
+   * The package sends it down the same path the composer uses (`store.send`),
+   * which is what makes a picked row indistinguishable from a typed message:
+   * it queues behind a turn in flight, it gets the same optimistic row, and it
+   * obeys the same guards. A host performing the send itself would be a second
+   * path to one behaviour, and the two would drift on exactly those cases.
+   */
+  readonly onPick?: (suggestion: ChatSuggestion) => void;
+}
+
+/**
+ * One starter row.
+ *
+ * Two texts, deliberately, because two audiences read them: `title` is shown
+ * and translated, `prompt` is sent to the model and is not. One string used as
+ * both — the shape Vercel's primitive takes — forces a choice between a row too
+ * long to scan and a prompt too terse to act on.
+ */
+export interface ChatSuggestion {
+  readonly id: string;
+  /** What the row READS. Short enough for a narrow pane. */
+  readonly title: string;
+  /** What is SENT. May be much longer than the title. */
+  readonly prompt: string;
+  /**
+   * Glyph KEY, never a node — the catalogue crosses the transport as data. An
+   * unmapped key draws no glyph rather than failing, so a row may ship before
+   * its icon.
+   */
+  readonly icon?: string;
+}
+
+/**
+ * Reading back a mention the composer wrote as an opaque token.
+ *
+ * Absent ⇒ every mention already reads as itself, which is true wherever the
+ * written token IS the name. A host whose correspondents are named in free text
+ * writes an id instead — that is what keeps a mention resolvable and durable
+ * across a rename — and supplies this so the reader still sees the name.
+ *
+ * An unknown token resolves to nothing and stays as written. It names someone
+ * who has left or has not loaded, and a substituted guess would put a wrong
+ * name into a message already sent.
+ */
+export interface MentionNamesCapability {
+  readonly nameFor: (token: string) => string | undefined;
+  /**
+   * The whole correspondent behind a token, for a host that draws more than a
+   * name — a face, a role, a card.
+   *
+   * `unknown`, not a typed row: `src/core` imports no React and knows nothing
+   * about what a correspondent IS. The host that supplies this is the same one
+   * that renders it, so the type is checked where both ends meet rather than
+   * described here. Absent ⇒ the name alone.
+   */
+  readonly contactFor?: (token: string) => unknown;
+  /**
+   * How to WRITE a mention of this address, already serialized.
+   *
+   * The finished text rather than its parts, because the spelling belongs to
+   * the host that owns how a mention is written — returning the parts would let
+   * a second caller compose them differently. Absent ⇒ no way to write one, and
+   * the affordance is omitted.
+   */
+  readonly mentionFor?: (token: string) => string | undefined;
+}
+
+/**
+ * A longer reasoning pass before the answer — the composer's "Think" toggle.
+ *
+ * Absent ⇒ no button renders. That is the required shape here, not a
+ * preference: only a third of the catalogue accepts the `reasoning_effort`
+ * request field (measured 2026-08-29 — 133 of 396 models, a strict subset of
+ * the 270 that reason), so a toggle shown unconditionally would be pressable
+ * and inert on models like Claude Opus and DeepSeek R1. A control that silently
+ * does nothing is worse than one that is not there.
+ *
+ * The host owns the decision because only it can see which model is active —
+ * the model catalogue it fetches is what carries `reasoningEffort` per model.
+ */
+export interface ThinkCapability {
+  /**
+   * Whether the toggle is currently on. STICKY across turns, like ChatGPT's:
+   * it lives with the host, not in the draft, because the draft is cleared on
+   * every send and a value stored there would silently switch itself off.
+   */
+  readonly enabled: boolean;
+  readonly setEnabled: (enabled: boolean) => void;
+}
+
+export interface ChatCapabilities {
+  readonly suggestions?: SuggestionsCapability;
+  readonly tools?: ToolsCapability;
+  readonly retry?: RetryCapability;
+  readonly cancelRun?: CancelRunCapability;
+  readonly voice?: VoiceCapability | false;
+  readonly voiceSounds?: VoiceSoundsCapability;
+  readonly think?: ThinkCapability;
+  readonly media?: MediaCapability;
+  readonly mentionNames?: MentionNamesCapability;
+}

package/src/core/chunks.ts

@@ -0,0 +1,66 @@
+/**
+ * The wire vocabulary between an adapter and this package.
+ *
+ * An adapter's ONLY obligation is to emit these. It does not build messages,
+ * hold state, or know about React — so a new backend is one file, and the
+ * reducer stays the single owner of how a transcript is assembled.
+ *
+ * Chunks name PART ids explicitly (`partId`) rather than implying "the last
+ * part". Implicit targeting is what makes interleaved output — text, then a
+ * tool, then more text — collapse into the wrong part; naming it costs the
+ * adapter nothing since it already knows which stream it is reading.
+ */
+
+import type { DataPart } from "./parts";
+
+export type StreamChunk =
+  /**
+   * A new assistant message begins. Everything after targets this message.
+   *
+   * `createdAt` comes from the adapter because the core reads no clock: a
+   * reducer that called `Date.now()` would make every transcript test
+   * time-dependent, and history replay would stamp old turns with now.
+   */
+  | { readonly type: "message-start"; readonly messageId: string; readonly createdAt: number }
+  | { readonly type: "text-start"; readonly partId: string }
+  | { readonly type: "text-delta"; readonly partId: string; readonly delta: string }
+  | { readonly type: "reasoning-start"; readonly partId: string }
+  | { readonly type: "reasoning-delta"; readonly partId: string; readonly delta: string }
+  /**
+   * The thought is finished — the only chunk that can say so.
+   *
+   * Without it a block is sealed by the NEXT part opening, which leaves the
+   * last thought of a turn streaming forever when the model answers with a
+   * tool call, or with nothing at all. `elapsedMs` and `tokens` carry whatever
+   * the engine measured; both absent is ordinary.
+   */
+  | {
+      readonly type: "reasoning-end";
+      readonly partId: string;
+      readonly elapsedMs?: number;
+      readonly tokens?: number;
+    }
+  /** Arguments begin streaming; the part appears immediately, in `input-streaming`. */
+  | { readonly type: "tool-input-start"; readonly toolCallId: string; readonly toolName: string }
+  | { readonly type: "tool-input-delta"; readonly toolCallId: string; readonly delta: string }
+  | { readonly type: "tool-input-available"; readonly toolCallId: string; readonly input: unknown }
+  | { readonly type: "tool-output"; readonly toolCallId: string; readonly output: unknown }
+  | { readonly type: "tool-error"; readonly toolCallId: string; readonly error: string }
+  | { readonly type: "data"; readonly part: DataPart }
+  /**
+   * Discard everything accumulated for the current message and start it over —
+   * the agent is re-issuing the turn after a mid-stream cut.
+   *
+   * An INSTRUCTION, not a notice. Ignoring it renders the abandoned fragment
+   * followed by the real one, which reads as the agent repeating itself.
+   */
+  | { readonly type: "reset" }
+  | { readonly type: "finish" }
+  /** The server reported the turn as failed. Terminal, and durable server-side. */
+  | { readonly type: "error"; readonly message: string }
+  /**
+   * The transport died without a terminal frame. NOT a failure verdict: the
+   * reply may or may not have been persisted, so the host reconciles on
+   * reconnect rather than showing a permanent error.
+   */
+  | { readonly type: "interrupted" };