feat: Property value operation handlers + generic AI tools

[mattbrailsford]

Stacked on top of #153 — must not merge before #153 lands. The diff here is only the changes added on top.

Summary

Replaces the single, coarse set_value frontend tool with a family of five generic LLM-visible tools (add_item, remove_item, move_item, set_value, clear_value) backed by a schema-aware backend dispatcher and a C# property value handler plugin surface (IAIPropertyValueHandler). Sonnet 4.6 reliably bails into narration when asked to author block-list / block-grid / RTE envelopes (cross-referenced layout/contentData/expose arrays with fresh GUIDs threaded through); these tools shift envelope assembly to the server so the LLM only has to produce 1-4 short fields per call.

The shape mirrors what Sanity ships in production with their Content Agent (operation primitives + path-with-key-predicates + schema validation at dispatch). Same dispatcher, same handlers will be reused by future server-side tools that mutate content not currently in any user's UI.

Architecture

• Backend dispatcher (IAIPropertyValueDispatcher) walks an [propertyAlias, { blockKey: 'X' }, ...] path, calls handlers, returns the mutated root value. Stateless: never reads or writes data — the caller supplies rootValue, the caller persists the result.
• Stateless transformation endpoint (POST /umbraco/ai/management/api/v1/property-value-operation) is the HTTP surface frontend tools consume. Locked behind SectionAccessAI. The endpoint never touches the DB. This lets frontend tools transport the workspace's staged value (preserving the user's unsaved edits) through the dispatcher and back.
• Handler plugin surface (IAIPropertyValueHandler) is C#, auto-discovered via IDiscoverable, registered through builder.AIPropertyValueHandlers(). Third-party editor authors add a handler to gain AI authoring capability with no further plumbing — same lift as registering a custom property editor.
• First-party handlers ship for Umbraco.BlockList, Umbraco.BlockGrid (root-level only in v1), Umbraco.RichText (rejects AddItem — adding to value.blocks without a markup placeholder produces an orphan), Umbraco.MediaPicker3, Umbraco.MultiUrlPicker.
• Frontend tools are thin HTTP consumers: read root value from workspace, POST through the typed PropertyValueOperationsService (hey-api), apply returned value via applyValueChange (the existing workspace staging path — the user's typing and our staging share the same write surface, so dirty-state and undo history keep working).

Load-bearing guarantees

The dispatcher endpoint never reads the property value itself. The caller always supplies it.

A controller-level test asserts this directly: any future change that has the controller swap the supplied rootValue for a freshly-fetched DB read silently breaks the design that lets frontend tools transport unsaved staged changes. The test fails loudly if regressed.

The matching frontend guard — prepareValueForEditor skip-path for pre-built block envelopes (commit 0a8b175f) — protects the staged result from being silently corrupted on the way back into the workspace.

What's intentionally limited in v1

• Block-grid: root-level operations only. gridArea parameter is reserved on the contract for v2 row/area/span work; supplying it today returns a structured operation-not-supported error so the LLM can correct.
• RTE-with-blocks AddItem: rejected. Edit RTE markup via set_value to insert a placeholder, then set_value against the embedded block's properties via path.
• Default-value provider: stub returning null until CMS exposes a unified server-side propertyValuePreset equivalent (CMS-side proposal). In practice, handlers expose canonical empty representations themselves.

Tests

• 42 new unit tests under Umbraco.AI.Tests.Unit/PropertyValueOperations/ (dispatcher, path JSON converter, envelope ops, BlockList / BlockGrid / RichText / MediaPicker3 / MultiUrlPicker handlers).
• 1 controller test asserting the staged-value rule.
• Full unit suite: 794 tests pass, no regressions.
• All five frontend packages build clean (core → prompt → agent → agent-ui → copilot).

Test plan / remaining validation (out of this PR's autonomous scope)

The plan called for three follow-up phases that need an interactive browser session against the demo. They aren't blocking this PR's review but should land before the work goes to release:

• Phase 6 — Sonnet path-construction spike: with the BlockList handler + add_item only, verify Sonnet 4.6 reliably constructs paths for a depth-2 nested operation across ~5 phrasings (e.g. "add a hero block to the inner blocks of the row block"). If reliability is low, tighten tool descriptions and add a path examples section to the entity context preamble. Worst case: fall back to active-entity convention with an open_block tool — flagged so we surface it before demo prep.
• Phase 7 — Demo seed + docs:
  • Verify the seeded "Content Assistant" agent uses AllowedToolScopeIds: ["entity-write"] not explicit IDs (if explicit, add the new tool IDs to the seed, or new tools are invisible in demo).
  • Update docs/public/add-ons/agent/permissions.md with the new tool IDs + migration path for explicit allow-lists.
  • New docs/public/add-ons/agent/property-value-handlers.md — third-party C# handler authoring guide.
• Phase 8 — End-to-end verification matrix on demo (Sonnet 4.6 + GPT-4):
  • "Add a hero block to contentRows with title X" → add_item(path: ["contentRows"], elementType: "hero", values: { title: "X" })
  • "Add a row with two heroes inside" → 1× add_item (returns rowKey) → 2× add_item(path: ["rows", { blockKey: rowKey }, "innerBlocks"], …)
  • "Change the title of the hero block to Z" → set_value(path: ["contentRows", { blockKey }, "title"], value: "Z")
  • "Remove the third block" → remove_item(path: ["contentRows"], blockKey: <key>)
  • "Set the hero image to media XYZ" → add_item(path: ["heroImage"], values: { mediaKey: "XYZ" }) against MediaPicker3
  • "Clear the contentRows" → clear_value(path: ["contentRows"])
  • "Add a hero block" against an RTE property → expect { success: false, error: { code: "operation-not-supported", … } }
  • Stretch: multi-variant document, segmented document, depth-2 nested edit, AI mutation while user has unsaved staged changes (verify staged changes survive).

CMS-side proposals (separate issues, not blocking)

To file against umbraco/Umbraco.CMS after this lands:

1. Native x-allowedElementTypes enrichment on block schemas — currently we patch in aliases via BlockSchemaEnricher.
2. Headless createWithPresets exposure — block managers' assembly logic is editor-component-scoped; a callable service would let our handlers shrink and stay in lock-step with CMS internals.
3. Server-side IPropertyValueDefaultProvider — defaults are scattered across IDataValueEditor.DefaultValue, IPropertyType.GetDefaultValue(), etc. A unified surface would let our DefaultValueProvider be a thin wrapper.

🤖 Generated with Claude Code