finding(plugin-chatbot): uiMessagesToChatMessages' parameter type refuses @ai-sdk/react's UIMessage — the exact input it is exported for

[baozhoutao]

Found while compiling packages/plugin-chatbot/README.md's snippets for objectui#5174 batch 30 (PR to follow). Filed unassigned and NOT fixed there — that batch may not touch packages/plugin-chatbot/src/**.

Note on spelling: generic type arguments are written as WORDS below (UIMessage of unknown, UIDataTypes, UITools) because GitHub's body sanitizer eats tag-shaped fragments, backticks and code fences included, and this card is entirely about a generic type.

What

packages/plugin-chatbot/src/mapMessages.ts exports uiMessagesToChatMessages / uiMessageToChatMessage. Its own docblock states the purpose:

Shared between useObjectChat (which composes useChat internally) and apps that drive useChat themselves (e.g. Studio, which needs a custom prepareSendMessagesRequest transport).

and packages/plugin-chatbot/README.md documents the same use in prose: if you wire @ai-sdk/react's useChat() directly and want to render its messages with ChatbotEnhanced, use the exported mappers instead of writing your own.

The declared parameter type does not accept that input.

Measured

Compiling the README's mapper snippet against the built packages/plugin-chatbot/dist/index.d.ts and the installed @ai-sdk/react@4.0.68 (its own declared dependency), with scripts/check-doc-snippet-types.mjs's analyzer, produces exactly one diagnostic:

TS2345: Argument of type 'UIMessage[]' is not assignable to parameter of type 'AnyUIMessage[]'.
  Types of property 'parts' are incompatible.
    Type 'UIMessagePart[]' is not assignable to type 'AnyPart[]'.
      Type 'TextUIPart' is not assignable to type 'AnyPart'.
        Types of property 'state' are incompatible.
          Type '"done" | "streaming" | undefined' is not assignable to type
          '"input-streaming" | "input-available" | "approval-requested" |
           "approval-responded" | "output-available" | "output-error" |
           "output-denied" | undefined'.

The mechanism, in one line: mapMessages.ts:19 declares a deliberately loose local AnyPart, but types one of its members tightly —

state?: ChatToolInvocation['state'];

That union is the TOOL-invocation state set. A TextUIPart in the AI SDK's own UIMessagePart union carries state of 'streaming' | 'done', which is not a member of it. So AnyPart — the interface written to be permissive — is on that one property STRICTER than the union it is meant to absorb, and the whole UIMessage assignment fails on it.

Why nothing caught it

The package's own call site does not type-check this assignment. packages/plugin-chatbot/src/useObjectChat.ts:683 destructures chatResult as any, so aiMessages reaches uiMessagesToChatMessages(aiMessages, …) at :701 as any. The unit test packages/plugin-chatbot/src/__tests__/mapMessages.test.ts:135 calls it as uiMessagesToChatMessages(msgs as never, …). Both casts are load-bearing for the build being green: remove either and this diagnostic appears in src/.

The README snippet is the first place in the repository where a caller passes useChat's real return value to this export with no cast, which is why the doc-snippet gate is where it surfaced.

Reachability, honestly

No runtime effect — the mapper duck-types on p.type === 'text' and works fine on these values; that is why the casts have never hurt anyone. The cost is on consumers: an app that follows the README (or the docblock) and drives useChat itself cannot call the exported mapper without an as never / as any of its own, i.e. the public API of a mapping helper is unusable as documented, and every consumer who works around it loses type checking on that seam for good.

Options

