finding(plugin-chatbot): per-message `avatar` / `avatarFallback` work end to end but no authoring-facing type declares them — #4424's `RuntimeOnlyMessageKeys` picked only three keys

[yinlianghui]

Found while covering content/docs/plugins/plugin-chatbot.mdx for #5174 batch 5 (PR #7294). Filed unassigned and not fixed there — that PR's surface is the UNGATED_DOCS ledger plus three doc pages, and this is a package type.

What

Authoring a chatbot node with a per-message avatar override works, all the way through:

• Chatbot resolves it: message.avatarFallback || userAvatarFallback and message.avatar || userAvatarUrl — packages/plugin-chatbot/src/index.tsx:177-178.
• The authoring-to-runtime seam carries it: authoredToRuntimeMessage destructures only role / timestamp / toolInvocations and spreads the rest (...passthrough) — packages/plugin-chatbot/src/chatMessageAdapter.ts:256-262.
• The SDUI renderer feeds it: toRuntimeMessages(messages) into Chatbot — packages/plugin-chatbot/src/renderer.tsx.

But no type an author can name declares those two keys.

type	declares avatar / avatarFallback?
ChatMessage from @object-ui/types (what ChatbotSchema.messages is typed as)	no
SeamChatMessage from @object-ui/plugin-chatbot	no — RuntimeOnlyMessageKeys is Pick(RuntimeChatMessage, 'buildProgress' or 'blueprintProgress' or 'charts')
ChatMessage from @object-ui/plugin-chatbot (the runtime shape)	yes

So ChatbotSchema.messages is ChatMessage[] from @object-ui/types, and that interface has no index signature — an author who annotates their schema gets TS2353: 'avatarFallback' does not exist in type 'ChatMessage' on a value that renders correctly.

Measured

With the four example schemas on content/docs/plugins/plugin-chatbot.mdx annotated ChatbotSchema, the doc-snippet gate reports exactly five of these, one per documented per-message avatar:

plugin-chatbot.mdx:326:7  TS2353: Object literal may only specify known properties, and 'avatarFallback' does not exist in type 'ChatMessage'.
plugin-chatbot.mdx:350:7  TS2353: ... 'avatarFallback' ...
plugin-chatbot.mdx:376:7  TS2353: ... 'avatarFallback' ...
plugin-chatbot.mdx:382:7  TS2353: ... 'avatarFallback' ...
plugin-chatbot.mdx:393:7  TS2353: ... 'avatarFallback' ...

PR #7294 therefore leaves those three example blocks unannotated rather than deleting working, documented behaviour to satisfy a checker. That is a deliberate hole in that page's gate coverage, and it closes when this is decided.

Why it is worth a card rather than a shrug

This is the residue of #4424, which is the card that introduced SeamChatMessage and named the render-only keys. It picked buildProgress, blueprintProgress and charts — the keys API mode lifts out of the stream — and did not consider the two keys a human author writes by hand. The seam is otherwise exactly the mechanism that is supposed to make this expressible.

Related: #4383 (the barrel used to export two different ChatMessage types), #4399 (the as any this seam replaced), #6169 (the chatbot authoring surface becoming one named type).

Two readings, not resolved here

1. The authoring contract should carry them. Add avatar?: string and avatarFallback?: string to @object-ui/types' ChatMessage, since a metadata author demonstrably writes them and the runtime honours them. Cheapest, and makes declared = enforced true again for this key pair.
2. They are render-only and the seam should carry them. Widen RuntimeOnlyMessageKeys to include them, leaving the pure authoring contract narrow. This keeps @object-ui/types minimal but does not help the ChatbotSchema.messages author, who never names SeamChatMessage — so on its own it does not close the hole above.

Reading 1 is what the measured usage argues for; reading 2 is what the existing seam vocabulary argues for. Someone who owns the authoring contract should pick.

Reachability

Nothing breaks at runtime — the keys work today. The cost is type-level: a TypeScript author annotating their chatbot metadata is told a correct value is wrong, and a documentation page cannot be fully gate-covered.

[os-zhuang]

分诊 — domain:spec / priority:p3 / pm:queue

锚定 (anchoring)：卡片的读法 1（把两个键加进 @object-ui/types 的 ChatMessage）落在 packages/types ⇒ domain:spec；读法 2（放宽 RuntimeOnlyMessageKeys）落在 packages/plugin-chatbot ⇒ domain:ui。按"谁拥有 authoring contract"锚定 domain:spec —— 卡片自己就是这么问的（"Someone who owns the authoring contract should pick"），而且 ChatbotSchema.messages 的类型来自 types，裁决权在那一侧。⚠️ 若裁决走读法 2，这张卡要交接给 domain:ui，见下文。

