@agent-native/core 0.84.9 → 0.84.12

package/corpus/README.md

@@ -28,4 +28,4 @@ rg -n "defineAction|useActionQuery" node_modules/@agent-native/core/corpus
 ## Generated Counts
 
 - core files: 2043
-- template files: 4908
+- template files: 4912

package/corpus/core/CHANGELOG.md

@@ -1,5 +1,48 @@
 # @agent-native/core
 
+## 0.84.12
+
+### Patch Changes
+
+- 9032acb: Don't reap a run that is actively making progress. The stale reapers
+  (`reapIfStale`, `reapAllStaleRuns`, and the heartbeat-stale path of
+  `cleanupOldRuns`) keyed liveness solely on `heartbeat_at` (the 1.5s
+  process-liveness timer) and ignored `last_progress_at` (bumped whenever the
+  agent emits an event, including a long-running tool's periodic activity
+  heartbeats — e.g. image generation streaming activity every 8s). When the
+  heartbeat write lagged while a multi-minute tool was in flight, the run was
+  flipped to `errored`, and the producing isolate's SQL-abort check then
+  self-aborted the in-flight tool with "Run aborted" — looping on the
+  durable-background self-chaining path and interrupting once inline. The reapers
+  now use the most recent of `heartbeat_at` and `last_progress_at` (falling back to
+  `started_at`) as their liveness basis, so a demonstrably-progressing run is never
+  reaped mid-tool. Portable across SQLite and Postgres; can only make reaping more
+  conservative (a dead producer emits neither signal).
+- 9032acb: Add a `trigger="label-icon"` option to `ShareButton` that renders a leading
+  share glyph alongside the "Share" label, so the trigger matches adjacent
+  icon+label buttons (e.g. an Upload button). The default `"label"` trigger stays
+  text-only and `"icon"` stays icon-only.
+- 351ee93: Fix an infinite sign-in redirect loop under base-path deploys. When the
+  authenticated app shell (wrapped in `RequireSession`) was served at the sign-in
+  path — e.g. `/<app>/_agent-native/sign-in` on a path-prefixed deploy — the gate
+  redirected to the sign-in page from the sign-in page, nesting and re-encoding the
+  current URL as a fresh `?return=` on every hop (`…sign-in?return=%252F…sign-in%253Freturn…`).
+  `RequireSession` now refuses to redirect when already on the sign-in entry point
+  (new exported `isOnSignInPage` helper), and `safeReturnPath` collapses any
+  `return` that resolves back to `…/_agent-native/sign-in` to `/`.
+
+## 0.84.11
+
+### Patch Changes
+
+- a2ce30e: Improve local SQLite collab write robustness for Design editor workflows.
+
+## 0.84.10
+
+### Patch Changes
+
+- 720b8b0: Make agent chat recovery surface completed-tool timeouts more reliably and keep Design variant follow-ups bounded to the selected screen.
+
 ## 0.84.9
 
 ### Patch Changes

