> ⚠️ **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**. **Optional capability** — the output-side issue set stands without it. **Depends on:** [content blocks (#3586643)](https://git.drupalcode.org/project/ai/-/work_items/3586643); history persistence via [structured response channel (#3586644)](https://git.drupalcode.org/project/ai/-/work_items/3586644). ### Problem/Motivation The assistant→user direction gets a typed payload model in this plan, but the user→assistant direction still communicates through `text` plus one untyped side-channel. "Chat about this page", "I mean this node", "answer based on this selected paragraph" — context references — currently travel as the free-form `contexts` array that the DeepChat controller stuffs into the request metadata bag: ```php $input->setRequestMetadataValue('contexts', $data['contexts']); ``` This has three problems: 1. **Every frontend invents its own shape.** `contexts` is untyped; a different chatbot attaching page context has no contract to follow, and the assistant prompt-builder consumes whatever arrives ad hoc. 2. **History loses it.** The reference never lands on the user `ChatMessage`, so a reloaded thread cannot show *what* the user was asking about — the model saw context the transcript no longer contains. 3. **Tools can't see it.** An agent tool that needs to know which entity the user means has to parse it back out of prose or prompt scaffolding, even though the frontend knew the entity ID precisely. Created-content input (images, files) is *not* the gap: `ChatMessage` already accepts those (`setImageFromBinary()`, `setFile()`), and `ChatProcessorInterface` already exposes the matching capability discovery (`allowsImages()`, `allowedFileExtensions()`). What is missing is the typed-*reference* equivalent. Input widgets — page selectors, sketchpads, voice recorders — are explicitly **not** this issue: those are frontend affordances, and the abstraction should not know they exist (the same layering that keeps feedback/retry out of this plan; see the meta issue). MCP already models this symmetrically: prompt messages use the same content blocks as results, so a user message carrying a `resource_link` is spec-shaped, not an invention. ### Proposed resolution Reuse the block vocabulary from #3586643 on **user** messages — no new types: - **Entity/page reference:** `{type: "resource_link", uri: "entity:node/5", name: "Pricing page"}` (or a plain URL `uri` for non-entity pages), with `_meta['drupal.org/ai.entity']` where the frontend knows entity type/ID/UUID. `ContentBlock::entityCard()` from #3586643 already builds this. - **Text selection:** an embedded `resource` block `{type: "resource", resource: {uri: <source>, mimeType: "text/plain", text: <excerpt>}}` so the quoted passage and its provenance travel together. - Blocks are attached to the outgoing user `ChatMessage` via the accessors from #3586643 (`addContentBlock()`), persist into history via the extended item shape from #3586644, and render in the transcript through the same `ChatBlockRenderer` path (a user message showing the entity card it referenced). **Capability discovery**, extending the existing `allowsImages()`/`allowedFileExtensions()` pattern on `ChatProcessorInterface` (default in `ChatProcessorBase`): - `acceptedInputBlockTypes(): array` — default `[]` (no blocks accepted; text/images/files behave as today). A processor that understands context references returns e.g. `['resource_link', 'resource']`, and a frontend only offers its selector affordances when the processor accepts them. **Prompt-builder contract** (reference implementation in ai_assistant_api's runner, which already consumes `contexts`): - Document how input blocks are presented to the model: `resource_link`/`resource` blocks become clearly delimited context sections (with entity access checked at prompt-build time using the requesting user — a reference the user cannot view contributes nothing), and are exposed to the function-calling layer so tools can read the referenced entity IDs directly. - The existing `contexts` request-metadata path keeps working; the runner treats it as a legacy alias and the docs mark it superseded. **Out of scope, stated explicitly:** input widgets of any kind (selectors, sketchpads, recorders — consumer UI); new block types; multimodal *created* content (already served by the images/files paths, which get a doc note as the created-content equivalent). **Tests:** kernel test that a user message with an entity `resource_link` survives the round-trip into history and the prompt-builder output; access test that a reference to a forbidden entity is dropped from the prompt; unit test for the capability default. ### Backwards compatibility Additive: new interface method with base default, block handling only activates when a frontend sends blocks *and* the processor accepts them. The `contexts` side-channel is untouched. ### AI Assistance Yes, AI was used to explore the codebase and draft this issue.