Description
The overlay protocol no longer exposes agent stages to the host application. OverlayChatMessage, returned by GET_MESSAGES and SEND_MESSAGE, carries only id, role and content; custom_content (and with it stages) was part of the legacy Message and has no counterpart in the new protocol. There is also no per-stage event — the host-facing events stop at GPT_START_GENERATING / GPT_END_GENERATING.
The capability itself is not missing from the chat: custom_content.stages is still parsed (libs/chat-shared/src/models/chat.ts) and rendered as a live stage panel (libs/conversation-stages, apps/chat/src/components/ConversationView/ConversationMessageItem.tsx). This is a gap in the overlay protocol only, and it silently breaks hosts that reacted to tool calls.
Scope:
- Add a read-only stages projection to
OverlayChatMessage in libs/chat-overlay/src/protocol/overlay-protocol.ts, populated by the request handlers in apps/chat/src/context/overlay/OverlayContext.tsx.
- Keep the projection host-agnostic: project
Stage from @epam/ai-dial-chat-shared into a narrow overlay type rather than re-exposing the chat's internal entity.
- Follow-up (separate slice): a per-stage event emitted during streaming, so a host can react while the response is still streaming instead of only after
GPT_END_GENERATING.
- Update
docs/chat-overlay-migration-guide.md — the "Changed message and conversation shapes" section currently states that a host reading custom_content has no replacement — and the libs/chat-overlay README.
Use case/motivation
Raised by a host application migrating from the legacy overlay. It inspects the stages (tool calls) in a message's custom_content to react to specific tools — reloading its own canvas when a particular tool has run. With the current protocol the only available signal is GPT_END_GENERATING, which forces an unconditional refresh after every response instead of a targeted one.
Related issues
Confidential information
Description
The overlay protocol no longer exposes agent stages to the host application.
OverlayChatMessage, returned byGET_MESSAGESandSEND_MESSAGE, carries onlyid,roleandcontent;custom_content(and with itstages) was part of the legacyMessageand has no counterpart in the new protocol. There is also no per-stage event — the host-facing events stop atGPT_START_GENERATING/GPT_END_GENERATING.The capability itself is not missing from the chat:
custom_content.stagesis still parsed (libs/chat-shared/src/models/chat.ts) and rendered as a live stage panel (libs/conversation-stages,apps/chat/src/components/ConversationView/ConversationMessageItem.tsx). This is a gap in the overlay protocol only, and it silently breaks hosts that reacted to tool calls.Scope:
OverlayChatMessageinlibs/chat-overlay/src/protocol/overlay-protocol.ts, populated by the request handlers inapps/chat/src/context/overlay/OverlayContext.tsx.Stagefrom@epam/ai-dial-chat-sharedinto a narrow overlay type rather than re-exposing the chat's internal entity.GPT_END_GENERATING.docs/chat-overlay-migration-guide.md— the "Changed message and conversation shapes" section currently states that a host readingcustom_contenthas no replacement — and thelibs/chat-overlayREADME.Use case/motivation
Raised by a host application migrating from the legacy overlay. It inspects the stages (tool calls) in a message's
custom_contentto react to specific tools — reloading its own canvas when a particular tool has run. With the current protocol the only available signal isGPT_END_GENERATING, which forces an unconditional refresh after every response instead of a targeted one.Related issues
Confidential information