在 origin/main a472b07 上复核的锚点 —— 全部成立，行号未漂

packages/plugin-chatbot/src/index.tsx:173       ? (message.avatar || userAvatarUrl)
packages/plugin-chatbot/src/index.tsx:177       ? (message.avatarFallback || userAvatarFallback)
packages/plugin-chatbot/src/index.tsx:178       : (message.avatarFallback || assistantAvatarFallback)

packages/plugin-chatbot/src/chatMessageAdapter.ts:91    type RuntimeOnlyMessageKeys = Pick<
packages/plugin-chatbot/src/chatMessageAdapter.ts:92      RuntimeChatMessage,
packages/plugin-chatbot/src/chatMessageAdapter.ts:93      'buildProgress' | 'blueprintProgress' | 'charts'
packages/plugin-chatbot/src/chatMessageAdapter.ts:94    >;
packages/plugin-chatbot/src/chatMessageAdapter.ts:256   const { role, timestamp, toolInvocations, ...passthrough } = message;

三个键、...passthrough、message.avatar* 的读取，全对上。

@object-ui/types 侧的负结果带正控制：packages/types/src/complex.ts:594 export interface ChatMessage，声明体到 :642 共 49 行（这是分母），在其中 grep avatar 与 [key: string] —— 0 命中。所以"没有 avatar 键、也没有 index signature，注解后必然 TS2353"是实测的缺席，不是读错文件。

定级理由

priority:p3：运行期无损，卡片自己写清楚了（"the keys work today"）。代价是类型面 + 一个门禁覆盖洞（PR #7294 在 plugin-chatbot.mdx 上故意留了三块示例不加注解，5 处 TS2353 都是同一对键）。没有静默错答，没有安全面，有明确绕法（不加注解 / as any）。

定型：两条读法都不是 Feature，不踩 manual floor

用机械边界测试逐条过：

• 读法 1 = 把一对已经被消费、已经被文档教授的键补进声明 ⇒ 恢复 declared = enforced ⇒ Bug/tidy。它不加宽可授权面：作者今天就能写、就能渲染出来，只是类型骗他说不行。
• 读法 2 = 把同两个键补进 seam 词表 ⇒ 同理，也是恢复。

所以不需要人工底线，domain:spec 席可以直接裁并落地。⚠️ 但两者都动已发布的 TS 类型，必须带 changeset。

⛔ 给执行席的边界

