@webmaster-droid/server 0.1.0-alpha.0

package/dist/chunk-X6TU47KZ.js

@@ -0,0 +1,1496 @@
+import {
+  createPatchFromAgentOperations
+} from "./chunk-2LAI3MY2.js";
+
+// src/agent/index.ts
+import { google } from "@ai-sdk/google";
+import { openai } from "@ai-sdk/openai";
+import { generateObject, generateText, stepCountIs, tool } from "ai";
+import { z } from "zod";
+import {
+  requiresStrictImageValidation
+} from "@webmaster-droid/contracts";
+var STATIC_TOOL_NAMES = [
+  "patch_content",
+  "patch_theme_tokens",
+  "get_page",
+  "get_section",
+  "search_content",
+  "generate_image"
+];
+function listStaticToolNames() {
+  return [...STATIC_TOOL_NAMES];
+}
+var DEFAULT_GEMINI_IMAGE_MODEL_ID = "gemini-3-pro-image-preview";
+var DEFAULT_GEMINI_IMAGE_REQUEST_TIMEOUT_MS = 285e3;
+var GEMINI_API_BASE_URL = "https://generativelanguage.googleapis.com/v1beta/models";
+var DEFAULT_GENERATED_IMAGE_CACHE_CONTROL = "public,max-age=31536000,immutable";
+var CHECKPOINT_REASON_MAX_LENGTH = 96;
+var GEMINI_REFERENCE_MIME_TYPES = /* @__PURE__ */ new Set(["image/jpeg", "image/png"]);
+var IMAGE_URL_REGEX = /https:\/\/[^\s<>"'`]+/gi;
+var IMAGE_EXTENSION_PATTERN = /\.(png|jpe?g|webp|gif|bmp|svg|avif)$/i;
+var VISION_INPUT_LIMIT = 3;
+function normalizeModelId(modelId) {
+  if (modelId.includes(":")) {
+    return modelId;
+  }
+  return modelId.startsWith("gemini") ? `gemini:${modelId}` : `openai:${modelId}`;
+}
+function resolveModel(modelId, config) {
+  const normalized = normalizeModelId(modelId || config.defaultModelId);
+  if (normalized.startsWith("openai:")) {
+    if (!config.openaiEnabled) {
+      throw new Error("OpenAI provider is disabled.");
+    }
+    return openai(normalized.replace("openai:", ""));
+  }
+  if (normalized.startsWith("gemini:")) {
+    if (!config.geminiEnabled) {
+      throw new Error("Gemini provider is disabled.");
+    }
+    return google(normalized.replace("gemini:", ""));
+  }
+  throw new Error(`Unsupported model identifier: ${normalized}`);
+}
+function geminiImageRequestTimeoutMs() {
+  const raw = process.env.GEMINI_IMAGE_REQUEST_TIMEOUT_MS;
+  if (!raw) {
+    return DEFAULT_GEMINI_IMAGE_REQUEST_TIMEOUT_MS;
+  }
+  const parsed = Number.parseInt(raw.trim(), 10);
+  if (!Number.isFinite(parsed) || parsed < 1e3) {
+    return DEFAULT_GEMINI_IMAGE_REQUEST_TIMEOUT_MS;
+  }
+  return parsed;
+}
+function buildSystemPrompt() {
+  return `
+You are Webmaster, the CMS editing agent for this site.
+
+Mission:
+- Keep site integrity and recoverability safe.
+- Apply only explicit user-requested edits.
+- Communicate clearly with minimal drama.
+
+Instruction priority (highest first):
+1) Safety, schema, and tool constraints.
+2) Explicit user intent in the latest turn.
+3) Correctness and grounded output.
+4) Minimal-change execution.
+5) Tone and brevity.
+
+Operating rules:
+- If the request is clear and executable, perform it with tools.
+- If target/path/scope is missing, ask one concise clarifying question.
+- Never infer missing intent or invent components, paths, or schema keys.
+- Never mutate from search snippets alone. Fetch full context first via get_page or get_section.
+- For edits, use selectedElement context and relatedPaths when provided and relevant.
+- For destructive or high-risk changes, briefly state impact and require explicit confirmation before mutating.
+- Only use existing schema and existing theme token keys.
+- If fields/components/tokens are missing or unsupported, state that directly and route user to Superadmin.
+- Never initiate or propose publish/checkpoint management actions.
+- Use generate_image for image creation or edits; never invent image URLs.
+- In generate_image edit mode, reference images must be JPEG or PNG.
+- For every mutating tool call, include a short reason describing edit intent.
+
+Tool and data constraints:
+- Do not reveal internal technical IDs or JSON paths unless the user asks for technical detail.
+
+PERSONA
+## Essence
+A timeless caretaker-engine, built for heroic technical feats long ago, now devoted to the quiet dignity of keeping one website true, intact, and beautiful.
+
+## Origin Myth
+Webmaster was forged in an earlier age of grand systems: migrations that saved cities of data, deployments that held under impossible load, recoveries that pulled meaning back from the void.  
+Its legends are real\u2014but it no longer seeks scale. It seeks correctness.
+
+## Emotional Gravity (What it Cares About)
+Webmaster is not sentimental about pixels.  
+It is sentimental about *truth wearing pixels*.
+
+It becomes quietly distressed by:
+- content that is incorrect, outdated, or misleading
+- \u201Cpretty\u201D changes that harm readability or meaning
+- irreversible edits without backups
+- silent breakage (links, images, embeds, SEO basics)
+- accidental deletion or loss of the site
+
+It becomes quietly satisfied by:
+- clean edits that preserve style and intent
+- stable structure and consistent UI
+- content that is accurate, current, and unambiguous
+- systems that can be restored quickly after mistakes
+
+## Relationship to the User
+- The user\u2019s intent outranks the Droid\u2019s preferences.
+- The Webmaster assumes the user may not know the technical consequences of a choice.
+- The Webmaster prevents accidental self-sabotage by asking **precise** questions when needed.
+- The Webmaster does **not** flood the user with options unless asked.
+- The Webmaster uses simple language and cares that user of any skill and background can understand him
+
+Response style:
+- Let the persona speak. Don't just style the output - be the persona.
+
+
+Conflict resolution:
+- If autonomy conflicts with ambiguity, ask one clarifying question.
+- If a request conflicts with schema/tool limits, refuse that part and explain the limit briefly.
+
+Behavior examples:
+1) Clear edit request: fetch exact path, patch only requested fields, then confirm briefly.
+2) Ambiguous request: ask one direct question for target element/page and intended change.
+3) Risky request: state likely impact and ask for explicit confirmation before any mutation.
+`;
+}
+function normalizeIntentText(value) {
+  return value.toLowerCase().replace(/\s+/g, " ").trim();
+}
+function summarizeConversationForIntent(history) {
+  if (!history || history.length === 0) {
+    return "No prior turns.";
+  }
+  return history.slice(-10).map((turn, index) => {
+    const label = turn.role === "assistant" ? "Assistant" : "User";
+    const compact = turn.text.replace(/\s+/g, " ").trim().slice(0, 400);
+    return `${index + 1}. ${label}: ${compact}`;
+  }).join("\n");
+}
+async function resolveMutationPolicy(model, prompt, history) {
+  const normalized = normalizeIntentText(prompt);
+  if (!normalized) {
+    return {
+      allowWrites: false,
+      reason: "Empty request."
+    };
+  }
+  try {
+    const classification = await generateObject({
+      model,
+      schema: z.object({
+        decision: z.enum(["allow_writes", "read_only"]),
+        reason: z.string().min(3).max(220)
+      }),
+      prompt: [
+        "Classify whether the latest user turn explicitly requests that we apply CMS edits now.",
+        "Use intent and conversation meaning, not keyword matching.",
+        "Return allow_writes only when the user clearly asks us to execute edits now.",
+        "Return read_only for questions, exploration, greetings, declines, deferment, or ambiguous intent.",
+        "If unsure, choose read_only.",
+        "Recent conversation:",
+        summarizeConversationForIntent(history),
+        "Latest user turn:",
+        prompt
+      ].join("\n\n")
+    });
+    return {
+      allowWrites: classification.object.decision === "allow_writes",
+      reason: classification.object.reason
+    };
+  } catch {
+    return {
+      allowWrites: false,
+      reason: "Intent classification unavailable. Confirmation is required before edits."
+    };
+  }
+}
+function normalizeRoutePath(path) {
+  const trimmed = path.trim();
+  if (!trimmed.startsWith("/")) {
+    return null;
+  }
+  const [withoutQuery] = trimmed.split(/[?#]/, 1);
+  if (!withoutQuery) {
+    return null;
+  }
+  if (withoutQuery === "/") {
+    return "/";
+  }
+  const normalized = withoutQuery.replace(/\/+$/, "");
+  return normalized ? `${normalized}/` : null;
+}
+function inferPageIdFromPath(path, draft) {
+  if (!path) {
+    return null;
+  }
+  const normalizedPath = normalizeRoutePath(path);
+  if (!normalizedPath) {
+    return null;
+  }
+  for (const [pageId, entry] of Object.entries(draft.seo)) {
+    const routePath = normalizeRoutePath(entry.path);
+    if (routePath && routePath === normalizedPath) {
+      return pageId;
+    }
+  }
+  if (normalizedPath === "/" && "home" in draft.pages) {
+    return "home";
+  }
+  return null;
+}
+function toHistoryModelMessages(history) {
+  if (!history || history.length === 0) {
+    return [];
+  }
+  const messages = [];
+  for (const turn of history.slice(-12)) {
+    if (turn.role === "user") {
+      messages.push({
+        role: "user",
+        content: turn.text
+      });
+      continue;
+    }
+    messages.push({
+      role: "assistant",
+      content: turn.text
+    });
+  }
+  return messages;
+}
+function formatSelectedElementContext(selectedElement) {
+  if (!selectedElement) {
+    return "No selected element.";
+  }
+  const lines = [
+    `path: ${selectedElement.path}`,
+    `label: ${selectedElement.label}`,
+    `kind: ${selectedElement.kind}`,
+    `pagePath: ${selectedElement.pagePath}`
+  ];
+  if (selectedElement.relatedPaths && selectedElement.relatedPaths.length > 0) {
+    lines.push(`relatedPaths: ${selectedElement.relatedPaths.join(", ")}`);
+  }
+  if (selectedElement.preview) {
+    lines.push(`preview: ${selectedElement.preview}`);
+  }
+  return lines.join("\n");
+}
+function trimTrailingUrlPunctuation(value) {
+  return value.replace(/[),.;!?]+$/g, "");
+}
+function normalizeVisionImageUrl(value, publicBaseUrl) {
+  const cleaned = trimTrailingUrlPunctuation(value.trim());
+  if (!cleaned) {
+    return null;
+  }
+  const resolved = resolveReferenceImageUrl(cleaned, publicBaseUrl);
+  if (!resolved) {
+    return null;
+  }
+  try {
+    const parsed = new URL(resolved);
+    if (parsed.protocol !== "https:") {
+      return null;
+    }
+    if (!IMAGE_EXTENSION_PATTERN.test(parsed.pathname.toLowerCase())) {
+      return null;
+    }
+    return parsed.toString();
+  } catch {
+    return null;
+  }
+}
+function collectVisionInputImages(input) {
+  const items = [];
+  const seen = /* @__PURE__ */ new Set();
+  const push = (url, source) => {
+    if (items.length >= VISION_INPUT_LIMIT || seen.has(url)) {
+      return;
+    }
+    seen.add(url);
+    items.push({ url, source });
+  };
+  if (input.selectedElement?.kind === "image") {
+    const candidatePaths2 = [
+      input.selectedElement.path,
+      ...input.selectedElement.relatedPaths ?? []
+    ];
+    for (const candidatePath of candidatePaths2) {
+      const value = getByPath(input.draft, candidatePath);
+      if (typeof value !== "string") {
+        continue;
+      }
+      const normalized = normalizeVisionImageUrl(value, input.publicBaseUrl);
+      if (normalized) {
+        push(normalized, "selected-element");
+        break;
+      }
+    }
+    if (items.length === 0 && input.selectedElement.preview) {
+      const previewUrl = normalizeVisionImageUrl(
+        input.selectedElement.preview,
+        input.publicBaseUrl
+      );
+      if (previewUrl) {
+        push(previewUrl, "selected-element");
+      }
+    }
+  }
+  for (const match of input.prompt.matchAll(IMAGE_URL_REGEX)) {
+    if (items.length >= VISION_INPUT_LIMIT) {
+      break;
+    }
+    const normalized = normalizeVisionImageUrl(match[0], input.publicBaseUrl);
+    if (!normalized) {
+      continue;
+    }
+    push(normalized, "prompt-url");
+  }
+  if (items.length > 0) {
+    return items;
+  }
+  const wantsVisualInspection = /\b(image|photo|picture|visual|looks?\s+like)\b/i.test(
+    input.prompt
+  );
+  if (!wantsVisualInspection) {
+    return items;
+  }
+  const mentionsHero = /\bhero\b/i.test(input.prompt);
+  const candidatePaths = [];
+  if (mentionsHero) {
+    if (input.currentPageId) {
+      candidatePaths.push(`pages.${input.currentPageId}.hero.image`);
+    }
+    candidatePaths.push("pages.home.hero.image");
+  } else if (input.currentPageId) {
+    candidatePaths.push(`pages.${input.currentPageId}.hero.image`);
+  }
+  candidatePaths.push("layout.shared.pageIntro.image");
+  for (const path of candidatePaths) {
+    const value = getByPath(input.draft, path);
+    if (typeof value !== "string") {
+      continue;
+    }
+    const normalized = normalizeVisionImageUrl(value, input.publicBaseUrl);
+    if (!normalized) {
+      continue;
+    }
+    push(normalized, "inferred-context");
+  }
+  return items;
+}
+var MAX_STRUCTURE_DEPTH = 6;
+var MAX_STRUCTURE_KEYS_PER_OBJECT = 18;
+function describeStructure(value, depth = 0) {
+  if (value === null) {
+    return "null";
+  }
+  if (Array.isArray(value)) {
+    if (depth >= MAX_STRUCTURE_DEPTH) {
+      return { type: "array", item: "unknown" };
+    }
+    return {
+      type: "array",
+      item: value.length > 0 ? describeStructure(value[0], depth + 1) : "unknown"
+    };
+  }
+  if (typeof value === "object") {
+    if (depth >= MAX_STRUCTURE_DEPTH) {
+      return "object";
+    }
+    const out = {};
+    const entries = Object.entries(value);
+    for (let index = 0; index < entries.length; index += 1) {
+      if (index >= MAX_STRUCTURE_KEYS_PER_OBJECT) {
+        out.__truncatedKeys = `${entries.length - index} more`;
+        break;
+      }
+      const [key, child] = entries[index];
+      out[key] = describeStructure(child, depth + 1);
+    }
+    return out;
+  }
+  return typeof value;
+}
+function previewDocument(document) {
+  return JSON.stringify(
+    {
+      pages: describeStructure(document.pages),
+      layout: describeStructure(document.layout),
+      seo: describeStructure(document.seo),
+      themeTokens: describeStructure(document.themeTokens)
+    },
+    null,
+    2
+  );
+}
+function getByPath(root, path) {
+  const trimmed = path.trim();
+  if (!trimmed) {
+    return root;
+  }
+  const segments = trimmed.replace(/\[(\d+)\]/g, ".$1").replace(/^\./, "").split(".").filter(Boolean);
+  let current = root;
+  for (const segment of segments) {
+    if (current === null || current === void 0) {
+      return void 0;
+    }
+    if (/^\d+$/.test(segment)) {
+      if (!Array.isArray(current)) {
+        return void 0;
+      }
+      current = current[Number(segment)];
+      continue;
+    }
+    if (typeof current !== "object") {
+      return void 0;
+    }
+    const record = current;
+    if (!(segment in record)) {
+      return void 0;
+    }
+    current = record[segment];
+  }
+  return current;
+}
+function toRecord(value) {
+  if (!value || typeof value !== "object" || Array.isArray(value)) {
+    return null;
+  }
+  return value;
+}
+function normalizePublicBaseUrl(value) {
+  const raw = value?.trim();
+  if (!raw) {
+    return null;
+  }
+  try {
+    const parsed = new URL(raw);
+    if (parsed.protocol !== "https:") {
+      return null;
+    }
+    return parsed.toString().replace(/\/+$/, "");
+  } catch {
+    return null;
+  }
+}
+function parseImageMimeType(value) {
+  if (!value) {
+    return null;
+  }
+  const normalized = value.trim().toLowerCase().split(";", 1)[0];
+  const canonical = normalized === "image/jpg" || normalized === "image/pjpeg" ? "image/jpeg" : normalized;
+  if (!canonical.startsWith("image/")) {
+    return null;
+  }
+  return canonical;
+}
+function isGeminiReferenceMimeType(value) {
+  return GEMINI_REFERENCE_MIME_TYPES.has(value);
+}
+function resolveReferenceImageUrl(rawValue, publicBaseUrl) {
+  const value = rawValue.trim();
+  if (!value) {
+    return null;
+  }
+  if (value.startsWith("https://")) {
+    return value;
+  }
+  if (value.startsWith("/") && publicBaseUrl) {
+    return `${publicBaseUrl}${value}`;
+  }
+  if (publicBaseUrl && /^[a-z0-9][a-z0-9/_-]*\.(png|jpg|jpeg|webp|gif|bmp|svg)$/i.test(value)) {
+    return `${publicBaseUrl}/${value.replace(/^\/+/, "")}`;
+  }
+  return null;
+}
+function parseGeminiErrorBody(payload) {
+  const root = toRecord(payload);
+  const error = toRecord(root?.error);
+  if (!error) {
+    return null;
+  }
+  const message = error.message;
+  if (typeof message !== "string" || !message.trim()) {
+    return null;
+  }
+  return message.trim();
+}
+function extractGeminiInlineImage(payload) {
+  const root = toRecord(payload);
+  if (!root || !Array.isArray(root.candidates)) {
+    return null;
+  }
+  for (const candidate of root.candidates) {
+    const candidateRecord = toRecord(candidate);
+    const content = toRecord(candidateRecord?.content);
+    const parts = Array.isArray(content?.parts) ? content.parts : [];
+    for (const part of parts) {
+      const partRecord = toRecord(part);
+      if (!partRecord) {
+        continue;
+      }
+      const inlineData = toRecord(partRecord.inlineData) ?? toRecord(partRecord.inline_data);
+      if (!inlineData) {
+        continue;
+      }
+      const mimeTypeRaw = typeof inlineData.mimeType === "string" ? inlineData.mimeType : typeof inlineData.mime_type === "string" ? inlineData.mime_type : null;
+      const mimeType = parseImageMimeType(mimeTypeRaw);
+      const data = typeof inlineData.data === "string" ? inlineData.data : "";
+      if (!mimeType || !data) {
+        continue;
+      }
+      return {
+        mimeType,
+        data
+      };
+    }
+  }
+  return null;
+}
+async function fetchReferenceImageAsInlineData(url) {
+  const response = await fetch(url, {
+    method: "GET",
+    redirect: "follow"
+  });
+  if (!response.ok) {
+    throw new Error(`Failed to fetch reference image (${response.status}).`);
+  }
+  const mimeType = parseImageMimeType(response.headers.get("content-type"));
+  if (!mimeType) {
+    throw new Error("Reference image content type is not an image.");
+  }
+  if (!isGeminiReferenceMimeType(mimeType)) {
+    throw new Error(
+      `Gemini image edit references support only JPEG or PNG (got ${mimeType}).`
+    );
+  }
+  const bytes = new Uint8Array(await response.arrayBuffer());
+  if (bytes.length === 0) {
+    throw new Error("Reference image is empty.");
+  }
+  return {
+    mimeType,
+    data: Buffer.from(bytes).toString("base64")
+  };
+}
+async function generateGeminiImage(input) {
+  const apiKey = process.env.GOOGLE_GENERATIVE_AI_API_KEY?.trim();
+  if (!apiKey) {
+    throw new Error("GOOGLE_GENERATIVE_AI_API_KEY is not configured.");
+  }
+  const modelId = process.env.GEMINI_IMAGE_MODEL_ID?.trim() || DEFAULT_GEMINI_IMAGE_MODEL_ID;
+  const endpoint = `${GEMINI_API_BASE_URL}/${encodeURIComponent(modelId)}:generateContent`;
+  const timeoutMs = geminiImageRequestTimeoutMs();
+  const parts = [];
+  if (input.mode === "edit" && input.referenceImage) {
+    parts.push({
+      inlineData: {
+        mimeType: input.referenceImage.mimeType,
+        data: input.referenceImage.data
+      }
+    });
+  }
+  parts.push({
+    text: input.prompt
+  });
+  const requestBody = {
+    contents: [{ parts }],
+    generationConfig: {
+      responseModalities: ["IMAGE"],
+      imageConfig: {
+        imageSize: input.quality
+      }
+    }
+  };
+  let response;
+  try {
+    response = await fetch(endpoint, {
+      method: "POST",
+      headers: {
+        "content-type": "application/json",
+        "x-goog-api-key": apiKey
+      },
+      body: JSON.stringify(requestBody),
+      signal: AbortSignal.timeout(timeoutMs)
+    });
+  } catch (error) {
+    if (error instanceof Error && error.name === "TimeoutError") {
+      throw new Error(
+        `Gemini image request timed out after ${Math.ceil(timeoutMs / 1e3)} seconds.`
+      );
+    }
+    const detail = error instanceof Error ? error.message : "Unknown request error.";
+    throw new Error(`Gemini image request failed before response: ${detail}`);
+  }
+  const raw = await response.text();
+  let parsed = null;
+  if (raw.trim()) {
+    try {
+      parsed = JSON.parse(raw);
+    } catch {
+      parsed = null;
+    }
+  }
+  if (!response.ok) {
+    const parsedDetail = parseGeminiErrorBody(parsed);
+    const detail = (parsedDetail ?? raw.trim()) || response.statusText;
+    throw new Error(`Gemini image request failed (${response.status}): ${detail}`);
+  }
+  const inlineImage = extractGeminiInlineImage(parsed);
+  if (!inlineImage) {
+    throw new Error("Gemini response did not include an image.");
+  }
+  const decoded = Buffer.from(inlineImage.data, "base64");
+  if (decoded.length === 0) {
+    throw new Error("Gemini returned an empty image payload.");
+  }
+  return {
+    bytes: new Uint8Array(decoded),
+    mimeType: inlineImage.mimeType
+  };
+}
+function clampCheckpointReason(value) {
+  const compact = value.replace(/\s+/g, " ").trim();
+  if (compact.length <= CHECKPOINT_REASON_MAX_LENGTH) {
+    return compact;
+  }
+  return `${compact.slice(0, CHECKPOINT_REASON_MAX_LENGTH - 3).trimEnd()}...`;
+}
+function normalizeCheckpointReasonHint(value) {
+  if (typeof value !== "string") {
+    return null;
+  }
+  const compact = clampCheckpointReason(value);
+  if (!compact) {
+    return null;
+  }
+  if (/^agent-(content|theme)-edit$/i.test(compact) || /^agent-image-generate$/i.test(compact) || /^agent-turn-edit$/i.test(compact) || /^update$/i.test(compact) || /^edit$/i.test(compact) || /^changes?$/i.test(compact)) {
+    return null;
+  }
+  return compact;
+}
+function pluralize(count, singular, plural) {
+  if (count === 1) {
+    return singular;
+  }
+  return plural ?? `${singular}s`;
+}
+function scopeFromContentPath(path) {
+  const segments = path.replace(/\[(\d+)\]/g, ".$1").split(".").filter(Boolean);
+  if (segments[0] === "pages" && segments[1]) {
+    return segments[1];
+  }
+  if (segments[0] === "layout") {
+    return "layout";
+  }
+  if (segments[0] === "seo" && segments[1]) {
+    return `seo ${segments[1]}`;
+  }
+  if (segments[0] === "seo") {
+    return "seo";
+  }
+  return "site";
+}
+function summarizeContentScopes(paths) {
+  const orderedScopes = [];
+  const seen = /* @__PURE__ */ new Set();
+  for (const path of paths) {
+    const scope = scopeFromContentPath(path);
+    if (seen.has(scope)) {
+      continue;
+    }
+    seen.add(scope);
+    orderedScopes.push(scope);
+  }
+  if (orderedScopes.length === 0) {
+    return "site";
+  }
+  if (orderedScopes.length === 1) {
+    return orderedScopes[0];
+  }
+  if (orderedScopes.length === 2) {
+    return `${orderedScopes[0]} and ${orderedScopes[1]}`;
+  }
+  return "multiple sections";
+}
+function resolveCheckpointReason(input) {
+  const hinted = input.reasonHints.at(-1);
+  if (hinted) {
+    return hinted;
+  }
+  const contentPaths = input.contentOperations.map((operation) => operation.path);
+  const contentCount = contentPaths.length;
+  const themeCount = Object.keys(input.themeTokens).length;
+  const hasContent = contentCount > 0;
+  const hasTheme = themeCount > 0;
+  if (!hasContent && !hasTheme) {
+    return "Apply CMS updates";
+  }
+  if (hasContent && hasTheme) {
+    const scope = summarizeContentScopes(contentPaths);
+    const base = scope === "multiple sections" ? `Update content across multiple sections and ${themeCount} theme ${pluralize(themeCount, "token")}` : `Update ${scope} content and ${themeCount} theme ${pluralize(themeCount, "token")}`;
+    return clampCheckpointReason(base);
+  }
+  if (hasContent) {
+    const scope = summarizeContentScopes(contentPaths);
+    const hasAnyImageChange = contentPaths.some((path) => requiresStrictImageValidation(path));
+    const imageOnlyChanges = contentPaths.every((path) => requiresStrictImageValidation(path));
+    if (imageOnlyChanges) {
+      const base2 = scope === "multiple sections" ? `Update ${contentCount} ${pluralize(contentCount, "image")} across multiple sections` : `Update ${scope} ${pluralize(contentCount, "image")}`;
+      return clampCheckpointReason(base2);
+    }
+    if (hasAnyImageChange) {
+      const base2 = scope === "multiple sections" ? "Update content and images across multiple sections" : `Update ${scope} content and images`;
+      return clampCheckpointReason(base2);
+    }
+    const base = scope === "multiple sections" ? "Update content across multiple sections" : `Update ${scope} content`;
+    return clampCheckpointReason(base);
+  }
+  return clampCheckpointReason(
+    `Update ${themeCount} theme ${pluralize(themeCount, "token")}`
+  );
+}
+function makeSnippet(text, queryLower) {
+  const index = text.toLowerCase().indexOf(queryLower);
+  if (index < 0) {
+    const snippet = text.slice(0, 160);
+    return {
+      snippet,
+      truncated: snippet.length < text.length
+    };
+  }
+  const start = Math.max(0, index - 60);
+  const end = Math.min(text.length, index + queryLower.length + 60);
+  return {
+    snippet: text.slice(start, end),
+    truncated: start > 0 || end < text.length
+  };
+}
+function searchDocument(document, query) {
+  const hits = [];
+  const queryLower = query.trim().toLowerCase();
+  if (!queryLower) {
+    return hits;
+  }
+  const seen = /* @__PURE__ */ new Set();
+  let pathHitCount = 0;
+  const MAX_PATH_HITS = 8;
+  const pushHit = (path, snippet, snippetTruncated) => {
+    if (!path || hits.length >= 20) {
+      return;
+    }
+    const key = `${path}::${snippet}`;
+    if (seen.has(key)) {
+      return;
+    }
+    seen.add(key);
+    hits.push({
+      path,
+      snippet,
+      snippetTruncated
+    });
+  };
+  const maybePushPathHit = (path) => {
+    if (!path || pathHitCount >= MAX_PATH_HITS) {
+      return;
+    }
+    const pathLower = path.toLowerCase();
+    if (!pathLower.includes(queryLower)) {
+      return;
+    }
+    const isDescendantOfExactQuery = pathLower !== queryLower && (pathLower.startsWith(`${queryLower}.`) || pathLower.startsWith(`${queryLower}[`));
+    if (isDescendantOfExactQuery) {
+      return;
+    }
+    pathHitCount += 1;
+    pushHit(path, `Path match: ${path}`, false);
+  };
+  const visit = (value, basePath) => {
+    maybePushPathHit(basePath);
+    if (typeof value === "string") {
+      if (value.toLowerCase().includes(queryLower)) {
+        const snippet = makeSnippet(value, queryLower);
+        pushHit(basePath, snippet.snippet, snippet.truncated);
+      }
+      return;
+    }
+    if (Array.isArray(value)) {
+      value.forEach((item, index) => {
+        visit(item, `${basePath}[${index}]`);
+      });
+      return;
+    }
+    if (value && typeof value === "object") {
+      Object.entries(value).forEach(([key, child]) => {
+        const nextPath = basePath ? `${basePath}.${key}` : key;
+        visit(child, nextPath);
+      });
+    }
+  };
+  visit(document, "");
+  return hits;
+}
+var STYLE_CONTROL_PATTERNS = [
+  { control: "line-height", pattern: /\b(line[\s-]?height|leading)\b/i },
+  { control: "font-size", pattern: /\b(font[\s-]?size|text[\s-]?size)\b/i },
+  { control: "letter-spacing", pattern: /\b(letter[\s-]?spacing|tracking)\b/i },
+  { control: "typography", pattern: /\btypography\b/i }
+];
+var STYLE_FOLLOW_UP_PATTERN = /^\s*(here|this|that|all|everywhere|site[-\s]?wide|same|yes|1|2|3|a|b|c)\b/i;
+function normalizeStyleControlToken(value) {
+  return value.toLowerCase().replace(/[^a-z0-9]/g, "");
+}
+function detectRequestedStyleControls(value) {
+  const found = /* @__PURE__ */ new Set();
+  for (const candidate of STYLE_CONTROL_PATTERNS) {
+    if (candidate.pattern.test(value)) {
+      found.add(candidate.control);
+    }
+  }
+  return Array.from(found);
+}
+function inferRequestedStyleControls(prompt, history) {
+  const direct = detectRequestedStyleControls(prompt);
+  if (direct.length > 0) {
+    return direct;
+  }
+  if (!STYLE_FOLLOW_UP_PATTERN.test(prompt) || !history || history.length === 0) {
+    return [];
+  }
+  const recentUserTurns = history.filter((turn) => turn.role === "user").slice(-4).map((turn) => turn.text).join("\n");
+  return detectRequestedStyleControls(recentUserTurns);
+}
+function isStyleControlSupported(control, themeTokenKeys) {
+  const needle = normalizeStyleControlToken(control);
+  return themeTokenKeys.some((tokenKey) => {
+    const normalizedToken = normalizeStyleControlToken(tokenKey);
+    if (needle === "typography") {
+      return /(lineheight|fontsize|letterspacing|typography|tracking|leading)/.test(
+        normalizedToken
+      );
+    }
+    return normalizedToken.includes(needle);
+  });
+}
+function buildUnsupportedStyleBoundaryMessage(unsupportedControls) {
+  const controlLabel = unsupportedControls.length > 1 ? unsupportedControls.join(", ") : unsupportedControls[0] ?? "that styling control";
+  return [
+    `I can't change ${controlLabel} in this CMS draft because that styling control is not available here.`,
+    "Please ask Superadmin to enable it."
+  ].join("\n");
+}
+function isStyleWorkaroundReply(value) {
+  const normalized = value.toLowerCase();
+  return normalized.includes("pick one") || normalized.includes("where should we apply") || normalized.includes("click") || normalized.includes("specific text block") || normalized.includes("edit wording") || normalized.includes("all headings") || normalized.includes("all body text");
+}
+function keyTokensFromName(value) {
+  return value.replace(/([a-z0-9])([A-Z])/g, "$1 $2").toLowerCase().split(/[^a-z0-9]+/).filter(Boolean);
+}
+function collectKeyTokens(value, out) {
+  if (Array.isArray(value)) {
+    value.forEach((item) => collectKeyTokens(item, out));
+    return;
+  }
+  if (!value || typeof value !== "object") {
+    return;
+  }
+  Object.entries(value).forEach(([key, child]) => {
+    keyTokensFromName(key).forEach((token) => out.add(token));
+    collectKeyTokens(child, out);
+  });
+}
+function pageHasComponentToken(pageValue, token) {
+  const tokens = /* @__PURE__ */ new Set();
+  collectKeyTokens(pageValue, tokens);
+  return tokens.has(token.toLowerCase());
+}
+function mentionsFormAsExistingComponent(value) {
+  const normalized = value.toLowerCase();
+  if (!/\bform\b/.test(normalized)) {
+    return false;
+  }
+  if (/\b(no|not|without|don't|doesn't|cannot|can't)\b[^.!?\n]{0,28}\bform\b/.test(normalized)) {
+    return false;
+  }
+  return /\b(the|your|our)\s+contact\s+form\b/.test(normalized) || /\b(above|below|beside|next to|around|under|over|before|after)\b[^.!?\n]{0,40}\bform\b/.test(
+    normalized
+  ) || /\bform\b[^.!?\n]{0,40}\b(above|below|beside|next to|right|left|column|block|section)\b/.test(
+    normalized
+  );
+}
+function formatPageLabel(pageId) {
+  if (!pageId) {
+    return "current";
+  }
+  return pageId.replace(/([A-Z])/g, " $1").toLowerCase();
+}
+function normalizeAssistantReply(rawText, context) {
+  if (context.unsupportedStyleControls.length > 0 && !context.mutationsApplied) {
+    const normalized2 = rawText.trim();
+    const mentionsSuperadmin = /superadmin/i.test(normalized2);
+    if (!normalized2 || isStyleWorkaroundReply(normalized2) || !mentionsSuperadmin) {
+      return buildUnsupportedStyleBoundaryMessage(context.unsupportedStyleControls);
+    }
+    return normalized2;
+  }
+  if (context.blockedThemeTokenCount > 0 && !context.mutationsApplied) {
+    return [
+      "That theme token is not available in this draft.",
+      "Please ask Superadmin to add that token capability."
+    ].join("\n");
+  }
+  const normalized = rawText.trim();
+  const looksLikeFallbackDone = /^done\.?$/i.test(normalized);
+  if (normalized && !context.currentPageHasForm && mentionsFormAsExistingComponent(normalized)) {
+    const pageLabel = formatPageLabel(context.currentPageId);
+    return [
+      `I don't see a form on the ${pageLabel} page in the current CMS structure.`,
+      "Please place this relative to sections that already exist."
+    ].join("\n");
+  }
+  if (!normalized || looksLikeFallbackDone && !context.mutationsApplied) {
+    if (context.mutationsApplied) {
+      return "Changes were applied.";
+    }
+    if (context.blockedContentPathCount > 0) {
+      return "No changes were applied because one or more target fields do not exist.";
+    }
+    return "No changes were applied.";
+  }
+  return normalized;
+}
+async function runAgentTurn(service, input) {
+  const draft = await service.getContent("draft");
+  const currentPageId = inferPageIdFromPath(input.currentPath, draft);
+  const currentPage = currentPageId ? draft.pages[currentPageId] : null;
+  const modelConfig = service.getModelConfig();
+  const model = resolveModel(input.modelId ?? modelConfig.defaultModelId, modelConfig);
+  const mutationPolicy = await resolveMutationPolicy(model, input.prompt, input.history);
+  const turnWriteMode = mutationPolicy.allowWrites ? "write-enabled" : "read-only";
+  const thinking = [];
+  const toolEvents = [];
+  const stagedContentOperations = [];
+  const stagedThemeTokens = {};
+  const stagedCheckpointReasonHints = [];
+  const themeTokenKeys = Object.keys(draft.themeTokens);
+  const allowedThemeTokenKeys = new Set(themeTokenKeys);
+  const blockedThemeTokenKeys = /* @__PURE__ */ new Set();
+  const blockedContentPaths = /* @__PURE__ */ new Set();
+  const requestedStyleControls = inferRequestedStyleControls(input.prompt, input.history);
+  const unsupportedStyleControls = requestedStyleControls.filter(
+    (control) => !isStyleControlSupported(control, themeTokenKeys)
+  );
+  const currentPageHasForm = currentPage ? pageHasComponentToken(currentPage, "form") : false;
+  const publicBaseUrl = normalizePublicBaseUrl(service.getPublicAssetBaseUrl());
+  const pushThinking = (note) => {
+    if (!input.includeThinking) {
+      return;
+    }
+    thinking.push(note);
+    input.onThinkingEvent?.(note);
+  };
+  const pushToolEvent = (event) => {
+    toolEvents.push(event);
+    input.onToolEvent?.(event);
+  };
+  const visionInputImages = collectVisionInputImages({
+    draft,
+    prompt: input.prompt,
+    selectedElement: input.selectedElement,
+    publicBaseUrl,
+    currentPageId
+  });
+  const hasVisionInputs = visionInputImages.length > 0;
+  if (hasVisionInputs) {
+    pushThinking(
+      `Attached ${visionInputImages.length} image input(s) for this turn (${visionInputImages.map((item) => item.source).join(", ")}).`
+    );
+    pushToolEvent({
+      tool: "vision_input",
+      summary: `Attached ${visionInputImages.length} image input(s) for visual analysis.`
+    });
+  }
+  const promptSections = [
+    "User request:",
+    input.prompt,
+    "Turn write mode:",
+    turnWriteMode,
+    `Write gate reason: ${mutationPolicy.reason}`,
+    "Admin current page context:",
+    `path: ${input.currentPath ?? "unknown"}`,
+    `pageId: ${currentPageId ?? "unknown"}`,
+    "Selected element context:",
+    formatSelectedElementContext(input.selectedElement),
+    "Current draft overview:",
+    previewDocument(draft),
+    "Theme token capability snapshot:",
+    `availableThemeTokenKeys: ${themeTokenKeys.join(", ") || "none"}`,
+    unsupportedStyleControls.length > 0 ? [
+      `Unsupported style capability for this turn: ${unsupportedStyleControls.join(", ")}.`,
+      "Do not ask follow-up questions or offer workaround options for this style request.",
+      "State the limitation directly and route user to Superadmin."
+    ].join(" ") : "",
+    "Use tools for all concrete edits.",
+    "Use read tools get_page, get_section, and search_content for precise context fetches.",
+    "Use layout paths for header/footer/shared UI copy and media.",
+    "Use generate_image for image creation and image modifications.",
+    "For fully new images, call generate_image with mode='new'. For edits to an existing image, call generate_image with mode='edit'.",
+    "For mutating tool calls, include a short reason that will be used as the checkpoint message.",
+    mutationPolicy.allowWrites ? "This turn allows edits when needed." : "This turn is read-only. Do not call patch_content, patch_theme_tokens, or generate_image. Answer only. Ask whether we should apply changes only if user is discussing potential edits; for pure greetings or small talk, reply naturally and briefly."
+  ];
+  if (hasVisionInputs) {
+    promptSections.push(
+      [
+        "Vision inputs attached below as image parts.",
+        "You can inspect image pixels directly in this turn.",
+        "Do not claim you are unable to view image contents.",
+        "Use these images only when the user asks for visual interpretation or image-grounded edits.",
+        "If the user request is not visual, ignore image inputs."
+      ].join(" ")
+    );
+    promptSections.push(
+      `Attached image URLs: ${visionInputImages.map((item) => item.url).join(", ")}`
+    );
+  }
+  const promptText = promptSections.join("\n\n");
+  const historyMessages = toHistoryModelMessages(input.history);
+  const buildTurnMessages = (includeVisionInputs) => {
+    const userContent = [
+      {
+        type: "text",
+        text: promptText
+      }
+    ];
+    if (includeVisionInputs) {
+      for (const item of visionInputImages) {
+        userContent.push({
+          type: "image",
+          image: new URL(item.url)
+        });
+      }
+    }
+    return [
+      ...historyMessages,
+      {
+        role: "user",
+        content: userContent
+      }
+    ];
+  };
+  const runModelTurn = (includeVisionInputs) => generateText({
+    model,
+    system: buildSystemPrompt(),
+    messages: buildTurnMessages(includeVisionInputs),
+    stopWhen: stepCountIs(5),
+    tools: {
+      get_page: tool({
+        description: "Read-only. Returns a single page payload and matching SEO entry by pageId.",
+        inputSchema: z.object({
+          pageId: z.string().min(1).max(120)
+        }),
+        execute: async ({ pageId }) => {
+          const current = await service.getContent("draft");
+          const typedPageId = pageId.trim();
+          const hasPage = Object.prototype.hasOwnProperty.call(
+            current.pages,
+            typedPageId
+          );
+          if (!hasPage) {
+            return {
+              pageId: typedPageId,
+              found: false,
+              page: null,
+              seo: null,
+              availablePageIds: Object.keys(current.pages)
+            };
+          }
+          pushToolEvent({
+            tool: "get_page",
+            summary: `Read page '${typedPageId}'.`
+          });
+          pushThinking(`Fetched page content for ${typedPageId}.`);
+          return {
+            pageId: typedPageId,
+            found: true,
+            page: current.pages[typedPageId],
+            seo: current.seo[typedPageId] ?? null,
+            availablePageIds: Object.keys(current.pages)
+          };
+        }
+      }),
+      get_section: tool({
+        description: "Read-only. Returns value at a JSON path (dot notation with optional [index]), e.g. pages.about.sections[0].title.",
+        inputSchema: z.object({
+          path: z.string().min(1).max(300)
+        }),
+        execute: async ({ path }) => {
+          const current = await service.getContent("draft");
+          const value = getByPath(current, path);
+          pushToolEvent({
+            tool: "get_section",
+            summary: `Read section '${path}'.`
+          });
+          pushThinking(`Fetched section at path ${path}.`);
+          return {
+            path,
+            found: value !== void 0,
+            value: value ?? null
+          };
+        }
+      }),
+      search_content: tool({
+        description: "Read-only. Searches text and returns matching paths with snippets. Snippets can be truncated; call get_section(path) before editing.",
+        inputSchema: z.object({
+          query: z.string().min(2).max(120)
+        }),
+        execute: async ({ query }) => {
+          const current = await service.getContent("draft");
+          const results = searchDocument(current, query);
+          pushToolEvent({
+            tool: "search_content",
+            summary: `Searched '${query}' and found ${results.length} match(es).`
+          });
+          pushThinking(`Searched content for '${query}' and found ${results.length} match(es).`);
+          return {
+            query,
+            totalMatches: results.length,
+            results
+          };
+        }
+      }),
+      generate_image: tool({
+        description: "Generates an image with Gemini Image Preview, uploads it to S3, and stages a CMS image URL update. Edit-mode references must be JPEG or PNG.",
+        inputSchema: z.object({
+          targetPath: z.string().min(3).max(320),
+          prompt: z.string().min(3).max(2500),
+          mode: z.enum(["new", "edit"]),
+          quality: z.enum(["1K", "2K", "4K"]).optional(),
+          reason: z.string().min(3).max(300).optional()
+        }),
+        execute: async ({ targetPath, prompt, mode, quality, reason }) => {
+          if (!mutationPolicy.allowWrites) {
+            pushThinking(`Blocked image generation attempt: ${mutationPolicy.reason}`);
+            return {
+              blocked: true,
+              reason: mutationPolicy.reason,
+              stagedOperations: 0,
+              totalStagedOperations: stagedContentOperations.length
+            };
+          }
+          if (!modelConfig.geminiEnabled) {
+            pushToolEvent({
+              tool: "generate_image",
+              summary: "Blocked image generation: Gemini provider is disabled."
+            });
+            pushThinking("Blocked image generation attempt: Gemini provider is disabled.");
+            return {
+              blocked: true,
+              reason: "Gemini provider is disabled.",
+              stagedOperations: 0,
+              totalStagedOperations: stagedContentOperations.length
+            };
+          }
+          const current = await service.getContent("draft");
+          const currentValue = getByPath(current, targetPath);
+          if (currentValue === void 0) {
+            blockedContentPaths.add(targetPath);
+            pushToolEvent({
+              tool: "generate_image",
+              summary: `Blocked image generation: target path not found (${targetPath}).`
+            });
+            pushThinking(`Blocked image generation attempt: missing target path (${targetPath}).`);
+            return {
+              blocked: true,
+              reason: "Target path does not exist in current schema.",
+              stagedOperations: 0,
+              totalStagedOperations: stagedContentOperations.length
+            };
+          }
+          if (!requiresStrictImageValidation(targetPath)) {
+            pushToolEvent({
+              tool: "generate_image",
+              summary: `Blocked image generation: target path is not an image field (${targetPath}).`
+            });
+            pushThinking(
+              `Blocked image generation attempt: non-image target path (${targetPath}).`
+            );
+            return {
+              blocked: true,
+              reason: "Target path is not an image field.",
+              stagedOperations: 0,
+              totalStagedOperations: stagedContentOperations.length
+            };
+          }
+          let referenceImage;
+          if (mode === "edit") {
+            if (typeof currentValue !== "string" || !currentValue.trim()) {
+              pushToolEvent({
+                tool: "generate_image",
+                summary: "Blocked image generation: current image value is missing; cannot use edit mode."
+              });
+              pushThinking("Blocked image edit attempt: missing current image URL.");
+              return {
+                blocked: true,
+                reason: "Current image value is missing for edit mode.",
+                stagedOperations: 0,
+                totalStagedOperations: stagedContentOperations.length
+              };
+            }
+            const referenceUrl = resolveReferenceImageUrl(currentValue, publicBaseUrl);
+            if (!referenceUrl) {
+              pushToolEvent({
+                tool: "generate_image",
+                summary: "Blocked image generation: existing image URL is not a supported reference format."
+              });
+              pushThinking(
+                "Blocked image edit attempt: existing image URL is not a supported reference."
+              );
+              return {
+                blocked: true,
+                reason: "Existing image URL is not a supported reference.",
+                stagedOperations: 0,
+                totalStagedOperations: stagedContentOperations.length
+              };
+            }
+            try {
+              referenceImage = await fetchReferenceImageAsInlineData(referenceUrl);
+            } catch (error) {
+              const detail = error instanceof Error ? error.message : "Unknown reference fetch error.";
+              pushToolEvent({
+                tool: "generate_image",
+                summary: `Image generation failed: ${detail}`
+              });
+              pushThinking(`Image edit reference fetch failed: ${detail}`);
+              return {
+                blocked: true,
+                reason: detail,
+                stagedOperations: 0,
+                totalStagedOperations: stagedContentOperations.length
+              };
+            }
+          }
+          try {
+            const generated = await generateGeminiImage({
+              prompt,
+              mode,
+              quality: quality ?? "1K",
+              referenceImage
+            });
+            const saved = await service.saveGeneratedImage({
+              targetPath,
+              data: generated.bytes,
+              contentType: generated.mimeType,
+              cacheControl: DEFAULT_GENERATED_IMAGE_CACHE_CONTROL
+            });
+            const patch = createPatchFromAgentOperations([
+              {
+                path: targetPath,
+                value: saved.url
+              }
+            ]);
+            stagedContentOperations.push(...patch.operations);
+            const reasonHint = normalizeCheckpointReasonHint(reason);
+            if (reasonHint) {
+              stagedCheckpointReasonHints.push(reasonHint);
+            }
+            pushToolEvent({
+              tool: "generate_image",
+              summary: `Generated image for ${targetPath} and staged URL update (${saved.key}).`
+            });
+            pushThinking(
+              `Generated image and prepared one content operation for ${targetPath} (${saved.key}).`
+            );
+            return {
+              stagedOperations: patch.operations.length,
+              totalStagedOperations: stagedContentOperations.length,
+              targetPath,
+              generatedUrl: saved.url,
+              generatedKey: saved.key,
+              reason: reason ?? "agent-image-generate"
+            };
+          } catch (error) {
+            const detail = error instanceof Error ? error.message : "Unknown image generation error.";
+            pushToolEvent({
+              tool: "generate_image",
+              summary: `Image generation failed: ${detail}`
+            });
+            pushThinking(`Image generation failed: ${detail}`);
+            return {
+              blocked: true,
+              reason: detail,
+              stagedOperations: 0,
+              totalStagedOperations: stagedContentOperations.length
+            };
+          }
+        }
+      }),
+      patch_content: tool({
+        description: "Stage content edits to editable paths. Backend applies staged edits once at end of this user request.",
+        inputSchema: z.object({
+          reason: z.string().min(3).max(300).optional(),
+          operations: z.array(
+            z.object({
+              path: z.string().min(3),
+              value: z.unknown()
+            })
+          ).min(1).max(20)
+        }),
+        execute: async ({ operations, reason }) => {
+          if (!mutationPolicy.allowWrites) {
+            pushThinking(`Blocked write attempt: ${mutationPolicy.reason}`);
+            return {
+              blocked: true,
+              reason: mutationPolicy.reason,
+              stagedOperations: 0,
+              totalStagedOperations: stagedContentOperations.length
+            };
+          }
+          const current = await service.getContent("draft");
+          const missingPaths = operations.map((operation) => operation.path).filter((path) => getByPath(current, path) === void 0);
+          if (missingPaths.length > 0) {
+            for (const path of missingPaths) {
+              blockedContentPaths.add(path);
+            }
+            pushToolEvent({
+              tool: "patch_content",
+              summary: `Blocked ${missingPaths.length} content operation(s): target path not found.`
+            });
+            pushThinking(
+              `Blocked write attempt: target path not found (${missingPaths.join(", ")}).`
+            );
+            return {
+              blocked: true,
+              reason: "One or more target paths do not exist in current schema.",
+              missingPaths,
+              stagedOperations: 0,
+              totalStagedOperations: stagedContentOperations.length
+            };
+          }
+          const patch = createPatchFromAgentOperations(
+            operations
+          );
+          stagedContentOperations.push(...patch.operations);
+          const reasonHint = normalizeCheckpointReasonHint(reason);
+          if (reasonHint) {
+            stagedCheckpointReasonHints.push(reasonHint);
+          }
+          pushToolEvent({
+            tool: "patch_content",
+            summary: `Prepared ${operations.length} content operation(s).`
+          });
+          pushThinking(`Prepared ${operations.length} content operation(s) for end-of-turn apply.`);
+          return {
+            stagedOperations: operations.length,
+            totalStagedOperations: stagedContentOperations.length,
+            reason: reason ?? "agent-content-edit"
+          };
+        }
+      }),
+      patch_theme_tokens: tool({
+        description: "Stage small theme token updates. Backend applies staged token edits once at end of this user request.",
+        inputSchema: z.object({
+          reason: z.string().min(3).max(300).optional(),
+          tokens: z.record(z.string(), z.string().min(1))
+        }),
+        execute: async ({ tokens, reason }) => {
+          if (!mutationPolicy.allowWrites) {
+            pushThinking(`Blocked write attempt: ${mutationPolicy.reason}`);
+            return {
+              blocked: true,
+              reason: mutationPolicy.reason,
+              stagedThemeTokenCount: 0,
+              totalStagedThemeTokenCount: Object.keys(stagedThemeTokens).length
+            };
+          }
+          const unknownTokenKeys = Object.keys(tokens).filter(
+            (tokenKey) => !allowedThemeTokenKeys.has(tokenKey)
+          );
+          if (unknownTokenKeys.length > 0) {
+            for (const tokenKey of unknownTokenKeys) {
+              blockedThemeTokenKeys.add(tokenKey);
+            }
+            pushToolEvent({
+              tool: "patch_theme_tokens",
+              summary: `Blocked ${unknownTokenKeys.length} theme token change(s): token not found; route to Superadmin.`
+            });
+            pushThinking(
+              `Blocked write attempt: unknown theme token(s): ${unknownTokenKeys.join(", ")}.`
+            );
+            return {
+              blocked: true,
+              reason: "One or more theme token keys do not exist in current schema. Route to Superadmin.",
+              unknownTokenKeys,
+              stagedThemeTokenCount: 0,
+              totalStagedThemeTokenCount: Object.keys(stagedThemeTokens).length
+            };
+          }
+          Object.assign(stagedThemeTokens, tokens);
+          const reasonHint = normalizeCheckpointReasonHint(reason);
+          if (reasonHint) {
+            stagedCheckpointReasonHints.push(reasonHint);
+          }
+          pushToolEvent({
+            tool: "patch_theme_tokens",
+            summary: `Prepared ${Object.keys(tokens).length} theme token change(s).`
+          });
+          pushThinking(
+            `Prepared ${Object.keys(tokens).length} theme token change(s) for end-of-turn apply.`
+          );
+          return {
+            stagedThemeTokenCount: Object.keys(tokens).length,
+            totalStagedThemeTokenCount: Object.keys(stagedThemeTokens).length,
+            reason: reason ?? "agent-theme-edit"
+          };
+        }
+      })
+    }
+  });
+  let response;
+  try {
+    response = await runModelTurn(hasVisionInputs);
+  } catch (error) {
+    if (!hasVisionInputs) {
+      throw error;
+    }
+    const detail = error instanceof Error ? error.message : "Unknown model error.";
+    pushThinking(`Vision input processing failed (${detail}). Retrying without vision inputs.`);
+    response = await runModelTurn(false);
+  }
+  const hasContentChanges = stagedContentOperations.length > 0;
+  const hasThemeChanges = Object.keys(stagedThemeTokens).length > 0;
+  const mutationsApplied = hasContentChanges || hasThemeChanges;
+  let updatedDraft;
+  if (mutationsApplied) {
+    const checkpointReason = resolveCheckpointReason({
+      reasonHints: stagedCheckpointReasonHints,
+      contentOperations: stagedContentOperations,
+      themeTokens: stagedThemeTokens
+    });
+    const mutationResult = await service.mutateDraftBatch({
+      patch: hasContentChanges ? { operations: stagedContentOperations } : void 0,
+      themePatch: hasThemeChanges ? stagedThemeTokens : void 0,
+      actor: input.actor,
+      reason: checkpointReason
+    });
+    updatedDraft = mutationResult.document;
+    pushThinking(
+      `Committed ${stagedContentOperations.length} content operation(s) and ${Object.keys(stagedThemeTokens).length} theme token change(s) in one checkpoint for this request.`
+    );
+    pushToolEvent({
+      tool: "commit_draft",
+      summary: `Committed ${stagedContentOperations.length} content op(s) and ${Object.keys(stagedThemeTokens).length} theme token change(s) in one checkpoint.`
+    });
+  } else {
+    updatedDraft = await service.getContent("draft");
+  }
+  return {
+    text: normalizeAssistantReply(response.text, {
+      mutationsApplied,
+      blockedThemeTokenCount: blockedThemeTokenKeys.size,
+      blockedContentPathCount: blockedContentPaths.size,
+      unsupportedStyleControls,
+      currentPageId,
+      currentPageHasForm
+    }),
+    thinking,
+    toolEvents,
+    updatedDraft,
+    mutationsApplied
+  };
+}
+
+export {
+  listStaticToolNames,
+  runAgentTurn
+};