> ⚠️ **Postponed pending approval.** Part of the [Chat Fundamentals plan](https://git.drupalcode.org/project/ai/-/work_items/3586640); awaits maintainer approval ([approval issue](https://git.drupalcode.org/project/ai/-/work_items/3586639)). Targets the **1.6.x branch once it is created**. **Depends on:** the [meta plan](https://git.drupalcode.org/project/ai/-/work_items/3586640) (conventions). Foundation for the structured-response, renderer, elicitation, agent-loop and citations child issues (see the meta issue's child list). ### Problem/Motivation `ChatMessage` can carry only text, files, and tool calls (`role`, `text`, `files`, `remoteFiles`, `tools`, `toolId` — all private, no metadata bag, no interface). There is no way to attach a structured, renderable payload to a message: a source list for a RAG answer, a weather card from a tool, a link to a generated entity, an image the assistant wants shown inline. Every rich-output need is forced through untyped strings or the trusted-HTML `getPostResponseMarkup()` channel. Rather than inventing a Drupal-specific payload model, we adopt the MCP content block shapes (spec 2025-06-18) directly — see the meta issue for the rationale. The five block types: ``` {type: "text", text} {type: "image", data: <base64>, mimeType} {type: "audio", data: <base64>, mimeType} {type: "resource_link", uri, name, title?, description?, mimeType?, size?} {type: "resource", resource: {uri, mimeType?, text | blob}} ``` All accept optional `annotations` (`audience: ("user"|"assistant")[]`, `priority: 0..1`, `lastModified`) and `_meta`. Notably, Drupal entity cards need **no custom block type**: core already has the `entity:` URI scheme, so an entity card is a `resource_link` with `uri: "entity:node/5"` plus a `_meta` view-mode hint — pure-MCP consumers degrade to a link, Drupal-aware renderers upgrade to a rendered entity (renderer child issue). ### Proposed resolution **`ContentBlock` value object** — one final class wrapping the canonical MCP array, not a class-per-type hierarchy (a hierarchy would just re-encode the spec and complicate serialization through tempstore and history): - `src/OperationType/Chat/ContentBlock/ContentBlockInterface.php` — `getType(): string`, `getAnnotations(): array`, `getMeta(?string $key = NULL): mixed`, `setMetaValue(string $key, mixed $value): void`, `toArray(): array` (exact MCP shape), `static fromArray(array $data): static`. - `src/OperationType/Chat/ContentBlock/ContentBlock.php` — validates `type` against the five MCP types on construction; named constructors for ergonomics: `::text(string $text)`, `::image(string $base64, string $mimeType)`, `::audio(...)`, `::resourceLink(string $uri, string $name, array $extra = [])`, `::embeddedResource(array $resource)`, plus Drupal sugar `::entityCard(EntityInterface $entity, string $view_mode = 'teaser')` emitting a `resource_link` with an `entity:` URI and `_meta['drupal.org/ai.entity'] = {entity_type, id, uuid, view_mode}`. - The dedicated `ContentBlock` sub-namespace is deliberate: "content block" collides mentally with core Block / `block_content`, so the FQCN disambiguates, and docs consistently say "message content block (MCP)". **`ChatMessage` additions** (BC-safe — the class has no interface, so new methods break nothing): - `getContentBlocks(): array` / `setContentBlocks(array $blocks): void` / `addContentBlock(ContentBlockInterface $block): void` / `hasContentBlocks(): bool` - Message-level `_meta` bag: `getMeta(?string $key = NULL): mixed` / `setMetaValue(string $key, mixed $value): void` - `toArray()` gains optional `content_blocks` (array of MCP arrays) and `_meta` keys; `fromArray()` restores them when present. **Documented invariant:** `text` remains authoritative for block-unaware consumers. Blocks are enrichment; a blocks-aware consumer renders blocks, but `getText()` behavior never changes. A message may carry blocks with no text (pure card) — consumers fall back to rendering blocks' text representation. **`_meta` key registry** — new page under `docs/developers/` documenting: - The MCP key grammar: optional prefix of dot-separated labels terminated by a single `/`, then a name of alphanumerics, `-`, `_`, `.` — so `drupal.org/ai.citations` is valid, `drupal.org/ai/citations` is **not**. - The reserved `drupal.org/` prefix and the 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`. - The convention for contrib: `drupal.org/<module>.<name>`. **Tests:** unit tests for `ContentBlock` validation and each named constructor; `ChatMessage` round-trip via `toArray()`/`fromArray()` with blocks and `_meta`; assertion that messages without blocks serialize identically to today. ### Backwards compatibility All additions. `toArray()` gains two optional keys — consumers doing strict shape assertions on the array should be mentioned in the change record. The only theoretical break is a `ChatMessage` subclass already defining an identically-named method. ### AI Assistance Yes, AI was used to explore the codebase and draft this issue.