refactor(agent)!: Align AG-UI events with spec and bump @ag-ui/client

[mattbrailsford]

Summary

Stacked on top of #157. Resolves #158.

Started as a @ag-ui/client@0.0.42 → 0.0.53 dependency bump. Expanded once we discovered our event shapes had drifted from the published AG-UI spec — and a subsequent audit found further drift across most of the protocol surface. Going aggressive with one PR because we control both ends of the protocol, so the usual external-coordination cost of breaking wire changes doesn't apply.

Spec alignment landing in this PR

Topic	What changed
@ag-ui/client SDK bump	0.0.42 → 0.0.53. Re-export AG-UI's typed events from transport/types.ts instead of duplicating; #handleEvent now narrows naturally on event.type.
RUN_FINISHED outcome	Flat outcome: string + sibling interrupt/error fields → spec-shaped discriminated union `outcome: { type: "success" }
STATE_SNAPSHOT / STATE_DELTA	Frontend now reads spec field snapshot (was state); delta enforced as IReadOnlyList<JsonElement> (spec types as JSON Patch ops array).
ActivitySnapshotEvent.Content	string → JsonElement (spec types as Record<string, any>).
AGUIMessage	Id is now required (spec mandates id on every message variant). Added optional EncryptedValue (zero-data-retention envelope) and tool-only Error field.
AGUIToolCall.EncryptedValue?	Added optional spec field.
Role narrowing	New AGUITextMessageRole enum restricts TextMessageStart/Chunk roles to `developer
AGUIMessageRole.Reasoning	Added enum value (inert until reasoning emits, but accepts inbound spec-shaped reasoning messages).
Tool.metadata cleanup	Eliminated the forwardedProps.toolMetadata side-channel where metadata was sent in a parallel array and rejoined by name on the server. Tool metadata (scope, isDestructive) now travels inline via the spec's Tool.metadata field. Loosened Parameters from a constrained AGUIToolParameters class to JsonElement per AG-UI's z.ZodAny — supports the full JSON Schema vocabulary (oneOf, enum, $ref).
Resume protocol	Single-object Resume { interruptId, payload: { toolResults[] } } → spec-shaped IReadOnlyList<AGUIResumeEntry> { interruptId, status, payload? }. Server uses toolCallId as the interruptId to recover tool call without extra state.
Multimodal content	Dropped legacy AGUIBinaryInputContent. New typed variants: AGUIImage/Audio/Video/DocumentInputContent with nested source: { type, value, mimeType } discriminator. document is the catch-all per the SDK's official mime-type classifier (image/*/audio/*/video/*/else document). Filenames live in metadata.filename. Server AGUIFileProcessor and AGUIMessageConverter operate on the typed shapes. Frontend input.element.ts (uploads) and message.element.ts (rendering) updated.

Documented deviations we intentionally keep

Deviation	Why	Removal condition
Frontend local types RunFinishedAGUIEvent, AGUIInterrupt, AGUIRunOutcome	Spec docs include outcome discriminated union on RUN_FINISHED, but @ag-ui/client@0.0.53's Zod schema doesn't model it yet — we travel via Zod passthrough.	Drop these once the SDK adds outcome to RunFinishedEventSchema. The C# field stays — it's spec-correct.

Out of scope / follow-up

The audit also surfaced these items, which are net-new feature work or larger surface design and are deliberately deferred:

• REASONING_* events (7 events) + ReasoningMessage model — net-new feature work tied to reasoning support landing.
• AgentCapabilities model + /info advertisement endpoint — net-new public API surface; deserves dedicated design.
• ActivityMessage model — distinct from ActivitySnapshotEvent; not currently used.

These are captured here in the PR description rather than as separate issues so reviewers see the full audit findings, but no separate tracking is being filed.

Test results

• ✅ dotnet build Umbraco.AI.Agent/Umbraco.AI.Agent.slnx — 0 errors
• ✅ dotnet test Umbraco.AI.Agent.Tests.Unit — 135/135 passing (was 137; 2 tests verifying the now-deleted AIFrontendToolFunction.BuildJsonSchema helper were removed)
• ✅ Frontend npx tsc -p tsconfig.api.json — 0 errors in src/transport/

(Pre-existing local frontend errors against @umbraco-cms/backoffice from a parent-dir node_modules shadowing this dev env's worktree are unrelated; CI runs in a clean env.)

Frontend OpenAPI client regeneration

Umbraco.AI.Agent.Web.StaticAssets/Client/src/api/types.gen.ts is auto-generated from the server's OpenAPI spec and still references the legacy multimodal/resume shapes. It should be regenerated via npm run generate-client against the demo site so the committed types match the new server contract.

Test plan

• CI build
• Smoke-test agent streaming end-to-end in demo site:
  • Success path → RUN_FINISHED with outcome.type === "success"
  • Interrupt path → frontend tool surfaces approval, resume array round-trips, tool result injects on next turn
  • Error path → RUN_ERROR, no trailing RUN_FINISHED
  • Tool metadata flow → scope/isDestructive arrive via tool.metadata (not forwardedProps)
  • File upload → typed image/document content with nested source
• Regenerate frontend OpenAPI client (npm run generate-client) and commit types.gen.ts updates

🤖 Generated with Claude Code