## Summary `CanvasDevAiBuilder::render()` returns a hard-coded mocked response. Replace it with a copy of the live `CanvasBuilder::render()` that runs the Canvas component agent with **`$agent->setLooped(FALSE)`**, so the agent stops after each model decision instead of looping to completion inside one request. The controller serializes the paused agent to the tempstore, returns `should_continue`, and `AiWizardDev.tsx` re-POSTs with a freshly built page context until `should_continue` is `FALSE`. ## Why With looping on (the `ai_agents` default), one HTTP request runs the agent until it is finished: model decides → tool executes → model decides again, all server-side. Canvas tools do not change the page on the server — they return structured output that the *browser* applies to the Redux layout. So during a looped run the agent never sees the result of its own tool calls; it works from a prediction, and anything that depends on the previous call's outcome (a UUID it just created, a position relative to it) is a guess. With `setLooped(FALSE)`, each request ends as soon as the model has decided, the browser applies that decision's output to the page, and the next request carries the real page state. The narration for each step comes back in the same response, so no progress-polling endpoint is needed. The component agent is the agent to build this against: its tools work on code components only, so the loop can be debugged without page-placement correctness confounding it. Roadmap item 6: https://git.drupalcode.org/project/canvas/-/work_items/3591777 ## How `setLooped(FALSE)` behaves Read `Drupal\ai_agents\PluginBase\AiAgentEntityWrapper::determineSolvability()` before starting. Per call it: 1. Executes any tool calls **parked by the previous call** (`$this->contextTools`, `:511–537`), appends their results to `toolResults` and the chat history, and clears the parked list. 2. Calls the model. 3. If the model returned tool calls, converts and parks them (`:707`). With looping enabled it then recurses; with `setLooped(FALSE)` it returns instead (`:711`, `:720`) and `finished` stays `FALSE`. 4. If the model returned no tool calls, sets `finished = TRUE` (`:725`). Two consequences the implementation depends on: - A tool decided in request N executes at the start of request N+1 — after the browser has applied request N's output and rebuilt the layout. That lag is the point, not a bug to work around. - The parked call is part of `toArray()` (`:1628`) / `fromArray()` (`:1737`), so serializing the agent preserves the pending decision. ## Current behavior - `CanvasDevAiBuilder::render()` validates the CSRF token and returns `{ status: TRUE, should_continue: FALSE, message: 'This is a mocked response from the Canvas Dev AI controller.', progress: '' }` (https://git.drupalcode.org/project/canvas/-/work_items/3591809). No agent runs. - `AiWizardDev.tsx` posts once per submitted message and renders `message`, ignoring `should_continue` and `progress` (https://git.drupalcode.org/project/canvas/-/work_items/3591810). It sends no `request_id`. - `CanvasAiTempStore` has `setData()` / `getData()` / `deleteData()` and the `current_layout` key. It has no way to store agent state. ## Reference implementation A working end-to-end version of this flow — controller, serialized agent state, `should_continue`, per-response narration and the browser loop — exists in the POC merge request: https://git.drupalcode.org/project/canvas/-/merge_requests/1214 Use it to see the mechanics working together, not as a template. It was built as a fast prototype to prove the approach, largely AI-generated and never reviewed to contribution standard, so treat every detail in it as a suggestion. Cleaner or simpler implementations of any step below are welcome; the steps describe the required behavior, not the only way to get it. ## Proposed ### 1. Add agent-state storage to `CanvasAiTempStore` (`canvas_ai`) Add `private const AGENT_STATE_KEY_PREFIX = 'agent_state_';` and three methods keyed `AGENT_STATE_KEY_PREFIX . $job_id`: - `setStoredAgentState(string $job_id, array $state): void`. - `getStoredAgentState(string $job_id): ?array` — return `NULL` when absent or not an array. - `deleteStoredAgentState(string $job_id): void`. The prefix is private: callers pass a job id, never a key, so nothing outside the service needs it. Additive: nothing in the live flow calls them. ### 2. Copy the live controller into `CanvasDevAiBuilder` Copy `CanvasBuilder::render()` and the private helpers `getMenuFetchSource()` and `getSupportedLibraries()`, plus the constructor dependencies it needs: `ai.provider`, `plugin.manager.ai_agents`, `csrf_token`, `canvas_ai.page_builder_helper`, `canvas_ai.tempstore`, `file.upload_handler`, `ai_agents.agent_status_poller`, `canvas_ai.chat_helper`. Keep the existing CSRF check. Keep, unchanged: the JSON and multipart request branches including the `derived_proptypes` / `selected_component_required_props` decodes; the `message<N>` history reconstruction; `getFilteredChatHistory()`; the uploaded-image handling into `ImageFile` objects; `generateVerboseContextForOrchestrator()` + `formatMessageWithContext()`; the default chat provider, model and `http_client_options.timeout` setup; `setCreateDirectly(TRUE)`; writing `$prompt['current_layout']` to the tempstore before the run; and the four solvability branches (`JOB_NOT_SOLVABLE`, `JOB_SHOULD_ANSWER_QUESTION`, `JOB_INFORMS`, `JOB_SOLVABLE`) including the `BuilderResponseFunctionCallInterface` structured-output merge. ### 3. Delete from the copy - `$this->agentManager->createInstance('canvas_ai_orchestrator')` → `canvas_component_agent`. - **`getAgentDescription()`, and the `/ai-progress` route. Do not copy either** — narration comes back in each response (step 5), so a second channel cannot race the loop. The page-builder, title and metadata machinery the copy inherits — the `'layout'` and `'available_regions'` token contexts, the other eight token contexts, `processCanvasPageFields()`, and the `deleteData(CURRENT_LAYOUT_KEY)` branch keyed on the live page-builder and template-builder plugin ids — is **left in place**. `canvas_component_agent` reads none of it and it is inert at runtime, while the dev page-builder agent consumes most of it, so pruning here and restoring it in the same sprint would be churn. Tracked as followups. ### 4. One model decision per request - Read the turn id from `$prompt['request_id']`. The browser sends the same value on every request of one turn (step 6). Treat it as **required**: a missing or empty value is a client contract violation, so reject the request with a 400 naming the missing key rather than defaulting to `''` and keying stored state on it. One guard, once, so nothing downstream has to re-check it. - Before building anything, load `$stored_state = $this->canvasAiTempStore->getStoredAgentState($job_id);`. - If `$stored_state !== NULL`, call `$agent->fromArray($stored_state)` and **skip the fresh-turn seeding** — `fromArray()` restores the chat input and history, so calling `setChatInput()` / `setChatHistory()` again would duplicate the user message. Otherwise seed as the live controller does. - Apply the token contexts, provider, model and progress tracking on **every** request: they are not part of the serialized state. - `$agent->setLooped(FALSE);` before `determineSolvability()`. - After the call: `$should_continue = !$agent->isFinished();`. If it is `TRUE`, `setStoredAgentState($job_id, $agent->toArray())`; if `FALSE`, `deleteStoredAgentState($job_id)`. - In the `catch` around `determineSolvability()`, call `deleteStoredAgentState($job_id)` before returning the error, so a failed turn does not resume into a broken state. - In the `JOB_SOLVABLE` branch, call `$agent->solve()` **only when `$should_continue` is `FALSE`** — that is the final answer, and there is no answer to render mid-turn. Set `$response['should_continue']` on every response. - Response shape: `{ status, message, should_continue, progress, …structured tool output }`. ### 5. Narration in the response - Before the run: `$agent->setProgressThreadId($job_id);` and `$agent->setDetailedProgressTracking([AiAgentStatusItemTypes::Started, AiAgentStatusItemTypes::TextGenerated]);` - After the run: read `$this->poller->getLatestStatusUpdates($job_id)` and concatenate the `TextGenerated` events' text, separated by a blank line, into `$response['progress']` as a **plain string**. The poller returns the whole turn's updates, so every response carries the narration accumulated so far and the frontend re-renders one block rather than appending. - A list of per-agent items (`id`, `type`, `name`, `status`, `generated_text`) is not needed here: it exists to attribute narration across sub-agents, and one agent runs per turn. Running/completed state is a frontend concern — see step 6. - On the final request, strip the answer off the end of the narration before returning it. The poller records every piece of text the agent generates, the answer included, so it would otherwise render twice — once as narration, once as `message`. `strrpos()` on the answer is enough; guard the empty-answer case, since `strrpos($s, '')` returns `strlen($s)`. ### 6. Frontend loop in `AiWizardDev.tsx` - Generate one id per submitted message (e.g. `req_${Date.now()}_${random}`) and send it as `request_id` on every request of that turn. - Build the Drupal context **once per hop, in one place**, and serialize it per transport: JSON, or appended to the FormData when the user attached a file. Do not keep separate per-branch bodies — that split is what let the live wizard omit `current_layout` on the multipart path and send `selected_component` as the literal string `"undefined"` (`FormData.append()` stringifies `undefined`, where `JSON.stringify` drops the key). - Read the layout, page data and selection from **`store.getState()`** at request time, not from a ref. A ref is written in a `useEffect`, so straight after a hop's handlers dispatch layout changes it still holds the pre-mutation value — a render cycle too late for the next hop. - Only **hop 1** carries the attachments, as multipart. The controller folds them into the agent's stored chat history, so later hops send JSON. Re-POSTing the same FormData would also `append()` a second copy of every context key. - Wrap the `fetch` in a `do … while (data.should_continue)` loop, awaiting the existing response handlers each iteration, since they are what apply the layout changes. - **No iteration cap is needed.** `ai_agents` already bounds the turn: `determineSolvability()` increments `looped` and sets `finished = TRUE` past the agent's `max_loops` (10), and `looped` is serialized by `toArray()` / restored by `fromArray()`, so the count accumulates across hops instead of resetting per request. The over-limit hop returns `JOB_NOT_SOLVABLE` with `should_continue: FALSE` and the browser loop exits. - Aborting the in-flight fetch does not end a `do … while`. Carry a per-turn `{ stopped }` flag, set it on unmount, and check it in the loop condition. - Progress rendering: add one chat message the first time a response carries narration, remember its index, and update it in place on later hops. Add it as **`html`, never `text`** — `CanvasAiChatHelper::getFilteredChatHistory()` only feeds `text` messages back to the model, and that is what keeps narration out of the context window. Escape the narration before injecting it (`&`, `<`, `>`, then `\n` → `<br>`): it is model prose going into markup. - `chatEl.addMessage()` tears down deep-chat's own loading bubble, exactly as `signals.onResponse()` does. The progress message therefore carries its own status row — a spinner while hopping, a completed icon on the final hop. Those classes must live in `auxiliaryStyle`, since deep-chat renders messages inside its shadow root. - Call `signals.onResponse()` **only on the final hop**. Done that way, deep-chat's native loader covers send → first response and the message's own spinner covers the rest. - Preserve scroll position: test whether the reader is pinned to the bottom of deep-chat's shadow-root `#messages` **before** the mutation, and scroll **after** it, deferred a tick. - On a rejected fetch or `status: false`, stop the loop and show the error, leaving the progress block in place so the narration shows how far the turn got. Keep the existing abort handling. ## Tests - Kernel: drive whole turns through the controller, one request per hop, against the `ai` module's `echoai` provider matching recorded fixtures — no stubbed poller and no mocked agent. Cover a one-hop text answer, a two-hop tool call, a three-hop load-then-edit, and a turn carrying an image attachment; assert per hop that `should_continue` mirrors `isFinished()`, that a tool decided in hop N produces its structured output in hop N+1, and that the narration accumulates while the final answer is returned as `message` rather than repeated in it. The mocked-body assertion goes away with the mock; keep the CSRF and `aiDevMode` cases. - Playwright coverage of the browser loop is a followup, not part of this issue. - Running the real agent against a configured provider stays manual (below). Upstream coverage of executing an agent with `setLooped(FALSE)`: https://git.drupalcode.org/project/ai_agents/-/work_items/3586052 ## Acceptance (manual, `canvas_dev_ai` installed, chat provider configured) 1. Ask the dev chat for a new code component: several requests to `/admin/api/canvas/ai-dev` in the network panel, narration appearing as they complete, the component created and opened in the editor, the final reply rendered. 2. Ask for an edit to that component in the same conversation: the edit lands. 3. Ask a plain question needing no tool: one request, an answer, turn ends. 4. Reload mid-turn, then start a new turn: it runs cleanly (the abandoned state is not resumed). ## Explicitly out of scope - The live `/ai` endpoint, `AiWizard.tsx` and `/ai-progress`. - The page-building agent and the `place_components`, `edit_components`, `set_page_value`, `get_component_details` tools — unwired, so the dev chat cannot build a page yet. - Selecting the agent per turn from the chat's Tools dropdown (https://git.drupalcode.org/project/canvas/-/work_items/3591856, https://git.drupalcode.org/project/canvas/-/work_items/3591882). - Keying the stored `current_layout` per turn. It stays one key per user, so two concurrent turns in two tabs can overwrite each other's layout; the tools that read it are not wired to a dev agent yet. - Merging structured output when one response carries repeated calls of the same tool. - Streaming within a single model call. Roadmap: https://git.drupalcode.org/project/canvas/-/work_items/3591777 · POC MR: https://git.drupalcode.org/project/canvas/-/merge_requests/1214 _Issue generated with AI assistance._