> ⚠️ **Postponed pending approval.** This issue set awaits maintainer approval — see the [approval issue](https://git.drupalcode.org/project/ai/-/work_items/3586639). It targets the **1.6.x branch once it is created**; nothing here is intended for 1.5.x. ### Problem/Motivation Chat responses in the AI ecosystem are plain text plus one trusted-HTML escape hatch. Concretely, on 1.5.x today: - `ChatMessage` carries only `role`, `text`, `files`, `remoteFiles`, `tools`, `toolId`. There is no metadata bag and no slot for structured payloads. - `ChatOutput::$metadata` is `mixed`, settable only through the constructor, and `StreamedChatMessageIterator::reconstructChatOutput()` rebuilds the output as `new ChatOutput($message, $raw, [])` — per-chunk metadata is silently discarded. - The only channel for rich output to a consumer is `ChatProcessorInterface::getPostResponseMarkup(): string` — a raw trusted-HTML string appended after `Xss::filter()`, which every processor must escape by hand. - In ai_agents, `AiAgentEntityWrapper` flattens every tool result to `$tool->getReadableOutput()`; the structured output that `StructuredExecutableFunctionCallInterface` already provides is thrown away. - `AgentToolPreExecuteEvent` fires immediately before `$tool->execute()` but is observe-only — nothing can veto or gate a destructive tool call. - No citations/sources concept exists anywhere in the module. The result: structured tool output, source citations, forms-in-chat, tool confirmations, progress reporting, attachments and entity cards each get reinvented per chatbot, with no shared, frontend-agnostic contract. Rather than inventing a Drupal-specific payload model, this plan adopts the **Model Context Protocol (MCP) shapes, specification revision 2025-06-18**, as the canonical array shapes for rich chat: - **Content blocks** — `text`, `image`, `audio`, `resource_link`, embedded `resource` — each with optional `annotations` (`audience`, `priority`, `lastModified`) and `_meta`. - **Elicitation** — `{message, requestedSchema}` with a flat, primitives-only JSON schema and a `{action: accept|decline|cancel, content?}` result — covering both forms-in-chat and pre-tool confirmation. - **Tool annotations** — `readOnlyHint`, `destructiveHint`, `idempotentHint`, `openWorldHint` (spec defaults: an unannotated tool is assumed destructive and open-world). - **Progress notification params** — `{progressToken, progress, total?, message?}` as an ephemeral transport shape. - **`_meta`** as the extension mechanism for everything MCP does not define (citations anchors, suggested replies, entity card hints). Adopting MCP shapes directly means any MCP-aware frontend can consume our payloads with zero translation, and mcp_client tool results can flow through unchanged. ### Proposed resolution Land the child issues below. Foundation issues define the data model and contracts in ai; capability issues deliver the user-facing features in ai and ai_agents. **Conventions established by this plan (documented in the key registry, child issue 03):** - `_meta` keys follow the MCP key grammar: an optional prefix of dot-separated labels terminated by a single `/`, then a name of alphanumerics, `-`, `_`, `.`. The ai ecosystem reserves the prefix `drupal.org/` with dot-namespaced names — e.g. `drupal.org/ai.citations`, **not** `drupal.org/ai/citations` (slashes are not allowed in the name part). - Contrib modules extend under `drupal.org/<module>.<name>`. - Initial registry: `drupal.org/ai.citations`, `drupal.org/ai.suggested_replies`, `drupal.org/ai.entity`, `drupal.org/ai.tool_call`, `drupal.org/ai.structured_content`, `drupal.org/ai.status_item`, `drupal.org/ai.elicitation_id`, `drupal.org/ai.widgets`. - `ChatMessage::getText()` remains authoritative for block-unaware consumers; content blocks are enrichment, never a replacement. - `annotations.audience` routes payloads: `["user"]` blocks bubble to the end user, `["assistant"]` content feeds the model. Token cost of the agent loop is unchanged. **Child issues (dependency waves):** | Wave | Issue | Project | |---|---|---| | 1 | [#3586641 — `ChatOutput::setMetadata()` + stop discarding streamed chunk metadata](https://git.drupalcode.org/project/ai/-/work_items/3586641) | ai | | 1 | [#3586642 — MCP tool annotations + `ContentBlockProducerInterface`](https://git.drupalcode.org/project/ai/-/work_items/3586642) | ai | | 2 | [#3586643 — MCP content blocks and `_meta` bag on `ChatMessage`](https://git.drupalcode.org/project/ai/-/work_items/3586643) | ai | | 3 | [#3586644 — ChatProcessor structured response channel + block-aware history](https://git.drupalcode.org/project/ai/-/work_items/3586644) | ai | | 3 | [#3586645 — `ChatBlockRenderer` plugin type + default renderers + entity cards](https://git.drupalcode.org/project/ai/-/work_items/3586645) | ai | | 3 | [#3586646 — Elicitation round-trip (request/result objects, pause/resume)](https://git.drupalcode.org/project/ai/-/work_items/3586646) | ai | | 4 | [#3586070 — Preserve structured tool output through the agent loop](https://git.drupalcode.org/project/ai_agents/-/work_items/3586070) | ai_agents | | 4 | [#3586072 — Agent status stream as MCP-shaped progress](https://git.drupalcode.org/project/ai_agents/-/work_items/3586072) | ai_agents | | 5 | [#3586071 — Vetoable pre-execute event + pre-tool confirmation via elicitation](https://git.drupalcode.org/project/ai_agents/-/work_items/3586071) | ai_agents | | 5 | [#3586647 — Citations/sources and suggested replies conventions](https://git.drupalcode.org/project/ai/-/work_items/3586647) | ai | | 5 | [#3586648 — (Optional) Typed context references on user messages](https://git.drupalcode.org/project/ai/-/work_items/3586648) | ai | **Explicitly out of scope:** ai_chatbot/DeepChat integration. The contract is frontend-agnostic; each capability issue carries a one-line consumer-integration note pointing at the contract. Feedback actions (thumbs up/down, retry) are chat-frontend UX, not AI abstraction — the abstraction only needs stable identifiers (delivered via elicitation IDs and history item IDs) so frontends can build such features on top. Durable thread/history persistence is handled by separate in-progress work on 1.5.x and is deliberately not part of this set. ### 2.0.0 wishlist (tracked here, not in children) - Extract a `ChatMessageInterface`; promote content blocks and `_meta` to constructor parameters. - Deprecate `ChatProcessorInterface::getPostResponseMarkup()` in favor of the structured response channel. - Type `ChatOutput::$metadata` as `array` instead of `mixed`. - `getMessageHistory()` returning value objects instead of shaped arrays. - Fold the six `@todo Add to constructor in 2.0.0` setters on `StreamedChatMessageIterator` into the constructor. ### AI Assistance Yes, AI was used to explore the codebase, pressure-test the MCP mapping against the 2025-06-18 specification, and draft this issue set.