@desplega.ai/agent-swarm 2.7.6 → 2.7.7

package/src/themes/tokens.ts

@@ -0,0 +1,218 @@
+/**
+ * Page theme token contract: the dashboard token names that HTML pages
+ * (design version 2) expose.
+ *
+ * A page's look comes only from these custom properties. Presets, per-page
+ * overrides and imported themes all resolve to this set, so one switch
+ * restyles the whole page. Sidebar, action, peer, type-scale and easing
+ * tokens are dashboard-only and stay out of the contract.
+ */
+
+/** Color tokens: one value per mode. */
+export const PAGE_THEME_COLOR_TOKENS = [
+  "--color-background",
+  "--color-foreground",
+  "--color-card",
+  "--color-card-foreground",
+  "--color-surface",
+  "--color-popover",
+  "--color-popover-foreground",
+  "--color-primary",
+  "--color-primary-foreground",
+  "--color-secondary",
+  "--color-secondary-foreground",
+  "--color-muted",
+  "--color-muted-foreground",
+  "--color-accent",
+  "--color-accent-foreground",
+  "--color-destructive",
+  "--color-destructive-foreground",
+  "--color-border",
+  "--color-border-subtle",
+  "--color-input",
+  "--color-ring",
+  "--color-chart-1",
+  "--color-chart-2",
+  "--color-chart-3",
+  "--color-chart-4",
+  "--color-chart-5",
+  "--color-status-success",
+  "--color-status-success-strong",
+  "--color-status-success-foreground",
+  "--color-status-active",
+  "--color-status-active-strong",
+  "--color-status-active-foreground",
+  "--color-status-error",
+  "--color-status-error-strong",
+  "--color-status-error-foreground",
+  "--color-status-info",
+  "--color-status-info-strong",
+  "--color-status-info-foreground",
+  "--color-status-pending",
+  "--color-status-pending-strong",
+  "--color-status-pending-foreground",
+  "--color-status-warning",
+  "--color-status-warning-strong",
+  "--color-status-warning-foreground",
+  "--color-status-paused",
+  "--color-status-paused-strong",
+  "--color-status-paused-foreground",
+  "--color-status-neutral",
+  "--color-status-neutral-strong",
+  "--color-status-neutral-foreground",
+  "--color-status-success-solid",
+  "--color-status-active-solid",
+] as const;
+
+/** Font and radius tokens: one value for both modes. */
+export const PAGE_THEME_SHARED_TOKENS = [
+  "--font-sans",
+  "--font-mono",
+  "--radius-sm",
+  "--radius-md",
+  "--radius-lg",
+  "--radius-xl",
+] as const;
+
+export const PAGE_THEME_TOKENS = [...PAGE_THEME_COLOR_TOKENS, ...PAGE_THEME_SHARED_TOKENS] as const;
+
+export type PageThemeToken = (typeof PAGE_THEME_TOKENS)[number];
+export type PageThemeTokenValues = Partial<Record<PageThemeToken, string>>;
+export type PageThemeTokens = { light: PageThemeTokenValues; dark: PageThemeTokenValues };
+
+type PageThemeColorToken = (typeof PAGE_THEME_COLOR_TOKENS)[number];
+type PageThemeSharedToken = (typeof PAGE_THEME_SHARED_TOKENS)[number];
+
+/** Hive values from the light `@theme` block of `apps/ui/src/styles/globals.css`. */
+const HIVE_SHARED_TOKENS: Record<PageThemeSharedToken, string> = {
+  "--font-sans": '"Space Grotesk", sans-serif',
+  "--font-mono": '"Space Mono", monospace',
+  "--radius-sm": "0.375rem",
+  "--radius-md": "0.5rem",
+  "--radius-lg": "0.625rem",
+  "--radius-xl": "0.625rem",
+};
+
+const HIVE_LIGHT_COLORS: Record<PageThemeColorToken, string> = {
+  "--color-background": "oklch(1 0 0)",
+  "--color-foreground": "oklch(0.141 0.005 285.823)",
+  "--color-card": "oklch(1 0 0)",
+  "--color-card-foreground": "oklch(0.141 0.005 285.823)",
+  "--color-surface": "oklch(0.985 0.0015 286)",
+  "--color-popover": "oklch(1 0 0)",
+  "--color-popover-foreground": "oklch(0.141 0.005 285.823)",
+  "--color-primary": "oklch(0.555 0.163 48.998)",
+  "--color-primary-foreground": "oklch(0.985 0 0)",
+  "--color-secondary": "oklch(0.967 0.001 286.375)",
+  "--color-secondary-foreground": "oklch(0.21 0.006 285.885)",
+  "--color-muted": "oklch(0.967 0.001 286.375)",
+  "--color-muted-foreground": "oklch(0.552 0.016 285.938)",
+  "--color-accent": "oklch(0.943 0.003 286.375)",
+  "--color-accent-foreground": "oklch(0.21 0.006 285.885)",
+  "--color-destructive": "oklch(0.577 0.245 27.325)",
+  "--color-destructive-foreground": "oklch(0.985 0 0)",
+  "--color-border": "oklch(0.92 0.004 286.32)",
+  "--color-border-subtle": "oklch(0.945 0.003 286)",
+  "--color-input": "oklch(0.92 0.004 286.32)",
+  "--color-ring": "oklch(0.555 0.163 48.998)",
+  "--color-chart-1": "oklch(0.646 0.222 41.116)",
+  "--color-chart-2": "oklch(0.6 0.118 184.704)",
+  "--color-chart-3": "oklch(0.398 0.07 227.392)",
+  "--color-chart-4": "oklch(0.828 0.189 84.429)",
+  "--color-chart-5": "oklch(0.769 0.188 70.08)",
+  "--color-status-success": "oklch(0.74 0.1 163)",
+  "--color-status-success-strong": "oklch(0.5 0.09 163)",
+  "--color-status-success-foreground": "oklch(0.21 0.006 285.885)",
+  "--color-status-active": "oklch(0.81 0.11 75)",
+  "--color-status-active-strong": "oklch(0.55 0.1 68)",
+  "--color-status-active-foreground": "oklch(0.21 0.006 285.885)",
+  "--color-status-error": "oklch(0.72 0.12 25)",
+  "--color-status-error-strong": "oklch(0.51 0.14 25)",
+  "--color-status-error-foreground": "oklch(0.21 0.006 285.885)",
+  "--color-status-info": "oklch(0.74 0.09 235)",
+  "--color-status-info-strong": "oklch(0.5 0.09 240)",
+  "--color-status-info-foreground": "oklch(0.21 0.006 285.885)",
+  "--color-status-pending": "oklch(0.84 0.1 95)",
+  "--color-status-pending-strong": "oklch(0.55 0.09 90)",
+  "--color-status-pending-foreground": "oklch(0.21 0.006 285.885)",
+  "--color-status-warning": "oklch(0.76 0.11 55)",
+  "--color-status-warning-strong": "oklch(0.53 0.11 50)",
+  "--color-status-warning-foreground": "oklch(0.21 0.006 285.885)",
+  "--color-status-paused": "oklch(0.71 0.1 262)",
+  "--color-status-paused-strong": "oklch(0.5 0.1 262)",
+  "--color-status-paused-foreground": "oklch(0.21 0.006 285.885)",
+  "--color-status-neutral": "oklch(0.62 0.014 286)",
+  "--color-status-neutral-strong": "oklch(0.48 0.014 286)",
+  "--color-status-neutral-foreground": "oklch(0.21 0.006 285.885)",
+  "--color-status-success-solid": "oklch(0.627 0.194 149.2)",
+  "--color-status-active-solid": "oklch(0.666 0.179 58.318)",
+};
+
+const HIVE_DARK_COLORS: Record<PageThemeColorToken, string> = {
+  "--color-background": "oklch(0.141 0.005 285.823)",
+  "--color-foreground": "oklch(0.985 0 0)",
+  "--color-card": "oklch(0.21 0.006 285.885)",
+  "--color-card-foreground": "oklch(0.985 0 0)",
+  "--color-surface": "oklch(0.185 0.006 286)",
+  "--color-popover": "oklch(0.21 0.006 285.885)",
+  "--color-popover-foreground": "oklch(0.985 0 0)",
+  "--color-primary": "oklch(0.769 0.188 70.08)",
+  "--color-primary-foreground": "oklch(0.21 0.006 285.885)",
+  "--color-secondary": "oklch(0.274 0.006 286.033)",
+  "--color-secondary-foreground": "oklch(0.985 0 0)",
+  "--color-muted": "oklch(0.274 0.006 286.033)",
+  "--color-muted-foreground": "oklch(0.705 0.015 286.067)",
+  "--color-accent": "oklch(0.274 0.006 286.033)",
+  "--color-accent-foreground": "oklch(0.985 0 0)",
+  "--color-destructive": "oklch(0.704 0.191 22.216)",
+  "--color-destructive-foreground": "oklch(0.985 0 0)",
+  "--color-border": "oklch(1 0 0 / 10%)",
+  "--color-border-subtle": "oklch(1 0 0 / 8%)",
+  "--color-input": "oklch(1 0 0 / 15%)",
+  "--color-ring": "oklch(0.769 0.188 70.08)",
+  "--color-chart-1": "oklch(0.488 0.243 264.376)",
+  "--color-chart-2": "oklch(0.696 0.17 162.48)",
+  "--color-chart-3": "oklch(0.769 0.188 70.08)",
+  "--color-chart-4": "oklch(0.627 0.265 303.9)",
+  "--color-chart-5": "oklch(0.645 0.246 16.439)",
+  "--color-status-success": "oklch(0.78 0.1 163)",
+  "--color-status-success-strong": "oklch(0.78 0.1 163)",
+  "--color-status-success-foreground": "oklch(0.21 0.006 285.885)",
+  "--color-status-active": "oklch(0.84 0.1 80)",
+  "--color-status-active-strong": "oklch(0.84 0.1 80)",
+  "--color-status-active-foreground": "oklch(0.21 0.006 285.885)",
+  "--color-status-error": "oklch(0.74 0.11 22)",
+  "--color-status-error-strong": "oklch(0.74 0.11 22)",
+  "--color-status-error-foreground": "oklch(0.21 0.006 285.885)",
+  "--color-status-info": "oklch(0.78 0.09 235)",
+  "--color-status-info-strong": "oklch(0.78 0.09 235)",
+  "--color-status-info-foreground": "oklch(0.21 0.006 285.885)",
+  "--color-status-pending": "oklch(0.86 0.09 95)",
+  "--color-status-pending-strong": "oklch(0.86 0.09 95)",
+  "--color-status-pending-foreground": "oklch(0.21 0.006 285.885)",
+  "--color-status-warning": "oklch(0.79 0.1 55)",
+  "--color-status-warning-strong": "oklch(0.79 0.1 55)",
+  "--color-status-warning-foreground": "oklch(0.21 0.006 285.885)",
+  "--color-status-paused": "oklch(0.74 0.09 260)",
+  "--color-status-paused-strong": "oklch(0.74 0.09 260)",
+  "--color-status-paused-foreground": "oklch(0.21 0.006 285.885)",
+  "--color-status-neutral": "oklch(0.72 0.012 286)",
+  "--color-status-neutral-strong": "oklch(0.72 0.012 286)",
+  "--color-status-neutral-foreground": "oklch(0.21 0.006 285.885)",
+  "--color-status-success-solid": "oklch(0.723 0.219 149.6)",
+  "--color-status-active-solid": "oklch(0.769 0.188 70.08)",
+};
+
+/**
+ * Full Hive values for every contract token, copied from the light `@theme`
+ * and `.dark` blocks of `apps/ui/src/styles/globals.css` (keep in sync;
+ * `themes-presets.test.ts` fails on drift). The shared font and radius
+ * tokens come from the light block and apply to both modes.
+ */
+export const HIVE_PAGE_TOKENS: {
+  light: Record<PageThemeToken, string>;
+  dark: Record<PageThemeToken, string>;
+} = {
+  light: { ...HIVE_LIGHT_COLORS, ...HIVE_SHARED_TOKENS },
+  dark: { ...HIVE_DARK_COLORS, ...HIVE_SHARED_TOKENS },
+};

