@agent-native/core 0.80.10 → 0.80.11

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: 4719
+- template files: 4729

package/corpus/core/CHANGELOG.md

@@ -1,5 +1,11 @@
 # @agent-native/core
 
+## 0.80.11
+
+### Patch Changes
+
+- abf0681: Stop chat reconnect from falsely reporting "stopped before finishing" on long but healthy runs. The active-run reconnect now treats the stuck threshold as an idle deadline that resets on every streamed event, instead of a one-shot cap on total reconnect duration — so a long-running tool (e.g. image generation) that keeps emitting activity heartbeats is never aborted with a no-progress error just for running longer than the threshold. Also surfaces active tool progress while reconnecting, and waits for interrupted write-tool results before re-running them so long-running tools do not appear stopped or duplicate work.
+
 ## 0.80.10
 
 ### Patch Changes

package/corpus/core/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@agent-native/core",
-  "version": "0.80.10",
+  "version": "0.80.11",
   "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/production-agent.ts

@@ -2171,6 +2171,63 @@ function toolCallCacheKey(toolName: string, input: unknown): string {
   return `${toolName}:${stableStringify(normalizeToolCallInputForHistory(input))}`;
 }
 
+const INTERRUPTED_TOOL_LEDGER_POLL_MS =
+  process.env.NODE_ENV === "test" ? 0 : 2_000;
+
+async function waitForInterruptedToolLedgerEntry(opts: {
+  threadId: string;
+  toolKey: string;
+  toolName: string;
+  timeoutMs: number;
+  signal: AbortSignal;
+  send: (event: AgentChatEvent) => void;
+}): Promise<string | null> {
+  const pollMs = INTERRUPTED_TOOL_LEDGER_POLL_MS;
+  // Wait up to the tool's OWN declared timeout — the abandoned zombie can keep
+  // running that long (e.g. a 12-minute image generation, whose provider keeps
+  // generating after the run aborts), and giving up early re-runs the same
+  // write tool while the original is still in flight, duplicating work and
+  // double-charging. A flat sub-tool-timeout cap (previously 5 min) silently
+  // truncated long tools. The run's AbortSignal still bounds this to the run's
+  // remaining budget: when the run is cut off, the poll returns null and the
+  // re-dispatch hits the already-aborted signal instead of launching a real
+  // second call, so the wait never outlives the run.
+  const maxWaitMs =
+    process.env.NODE_ENV === "test" ? 1 : Math.max(0, opts.timeoutMs);
+  const maxPolls =
+    process.env.NODE_ENV === "test"
+      ? 3
+      : Math.max(1, Math.ceil(maxWaitMs / Math.max(1, pollMs)) + 1);
+
+  for (let attempt = 0; attempt < maxPolls; attempt++) {
+    if (opts.signal.aborted) return null;
+    const ledgerResult = await readLedgerEntry(opts.threadId, opts.toolKey);
+    if (ledgerResult !== null) return ledgerResult;
+
+    if (attempt >= maxPolls - 1) break;
+    opts.send({
+      type: "activity",
+      tool: opts.toolName,
+      label: `Waiting for previous ${opts.toolName} result.`,
+    });
+    if (pollMs <= 0) continue;
+    await new Promise<void>((resolve) => {
+      let settled = false;
+      const done = () => {
+        if (settled) return;
+        settled = true;
+        clearTimeout(timer);
+        opts.signal.removeEventListener("abort", done);
+        resolve();
+      };
+      const timer = setTimeout(done, pollMs);
+      opts.signal.addEventListener("abort", done, { once: true });
+    });
+  }
+
+  return null;
+}
+
 function normalizeToolErrorForBreaker(error: string): string {
   return error.replace(/\s+/g, " ").trim();
 }
@@ -3241,6 +3298,17 @@ export async function runAgentLoop(opts: {
         };
       }
 
+      const DEFAULT_TOOL_RESULT_CHARS = 50_000;
+      const DEFAULT_TOOL_TIMEOUT_MS = 60_000;
+      const toolTimeoutMs =
+        actionEntry.timeoutMs ??
+        opts.toolLimits?.timeoutMs ??
+        DEFAULT_TOOL_TIMEOUT_MS;
+      const toolMaxResultChars =
+        actionEntry.maxResultChars ??
+        opts.toolLimits?.maxResultChars ??
+        DEFAULT_TOOL_RESULT_CHARS;
+
       // TOOL-CALL JOURNAL HARD-BLOCK (resume safety, tool-layer enforcement).
       // The prompt-level resume journal already TELLS a resuming model not to
       // re-run completed tool calls; this enforces it at the tool layer so a
