## Background — how Canvas AI works today The Canvas AI chat is an **orchestrator system**. Every message goes first to a single orchestrator agent. The orchestrator reads the message, infers the intent, and launches the matching sub-agent: - "Build me a landing page" → orchestrator → page-builder sub-agent - "Create a React component" → orchestrator → component sub-agent - "Write a title / meta description" → orchestrator → the relevant sub-agent The routing is implicit — the user never chooses which sub-agent runs; the orchestrator decides on every turn. Roadmap: https://git.drupalcode.org/project/canvas/-/work_items/3591777 ## What we're changing The revamp makes agent selection **deterministic** and removes the orchestrator round-trip. Instead of the orchestrator inferring intent, the user explicitly picks which sub-agent handles the turn, from the chat UI: 1. A new Drupal backend configuration lets a site select which **Tools** are available in the chat. Each Tool maps to a sub-agent. 2. The selected Tools are exposed to the frontend via `drupalSettings.canvas.ai.tools`. 3. If any Tools exist, the chat input shows a **tool icon**. Clicking it opens a **dropdown** listing the available Tools. 4. **Multiple Tools can be available, but only one Tool is active at a time.** Selecting a Tool makes it the active Tool. 5. On submit, the request to the backend carries a `tools` parameter holding the active Tool's id. The backend runs that Tool's sub-agent for the turn. 6. The active Tool **stays selected across messages** until the user clears it manually or reloads the page. It is not persisted server-side. ### Backend → frontend contract `drupalSettings.canvas.ai.tools` — array of available Tools (may contain several): ```json [ { "id": "canvas_page_builder_agent", "label": "Page builder", "description": "Builds and edits page layouts." }, { "id": "component_agent", "label": "Component builder", "description": "Creates React/Preact code components." } ] ``` Outgoing request (on submit, on every hop of the turn): ``` tools: "<active-tool-id>" // present only while a Tool is active ``` ## Design - Roadmap screenshots (tool icon + open dropdown): {width="284" height="600"} {width="376" height="367"} {width="334" height="177"} - Prototype (built with Claude, linked from the meta issue): https://git.drupalcode.org/-/project/19391/uploads/c314deceeee5e425d1c8a61550b496c4/Drupal_Canvas_AI_V2.html ## Target file The dropdown is added to the chat wizard component `ui/src/components/aiExtension/AiWizardDev.tsx`\ Which was added in https://git.drupalcode.org/project/canvas/-/work_items/3591810 (reference — the expected end-state file: https://git.drupalcode.org/project/canvas/-/blob/b480068995b33cd19d15358f706a80ae84dc8b6a/ui/src/components/aiExtension/AiWizard.tsx) The chat is the deep-chat web component (`deep-chat-react` **2.4.2**), rendered as `<MemoDeepChat>` (a `memo()`-wrapped `DeepChat`). deep-chat has no native selector/dropdown; the only supported input-row hook is the `customButtons` prop. The dropdown is therefore built in React and deep-chat is touched through that single documented prop only. ## Proposed implementation direction Build the dropdown entirely in React; deep-chat contributes only a static trigger button. No deep-chat shadow-DOM mutation. 1. **Trigger** — one `customButtons` entry at `inside-end` (the native "+" upload button already occupies `inside-start`), flat shape only (`{ position, tooltip, onClick }`). Used purely to open the dropdown. 2. **Dropdown + active state** — the trigger opens a controlled Radix `Popover`, rendered as a sibling of `<MemoDeepChat>` and anchored in the input row. It renders the Tool list from `drupalSettings.canvas.ai.tools`, the single active selection, and a clear/remove affordance. All selection UI lives in our React tree; nothing is written onto deep-chat's button (deep-chat rebuilds that button across turns). 3. **Selection state** — a single active Tool id in React, mirrored into the `connect` handler's ref so the send-time handler reads it. 4. **Request wiring** — append the `tools` param in **both** body-build paths (the FormData/file path and the per-hop JSON rebuild in `runHops`) so the active Tool rides every request and every hop. ### Why this direction Canvas is a contrib module on a large number of production sites, and `canvas_ai` graduates with a Canvas release, so this ships broadly and must survive deep-chat minor upgrades. deep-chat is a third-party web component. Keeping the menu, the active state, and the request wiring inside our own React code — and contacting deep-chat through only one documented prop — avoids coupling to undocumented internals (shadow-DOM class names, observers on private structure) that a minor bump could break. It also matches deep-chat's guidance of orchestrating richer controls in the host application. ## Implementation sketch (high level) ```tsx // --- state --- const tools = drupalSettings.canvas?.ai?.tools ?? []; // { id, label, description }[] const [activeToolId, setActiveToolId] = useState<string | null>(null); const [pickerOpen, setPickerOpen] = useState(false); // Mirror the active Tool into the ref the stable connect handler reads at send-time. useEffect(() => { currentValuesRef.current.activeToolId = activeToolId; }, [activeToolId]); // deep-chat trigger button. Memoized so its identity stays stable and does not // re-render <MemoDeepChat> (the useState setter identity is already stable). const CUSTOM_BUTTONS = useMemo( () => (tools.length ? [{ position: 'inside-end', tooltip: 'Select a tool', onClick: () => setPickerOpen((open) => !open), }] : undefined), [tools.length], ); // --- render (existing return, additions marked) --- <Flex direction="column" align="stretch" className={styles.aiWizard}> {/* …existing header (AiWelcome, title, subtitle)… */} <MemoDeepChat ref={chatElementRef} images={DEEP_CHAT_IMAGES} connect={connectConfig} textInput={DEEP_CHAT_TEXT_INPUT} submitButtonStyles={DEEP_CHAT_SUBMIT_BUTTON_STYLES} auxiliaryStyle={DEEP_CHAT_AUXILIARY_STYLE} customButtons={CUSTOM_BUTTONS} // ← NEW: static trigger only /* …other existing props… */ /> {/* NEW: the picker — sibling of the chat, anchored over the input row. */} <Popover.Root open={pickerOpen} onOpenChange={setPickerOpen}> <Popover.Anchor className={styles.menuAnchor} /> <Popover.Content> {tools.map((tool) => ( <ToolRow key={tool.id} tool={tool} active={tool.id === activeToolId} onSelect={() => { setActiveToolId(tool.id); setPickerOpen(false); }} /> ))} {activeToolId && ( <button onClick={() => setActiveToolId(null)}>Clear selection</button> )} </Popover.Content> </Popover.Root> {/* …existing legal footer… */} </Flex> // --- request wiring (inside connectHandler, BOTH branches) --- // FormData / file path: if (currentValuesRef.current.activeToolId) { requestBody.append('tools', currentValuesRef.current.activeToolId); } // JSON path (rebuilt every hop in runHops): requestBody = JSON.stringify({ ...body, /* …existing fields… */ tools: currentValuesRef.current.activeToolId ?? undefined, }); ``` ## Acceptance criteria - Tool icon appears only when `drupalSettings.canvas.ai.tools` is non-empty. - Dropdown lists every available Tool with its label and description. - Exactly one Tool is active at a time; selecting another replaces the active one. - The active Tool persists across messages/turns; it clears on manual removal or page reload. - The `tools` param carries the active Tool id on both the JSON and FormData request paths, on every hop of a multi-hop turn. - Changing or clearing the selection does not reset the chat or wipe in-progress messages. ## Out of scope - The Drupal backend configuration that selects available Tools and populates `drupalSettings.canvas.ai.tools`. - Backend consumption of the `tools` param (running the chosen sub-agent). ## Dependencies - Backend populates `drupalSettings.canvas.ai.tools` with `{ id, label, description }`. - Backend reads the `tools` request param and runs the selected sub-agent. _Issue generated with AI assistance._