task(AI): #3592030 Canvas AI: Remove obsolete region-based AI instructions and the unused page variant descriptions form

Ahmad Khalilrequested to merge
issue/canvas-3592030:3592030-canvas-ai-remove-obsolete-region-based-ai-instructions-and-the-unused-page-variant-descriptions-form into 1.x

Summary

Canvas replaced theme-global regions with page variants: a page's own content still renders in the content region, and the page variant supplies everything around it. canvas_ai still carried the old multi-region model in two places:

  • The canvas_page_builder_agent and canvas_template_builder_agent system prompts described header, footer and sidebar regions and consumed a [canvas_ai:available_regions] token whose value only ever listed content.
  • CanvasAiPageVariantSettingsForm (/admin/config/ai/canvas-ai-page-variant-settings) collected per-variant AI descriptions in canvas_ai.page_variant.settings. Those descriptions reached the prompts only through that same token, so once the token goes they have no consumer.

This MR removes the token and the code that fed it, makes both agents always build in the content region and never generate site chrome, deletes the form with its route, tab, schema and test, and ships post-updates that refresh existing sites.

Closes #3592030.

Out of scope, per the issue: the placement tools keep their region parameter, getRegionIndex() and validateRegionExists() stay, and the multi-region placement tests stay.

What changed

Token and its supplier chain (commit 1)

  • modules/canvas_ai/src/Hook/CanvasAiHooks.php: the available_regions entry is removed from canvas_ai_token_info() and its case from canvas_ai_tokens(). The other ten tokens are untouched.
  • modules/canvas_ai/src/CanvasAiPageBuilderHelper.php: getAvailableRegions(), resolveVariantForContext() and getVariantDescription() are removed together with the PageVariantResolver constructor dependency and four now-unused imports. The service is autowired, so canvas_ai.services.yml needs no change.
  • modules/canvas_ai/src/Controller/CanvasBuilder.php and modules/canvas_dev_ai/src/Controller/CanvasDevAiBuilder.php: the available_regions token context is removed. The dev controller's buildTokenContexts() lost its now-unused $current_layout parameter.
  • ui/src/components/aiExtension/currentLayout.ts: a dangling @see docblock line is removed (comment only, no behavior change).
  • CanvasAiPageBuilderHelperTest::testGetAvailableRegionsSurfacesVariantDescription() is removed with the method it covered.

Prompts (commit 2)

modules/canvas_ai/config/install/ai_agents.ai_agent.canvas_page_builder_agent.yml

  • The "Available regions" context item and the trailing ## Available regions / token block are gone.
  • A Region rule paragraph states that every component goes in the content region and that header, navigation, footer and sidebars are supplied by the page variant and must never be generated or targeted.
  • Layout comprehension and the placement table now speak of the content region only. The target: [REGION_NAME or SLOT_ID] tool syntax stays, because set_component_structure still accepts it.

modules/canvas_ai/config/install/ai_agents.ai_agent.canvas_template_builder_agent.yml

  • description no longer advertises "with or without header and footer"; it states the agent builds the page body in the content region and that the page variant supplies the chrome.
  • "Component Placement Strategy" is reduced to Content Region Only, No Site Chrome (even when the user asks for a page "with a header and footer", build the body and say the page variant provides them) and the existing minimum-sections rule. The "Region Awareness ... active theme" and "Region descriptions" bullets are gone.
  • "Layout Integration" keeps one bullet about what content already holds; the YAML format example uses a single content: key; the ## Available regions block is gone.

Form removal (commit 3)

  • Deleted: modules/canvas_ai/src/Form/CanvasAiPageVariantSettingsForm.php, the canvas_ai.page_variant_settings route, its local task in canvas_ai.links.task.yml, the canvas_ai.page_variant.settings block in config/schema/canvas_ai.schema.yml, and tests/src/Functional/Form/CanvasAiPageVariantSettingsFormTest.php.
  • The use Drupal Canvas AI permission is shared by the other routes and stays.

Post-updates (commit 4)

  • canvas_ai_post_update_0011_reimport_region_free_builder_agents(): re-imports system_prompt for both agents and description for the template builder from config/install, setting only those keys so the per-site uuid and _core hash survive (the 0003/0006 lesson), and logs the usual "customizations overwritten" warning.
  • canvas_ai_post_update_0012_delete_page_variant_settings(): deletes canvas_ai.page_variant.settings from the default storage and every language collection, resets the config factory and rebuilds the router because the route and tab are gone.
  • CanvasAiOrchestratorPostUpdateTest is renamed to CanvasAiPostUpdateTest (existing 0003/0006 cases kept) and gains testPostUpdate0011RefreshesBuilderAgentPrompts() and testPostUpdate0012DeletesPageVariantSettings(). The 0012 test seeds the object through raw config storage in the default and a language.fr collection, since the schema is gone.

Docs and eval harness (commits 5 and 6)

  • docs/page-variants.md: the canvas_ai clause now says agents build only the content region.
  • docs/user/src/content/docs/ai-assistant/index.mdx: the template builder builds the page body; the header and footer example prompts are removed.
  • modules/canvas_ai/tests/modules/canvas_ai_agents_test/tests/test_drupal_canvas_page_builder_agent_test_group.yaml (manual LLM eval harness, not CI): the available_regions token values are stripped from every case, and the one case that existed only to check that a region description drives the heading level is deleted, because that mechanism no longer exists. The multi-region placement cases stay for the follow-up.