package/corpus/core/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@agent-native/core",
-  "version": "0.84.9",
+  "version": "0.84.12",
   "description": "Framework for agent-native application development — where AI agents and UI share SQL state, actions, and context",
   "homepage": "https://github.com/BuilderIO/agent-native#readme",
   "bugs": {

package/corpus/core/src/agent/run-store.ts

@@ -428,6 +428,29 @@ function backgroundAwareStaleCutoffSql(): string {
   return `(CAST(? AS BIGINT) - CASE WHEN dispatch_mode LIKE 'background%' THEN ${BACKGROUND_RUN_STALE_MS} ELSE ${RUN_STALE_MS} END)`;
 }
 
+/**
+ * Liveness basis for the stale reapers: the MOST RECENT of `heartbeat_at`
+ * ("process is up", bumped on a 1.5s timer) and `last_progress_at` ("real work
+ * is happening", bumped whenever the agent emits an event — including a
+ * long-running tool's periodic activity heartbeats, e.g. image generation every
+ * 8s), falling back to `started_at`.
+ *
+ * The reapers previously keyed liveness on `heartbeat_at` alone, so a run that
+ * was demonstrably progressing got reaped ('running' → 'errored') the moment the
+ * process-liveness write lagged (DB latency, a brief event-loop stall). The
+ * producing isolate's SQL-abort check then self-aborted the in-flight action
+ * with "Run aborted"; on the durable-background self-chaining path this re-drove
+ * the turn in a loop. Honoring progress means a run doing real work is never
+ * reaped mid-tool. It can only make reaping MORE conservative — a genuinely dead
+ * producer emits neither signal — so a truly-dead run is still reaped.
+ *
+ * Portable across SQLite and Postgres (CASE + COALESCE only; no GREATEST or
+ * scalar MAX, which differ between engines).
+ */
+function livenessBasisSql(): string {
+  return `(CASE WHEN COALESCE(last_progress_at, started_at) > COALESCE(heartbeat_at, started_at) THEN COALESCE(last_progress_at, started_at) ELSE COALESCE(heartbeat_at, started_at) END)`;
+}
+
 /**
  * Atomically claim a background-dispatched run for processing. The foreground
  * POST inserts the run row with `dispatch_mode = 'background'`; the FIRST
@@ -733,8 +756,8 @@ export async function reapIfStale(
   // override forces a flat window for callers that want one.
   const staleClause =
     typeof maxStaleMs === "number"
-      ? `COALESCE(heartbeat_at, started_at) < ?`
-      : `COALESCE(heartbeat_at, started_at) < ${backgroundAwareStaleCutoffSql()}`;
+      ? `${livenessBasisSql()} < ?`
+      : `${livenessBasisSql()} < ${backgroundAwareStaleCutoffSql()}`;
   const staleArgs =
     typeof maxStaleMs === "number" ? [completedAt - maxStaleMs] : [completedAt];
   const { rowsAffected } = await client.execute({
@@ -1151,7 +1174,7 @@ export async function reapAllStaleRuns(): Promise<number> {
   const stale = await client.execute({
     sql: `SELECT id FROM agent_runs
           WHERE status = 'running'
-            AND COALESCE(heartbeat_at, started_at) < ${backgroundAwareStaleCutoffSql()}`,
+            AND ${livenessBasisSql()} < ${backgroundAwareStaleCutoffSql()}`,
     args: [now],
   });
   const completedAt = Date.now();
@@ -1162,7 +1185,7 @@ export async function reapAllStaleRuns(): Promise<number> {
               error_code = ?,
               error_detail = ?
           WHERE status = 'running'
-            AND COALESCE(heartbeat_at, started_at) < ${backgroundAwareStaleCutoffSql()}`,
+            AND ${livenessBasisSql()} < ${backgroundAwareStaleCutoffSql()}`,
     args: [
       completedAt,
       STALE_RUN_ERROR_EVENT.errorCode,
@@ -1207,7 +1230,7 @@ export async function cleanupOldRuns(
     sql: `SELECT id FROM agent_runs
           WHERE status = 'running'
             AND (
-              COALESCE(heartbeat_at, started_at) < ${backgroundAwareStaleCutoffSql()}
+              ${livenessBasisSql()} < ${backgroundAwareStaleCutoffSql()}
               OR started_at < ?
     )`,
     args: [now, cutoff],
@@ -1236,7 +1259,7 @@ export async function cleanupOldRuns(
               error_code = ?,
               error_detail = ?
           WHERE status = 'running'
-            AND COALESCE(heartbeat_at, started_at) < ${backgroundAwareStaleCutoffSql()}`,
+            AND ${livenessBasisSql()} < ${backgroundAwareStaleCutoffSql()}`,
     args: [
       completedAt,
       STALE_RUN_ERROR_EVENT.errorCode,

package/corpus/core/src/cli/skills.ts

@@ -328,7 +328,8 @@ iteration, or a human-in-the-loop choice among design directions.
   full app per variant. Design saves every option as a normal screen on the
   overview board and renders an inline chat choice with one button per screen
   name. After the user picks, delete the unchosen variant screens and continue
-  from the kept screen.
+  from the kept screen by first calling \`get-design-snapshot\` with that
+  screen's \`fileId\`, then making a bounded single-file pass.
 - If the chat choice buttons are not available in the host, ask the user to
   tell you the screen name they prefer. The variants are already real screens
   on the board, so do not ask them to paste HTML or copy a generated handoff
@@ -351,8 +352,10 @@ iteration, or a human-in-the-loop choice among design directions.
    and realistic controls over decorative mockups.
 5. After \`present-design-variants\`, wait for the user's pick before
    generating the next version. Keep the chosen screen, delete the other
-   variant screens, then refine that direction with \`generate-design\` or
-   \`edit-design\`.
+   variant screens, call \`get-design-snapshot\` with \`fileId\` for the kept
+   screen, then continue from that single file in a bounded pass. Prefer
+   \`edit-design\`; if \`generate-design\` is needed, update only the kept file
+   compactly and stop after the first successful save.
 
 ## Design Quality Bar
 

package/corpus/core/src/client/agent-chat-adapter.ts

@@ -703,7 +703,26 @@ function hasContinuationProgress(content: ContentPart[]): boolean {
   );
 }
 
-function lastCompletedSideEffectTool(
+const COMPLETED_TOOL_TIMEOUT_NAME_RE =
+  /^(add|apply|archive|capture|create|delete|deploy|duplicate|edit|generate|grant|insert|migrate|move|present|publish|remove|rename|reorder|revoke|save|send|set|sync|trash|update|write)(-|$)/;
+const COMPLETED_TOOL_TIMEOUT_NAME_ALLOWLIST = new Set([
+  "connect-assets-mcp",
+  "import-design-tokens",
+]);
+
+function isCompletedToolTimeoutCandidate(
+  part: Extract<ContentPart, { type: "tool-call" }>,
+): boolean {
+  if (part.completedSideEffect === false) return false;
+  if (part.completedSideEffect === true) return true;
+  const toolName = part.toolName.toLowerCase();
+  return (
+    COMPLETED_TOOL_TIMEOUT_NAME_ALLOWLIST.has(toolName) ||
+    COMPLETED_TOOL_TIMEOUT_NAME_RE.test(toolName)
+  );
+}
+
+function lastCompletedTimeoutCandidateTool(
   content: ContentPart[],
 ): Extract<ContentPart, { type: "tool-call" }> | undefined {
   for (let i = content.length - 1; i >= 0; i--) {
@@ -713,7 +732,7 @@ function lastCompletedSideEffectTool(
       part.activity !== true &&
       part.result !== undefined &&
       part.isError !== true &&
-      part.completedSideEffect === true
+      isCompletedToolTimeoutCandidate(part)
     ) {
       return part;
     }
@@ -1866,7 +1885,7 @@ export function createAgentChatAdapter(
           // before tool_start; treating it as progress caused silent retry
           // loops when the LLM timed out while assembling a large tool input.
           const hasInFlightTool = hasInFlightToolCall(visibleContent);
-          const completedSideEffectTool = lastCompletedSideEffectTool(content);
+          const completedTool = lastCompletedTimeoutCandidateTool(content);
           // Either real output or an actively-running tool counts as progress
           // for the stalled/empty caps.
           const madeProgress = madeContentProgress || hasInFlightTool;
@@ -1963,22 +1982,23 @@ export function createAgentChatAdapter(
             emptyTransientContinuationAttempts = 0;
           } else {
             totalTransientContinuationAttempts += 1;
-            // If a mutating action already completed, do not turn a missing
-            // closing sentence into a scary connection failure. Give the model
-            // one continuation opportunity (the completed tool itself counts
-            // as progress on the first timeout); if the follow-up produces no
-            // new content, stop locally with a clear "saved, final note timed
-            // out" message.
+            // If a tool already completed, do not turn a missing closing
+            // sentence into a scary connection failure. Give the model one
+            // continuation opportunity (the completed tool itself counts as
+            // progress on the first timeout); if the follow-up produces no new
+            // content, stop locally with a clear completed-tool warning.
             if (
-              completedSideEffectTool &&
+              signal.reason === "run_timeout" &&
+              completedTool &&
               !hasInFlightToolCall(content) &&
+              !currentPreparingToolName &&
               !madeContentProgress &&
               !hasInFlightTool
             ) {
               return {
                 ok: false,
                 resetVisibleContent: false,
-                completedToolName: completedSideEffectTool.toolName,
+                completedToolName: completedTool.toolName,
               };
             }
             // Bail when the same write tool is stuck in-flight across too many

package/corpus/core/src/client/require-session.tsx

@@ -70,6 +70,24 @@ export function buildSignInReturnHref(): string {
   return `${base}?return=${encodeURIComponent(ret)}`;
 }
 
+/**
+ * True when the browser is already sitting on the framework sign-in entry
+ * point. Redirecting to sign-in from here would append the current sign-in
+ * URL as a fresh `?return=`, re-encode it, and navigate again — an infinite
+ * loop of ever-growing `…sign-in?return=%252F…sign-in%253Freturn%253D…` URLs.
+ *
+ * This happens when the authenticated app shell (wrapped in `RequireSession`)
+ * is served at the sign-in path instead of the framework login HTML — e.g.
+ * under a base-path deploy where the SPA shell answers `/<app>/_agent-native/
+ * sign-in`. The sign-in page is the framework's job, not the gate's: never
+ * redirect to ourselves. Compared against `agentNativePath(...)` so it matches
+ * whether or not the app is mounted under a base path.
+ */
+export function isOnSignInPage(): boolean {
+  if (typeof window === "undefined") return false;
+  return window.location.pathname === agentNativePath("/_agent-native/sign-in");
+}
+
 export function RequireSession({
   children,
   fallback,
@@ -83,7 +101,8 @@ export function RequireSession({
   // flight is harmless but noisy.
   const redirectedRef = useRef(false);
 
-  const mustRedirect = !bypass && !isLoading && !session && redirect;
+  const mustRedirect =
+    !bypass && !isLoading && !session && redirect && !isOnSignInPage();
 
   useEffect(() => {
     if (!mustRedirect) return;

package/corpus/core/src/client/sharing/ShareButton.tsx

@@ -46,8 +46,10 @@ export interface ShareButtonProps {
   /** @deprecated No longer affects rendering — trigger always says
    *  "Share". Kept for callsite compatibility. */
   variant?: "compact" | "label";
-  /** Optional trigger style. Defaults to the Google-Docs-style "Share" label. */
-  trigger?: "label" | "icon";
+  /** Optional trigger style. Defaults to the Google-Docs-style "Share" label.
+   *  Use "label-icon" to render a leading share glyph alongside the label so
+   *  the trigger matches adjacent icon+label buttons; "icon" is icon-only. */
+  trigger?: "label" | "icon" | "label-icon";
   /** @deprecated Label triggers no longer render a visibility/share glyph. */
   hideTriggerIcon?: boolean;
   /** Optional className applied to the trigger button. */
@@ -355,7 +357,9 @@ export function ShareButton(props: ShareButtonProps) {
   };
 
   // The default trigger stays text-only; the icon trigger keeps the share glyph.
+  // "label-icon" renders the glyph alongside the label for icon+label parity.
   const iconOnly = props.trigger === "icon";
+  const showLabelIcon = props.trigger === "label-icon";
 
   return (
     <Popover open={open} onOpenChange={handleOpenChange}>
@@ -368,7 +372,9 @@ export function ShareButton(props: ShareButtonProps) {
           )}
           aria-label={iconOnly ? "Share" : undefined}
         >
-          {iconOnly ? <IconShare3 size={16} strokeWidth={1.75} /> : null}
+          {iconOnly || showLabelIcon ? (
+            <IconShare3 size={16} strokeWidth={1.75} />
+          ) : null}
           {!iconOnly && <span>Share</span>}
         </button>
       </PopoverTrigger>

package/corpus/core/src/collab/storage.ts

@@ -10,6 +10,41 @@ import { ensureTableExists, ensureColumnExists } from "../db/ddl-guard.js";
 
 let _initPromise: Promise<void> | undefined;
 
+type DbExecClient = ReturnType<typeof getDbExec>;
+type DbExecuteArg = Parameters<DbExecClient["execute"]>[0];
+type DbExecuteResult = Awaited<ReturnType<DbExecClient["execute"]>>;
+
+function isSqliteBusyError(error: unknown): boolean {
+  if (isPostgres()) return false;
+  const candidate = error as { code?: unknown; message?: unknown } | null;
+  return (
+    candidate?.code === "SQLITE_BUSY" ||
+    candidate?.code === "SQLITE_BUSY_RECOVERY" ||
+    (typeof candidate?.message === "string" &&
+      /database is locked|SQLITE_BUSY/i.test(candidate.message))
+  );
+}
+
+function sleep(ms: number): Promise<void> {
+  return new Promise((resolve) => setTimeout(resolve, ms));
+}
+
+async function executeWithSqliteRetry(
+  client: DbExecClient,
+  statement: DbExecuteArg,
+): Promise<DbExecuteResult> {
+  const delays = [25, 75, 150, 300, 600];
+  for (let attempt = 0; ; attempt += 1) {
+    try {
+      return await client.execute(statement);
+    } catch (error) {
+      const delay = delays[attempt];
+      if (delay === undefined || !isSqliteBusyError(error)) throw error;
+      await sleep(delay);
+    }
+  }
+}
+
 async function ensureTable(): Promise<void> {
   if (!_initPromise) {
     _initPromise = (async () => {
@@ -97,7 +132,7 @@ export async function trySaveYDocState(
   const b64 = uint8ArrayToBase64(state);
   const nowExpr = isPostgres() ? "NOW()::text" : "datetime('now')";
   if (expectedVersion === null) {
-    const result = await client.execute({
+    const result = await executeWithSqliteRetry(client, {
       sql: isPostgres()
         ? `INSERT INTO _collab_docs (doc_id, yjs_state, text_snapshot, version, updated_at) VALUES (?, ?, ?, 0, ${nowExpr}) ON CONFLICT (doc_id) DO NOTHING`
         : `INSERT OR IGNORE INTO _collab_docs (doc_id, yjs_state, text_snapshot, version, updated_at) VALUES (?, ?, ?, 0, ${nowExpr})`,
@@ -106,7 +141,7 @@ export async function trySaveYDocState(
     return result.rowsAffected > 0;
   }
 
-  const result = await client.execute({
+  const result = await executeWithSqliteRetry(client, {
     sql: `UPDATE _collab_docs SET yjs_state = ?, text_snapshot = ?, version = version + 1, updated_at = ${nowExpr} WHERE doc_id = ? AND version = ?`,
     args: [b64, textSnapshot, docId, expectedVersion],
   });
@@ -123,13 +158,13 @@ export async function saveYDocState(
   const client = getDbExec();
   const b64 = uint8ArrayToBase64(state);
   const nowExpr = isPostgres() ? "NOW()::text" : "datetime('now')";
-  const updated = await client.execute({
+  const updated = await executeWithSqliteRetry(client, {
     sql: `UPDATE _collab_docs SET yjs_state = ?, text_snapshot = ?, version = version + 1, updated_at = ${nowExpr} WHERE doc_id = ?`,
     args: [b64, textSnapshot, docId],
   });
   if (updated.rowsAffected > 0) return;
 
-  const inserted = await client.execute({
+  const inserted = await executeWithSqliteRetry(client, {
     sql: isPostgres()
       ? `INSERT INTO _collab_docs (doc_id, yjs_state, text_snapshot, version, updated_at) VALUES (?, ?, ?, 0, ${nowExpr}) ON CONFLICT (doc_id) DO NOTHING`
       : `INSERT OR IGNORE INTO _collab_docs (doc_id, yjs_state, text_snapshot, version, updated_at) VALUES (?, ?, ?, 0, ${nowExpr})`,
@@ -137,7 +172,7 @@ export async function saveYDocState(
   });
   if (inserted.rowsAffected > 0) return;
 
-  await client.execute({
+  await executeWithSqliteRetry(client, {
     sql: `UPDATE _collab_docs SET yjs_state = ?, text_snapshot = ?, version = version + 1, updated_at = ${nowExpr} WHERE doc_id = ?`,
     args: [b64, textSnapshot, docId],
   });

package/corpus/core/src/server/auth.ts

@@ -542,6 +542,12 @@ export function safeReturnPath(raw: string | null | undefined): string {
   try {
     const parsed = new URL(raw, "http://safe-base.invalid");
     if (parsed.origin !== "http://safe-base.invalid") return "/";
+    // Never return to the sign-in entry point itself. A `return` that resolves
+    // back to `…/_agent-native/sign-in` re-enters the redirect loop — each hop
+    // nests the prior sign-in URL as a fresh `?return=`. Collapse it to "/" so
+    // the post-sign-in 302 lands on the app, not another sign-in page. Matches
+    // with or without an app base-path prefix (`/<app>/_agent-native/sign-in`).
+    if (parsed.pathname.endsWith("/_agent-native/sign-in")) return "/";
     return parsed.pathname + parsed.search + parsed.hash;
   } catch {
     return "/";

package/corpus/templates/assets/.agents/skills/logo-composite/SKILL.md

@@ -10,16 +10,17 @@ LLMs — including Gemini Pro — degrade complex logos. They smear gradients, d
 ## How it works
 
 1. The library has a `canonicalLogoUrl` (set via `set-canonical-logo --libraryId --assetId`). The asset's role is `logo_reference`.
-2. When `generate-image --includeLogo=true` runs, the prompt envelope adds:
+2. **Logo compositing is a preset option.** A generation preset carries `includeLogo` (stored in the preset `settings` and surfaced as a first-class field). When a generation resolves to a preset with `includeLogo: true`, `generate-image` composites the logo. A generate call's own `includeLogo` arg, when passed, overrides the preset for that run; when omitted, the preset's value wins.
+3. When logo compositing is on, the prompt envelope adds:
    > Leave a clean uncluttered area in the upper-right for the real brand logo; do not draw or approximate the logo yourself.
-3. Gemini returns an image with empty space in that corner.
-4. `compositeLogo()` from `server/lib/image-processing.ts` (Sharp) loads the canonical logo PNG / SVG, resizes it to ~16% of the image width with reasonable inset, and composites it onto the generated image.
-5. Output: the image with the actual logo, pixel-perfect, vector-quality if the source is SVG.
+4. Gemini returns an image with empty space in that corner.
+5. `compositeLogo()` from `server/lib/image-processing.ts` (Sharp) loads the canonical logo PNG / SVG, resizes it to ~16% of the image width with reasonable inset, and composites it onto the generated image.
+6. Output: the image with the actual logo, pixel-perfect, vector-quality if the source is SVG.
 
 ## When to use it
 
-- The user explicitly toggled "Use logo" in the Generate popover.
-- The agent infers the user wants the logo (e.g. "make a hero with our brand logo").
+- The user turned on "Composite canonical logo" when creating a generation preset (the preset then stamps the logo on every image made with it).
+- The agent infers the user wants the logo for a one-off (e.g. "make a hero with our brand logo") — pass `includeLogo: true` on that single generate call to override the preset.
 - The image will appear in a customer-facing context where logo accuracy matters.
 
 ## When NOT to use it

package/corpus/templates/assets/AGENTS.md

@@ -47,10 +47,25 @@ prompt, aspectRatio }`.
   composer is empty. The image model is the only remaining composer-side
   default; the image-model picker writes `imageGenerationModel`, which image
   generation actions may use when `model` is omitted.
+- When a `preset` is tagged, the server embeds that preset's aesthetics and
+  creative philosophy (brand style brief, prompt template, text/logo policy,
+  output format) into your message inside a `<tagged-generation-presets>` block.
+  Study and internalize that brief before you generate — let it drive
+  composition, mood, lighting, and subject — then pass the `presetId` to
+  `generate-image` / `generate-image-batch` so the saved format/model/tier/logo
+  apply automatically. Do not restate those as ad-hoc args.
 - For exact visible copy inside a generated image, pass `embeddedText` and
   optional `textPlacement` to `generate-image` or each `generate-image-batch`
   slot. Keep the general `prompt` for creative direction; the structured text
   fields are what allow the pipeline to render copy instead of suppressing it.
+- Logo compositing is a preset option: a generation preset carries
+  `includeLogo`, and `generate-image` / `generate-image-batch` stamp the
+  library's pixel-perfect canonical logo onto the result when the resolved
+  preset has it on (no-op if the library has no canonical logo). Set it via
+  `create-generation-preset` / `update-generation-preset` (`includeLogo`). The
+  model never draws the logo itself. Pass `includeLogo` on a generate call only
+  to override the preset for that one run; otherwise omit it. See the
+  `logo-composite` skill.
 - `asset-variants` is the shared live generation tray state. New image
   candidates should appear there through `generate-image` or
   `generate-image-batch`; do not invent page-local progress surfaces.

package/corpus/templates/assets/actions/_helpers.ts

@@ -155,6 +155,7 @@ export function serializeGenerationRun(row: any) {
 }
 
 export function serializeGenerationPreset(row: any): GenerationPresetSummary {
+  const settings = parseJson<Record<string, unknown>>(row.settings, {});
   return {
     id: row.id,
     libraryId: row.libraryId,
@@ -169,7 +170,8 @@ export function serializeGenerationPreset(row: any): GenerationPresetSummary {
     model: row.model,
     textPolicy: row.textPolicy ?? "",
     referencePolicy: row.referencePolicy ?? "auto",
-    settings: parseJson<Record<string, unknown>>(row.settings, {}),
+    includeLogo: settings.includeLogo === true,
+    settings,
     sortOrder: Number(row.sortOrder ?? 0),
     createdAt: row.createdAt,
     updatedAt: row.updatedAt,

package/corpus/templates/assets/actions/create-generation-preset.ts

@@ -32,6 +32,12 @@ export default defineAction({
     referencePolicy: z
       .enum(GENERATION_PRESET_REFERENCE_POLICIES)
       .default("auto"),
+    includeLogo: z.coerce
+      .boolean()
+      .optional()
+      .describe(
+        "When true, images generated with this preset composite the library's canonical logo (no-op if the library has no canonical logo).",
+      ),
     settings: z.record(z.string(), z.unknown()).optional(),
     sortOrder: z.coerce.number().optional(),
   }),
@@ -62,7 +68,12 @@ export default defineAction({
       model: args.model,
       textPolicy: args.textPolicy,
       referencePolicy: args.referencePolicy,
-      settings: stringifyJson(args.settings ?? {}),
+      settings: stringifyJson({
+        ...(args.settings ?? {}),
+        ...(args.includeLogo !== undefined
+          ? { includeLogo: args.includeLogo }
+          : {}),
+      }),
       sortOrder: args.sortOrder ?? 100,
       createdAt: now,
       updatedAt: now,

package/corpus/templates/assets/actions/generate-asset.ts

@@ -48,7 +48,11 @@ const schema = z.object({
     .describe("Number of image candidates to generate in the picker."),
   tier: z.enum(IMAGE_QUALITY_TIERS).optional(),
   styleStrength: z.enum(STYLE_STRENGTHS).default("balanced"),
-  includeLogo: booleanParam.default(false),
+  includeLogo: booleanParam
+    .optional()
+    .describe(
+      "Override logo compositing for this run. When omitted, the selected preset's logo setting decides whether the library's canonical logo is composited.",
+    ),
   callerAppId: z
     .string()
     .optional()

package/corpus/templates/assets/actions/generate-image-batch.ts

@@ -86,7 +86,12 @@ export default defineAction({
     tier: z.enum(IMAGE_QUALITY_TIERS).optional(),
     intent: z.enum(GENERATION_INTENTS).default("generate"),
     styleStrength: z.enum(STYLE_STRENGTHS).default("balanced"),
-    includeLogo: z.coerce.boolean().default(false),
+    includeLogo: z.coerce
+      .boolean()
+      .optional()
+      .describe(
+        "Composite the library's canonical logo onto every slot. When omitted, the selected preset's logo setting is used; pass an explicit value to override it. No-op if the library has no canonical logo.",
+      ),
     groundingMode: z.enum(["auto", "off", "google-search"]).default("auto"),
     source: z.enum(["chat", "ui", "a2a"]).default("chat"),
     callerAppId: z

package/corpus/templates/assets/actions/generate-image.ts

@@ -103,7 +103,12 @@ export default defineAction({
       .describe(
         "Exact reference assets to use. When omitted, the server deterministically chooses a small relevant subset from the latest library references.",
       ),
-    includeLogo: z.coerce.boolean().default(false),
+    includeLogo: z.coerce
+      .boolean()
+      .optional()
+      .describe(
+        "Composite the library's pixel-perfect canonical logo onto the finished image. When omitted, the selected preset's logo setting is used; pass an explicit value to override it. No-op if the library has no canonical logo.",
+      ),
     slotId: z.string().optional(),
     variantBatchId: z.string().optional(),
     variantScopeId: z
@@ -259,11 +264,13 @@ export default defineAction({
       preset?.imageSize ??
       collection?.defaultImageSize ??
       "2K") as (typeof IMAGE_SIZES)[number];
-    const presetSettings = parseJson<{ tier?: ImageQualityTier }>(
-      preset?.settings,
-      {},
-    );
+    const presetSettings = parseJson<{
+      tier?: ImageQualityTier;
+      includeLogo?: boolean;
+    }>(preset?.settings, {});
     const resolvedTier = args.tier ?? presetSettings.tier;
+    const resolvedIncludeLogo =
+      args.includeLogo ?? presetSettings.includeLogo ?? false;
     const category = (args.categories?.[0] ??
       preset?.category ??
       collection?.category) as ImageCategory | undefined;
@@ -320,7 +327,7 @@ export default defineAction({
       embeddedText: args.embeddedText,
       textPlacement: args.textPlacement,
       referenceCount: references.length,
-      includeLogo: args.includeLogo,
+      includeLogo: resolvedIncludeLogo,
       aspectRatio: resolvedAspectRatio,
       imageSize: resolvedImageSize,
       category,
@@ -363,7 +370,7 @@ export default defineAction({
       aspectRatio: resolvedAspectRatio,
       imageSize: resolvedImageSize,
       groundingMode: args.groundingMode,
-      includeLogo: args.includeLogo,
+      includeLogo: resolvedIncludeLogo,
       categories: resolvedCategories ?? [],
       collectionId: resolvedCollectionId ?? null,
       presetId: preset?.id ?? null,
@@ -386,7 +393,7 @@ export default defineAction({
       intent: args.intent,
       styleStrength: args.styleStrength,
       tier: resolvedTier,
-      includeLogo: args.includeLogo,
+      includeLogo: resolvedIncludeLogo,
       categories: resolvedCategories ?? [],
       presetId: preset?.id,
       sessionId: session?.id,
@@ -463,7 +470,7 @@ export default defineAction({
       await deleteAppState("image-generation-setup").catch(() => {});
       let image = generated.image;
       let mimeType = generated.mimeType;
-      if (args.includeLogo && library.canonicalLogoAssetId) {
+      if (resolvedIncludeLogo && library.canonicalLogoAssetId) {
         const [logo] = await db
           .select()
           .from(schema.assets)
@@ -539,7 +546,7 @@ export default defineAction({
               intent: args.intent,
               styleStrength: args.styleStrength,
               tier: resolvedTier,
-              includeLogo: args.includeLogo,
+              includeLogo: resolvedIncludeLogo,
               presetId: preset?.id,
               sessionId: session?.id,
               generated: true,
@@ -584,7 +591,7 @@ export default defineAction({
             intent: args.intent,
             styleStrength: args.styleStrength,
             tier: resolvedTier,
-            includeLogo: args.includeLogo,
+            includeLogo: resolvedIncludeLogo,
             categories: resolvedCategories ?? [],
             referenceSelection,
             settingsUsed,

package/corpus/templates/assets/actions/open-asset-picker.ts

@@ -72,8 +72,10 @@ const schema = z.object({
     .default("balanced")
     .describe("How strongly to follow the library style during generation."),
   includeLogo: booleanParam
-    .default(false)
-    .describe("Whether auto-generation should include the library logo."),
+    .optional()
+    .describe(
+      "Override logo compositing for auto-generation. When omitted, the selected preset's logo setting decides whether the library's canonical logo is composited.",
+    ),
   callerAppId: z
     .string()
     .optional()