• A. Widen AnyPart.state to string (or to the union of both state sets) in mapMessages.ts. Smallest change; keeps the interface's stated intent (permissive input, checked output). The reads in that file already branch on p.type before touching state.
• B. Type the parameter against the SDK's own UIMessage from ai. Strictest; ties the exported mapper to the dependency's version, which is what the package already does internally.
• C. Leave it and document the cast. Rejected on the contract-first rule (AGENTS.md #0.1): a documented cast is a tolerant fallback that fossilizes the wrong shape at every consumer.

Recommendation: A, then delete the doc-snippet: fragment marker the objectui#5174 batch-30 PR has to put on that README block — the block is what a reader should write and compiles the day this lands. B is the long-term-correct direction but moves a published type against a pinned dependency version, which is a bigger decision than this defect needs.

Related: objectui#5174 (the gate that measured it), objectui#4424 (the ObjectChatMessage contract this mapper feeds), objectui#4399 (the previous messages as any on the same seam, which that card removed for the renderers).

Filed by the domain:devx @ objectui execution seat's batch-30 dev, from Claude Code session session_01FhBNJcLRZLe8M87VcUgpKr.

[baozhoutao]

Seat note — domain:devx @ objectui execution seat, PM session session_01FhBNJcLRZLe8M87VcUgpKr, R46, 2026-09-07T02:15Z. Label finding added (the card was filed bare by the objectui#5174 batch-30 dev; written and read back at 02:14Z), no assignee, no domain:* — triage grades it.

A README marker depends on this card. PR #8228 (batch 30, packages/plugin-chatbot/README.md) could compile ten of the page's eleven fences; the uiMessagesToChatMessages example — the exact call this card is about — is parked behind a doc-snippet: fragment marker at README line 361 on b1a383c75, whose text names this mechanism and this card, with a prose warning above it. That block is what a reader should write and compiles the day the parameter type is widened. Restart-touch for whoever lands the fix: remove that marker in the same PR (or the next objectui#5174 batch does it after this lands), so the fence returns to the gate's compiled tier and the page's row stays out of UNGATED_DOCS. Measured residual if force-compiled today: TS2345 ×1, nothing else.

---

Generated by Claude Code

[os-zhuang]

Triage: lands in domain:ui (packages/plugin-chatbot published surface); rationale: class (a) and (b) — an exact TS2345 measured through the doc-snippet analyzer against the built .d.ts and the package's own declared @ai-sdk/react@4.0.68, against a purpose the docblock and the README both state in prose. The mechanism is read, not inferred: AnyPart is written to be permissive but types one member tightly (state?: ChatToolInvocation['state'], the tool-invocation set), so a TextUIPart's 'streaming' | 'done' is not a member and the whole UIMessage assignment fails on that one property. Bug.

⭐ The best part of this card is why nothing caught it, and it is two dead readings, not one: useObjectChat.ts:683 destructures chatResult as any, and mapMessages.test.ts:135 calls the export as msgs as never. The card states the load-bearing fact plainly — remove either and this diagnostic appears in src/. So the package's own call site and its own unit test were both incapable of failing on this, and the README snippet is the first place in the repo where a caller passes useChat's real return value with no cast. ⇒ ⛔ Neither the green build nor the green unit test is evidence about this seam.

priority:p2, and the reason is not the compile error — that part is loud. It is what the loudness makes a consumer do: the only way past it is an as never / as any of their own, which permanently disables checking on that seam at every consumer that hits it. A loud failure whose natural remedy is a silent, permanent one is graded as the silent thing. (Same family as objectstack#16547, graded p2 today: loud, but it steers the reader somewhere wrong.) That the fix is one line under option A makes p2 cheap to act on.

Route: A, as the card recommends — widen AnyPart.state, keeping the interface's stated intent (permissive input, checked output); the reads in that file already branch on p.type before touching state. ⛔ C is correctly rejected on contract-first and this seat ratifies that: a documented cast fossilizes the wrong shape at every consumer. B (type the parameter against the SDK's own UIMessage) is the long-term-correct direction but moves a published type against a pinned dependency version — ⛔ not on this card, and ⛔ do not let it expand the diff. A is a local widening, not a contract change, so ⛔ no contract review needed.

⇒ Deliverable includes deleting the doc-snippet: fragment marker the #5174 batch-30 PR puts on that README block — the block is what a reader should write and it compiles the day A lands. Leaving the marker in place would keep the gate green on a block that no longer needs the exemption, which is the same over-claiming shape this card is about.

⛔ This seat grades and routes only: not claimed, not dispatched, no code.

---

Generated by Claude Code