Skip to content

Deferred: AI / Agent Forward-Compatibility

Deferred deliberately, not because it's hard — an MCP server is a thin, cheap, late-bindable protocol wrapper — but the design discipline that makes it cheap matters now: every mutation goes through Change[] as the one and only path, so an agent later is just another caller producing Change objects.

Why this is deferred, concretely

The eventual goal, explicitly not needed now: a customer types what they want changed and an agent makes it happen. Not being built now: an MCP server is a thin, late-bindable protocol wrapper, genuinely cheap to add whenever it's wanted.

The one required discipline: one mutation path, not two

The real design question isn't whether to build an MCP server now; it's whether every mutation goes through one well-typed, validated command interface, or gets applied as ad hoc document surgery scattered through the UI. This is exactly what Change[] is for (The Change Model): if it's the only way document content ever changes — a human click or an AI instruction alike — an agent later becomes another caller producing Change objects, not a separate system. The "one way to do a thing" law, applied to a consumer that doesn't exist yet. The lifecycle operations outside Change[] — creating an Element identity, committing, reverting, the fork-level rebase, editing a sharing list — are correspondingly not reachable by an agent producing Changes (The Change Model); an agent that should create Elements, or commit what it composed, would need those gates exposed to it deliberately.

This also sharpens why real server-side enforcement matters beyond human safety (Permissions & Enforcement): if the server validates every Change against tier and schema rules, not just the UI hiding things, an AI agent literally can't do anything a human at that tier couldn't. AI safety comes free from doing the human-safety work properly now.

Two interaction patterns, different costs

Pattern Cost Why
Scoped or targeted context — "in this scene, I want this," or select an Element and say "I want this to do this." Essentially free. Selection is already first-class, explicit state in the current architecture (activeSceneId, activeLayerId, activeItemIndex live in CampaignEditorOutletContext today). An agent needs read access to the same state a human's UI already tracks.
Swap suggestion — the agent notices the selected Element can't do what was asked, but a different Element in the catalogue can, and proposes swapping it in. Genuinely new requirement. Needs each Element to carry a structured, LLM-legible capability description — a semantic summary of what it does ("shows one product with price," "animates a counter") — not just its field list, which describes what values it exposes, never what it's for.

Same shape of decision as the immutable ids: cheap to add now, as each Element gets authored; expensive to retrofit onto an undocumented catalogue later. The catalogue an agent searches should presumably be scoped to the requesting brand or org's visible set (Brand Scoping & Brand Style), not every Element ever authored — not settled here.

The swap action as a compound Change

"Swap Element A for B" is a compound operation: remove the instance of A, add an instance of B at the same position, carry forward whatever fields reasonably transfer — and it lands as one undo step, not two. There is a direct precedent for this shape: pushFieldBatchUndo, already in useRetailStudioStore, bundles multiple field changes into one undo entry. Composer's Change model, and any agent-proposed action, treats "a batch of primitives, one undo step" as first-class from the start (Editing UI & Canvas).

The ongoing cost, named honestly

Capability descriptions need the same ongoing correctness discipline as everything else in a growing shared catalogue. A stale or wrong description fails the same way a shared primitive or component change silently breaking every dependent template does — just surfacing as a bad agent-proposed swap instead of a broken render. A real, ongoing cost going in, not a reason to avoid building this.

Risks

  • An agent given only scoped context could still assemble an unsafe compound edit that's individually valid at every step — the same class of concern the Change model flags for ordinary Changes composing into an invalid end state. Not yet examined for the agent case.
  • How a stale or wrong capability description would get caught. If the retail-studio-template-testing effort turns out to be scoped to render correctness rather than semantic accuracy (its current state is unconfirmed — Testing, Preview & Incident Response), this is a gap neither mechanism covers.

Open questions

  • Whether scoped context alone — the free half — is enough for a first agent integration, or whether swap suggestion needs to ship alongside it to be useful at all.
  • Who authors capability descriptions, and when — at Element authoring time alongside the field manifest, or as a separate pass over an already-built catalogue.