How it works

​

Step 1: Route the intent

• Deterministic planner — unambiguous requests that can be turned into operations by parsing alone produce a plan with no model call at all.
• Fast intent router — a small model on the fast tier handles the next tier of requests.
• Full planner — everything else.

​

Step 2: Plan

• the system prompt that defines the operation vocabulary and how to use it;
• your block schemas — which block types exist on this site, what props each has, what values are legal;
• the current page, as a full PageDoc;
• the user’s message and recent conversation history;
• site context from your site config — purpose, tone and content constraints, when you have declared them.

​

Step 3: Validate against your block schema

1. Does it parse? The operation must match one of the nineteen members of operationSchema.
2. Does the target exist? The page, the block, the anchor block, the list index.
3. Are the props legal? When your site supplied a block manifest, the resulting props are validated against that manifest’s propsSchema — this is the path your custom blocks take. Without a manifest entry, they are validated against the registered Zod schema.
4. Is a polymorphic list row complete? A row added to a list that declares a discriminator must say which shape it is, or it is rejected here with the admissible types in the message.

​

Step 4: Apply, as the plan streams

• remove_block, and every page-level operation (create_page, duplicate_page, rename_page, remove_page, move_page), are held until the whole plan is known. Deleting blocks as they stream would erase content before the destructive-action gate could evaluate the plan’s full scope, and then present an approval card for something already gone.
• Once one structural operation has been deferred, every later operation in that stream is deferred too — a later update_props may target a page the deferred operation has not created yet.

​

What the stream carries

​

Step 5: The live preview updates

1. During streaming, the editor pushes liveDraft frames over the site-editor/v1 postMessage protocol, so individual field values change in place as the model writes them.
2. When operations land, the editor sends draftUpdated.
3. The site re-fetches draft content from the orchestrator (GET /draft/pages) and React re-renders the blocks that changed.
4. The changed or newly added block can be focused and scrolled into view.

​

Where the latency went

​

Step 6: The approval gate

• removes a page — always, whatever that page contains;
• touches more than one page in a single turn;
• contains three or more remove_block operations;
• would remove more than half the blocks on any one page.

​

Step 7: Review, undo, refine

• Undo and redo are per page, per session, capped at 50 entries each way. POST /history/undo, POST /history/redo, and GET /history/status says whether either is available.
• A chat turn is one undo entry. A plan with six operations undoes as one action — a sentence is what the person meant. Direct edits from the visual editor push their own entries as they are made.
• The version log keeps up to 100 entries per session, each with a restorable snapshot. GET /history/log lists them; POST /history/restore goes back to one. Restoring starts a new branch — the state you restored from goes onto the undo stack, so restoring is itself undoable.
• POST /history/discard throws away the whole draft for a slug and returns to what is published.

​

Publishing

​

Publishing a subset

​

The baseline a diff needs

interface CmsPublishContext {
  assets?: Record<string, CmsInlineAsset>
  /** The pages as the adapter last reported them. */
  baseline?: PageDoc[]
  /** @deprecated Misnamed — the same array, under the old name. Read `baseline`. */
  published?: PageDoc[]
}

​

The PublishTarget interface

interface PublishTarget {
  readonly name: string
  canHandle?(ctx: PublishContext): boolean
  publish(ctx: PublishContext): Promise<PublishOutcome>
}

• name — stable identifier, used by the registry and the PUBLISH_TARGET environment variable.
• canHandle() — optional selection hint. A target with no canHandle is only reachable when selected explicitly or by the legacy PUBLISH_MODE fallback.
• publish() — receives the PublishContext (session, scopedSession, siteId, siteOrigin, pages, slugs, siteConfig, generatedImageDir, logger) and returns a PublishOutcome (ok, httpStatus, tracker, response).

​

Built-in targets

​

Environment variables

​

Implementing your own target

import {
  registerPublishTarget,
  type PublishTarget,
  type PublishContext,
  type PublishOutcome,
} from "@avocadostudio-ai/orchestrator-core"

class S3PublishTarget implements PublishTarget {
  readonly name = "s3"

  canHandle(ctx: PublishContext): boolean {
    return ctx.siteId === "my-s3-site"
  }

  async publish(ctx: PublishContext): Promise<PublishOutcome> {
    const { session, pages, slugs, logger } = ctx
    const res = await fetch("https://example.com/publish", {
      method: "POST",
      headers: { "Content-Type": "application/json" },
      body: JSON.stringify({ pages }),
    })

    const now = new Date().toISOString()
    logger.info({ session, slugs, ok: res.ok }, "s3 publish")

    return {
      ok: res.ok,
      httpStatus: res.ok ? 200 : 400,
      tracker: {
        session,
        status: res.ok ? "triggered" : "failed",
        startedAt: now,
        updatedAt: now,
        slugs,
        vercelState: res.ok ? "READY" : "ERROR",
      },
      response: {
        status: res.ok ? "ready" : "failed",
        session,
        slugs,
        message: res.ok ? "Published" : `Upstream returned ${res.status}`,
      },
    }
  }
}

registerPublishTarget(new S3PublishTarget())

​

CMS publishing

​

What never happened