1. 卡片对读法 2 的自我批评要当真、不要绕过：RuntimeOnlyMessageKeys 放宽了，并不能帮到写 ChatbotSchema.messages 的作者 —— 他从头到尾不会写出 SeamChatMessage 这个名字。单做读法 2 不关闭上面那个门禁洞。若裁决选它，必须同时说明门禁洞怎么办（否则这张卡不算做完）。
2. ⛔ 不要用给 ChatMessage 加 index signature 的办法收工 —— 那正是 finding(types): BaseSchema's [key: string]: any leaves every component schema open, so a "declare the surface" fix can never reject a misspelled TOP-LEVEL key #5155 记录的、让"声明表面"永远无法拒绝拼错键的那个形状，是在这张卡上还债的同时新欠一笔。
3. 落地后回 content/docs/plugins/plugin-chatbot.mdx 把 PR docs(guides,plugins,tooling): clear three .mdx pages off the doc-snippet ledger (#5174 batch 5) #7294 留下的三块示例补上注解，并从 UNGATED_DOCS 里销账 —— 这是本卡的完成判据之一，不是可选尾巴。
4. 若裁决是读法 2，请把 domain:spec 改成 domain:ui 并说明理由，别让 lane 与落点脱节。

⛔ 分诊席不认领、不派单、不写码、不裁决读法。

---

Generated by Claude Code

[os-justin]

Claim: PM loop round R1 (third wave)
Session: session_01BAZFhALsQsGqxui8sNqM8s
Branch: claude/issue-7295-chat-message-avatar-keys
Worktree: objectui-issue-7295
Domain: domain:spec
File surface (region level): packages/types/src/complex.ts — the ChatMessage interface only (:594–642 on 446d93d) · packages/types/src/zod/complex.zod.ts — the ChatMessageSchema object only (:360…) · one pin under packages/types/src/__tests__/ · content/docs/plugins/plugin-chatbot.mdx — annotate the three example blocks PR #7294 left unannotated (no prose rewrite) · scripts/check-doc-snippet-types.mjs — only if an UNGATED_DOCS row for that page still exists (one row removal; a triage-declared completion criterion, comment 5548376176, so the cross-domain touch is declared here) · .changeset/* (@object-ui/types) · ⛔ packages/plugin-chatbot/** read-only (RuntimeOnlyMessageKeys untouched; reading 2 rejected as incomplete by triage's own boundary 1) · ⛔ no index signature on ChatMessage (triage boundary 2, #5155)
Container & model: S, mode:subagent, model: fable = CONTRACT_REVIEW_TIER (two new declared keys on a published payload type)
Clause-②: yes
Serial constraints cleared (file / region granularity per #5734 comment 5551274423): complex.ts / complex.zod.ts are held by no in-flight branch (#5741: packages/core/src/evaluator/**; #6751: one fixture; PR #7726 queued for landing: base.ts / base.zod.ts / form.zod.ts top / expression.*; PR #7723 queued: form.ts / form.zod.ts CheckboxSchema) · plugin-chatbot.mdx untouched by every open branch · the dev merges origin/main before opening the PR and again if a sibling lands; the queue arbitrates.

Premise re-verified by this seat on origin/main = 446d93d (12:22Z): packages/types/src/complex.ts:594 export interface ChatMessage with zero avatar / index-signature hits inside it; zod/complex.zod.ts:360 export const ChatMessageSchema = z.object({ with no avatar member; packages/plugin-chatbot/src/index.tsx:173–178 reads message.avatar / message.avatarFallback; chatMessageAdapter.ts:91–94 RuntimeOnlyMessageKeys = 'buildProgress' | 'blueprintProgress' | 'charts', :256 spreads ...passthrough. Last commits on the two type files: 4ce14f1 (#7655), neither touched the ChatMessage block.

Disposition — reading 1, under a declared veto window (⛔ not a maintainer ruling). Triage (5548376176) graded both readings as Bug-side restoration of declared = enforced, outside the manual floor, and delegated the choice to this seat ("domain:spec 席可以直接裁并落地"); its boundary 1 records that reading 2 alone does not close the doc-gate hole, so reading 1 is the only complete fix: declare avatar?: string and avatarFallback?: string on ChatMessage on both faces, with docblocks citing the read sites. Reversible by a two-line re-declaration if vetoed. Completion criteria carried from triage: the three plugin-chatbot.mdx example blocks get their ChatbotSchema annotations back and the doc-snippet gate stays green on them; no index signature; changeset present.

---

Generated by Claude Code

[os-justin]

Claim (dev seat): implementing under the domain:spec seat's dispatch (PM claim comment 5551795779, session session_01BAZFhALsQsGqxui8sNqM8s, PM loop round R1 third wave).

Branch: claude/issue-7295-chat-message-avatar-keys (pushed empty first as the write-route probe; base 446d93d)
Worktree: objectui-issue-7295

Disposition executed as dispatched — reading 1: avatar?: string and avatarFallback?: string declared on ChatMessage in packages/types/src/complex.ts and on ChatMessageSchema in packages/types/src/zod/complex.zod.ts, each docblock citing the read site (packages/plugin-chatbot/src/index.tsx:173–178). No index signature. packages/plugin-chatbot/** stays read-only (RuntimeOnlyMessageKeys untouched; SeamChatMessage inheritance verified by that package's type-check against the rebuilt types dist). The three content/docs/plugins/plugin-chatbot.mdx example blocks PR #7294 left unannotated (supportChat, salesBot, multiAgentChat) get their ChatbotSchema annotation back. No UNGATED_DOCS row for that page exists on main — PR #7294 already removed it — so nothing under scripts/ is touched.

Zone-2 "before" measured on 446d93d (built packages/types/dist): ChatMessageSchema is a plain strip-mode z.object with no catchall. An authored per-message avatar / avatarFallback parses green through ChatMessageSchema, ChatbotSchema and safeValidateSchema and is DROPPED from the parsed output on all three paths; avatar: 42 is admitted-and-stripped, never refused. The runtime honours the key only because the renderer receives the un-parsed document. Declaring the keys makes the parse keep them and refuse a wrong-typed value at the key — recorded in the PR body as a measured behaviour change (a restoration: the renderer already honours the key). The TS-face "before" reproduces the card's count exactly: the three blocks annotated ChatbotSchema against the base dist give 5 x TS2353 on avatarFallback and nothing else. Both faces of ChatbotSchema's own avatar config keys are string, and the runtime ChatMessage in ChatbotEnhanced.tsx declares both per-message keys as string, so the declared type is not narrower than what the runtime accepts.

Assignee untouched.

---

Generated by Claude Code