No echoai fixture changes: the provider matches on messages and tools, not the system prompt, and no fixture references either agent. No changeset: nothing under packages/* changed.

Testing instructions

Automated

  • [ ] composer run phpunit -- modules/canvas_ai/tests/src/Kernel/CanvasAiPostUpdateTest.php
  • [ ] composer run phpunit -- modules/canvas_ai/tests/src/Kernel/CanvasAiPageBuilderHelperTest.php
  • [ ] composer run phpunit -- modules/canvas_ai/tests/src/Kernel/CanvasAiBuilderControllerTest.php
  • [ ] composer run phpunit -- modules/canvas_ai/tests/src/Kernel/CanvasAiDevControllerTest.php
  • [ ] composer run phpunit -- modules/canvas_ai/tests/src/Kernel/Agents/CanvasDevPageBuilderAgentEndToEndTest.php and .../CanvasComponentAgentEndToEndTest.php (dev controller token contexts changed)
  • [ ] composer run phpunit -- modules/canvas_ai/tests/src/Kernel/Plugin/AiFunctionCall (region validation messages unchanged)
  • [ ] composer run phpunit -- modules/canvas_ai/tests/src/Kernel/CanvasAiDefaultInformationToolsTest.php, .../EventSubscriber/LayoutFixtureSubscriberTest.php, modules/canvas_ai/tests/src/Functional/Form/CanvasDevAiAgentSelectionFormTest.php
  • [ ] composer run lint and npm run lint

Manual, in the UI

Setup:

  • [ ] Check out the branch and run drush cr.
  • [ ] Optional, to exercise the update path: on 1.x first, open /admin/config/ai/canvas-ai-settings → Page Variant Descriptions tab (create a page variant at /admin/structure/canvas/page-variants if none exists), type Lead with a hero section. into a variant's Description and Save configuration; confirm with drush config:get canvas_ai.page_variant.settings. Then check out this branch and drush cr.
  • [ ] A default chat provider is configured at /admin/config/ai/settings (Test 4 makes real provider calls).

Test 1: the post-updates refresh an existing site

  • [ ] Run drush updb -y. Expected: canvas_ai_post_update_0011_reimport_region_free_builder_agents runs with a warning starting "The Canvas AI page builder and template builder agent system prompts have been updated", then canvas_ai_post_update_0012_delete_page_variant_settings, then "Finished performing updates."
  • [ ] drush config:get canvas_ai.page_variant.settings reports that the config does not exist.

Test 2: the form, tab and route are gone

  • [ ] /admin/config/ai/canvas-ai-settings shows General Settings and Component Descriptions (plus Agents & Tools when canvas_dev_ai is installed) and no Page Variant Descriptions tab.
  • [ ] /admin/config/ai/canvas-ai-page-variant-settings is a 404 even for an administrator.
  • [ ] /admin/config/ai/canvas-ai-component-description-settings still loads.

Test 3: the agent prompts no longer mention regions

  • [ ] /admin/config/ai/agents → Edit on Drupal Canvas Page Builder Agent. In Agent Instructions, available_regions has no match; Region rule matches the paragraph "Every component goes in the content region ...".
  • [ ] Edit on Drupal Canvas Template Builder Agent. Description begins "This tool specializes in building the body of a complete web page" and does not contain "with or without header and footer". In Agent Instructions, available_regions and another_region have no match; Content Region Only and No Site Chrome match once each.
  • [ ] Leave both forms without saving.

Test 4: both agents build in the content region (real provider)

A. Site running the shipped chat (no canvas_dev_ai):

  • [ ] Open a Canvas page in the editor and click Open AI Panel (sparkle icon in the top bar).
  • [ ] Send Add a hero section at the top of the page. Expected: a hero appears at the top of the page body; in the Layers panel it sits under Content.
  • [ ] Send Create a landing page for a bakery with a header and footer. Expected: several sections appear in the page body, all under Content; the reply says the header and footer are provided by the page variant; no header, navigation or footer components are created.

B. Site with canvas_dev_ai installed:

  • [ ] Note the current Tools list: drush config:get canvas_dev_ai.settings tools.

  • [ ] Offer both agents as Tools (the Agents & Tools form does not list them, so set config directly and do not save that form during the test):

    drush config:set --input-format=yaml -y canvas_dev_ai.settings tools '[canvas_page_builder_agent, canvas_template_builder_agent]' drush cr

  • [ ] Open a Canvas page in the editor and click Open AI Panel. Click the sliders icon at the bottom-left of the chat input and pick Drupal Canvas Page Builder Agent; send Add a hero section at the top of the page. Expected as in A.

  • [ ] Remove the pill with its ×, pick Drupal Canvas Template Builder Agent, send Create a landing page for a bakery with a header and footer. Expected as in A.

  • [ ] Optional: in DevTools → Network (filter ai-dev), the last response of each turn has an operations array whose components' nodePath values all start with 0 (the content region) and no target other than content.

Cleanup:

  • [ ] Discard the AI-placed components via Review changes, or do not publish.
  • [ ] Setup B only: restore the Tools list, e.g. drush config:set --input-format=yaml -y canvas_dev_ai.settings tools '[]' (or drush php:eval '\Drupal::configFactory()->getEditable("canvas_dev_ai.settings")->set("tools", [])->save();'), then drush cr.
  • [ ] Delete any page variant created only for the optional setup step.

Follow-ups (not in this MR)

  • The placement tools' region parameter and the multi-region placement tests, as noted in the issue.
  • The orchestrator prompt still routes "add a header/footer" requests to the builder agents; those agents now build the body and explain that the page variant provides the chrome.

AI use disclosure

Per Drupal's policy on the use of AI when contributing: this MR was developed with AI assistance (Claude Code). The author reviewed every change, ran the automated tests and lints locally, applied the updates on a live site and verified both agents with the real provider.

Merge request reports