package/src/tools/app-upsert.ts

@@ -24,7 +24,7 @@ export const registerAppUpsertTool = (server: McpServer) => {
     {
       title: "Create or update an app",
       description:
-        "Stores a schema-backed app definition with models, queries/actions, pages, reusable elements, optional userConfig fields, and an optional top-level theme (a dashboard preset slug for the app's canvas — hive (stock; omit to inherit the viewer's theme), meadow, iris, rose, cobalt, ember, carbon, plus the classic presets github, vscode, material, solarized, tokyo, monokai, gruvbox, catppuccin; viewers can override it per-user; unknown slugs degrade to the viewer's dashboard theme), then returns its dashboard URL. userConfig is versioned schema only; each user's values are stored separately, survive rollback, and schema changes are always compatible. Pages may bind a declared field read-only at exactly /user/<field>; pure and bound reusable elements must receive that value through a prop. Elements are private by default: pure elements read declared props, allow $item/$index inside repeats, may expose one leaf ElementSlot, and cannot invoke actions; bound elements may use the defining app's queries/actions, while exported bound elements cannot navigate. Prop kinds include enum with a required non-empty enum values array. Pages or elements reuse them with literal ElementRef targets, and cross-app refs require export: true. Zero-model pure-UI apps are valid. Pass appId to update; breaking a referenced export is blocked by the compatibility gate unless forceElementBreak explicitly names it.",
+        "Stores a schema-backed app definition with models, queries/actions, pages, reusable elements, optional userConfig fields, and an optional top-level theme (a dashboard preset slug for the app's canvas: hive (stock; omit to inherit the viewer's theme), meadow, iris, rose, cobalt, ember, carbon, paper (the warm editorial paper look), plus the classic presets github, vscode, material, solarized, tokyo, monokai, gruvbox, catppuccin; viewers can override it per-user; unknown slugs degrade to the viewer's dashboard theme), then returns its dashboard URL. userConfig is versioned schema only; each user's values are stored separately, survive rollback, and schema changes are always compatible. Pages may bind a declared field read-only at exactly /user/<field>; pure and bound reusable elements must receive that value through a prop. Elements are private by default: pure elements read declared props, allow $item/$index inside repeats, may expose one leaf ElementSlot, and cannot invoke actions; bound elements may use the defining app's queries/actions, while exported bound elements cannot navigate. Prop kinds include enum with a required non-empty enum values array. Pages or elements reuse them with literal ElementRef targets, and cross-app refs require export: true. Zero-model pure-UI apps are valid. Pass appId to update; breaking a referenced export is blocked by the compatibility gate unless forceElementBreak explicitly names it.",
       annotations: { destructiveHint: false },
       inputSchema: z.object({
         name: z.string().min(1).describe("Human-readable app name."),

package/src/tools/create-page.ts

@@ -12,6 +12,10 @@
  * the title slugifies to empty (e.g. all symbols), fall back to the
  * generated page id.
  *
+ * Design fields: `theme`, `themeTokens` and `designVersion` set how an HTML
+ * page is styled. A new page gets designVersion 2. On an upsert, an omitted
+ * field keeps the stored value, and `null` clears `theme` / `themeTokens`.
+ *
  * Architecture note: this tool runs on the API server (per
  * `src/server.ts:155`+ pattern) and accesses `src/be/db` directly. The
  * worker-side DB-boundary invariant doesn't apply because `src/tools/*`
@@ -23,9 +27,18 @@ import { authorizeAssetKeyWrite } from "@/be/asset-key-auth";
 import { resolveTaskAuditUserId } from "@/be/audit-user";
 import { createPage, getPage, getPageBySlug, updatePage } from "@/be/db";
 import { getPageEditCounter } from "@/be/db/page-versions";
+import { classAttributeValues, countColorLiterals } from "@/pages/color-literals";
 import { snapshotPage } from "@/pages/version";
+import { readThemeFields } from "@/themes/page-fields";
+import { PAGE_THEME_COLOR_TOKENS } from "@/themes/tokens";
 import { createToolRegistrar, swarmToolOutputSchema, toolErr, toolOk } from "@/tools/utils";
-import { AssetKeySchema, PageAuthModeSchema, PageContentTypeSchema } from "@/types";
+import {
+  AssetKeySchema,
+  type Page,
+  PageAuthModeSchema,
+  PageContentTypeSchema,
+  PageThemeTokensInputSchema,
+} from "@/types";
 import { getAppUrl, getPublicMcpBaseUrl } from "@/utils/constants";
 
 /** Same slugifier used by the HTTP createPage handler. */
@@ -46,6 +59,26 @@ function getAppBaseUrl(): string {
   return getAppUrl();
 }
 
+/** A `swarm-` primitive class inside one class attribute value. */
+const SWARM_CLASS = /(?:^|\s)swarm-/;
+const COLOR_TOKEN_REFERENCE = /var\(\s*--color-/i;
+const PAGE_COLOR_TOKENS: ReadonlySet<string> = new Set<string>(PAGE_THEME_COLOR_TOKENS);
+
+/** The body uses a `swarm-` class or a `var(--color-...)` token, which only design version 2 styles. */
+function bodyUsesDesignSystem(html: string): boolean {
+  return (
+    COLOR_TOKEN_REFERENCE.test(html) ||
+    classAttributeValues(html).some((value) => SWARM_CLASS.test(value))
+  );
+}
+
+/** The stored overrides set light colors and no dark colors, so dark mode keeps the preset's colors. */
+function hasLightOnlyColors(tokens: Page["themeTokens"]): boolean {
+  if (!tokens) return false;
+  const isColor = (name: string) => PAGE_COLOR_TOKENS.has(name);
+  return Object.keys(tokens.light).some(isColor) && !Object.keys(tokens.dark).some(isColor);
+}
+
 export const registerCreatePageTool = (server: McpServer) => {
   createToolRegistrar(server)(
     "create_page",
@@ -56,7 +89,15 @@ export const registerCreatePageTool = (server: McpServer) => {
         "Calls are upsert-by-(agent, slug): if you previously created a page " +
         "with the same slug, its prior state is snapshotted and the row is " +
         "updated. Use this for static reports, dashboards, or JSON action " +
-        "specs that don't need a long-lived process.",
+        "specs that don't need a long-lived process. " +
+        "HTML pages use the swarm design system (designVersion 2): theme " +
+        "tokens such as var(--color-primary), the swarm-* primitives, and " +
+        "Tailwind v4 utilities such as bg-card and text-muted-foreground. " +
+        "Set `theme` to a preset id or pass `themeTokens` (a token map, or a " +
+        'CSS variable block with format "css") to restyle the whole page. ' +
+        "Do not hardcode colors: inside the dashboard the page follows the " +
+        "viewer's theme and dark mode. Pages created before designVersion 2 " +
+        "keep the old look; pass designVersion: 2 when you rewrite one.",
       annotations: { destructiveHint: false },
       inputSchema: z.object({
         key: AssetKeySchema.optional().describe(
@@ -99,6 +140,27 @@ export const registerCreatePageTool = (server: McpServer) => {
           .describe(
             "Declared credential needs for JSON pages (renderer ignores for v1 — reserved for follow-up).",
           ),
+        theme: z
+          .string()
+          .nullable()
+          .optional()
+          .describe(
+            "Theme preset id that restyles the whole page, for example paper, github or hive. An unknown id returns an error that lists every preset. Omit to follow the viewer's theme (on update, to keep the stored one). Pass null to clear it.",
+          ),
+        themeTokens: PageThemeTokensInputSchema.nullable()
+          .optional()
+          .describe(
+            'Per-page token overrides, applied on top of the preset. Send { light, dark } maps of token name to CSS value (for example { light: { "--color-primary": "oklch(0.55 0.2 260)" } }), or { format: "css", css } with a CSS variable block (:root, .dark, @theme) as shadcn, tweakcn and Tailwind v4 export it. Stored normalized. Names outside the token contract, and values that reference a variable outside it, are ignored and reported in the result. Replaces the stored overrides. Omit to keep them on update. Pass null to clear them.',
+          ),
+        designVersion: z
+          .number()
+          .int()
+          .min(1)
+          .max(2)
+          .optional()
+          .describe(
+            "Design system version. 2 is the swarm design system and the default for new pages. 1 is the original look that older pages keep. Omit on update to keep the stored value.",
+          ),
       }),
       outputSchema: swarmToolOutputSchema({
         yourAgentId: z.string().optional(),
@@ -107,6 +169,11 @@ export const registerCreatePageTool = (server: McpServer) => {
         version: z.number().optional(),
         app_url: z.string().optional(),
         api_url: z.string().optional(),
+        designVersion: z.number().optional(),
+        ignoredTokens: z.array(z.string()).optional(),
+        colorLiteralCount: z.number().optional(),
+        usesDesignSystem: z.boolean().optional(),
+        lightOnlyColors: z.boolean().optional(),
       }),
     },
     async (input, requestInfo, _meta) => {
@@ -115,6 +182,9 @@ export const registerCreatePageTool = (server: McpServer) => {
         return toolErr(msg);
       }
 
+      const themeFields = readThemeFields(input);
+      if ("error" in themeFields) return toolErr(themeFields.error);
+
       const slug = input.slug ?? slugify(input.title);
       const finalSlug = slug || "page"; // Fallback if title slugifies to empty.
 
@@ -167,6 +237,10 @@ export const registerCreatePageTool = (server: McpServer) => {
           passwordHash: passwordHash ?? null,
           body: input.body,
           needsCredentials: needsCredentialsNames ?? null,
+          // Omitted design fields keep the stored values.
+          theme: themeFields.theme,
+          themeTokens: themeFields.themeTokens,
+          designVersion: input.designVersion,
         });
         if (!updated) {
           const msg = `Failed to update existing page ${existing.id}.`;
@@ -188,6 +262,9 @@ export const registerCreatePageTool = (server: McpServer) => {
             passwordHash,
             body: input.body,
             needsCredentials: needsCredentialsNames,
+            theme: themeFields.theme,
+            themeTokens: themeFields.themeTokens,
+            designVersion: input.designVersion,
           });
           id = created.id;
         } catch (err) {
@@ -209,17 +286,46 @@ export const registerCreatePageTool = (server: McpServer) => {
       const appUrl = `${getAppBaseUrl()}/pages/${id}`;
       const version = await getPageEditCounter(id);
 
-      return toolOk(`Page "${input.title}" saved (slug=${finalSlug}, version=${version}).`, {
-        details: `API: ${apiUrl}\n  App: ${appUrl}`,
-        data: {
-          yourAgentId: requestInfo.agentId,
-          id,
-          key: fresh.key,
-          version,
-          app_url: appUrl,
-          api_url: apiUrl,
+      // Judged on the saved page, so an upsert that keeps an older design
+      // version is judged by the version it keeps. The NUDGES entry for this
+      // tool reads these flags. Only HTML pages get the design system head.
+      const designFlags =
+        fresh.contentType === "text/html"
+          ? {
+              usesDesignSystem:
+                typeof input.theme === "string" ||
+                Boolean(input.themeTokens) ||
+                bodyUsesDesignSystem(fresh.body),
+              lightOnlyColors: hasLightOnlyColors(fresh.themeTokens),
+              ...(fresh.designVersion >= 2
+                ? { colorLiteralCount: countColorLiterals(fresh.body) }
+                : {}),
+            }
+          : {};
+      const { ignored } = themeFields;
+
+      return toolOk(
+        `Page "${input.title}" saved (slug=${finalSlug}, version=${version}, designVersion=${fresh.designVersion}).` +
+          (ignored.length > 0
+            ? " Some theme tokens were ignored (outside the page token contract or referencing a variable outside it)."
+            : ""),
+        {
+          details:
+            `API: ${apiUrl}\n  App: ${appUrl}` +
+            (ignored.length > 0 ? `\n  Ignored theme tokens: ${ignored.join(", ")}` : ""),
+          data: {
+            yourAgentId: requestInfo.agentId,
+            id,
+            key: fresh.key,
+            version,
+            app_url: appUrl,
+            api_url: apiUrl,
+            designVersion: fresh.designVersion,
+            ...(ignored.length > 0 ? { ignoredTokens: ignored } : {}),
+            ...designFlags,
+          },
         },
-      });
+      );
     },
   );
 };

package/src/tools/utils.ts

@@ -22,6 +22,7 @@ import { upsertKv } from "../be/db";
 import { MCP_OVERFLOW_NAMESPACE, mcpOverflowNamespace } from "../kv-overflow";
 import { joinKvPath, type KvShapeEntry, splitKvPath, summarizeKvShape } from "../kv-view";
 import { withSpan } from "../otel";
+import { COLOR_LITERAL_THRESHOLD } from "../pages/color-literals";
 import type { PermissionVerb } from "../rbac/permissions";
 import { SCRIPT_LONG_TIMEOUT_HINT_MS } from "../scripts-runtime/executors/types";
 import { scrubObject, scrubSecrets } from "../utils/secret-scrubber";
@@ -314,6 +315,37 @@ const workflowLongScriptTimeoutNudge = (r: SwarmToolResult): string | undefined
   return hint ? WORKFLOW_LONG_SCRIPT_TIMEOUT_NUDGE : undefined;
 };
 
+/**
+ * One call can fall into more than one create_page trap, and a result carries
+ * one nudge, so this entry joins one sentence per trap that applies: a
+ * design version 1 page that uses the design system, theme tokens that set
+ * light colors only, and hardcoded colors. The tool computes the flags.
+ */
+const createPageNudge = (r: SwarmToolResult): string | undefined => {
+  if (!r.ok) return undefined;
+  const data = r.data as
+    | {
+        designVersion?: unknown;
+        usesDesignSystem?: unknown;
+        lightOnlyColors?: unknown;
+        colorLiteralCount?: unknown;
+      }
+    | undefined;
+  const count = data?.colorLiteralCount;
+  const sentences = [
+    data?.designVersion === 1 && data.usesDesignSystem === true
+      ? "This page is on designVersion 1 (the original look), so design system classes, tokens and themes have no effect. Pass designVersion: 2."
+      : undefined,
+    data?.lightOnlyColors === true
+      ? "Your themeTokens set colors for light mode only. Dark mode keeps the preset's dark colors; add a dark map (or a .dark block) to restyle it too."
+      : undefined,
+    typeof count === "number" && count >= COLOR_LITERAL_THRESHOLD
+      ? `This page hardcodes ${count} color values. Use theme tokens (var(--color-primary), bg-primary, text-muted-foreground) so theme and dark-mode switches restyle it. Until then the page stays light in a dark dashboard.`
+      : undefined,
+  ].filter((sentence) => sentence !== undefined);
+  return sentences.length > 0 ? sentences.join(" ") : undefined;
+};
+
 /**
  * Central conditional nudges, keyed by tool name. Applied by the finalize
  * pipeline when the tool did not set an explicit nudge. Keep entries to a
@@ -333,6 +365,7 @@ export const NUDGES: Record<string, (result: SwarmToolResult) => string | undefi
   "patch-workflow-node": workflowLongScriptTimeoutNudge,
   "slack-download-file": slackDownloadFileNudge,
   "slack-read": slackReadNudge,
+  create_page: createPageNudge,
   "script-search": (r) => {
     if (!r.ok) return undefined;
     // proxyScriptsApi wraps the parsed HTTP body as data = { status, data },

package/src/types.ts

@@ -4,6 +4,7 @@
 
 import { normalizeAssetKey } from "./assets/key";
 import { isSafeBundlePath } from "./extensions/bundle-path";
+import { THEME_IMPORT_FORMATS } from "./themes/import";
 import { MAX_PROFILE_FILE_LENGTH } from "./utils/constants";
 import { z } from "./utils/zod-openapi";
 
@@ -1695,6 +1696,8 @@ export const AgentLogEventTypeSchema = z.enum([
   "task_deferred_wait_woke",
   // The lead follow-up was skipped because the woken waiter already carries the result
   "task_follow_up_suppressed",
+  // Shadow follow-up gate: what a verifier said about a gated run (never skips the follow-up)
+  "task_follow_up_gate_shadow",
   // store-progress refused a completion once because its citations were inaccurate
   "task_citation_check_refused",
   "channel_message",
@@ -2773,10 +2776,36 @@ export type PageContentType = z.infer<typeof PageContentTypeSchema>;
 export const PageAuthModeSchema = z.enum(["public", "authed", "password"]);
 export type PageAuthMode = z.infer<typeof PageAuthModeSchema>;
 
+// Per-page theme overrides as stored: page token names (`--color-primary`,
+// `--radius-lg`) mapped to CSS values, per mode. Writes go through
+// `importThemeTokens` (src/themes/import.ts), which maps outside names onto the
+// token contract and checks every value, so the stored form is always normalized.
+export const PageThemeTokensSchema = z
+  .object({
+    light: z.record(z.string(), z.string()),
+    dark: z.record(z.string(), z.string()),
+  })
+  .openapi("PageThemeTokens");
+
+// Write-side `themeTokens` input, mirroring `ThemeImportInput` (src/themes/import.ts)
+// as one flat object: the default `tokens` format sends `light` / `dark` maps,
+// the `css` format sends a CSS variable block. `importThemeTokens` checks which
+// fields go with which format, so a mismatch gets a precise error message. The
+// `format` enum is the importer's own list, so a new importer needs no change
+// here unless it takes a new payload field.
+export const PageThemeTokensInputSchema = z.strictObject({
+  format: z.enum(THEME_IMPORT_FORMATS).optional(),
+  light: z.record(z.string(), z.string()).optional(),
+  dark: z.record(z.string(), z.string()).optional(),
+  css: z.string().optional(),
+});
+export type PageThemeTokensInput = z.infer<typeof PageThemeTokensInputSchema>;
+
 // PageSnapshot captures the mutable content fields frozen per-version in
 // page_versions.snapshot. Omits id / agentId / slug / timestamps (these are
 // invariant across versions for a given page id; the slug is a parent-only
-// identifier).
+// identifier). The design fields are optional because snapshots taken before
+// design version 2 do not carry them (they read as design version 1).
 export const PageSnapshotSchema = z
   .object({
     title: z.string(),
@@ -2786,6 +2815,9 @@ export const PageSnapshotSchema = z
     passwordHash: z.string().optional(),
     body: z.string(),
     needsCredentials: z.array(z.string()).optional(),
+    theme: z.string().nullable().optional(),
+    themeTokens: PageThemeTokensSchema.nullable().optional(),
+    designVersion: z.number().int().min(1).optional(),
   })
   .openapi("PageSnapshot");
 export type PageSnapshot = z.infer<typeof PageSnapshotSchema>;
@@ -2803,6 +2835,9 @@ export const PageSchema = z
     passwordHash: z.string().optional(),
     body: z.string(),
     needsCredentials: z.array(z.string()).optional(),
+    theme: z.string().nullable(),
+    themeTokens: PageThemeTokensSchema.nullable(),
+    designVersion: z.number().int().min(1),
     viewCount: z.number().int().min(0).default(0),
     createdAt: z.string(),
     updatedAt: z.string(),
@@ -2826,8 +2861,15 @@ export type WorkflowSummary = Omit<
   "definition" | "triggers" | "cooldown" | "input" | "triggerSchema"
 > & { nodeCount: number };
 
-/** `/api/pages` list item — drops the (potentially huge) `body` and `passwordHash`. */
-export type PageSummary = Omit<Page, "body" | "passwordHash">;
+/**
+ * `/api/pages` list item: drops the (potentially huge) `body` and `passwordHash`,
+ * plus the design fields (`theme`, `themeTokens`, `designVersion`). List views do
+ * not render a page, so those only come with `?fields=full` or the get-by-id route.
+ */
+export type PageSummary = Omit<
+  Page,
+  "body" | "passwordHash" | "theme" | "themeTokens" | "designVersion"
+>;
 
 /** `/api/schedules` list item — swaps the full `taskTemplate` for a short preview. */
 export type ScheduledTaskSummary = Omit<ScheduledTask, "taskTemplate"> & {

package/src/utils/constants.ts

@@ -3,6 +3,7 @@
  */
 
 import { isEnvFlagEnabled, parseEnvFlag } from "./env-flag";
+import { isDevOrTestNodeEnv } from "./node-env";
 
 /** Maximum profile-file length in JavaScript characters (not UTF-8 bytes). */
 export const MAX_PROFILE_FILE_LENGTH = 256 * 1024;
@@ -45,6 +46,24 @@ export function getAppUrl(fallback = DEFAULT_APP_URL): string {
   return (getConfiguredAppUrls()[0] || fallback).replace(/\/+$/, "");
 }
 
+/**
+ * Local dashboard origins (Vite ports and portless `*.localhost`) that may
+ * iframe pages without being listed in `APP_URL`. Returned only when NODE_ENV
+ * is explicitly development or test: deployed images leave NODE_ENV unset, and
+ * an unset value must not let a localhost origin frame production pages.
+ */
+export function getLocalDevAppOrigins(): string[] {
+  if (!isDevOrTestNodeEnv()) return [];
+  return [
+    "http://localhost:5274",
+    "http://localhost:5175",
+    "http://127.0.0.1:5274",
+    "http://127.0.0.1:5175",
+    "https://*.localhost",
+    "http://*.localhost",
+  ];
+}
+
 /**
  * Internal API/MCP base URL — how workers/agents and in-process callers reach
  * the API server. May be a private/cluster address (e.g. the Helm ClusterIP

package/src/utils/follow-up-gate-schedule-ids.ts

@@ -0,0 +1,13 @@
+const UUID_RE = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
+
+/** Split `FOLLOW_UP_GATE_SCHEDULE_IDS`, a comma-separated id list. Blank entries are dropped. */
+export function parseFollowUpGateScheduleIds(raw: string | undefined): string[] {
+  return (raw ?? "")
+    .split(",")
+    .map((id) => id.trim())
+    .filter(Boolean);
+}
+
+export function isFollowUpGateScheduleId(id: string): boolean {
+  return UUID_RE.test(id);
+}