@@ -3291,17 +3359,23 @@ export async function runAgentLoop(opts: {
       // previous invocation's zombie actually completed and wrote its result to
       // the durable ledger. If so, return the ledger result without re-executing
       // (prevents the duplicate side effect) and skip counting it toward the
-      // interruption budget.
+      // interruption budget. A just-abandoned long tool may need a short grace
+      // period before its detached promise writes the ledger, so wait while the
+      // current run still has budget instead of immediately re-running it.
       if (!actionEntry.readOnly) {
         const writeCacheKey = toolCallCacheKey(toolCall.name, toolCall.input);
         const priorInterruptions =
           writeToolInterruptions.get(writeCacheKey) ?? 0;
 
         if (priorInterruptions > 0 && opts.threadId) {
-          const ledgerResult = await readLedgerEntry(
-            opts.threadId,
-            writeCacheKey,
-          );
+          const ledgerResult = await waitForInterruptedToolLedgerEntry({
+            threadId: opts.threadId,
+            toolKey: writeCacheKey,
+            toolName: toolCall.name,
+            timeoutMs: toolTimeoutMs,
+            signal,
+            send,
+          });
           if (ledgerResult !== null) {
             // Zombie completed — recover the real result without re-executing.
             const result =
@@ -3359,6 +3433,25 @@ export async function runAgentLoop(opts: {
         }
       }
 
+      // Stop BEFORE emitting tool_start if the run was already aborted —
+      // typically because the ledger wait above polled for minutes and the soft
+      // timeout fired meanwhile. Emitting tool_start/tool_done here would leave a
+      // bogus interrupted pair in the transcript for a tool that never re-ran,
+      // and re-invoking would spawn a duplicate zombie. Return the interrupted
+      // marker (no events) so the next continuation recovers via the ledger.
+      // (A second guard inside the try below still covers an abort that lands in
+      // the tiny sync window between here and the action invocation.)
+      if (signal.aborted) {
+        recordToolResult(INTERRUPTED_TOOL_RESULT_MARKER, false);
+        return {
+          type: "tool-result" as const,
+          toolCallId: toolCall.id,
+          toolName: toolCall.name,
+          toolInput: wireToolInput,
+          content: INTERRUPTED_TOOL_RESULT_MARKER,
+        };
+      }
+
       send({
         type: "tool_start",
         tool: toolCall.name,
@@ -3427,22 +3520,22 @@ export async function runAgentLoop(opts: {
         };
       }
 
-      const DEFAULT_TOOL_RESULT_CHARS = 50_000;
-      const DEFAULT_TOOL_TIMEOUT_MS = 60_000;
-      const toolTimeoutMs =
-        actionEntry.timeoutMs ??
-        opts.toolLimits?.timeoutMs ??
-        DEFAULT_TOOL_TIMEOUT_MS;
-      const toolMaxResultChars =
-        actionEntry.maxResultChars ??
-        opts.toolLimits?.maxResultChars ??
-        DEFAULT_TOOL_RESULT_CHARS;
       let result: string;
       let isError = false;
       let mcpApp:
         | import("../mcp-client/app-result.js").AgentMcpAppPayload
         | undefined;
       try {
+        // The run may have been aborted while we waited above for an
+        // interrupted tool's ledger result (the wait can poll for minutes).
+        // Re-check before invoking the action: starting it now would spawn a
+        // fresh zombie execution — a duplicate side effect / double charge —
+        // which the ledger-recovery path exists to prevent. The Promise.race
+        // "Run aborted" leg below only rejects AFTER the action is invoked, so
+        // it cannot guard this. Throw here instead, handled like any abort.
+        if (signal.aborted) {
+          throw new Error("Run aborted");
+        }
         const timeoutSignal = AbortSignal.timeout(toolTimeoutMs);
         const actionUserEmail = opts.ownerEmail ?? getRequestUserEmail();
         const actionOrgId = opts.orgId ?? getRequestOrgId() ?? null;

package/corpus/core/src/client/AssistantChat.tsx

@@ -230,6 +230,12 @@ const PENDING_SELECTION_KEY = "pending-selection-context";
 const ACTIVE_RUN_CLEAR_TIMEOUT_MS = 5_000;
 const ACTIVE_RUN_STUCK_THRESHOLD_MS = 90_000;
 const ACTIVE_RUN_POLL_INTERVAL_MS = 150;
+// How long a single activity (model call, tool prep, long tool) must stay
+// in-flight before its label is surfaced in the running indicator. Below this
+// the indicator stays a steady "Thinking" so normal fast turns don't flicker
+// through transient labels ("Contacting model", "Preparing X action"); past it
+// the live label appears so a genuinely slow step reads as working, not hung.
+const ACTIVITY_LABEL_REVEAL_DELAY_MS = 6_000;
 const SUBMIT_ENGINE_STATUS_TIMEOUT_MS = 1000;
 
 type ActiveRunLookup = {
@@ -254,6 +260,24 @@ function activeRunLooksStale(runInfo: ActiveRunLookup): boolean {
   );
 }
 
+/**
+ * Decide whether a reconnect should give up with "no progress". The signal is
+ * *time since the last streamed event*, NOT total reconnect duration: a healthy
+ * long-running tool (e.g. image generation, which emits `activity` heartbeats
+ * every few seconds) makes continuous progress and must never be aborted just
+ * for running longer than the threshold. Only genuine silence for the full
+ * stuck threshold counts as stuck. Pure + exported so the decision is unit
+ * testable without driving the whole reconnect lifecycle.
+ */
+export function reconnectProgressTimedOut(args: {
+  lastProgressAt: number;
+  now: number;
+  thresholdMs?: number;
+}): boolean {
+  const threshold = args.thresholdMs ?? ACTIVE_RUN_STUCK_THRESHOLD_MS;
+  return args.now - args.lastProgressAt >= threshold;
+}
+
 function isAssistantUiDuplicateMessageIdError(error: unknown): boolean {
   const message = error instanceof Error ? error.message : String(error ?? "");
   return (
@@ -1323,6 +1347,24 @@ const AssistantChatInner = forwardRef<
   // True during the 250ms continuation window and startup of the next chunk
   // (adapter's auto-continue delay before POSTing the next chunk).
   const [isAutoResuming, setIsAutoResuming] = useState(false);
+  const [runningActivityLabel, setRunningActivityLabel] = useState<
+    string | null
+  >(null);
+  // Delayed-reveal state for the activity label (see ACTIVITY_LABEL_REVEAL_DELAY_MS).
+  // `latest` holds the most recent activity label; `surfaced` flips true once the
+  // reveal timer fires; `timer` is the pending one-shot reveal.
+  const activityLabelTimerRef = useRef<number | null>(null);
+  const latestActivityLabelRef = useRef<string | null>(null);
+  const activityLabelSurfacedRef = useRef(false);
+  const resetRunningActivity = useCallback(() => {
+    if (activityLabelTimerRef.current !== null) {
+      window.clearTimeout(activityLabelTimerRef.current);
+      activityLabelTimerRef.current = null;
+    }
+    latestActivityLabelRef.current = null;
+    activityLabelSurfacedRef.current = false;
+    setRunningActivityLabel(null);
+  }, []);
   const [reconnectContent, setReconnectContent] = useState<ContentPart[]>([]);
   // When stop is clicked during reconnect, keep content visible (don't wipe it)
   const [reconnectFrozen, setReconnectFrozen] = useState(false);
@@ -1341,6 +1383,19 @@ const AssistantChatInner = forwardRef<
   const textStreaming = isRunning || externalStreaming;
   // UI-only running state — drives the stop button and thinking indicator.
   const showRunningInUI = isRunning;
+  // A revealed activity label wins; otherwise stay a steady "Thinking" by
+  // default. We only surface "Reconnecting" while we are actively replaying
+  // recovered content (reconnectContent populated). A bare reconnect with no
+  // replayed content — e.g. a tail-resume after the serverless wall, where
+  // `scheduleUpdate` intentionally leaves reconnectContent empty — is normal
+  // ongoing work, so it must read as "Thinking", never a perpetual "Working".
+  const runningStatusLabel = runningActivityLabel
+    ? runningActivityLabel
+    : isAutoResuming
+      ? "Resuming"
+      : isReconnecting && reconnectContent.length > 0
+        ? "Reconnecting"
+        : "Thinking";
   const lastBroadcastRunningRef = useRef(isRunning);
   const tiptapRef = useRef<TiptapComposerHandle>(null);
   // Stable ref to the "stop active run" action so addToQueue can abort
@@ -1608,11 +1663,32 @@ const AssistantChatInner = forwardRef<
       }, 1000);
 
       let reconnectTimedOut = false;
-      const maxReconnectTimer = setTimeout(() => {
+      // Idle deadline, NOT a total-duration cap. A long-but-healthy run (image
+      // generation emits `activity` heartbeats every few seconds) keeps
+      // advancing `lastReconnectProgressAt`, so it is never aborted for simply
+      // taking longer than the threshold. Only true silence for the full stuck
+      // threshold trips it — the same semantics as `activeRunLooksStale` and the
+      // SSE-level no-progress timeout. `markReconnectProgress` resets it on every
+      // streamed event (see the `onSeq` callback below, which fires for every
+      // event including activity, for both fresh and tail-resume reconnects).
+      let lastReconnectProgressAt = Date.now();
+      const markReconnectProgress = () => {
+        lastReconnectProgressAt = Date.now();
+      };
+      const idleCheck = setInterval(() => {
+        if (
+          !reconnectProgressTimedOut({
+            lastProgressAt: lastReconnectProgressAt,
+            now: Date.now(),
+          })
+        ) {
+          return;
+        }
         reconnectTimedOut = true;
         abortCtrl.abort();
         clearInterval(watchdog);
-      }, 20_000);
+        clearInterval(idleCheck);
+      }, 1000);
 
       const streamReconnect = async () => {
         let noProgressDuringReconnect = false;
@@ -1653,7 +1729,10 @@ const AssistantChatInner = forwardRef<
               toolCallCounter,
               tabId,
               scheduleUpdate,
-              (seq) => updateActiveRunSeq(seq),
+              (seq) => {
+                markReconnectProgress();
+                updateActiveRunSeq(seq);
+              },
             );
             if (afterSeq === 0) {
               setReconnectContent([...content]);
@@ -1677,7 +1756,7 @@ const AssistantChatInner = forwardRef<
             window.clearInterval(threadPollInterval);
           }
           clearInterval(watchdog);
-          clearTimeout(maxReconnectTimer);
+          clearInterval(idleCheck);
         }
 
         if (noProgressDuringReconnect && reconnectRunIdRef.current === runId) {
@@ -2235,11 +2314,9 @@ const AssistantChatInner = forwardRef<
     return () => window.removeEventListener("agent-chat:run-error", handler);
   }, [tabId]);
 
-  // Real activity means the next chunk has started — leave the auto-resume
-  // ("Resuming") state so the indicator settles back to "Thinking". The
-  // activity label itself is intentionally not surfaced: the running
-  // indicator stays a steady "Thinking" rather than flipping through
-  // transient step labels.
+  // Real activity means the next chunk has started. Surface longer-lived
+  // activity such as "Still generating image" so active-run reconnects do not
+  // look like failures while the server is still making progress.
   useEffect(() => {
     const handler = (e: Event) => {
       const detail = (e as CustomEvent).detail as {
@@ -2248,13 +2325,43 @@ const AssistantChatInner = forwardRef<
         tabId?: string;
       };
       if (tabId && detail?.tabId && detail.tabId !== tabId) return;
-      if (typeof detail?.label === "string" && detail.label.trim()) {
-        setIsAutoResuming(false);
+      const label =
+        typeof detail?.label === "string" ? detail.label.trim() : "";
+      if (!label) return;
+      setIsAutoResuming(false);
+      latestActivityLabelRef.current = label;
+      // Already past the delay → keep the visible label current.
+      if (activityLabelSurfacedRef.current) {
+        setRunningActivityLabel(label);
+        return;
+      }
+      // Not yet surfaced → arm a single reveal timer on the FIRST activity of
+      // this in-flight period. A burst of quick steps that all finish (clear)
+      // before the timer fires never surfaces anything, so normal fast turns
+      // stay a steady "Thinking". A step still in-flight at the deadline reveals
+      // the latest label so a slow operation reads as working, not hung.
+      if (activityLabelTimerRef.current === null) {
+        activityLabelTimerRef.current = window.setTimeout(() => {
+          activityLabelTimerRef.current = null;
+          activityLabelSurfacedRef.current = true;
+          if (latestActivityLabelRef.current) {
+            setRunningActivityLabel(latestActivityLabelRef.current);
+          }
+        }, ACTIVITY_LABEL_REVEAL_DELAY_MS);
       }
     };
+    const clear = (e: Event) => {
+      const detail = (e as CustomEvent).detail as { tabId?: string };
+      if (tabId && detail?.tabId && detail.tabId !== tabId) return;
+      resetRunningActivity();
+    };
     window.addEventListener("agent-chat:activity", handler);
-    return () => window.removeEventListener("agent-chat:activity", handler);
-  }, [tabId]);
+    window.addEventListener("agent-chat:activity-clear", clear);
+    return () => {
+      window.removeEventListener("agent-chat:activity", handler);
+      window.removeEventListener("agent-chat:activity-clear", clear);
+    };
+  }, [resetRunningActivity, tabId]);
 
   // Show "Resuming…" during the adapter's auto-continuation window (the
   // ~250ms gap between the end of one serverless chunk and the POST for the
@@ -2274,8 +2381,9 @@ const AssistantChatInner = forwardRef<
   useEffect(() => {
     if (!isRunning) {
       setIsAutoResuming(false);
+      resetRunningActivity();
     }
-  }, [isRunning]);
+  }, [isRunning, resetRunningActivity]);
 
   // Auto-dequeue: when the agent is idle, send the next queued message. This
   // intentionally does not depend on observing the running -> idle transition:
@@ -3336,18 +3444,7 @@ const AssistantChatInner = forwardRef<
                           <ReconnectStreamMessage content={reconnectContent} />
                         )}
                       {showRunningInUI && (
-                        <RunningActivityStatus
-                          label={
-                            isReconnecting
-                              ? "Reconnecting"
-                              : isAutoResuming
-                                ? "Resuming"
-                                : // Keep a steady "Thinking" while the model works —
-                                  // never flip through transient activity labels
-                                  // (e.g. "Contacting model", "Preparing X action").
-                                  "Thinking"
-                          }
-                        />
+                        <RunningActivityStatus label={runningStatusLabel} />
                       )}
                       {queuedMessages.map((msg) => {
                         const displayText = msg.text

package/corpus/core/src/client/sse-event-processor.ts

@@ -352,6 +352,11 @@ export function processEvent(
   }
 
   if (ev.type === "text") {
+    // Visible output means the run is plainly not hanging — drop any running
+    // activity label so a transient "Contacting model" / "Still generating
+    // image" doesn't linger beside streamed text. Idempotent (clears once, then
+    // no-ops) so per-token text deltas stay cheap.
+    if (ev.text) dispatchActivityClear(tabId);
     const lastPart = content[content.length - 1];
     if (lastPart && lastPart.type === "text") {
       lastPart.text += ev.text ?? "";
@@ -492,6 +497,10 @@ export function processEvent(
         }),
       );
     }
+    // Clear any sticky running-activity label (e.g. "Still generating image"):
+    // the tool that was emitting activity heartbeats has finished, so the label
+    // must not linger while the model streams its follow-up text or reasoning.
+    dispatchActivityClear(tabId);
     // Use id-based lookup when available so parallel same-name tool calls
     // get their results correctly assigned; fall back to name-matching.
     const doneIdx = findPendingToolCallIndex(content, doneTool, ev.id);

package/corpus/templates/assets/.agents/skills/image-generation/SKILL.md

@@ -15,8 +15,15 @@ Use this skill before calling `generate-image`, `generate-image-batch`, or
   `presetId`, and `media-type` references choose image generation versus video
   generation. Call `view-screen` when the user says "this library" or "this
   image" and you need fresh IDs. The image model may default from the composer
-  image-model picker; all other generation settings should be explicit action
-  args, preset values, or action schema defaults.
+  image-model picker.
+- A tagged `@preset` (presetId) owns `aspectRatio`, `imageSize`, `model`,
+  `tier`, and `category`. When a preset is set, do NOT pass those args yourself —
+  leave them out so the preset's saved values are used. You cannot see the
+  preset's settings from the presetId, so passing your own guess silently
+  overrides the preset (this is the usual cause of a preset's aspect ratio being
+  ignored). Pass one of these args alongside a preset ONLY when the user
+  explicitly asks for a value that differs from the preset. When there is no
+  preset, set them explicitly or rely on the action schema defaults.
 - Use category-tagged references. Blog heroes should prefer `hero`; diagrams
   should prefer `diagram`; product imagery should include `product` and `logo`
   references.

package/corpus/templates/assets/AGENTS.md

@@ -47,6 +47,10 @@ 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.
+- 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.
 - `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/_tool-activity.ts

@@ -0,0 +1,46 @@
+import type { ActionRunContext } from "@agent-native/core/action";
+
+const DEFAULT_TOOL_ACTIVITY_INTERVAL_MS = 8_000;
+
+type ToolActivityOptions = {
+  label: string;
+  ongoingLabel?: string;
+  intervalMs?: number;
+  tool?: string;
+};
+
+function canEmitToolActivity(
+  context: ActionRunContext | undefined,
+): context is ActionRunContext & Required<Pick<ActionRunContext, "send">> {
+  return context?.caller === "tool" && typeof context.send === "function";
+}
+
+export async function withToolActivity<T>(
+  context: ActionRunContext | undefined,
+  options: ToolActivityOptions,
+  work: () => Promise<T>,
+): Promise<T> {
+  if (!canEmitToolActivity(context)) return work();
+
+  const tool = options.tool ?? context.actionName;
+  const sendActivity = (label: string) => {
+    context.send({
+      type: "activity",
+      label,
+      ...(tool ? { tool } : {}),
+    });
+  };
+
+  sendActivity(options.label);
+  const interval = setInterval(
+    () => sendActivity(options.ongoingLabel ?? options.label),
+    options.intervalMs ?? DEFAULT_TOOL_ACTIVITY_INTERVAL_MS,
+  );
+  interval.unref?.();
+
+  try {
+    return await work();
+  } finally {
+    clearInterval(interval);
+  }
+}

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

@@ -18,7 +18,6 @@ import {
   STYLE_STRENGTHS,
 } from "../shared/api.js";
 import { requireGenerationSessionInLibrary } from "./_helpers.js";
-import { readImageModelDefault } from "./_image-model-default.js";
 import generateImage from "./generate-image.js";
 import { upsertVariantSlot } from "./variant-slots.js";
 
@@ -35,14 +34,36 @@ export default defineAction({
         "Brand kit/library ID. Pass the refId from a brand-kit @mention, or choose a kit from view-screen/list-libraries.",
       ),
     collectionId: z.string().optional(),
-    presetId: z.string().optional(),
+    presetId: z
+      .string()
+      .optional()
+      .describe(
+        "Generation preset ID (from a @preset mention or list-generation-presets). The preset already defines aspectRatio, imageSize, model, tier, and category. When you set presetId, OMIT each slot's aspectRatio/imageSize and the top-level model/tier so the preset's values are used; only pass one when the user explicitly asks for a value that differs from the preset.",
+      ),
     sessionId: z.string().optional(),
     slots: z
       .array(
         z.object({
           slotId: z.string(),
           prompt: z.string().min(1),
-          aspectRatio: z.enum(ASPECT_RATIOS).optional(),
+          embeddedText: z
+            .string()
+            .optional()
+            .describe(
+              "Exact words to render inside the image, spelled exactly. When set, the image is allowed to contain this text; when omitted, the image avoids embedded text.",
+            ),
+          textPlacement: z
+            .string()
+            .optional()
+            .describe(
+              "Where/how the embedded text should appear, e.g. 'centered headline', 'lower-left label'.",
+            ),
+          aspectRatio: z
+            .enum(ASPECT_RATIOS)
+            .optional()
+            .describe(
+              "Slot aspect ratio. When a presetId is set, omit this — the preset's aspect ratio is used unless the user explicitly asks for a different ratio for this slot.",
+            ),
           imageSize: z.enum(IMAGE_SIZES).optional(),
           categories: z.array(z.enum(IMAGE_CATEGORIES)).optional(),
           referenceAssetIds: z.array(z.string()).optional(),
@@ -78,7 +99,6 @@ export default defineAction({
   parallelSafe: true,
   timeoutMs: IMAGE_GENERATION_TOOL_TIMEOUT_MS,
   run: async ({ slots, ...inputBase }, context?: ActionRunContext) => {
-    const imageModelDefault = await readImageModelDefault();
     const libraryId = inputBase.libraryId;
     if (!libraryId) {
       throw new Error(
@@ -88,7 +108,6 @@ export default defineAction({
     const base = {
       ...inputBase,
       libraryId,
-      model: inputBase.model ?? imageModelDefault,
     };
     await assertAccess("asset-library", base.libraryId, "editor");
     if (base.sessionId) {
@@ -123,6 +142,8 @@ export default defineAction({
               presetId: base.presetId,
               sessionId: base.sessionId,
               prompt: slot.prompt,
+              embeddedText: slot.embeddedText,
+              textPlacement: slot.textPlacement,
               aspectRatio: slot.aspectRatio,
               imageSize: slot.imageSize,
               model: base.model,