@agent-native/core 0.84.10 → 0.84.13

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: 4909
+- template files: 4917

package/corpus/core/CHANGELOG.md

@@ -1,5 +1,53 @@
 # @agent-native/core
 
+## 0.84.13
+
+### Patch Changes
+
+- dd5b0a4: Honor the long Netlify background-function timeout for durable agent-chat workers and record runtime diagnostics when a background run starts.
+- dd5b0a4: Make agent chat recovery surface completed-tool timeouts more reliably and keep Design variant follow-ups bounded to the selected screen.
+- dd5b0a4: Double the agent chat smooth-streaming reveal speed.
+- dd5b0a4: Avoid noisy Sentry reports from expected chat auth states and best-effort client thread-save conflicts.
+- dd5b0a4: Keep activity-only tool cards and the latest assistant message visibly running during agent chat continuations, steer interrupted Design generation retries toward smaller existing-file edits, and capture run persistence failures with run IDs so missing request IDs are diagnosable.
+- dd5b0a4: Compress the Plan mode composer callout into a quieter inline status pill.
+
+## 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

package/corpus/core/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@agent-native/core",
-  "version": "0.84.10",
+  "version": "0.84.13",
   "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/durable-background.ts

@@ -235,6 +235,36 @@ export function isInBackgroundFunctionRuntime(): boolean {
   return false;
 }
 
+export function backgroundRunMarkerExpectsBackgroundRuntime(
+  marker: unknown,
+): boolean {
+  return (
+    typeof marker === "object" &&
+    marker !== null &&
+    (marker as { backgroundFunctionRuntimeExpected?: unknown })
+      .backgroundFunctionRuntimeExpected === true
+  );
+}
+
+export function shouldUseBackgroundFunctionTimeoutForWorker(
+  marker: unknown,
+): boolean {
+  return (
+    isInBackgroundFunctionRuntime() ||
+    backgroundRunMarkerExpectsBackgroundRuntime(marker)
+  );
+}
+
+export function backgroundRuntimeDiagnosticDetail(marker: unknown): string {
+  return [
+    `markerExpected=${backgroundRunMarkerExpectsBackgroundRuntime(marker)}`,
+    `runtimeDetected=${isInBackgroundFunctionRuntime()}`,
+    `globalMarker=${(globalThis as Record<string, unknown>).__AGENT_NATIVE_BACKGROUND_RUNTIME__ === true}`,
+    `lambdaNameEndsBackground=${typeof process.env.AWS_LAMBDA_FUNCTION_NAME === "string" && process.env.AWS_LAMBDA_FUNCTION_NAME.toLowerCase().endsWith("-background")}`,
+    `forceEnv=${typeof process.env.AGENT_CHAT_FORCE_BACKGROUND_RUNTIME === "string" && process.env.AGENT_CHAT_FORCE_BACKGROUND_RUNTIME.trim().length > 0}`,
+  ].join(" ");
+}
+
 function isFlagEnabled(): boolean {
   // Read the literal key (not `process.env[CONST]`) so guard:no-env-credentials
   // can statically verify it against the allowlisted `AGENT_*` prefix. Keep this

package/corpus/core/src/agent/production-agent.ts

@@ -53,9 +53,10 @@ import {
 import { computeProtectedSegmentIds } from "./context-xray/segments.js";
 import {
   AGENT_CHAT_BACKGROUND_RUN_FIELD,
+  backgroundRuntimeDiagnosticDetail,
   isAgentChatDurableBackgroundEnabled,
-  isInBackgroundFunctionRuntime,
   resolveAgentChatProcessRunDispatchPath,
+  shouldUseBackgroundFunctionTimeoutForWorker,
 } from "./durable-background.js";
 import {
   LLM_MISSING_CREDENTIALS_ERROR_CODE,
@@ -4032,6 +4033,7 @@ export async function claimBackgroundWorkerRunEarly(opts: {
   requestTurnId?: string | null;
   continuationCount: number;
   runsInBackgroundFunction: boolean;
+  backgroundRuntimeDetail?: string;
   deps?: {
     recordRunDiagnostic?: typeof recordRunDiagnostic;
     insertRun?: typeof insertRun;
@@ -4057,7 +4059,13 @@ export async function claimBackgroundWorkerRunEarly(opts: {
   await record(
     opts.runId,
     RUN_DIAG_STAGE.workerEntered,
-    `runsInBackgroundFunction=${opts.runsInBackgroundFunction} continuationCount=${opts.continuationCount}`,
+    [
+      `runsInBackgroundFunction=${opts.runsInBackgroundFunction}`,
+      `continuationCount=${opts.continuationCount}`,
+      opts.backgroundRuntimeDetail,
+    ]
+      .filter(Boolean)
+      .join(" "),
   ).catch(() => {});
 
   if (opts.continuationCount > 0) {
@@ -4218,7 +4226,11 @@ export function createProductionAgentHandler(
     // function. Only a true value unlocks the ~13-min soft-timeout budget; a
     // worker on the 60s function keeps the 40s clamp and checkpoints cleanly.
     const runsInBackgroundFunction =
-      isBackgroundWorker && isInBackgroundFunctionRuntime();
+      isBackgroundWorker &&
+      shouldUseBackgroundFunctionTimeoutForWorker(backgroundRunMarker);
+    const backgroundRuntimeDetail = isBackgroundWorker
+      ? backgroundRuntimeDiagnosticDetail(backgroundRunMarker)
+      : "";
     // How many server-driven background continuations have already chained into
     // this logical turn (0 on the first chunk). Used to bound the chain.
     const backgroundContinuationCount =
@@ -4239,6 +4251,7 @@ export function createProductionAgentHandler(
         requestTurnId,
         continuationCount: backgroundContinuationCount,
         runsInBackgroundFunction,
+        backgroundRuntimeDetail,
       });
       if (!earlyClaim.claimed) {
         return { ok: true, skipped: earlyClaim.skipped };
@@ -5001,6 +5014,9 @@ export function createProductionAgentHandler(
       }
 
       let dispatched = false;
+      const backgroundDispatchPath = resolveAgentChatProcessRunDispatchPath();
+      const expectsNetlifyBackgroundFunction =
+        backgroundDispatchPath.startsWith("/.netlify/functions/");
       try {
         await fireInternalDispatch({
           event,
@@ -5014,7 +5030,7 @@ export function createProductionAgentHandler(
           // inline. `fireInternalDispatch` strips the app base path for
           // /.netlify/* targets so the request reaches the host-root function url;
           // the Authorization Bearer HMAC is preserved either way.
-          path: resolveAgentChatProcessRunDispatchPath(),
+          path: backgroundDispatchPath,
           taskId: runId,
           body: {
             ...body,
@@ -5022,6 +5038,8 @@ export function createProductionAgentHandler(
             [AGENT_CHAT_BACKGROUND_RUN_FIELD]: {
               runId,
               turnId: effectiveTurnId,
+              backgroundFunctionRuntimeExpected:
+                expectsNetlifyBackgroundFunction,
             },
           },
         });
@@ -5302,6 +5320,8 @@ export function createProductionAgentHandler(
                         runId: nextRunId,
                         turnId: effectiveTurnId,
                         continuationCount: backgroundContinuationCount + 1,
+                        backgroundFunctionRuntimeExpected:
+                          runsInBackgroundFunction,
                       },
                     },
                   });
@@ -5335,7 +5355,13 @@ export function createProductionAgentHandler(
         await recordRunDiagnostic(
           runId,
           RUN_DIAG_STAGE.workerEntered,
-          `runsInBackgroundFunction=${runsInBackgroundFunction} continuationCount=${backgroundContinuationCount}`,
+          [
+            `runsInBackgroundFunction=${runsInBackgroundFunction}`,
+            `continuationCount=${backgroundContinuationCount}`,
+            backgroundRuntimeDetail,
+          ]
+            .filter(Boolean)
+            .join(" "),
         ).catch(() => {});
         if (isChainedBackgroundContinuation) {
           await insertRun(runId, effectiveThreadId, effectiveTurnId, {
@@ -5368,7 +5394,9 @@ export function createProductionAgentHandler(
     const setupDetail =
       Object.entries(setupMarks)
         .map(([k, v]) => `${k}=${v}`)
-        .join(" ") + ` total=${Date.now() - setupT0}`;
+        .join(" ") +
+      ` total=${Date.now() - setupT0}` +
+      (backgroundRuntimeDetail ? ` ${backgroundRuntimeDetail}` : "");
 
     startRun(
       runId,

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

@@ -349,11 +349,45 @@ export function startRun(
   activeRuns.set(runId, run);
   threadToRun.set(threadId, runId);
 
+  const captureRunPersistenceError = (
+    error: unknown,
+    phase: "insert-run" | "insert-event",
+    extra: Record<string, unknown> = {},
+  ) => {
+    captureError(error, {
+      route: "/_agent-native/agent-chat",
+      tags: {
+        source: "agent-run-manager",
+        phase,
+        runStatus: run.status,
+      },
+      extra: {
+        runId,
+        threadId,
+        eventCount: run.events.length,
+        startedAt: run.startedAt,
+        ...extra,
+      },
+      contexts: {
+        agentRun: {
+          runId,
+          threadId,
+          status: run.status,
+          phase,
+          eventCount: run.events.length,
+          startedAt: run.startedAt,
+        },
+      },
+    });
+  };
+
   // Persist run to SQL without blocking the response. Keep the promise so
   // final status cannot race ahead of a slow initial INSERT and then get
   // overwritten by a late row stuck at status='running'.
   const insertRunPromise = insertRun(runId, threadId, options?.turnId).catch(
-    () => {},
+    (error) => {
+      captureRunPersistenceError(error, "insert-run");
+    },
   );
 
   // Per-run event persistence chain: events are chained so SQL inserts commit
@@ -368,6 +402,7 @@ export function startRun(
   // chunk. The stuck-detector threshold is on the order of tens of seconds,
   // so 1s resolution is plenty.
   let lastProgressBumpAt = 0;
+  let eventPersistenceErrorCaptured = false;
   const bumpProgressIfDue = () => {
     const now = Date.now();
     if (now - lastProgressBumpAt < 1000) return;
@@ -494,7 +529,15 @@ export function startRun(
     const thisInsert = persistenceChain.then(() =>
       insertRunEvent(runId, runEvent.seq, JSON.stringify(runEvent.event)),
     );
-    persistenceChain = thisInsert.catch(() => {});
+    persistenceChain = thisInsert.catch((error) => {
+      if (!eventPersistenceErrorCaptured) {
+        eventPersistenceErrorCaptured = true;
+        captureRunPersistenceError(error, "insert-event", {
+          seq: runEvent.seq,
+          eventType: runEvent.event.type,
+        });
+      }
+    });
     const persistence = thisInsert;
     if (!options?.surfacePersistenceError) {
       persistence.catch(() => {});

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/chat-threads/store.ts

@@ -712,6 +712,7 @@ export interface UpdateThreadDataOptions {
   preserveExistingQueuedMessages?: boolean;
   preserveExistingTopLevelKeys?: boolean;
   maxAttempts?: number;
+  ignoreConflicts?: boolean;
 }
 
 function parseThreadData(value: string): any {
@@ -792,6 +793,7 @@ export async function updateThreadData(
   }
 
   if (lastConflict) {
+    if (options.ignoreConflicts) return;
     throw new Error(
       `Failed to update chat thread ${id} after concurrent write conflicts.`,
     );

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

@@ -329,15 +329,18 @@ iteration, or a human-in-the-loop choice among design directions.
   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 by first calling \`get-design-snapshot\` with that
-  screen's \`fileId\`, then making a bounded single-file pass.
+  screen's \`fileId\`, then calling \`edit-design\` on that same \`fileId\` in a
+  bounded single-file pass. Use \`mode: "replace-file"\` when expanding the
+  representative placeholder into the full chosen direction. Do not call
+  \`generate-design\` after a variant pick.
 - 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
   summary.
 - For direct refinements to an already chosen direction, call
   \`get-design-snapshot\`, edit from the current tuned HTML, and use
-  \`edit-design\` for surgical changes. Use \`generate-design\` for new files
-  or larger structural rewrites.
+  \`edit-design\` for surgical changes or \`mode: "replace-file"\` for a bounded
+  selected-file replacement. Use \`generate-design\` for new files only.
 - Use \`export-coding-handoff\` when the user wants to implement the chosen
   design in a codebase.
 
@@ -353,9 +356,10 @@ iteration, or a human-in-the-loop choice among design directions.
 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, 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.
+   screen, then call \`edit-design\` on that same \`fileId\` in a bounded pass.
+   Use \`mode: "replace-file"\` when expanding the representative placeholder
+   into the full chosen direction. Do not call \`generate-design\` after a
+   variant pick. Stop after the first successful \`edit-design\` save.
 
 ## Design Quality Bar
 

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

@@ -601,6 +601,31 @@ export function resolveAssistantChatSubmitIntent({
   return requestedIntent ?? "immediate";
 }
 
+export function resolveAssistantChatRunningState({
+  forceStopped,
+  isRuntimeRunning,
+  isReconnecting,
+  optimisticRunning,
+  isAutoResuming,
+}: {
+  forceStopped: boolean;
+  isRuntimeRunning: boolean;
+  isReconnecting: boolean;
+  optimisticRunning: boolean;
+  isAutoResuming: boolean;
+}): { isRunning: boolean; showRunningInUI: boolean } {
+  const isRunning =
+    !forceStopped && (isRuntimeRunning || isReconnecting || optimisticRunning);
+  return {
+    isRunning,
+    // During auto-continuation, assistant-ui can briefly mark the message done
+    // between chunks even though the adapter is about to POST the next run.
+    // Keep the visible chat state running so the latest assistant message shows
+    // Thinking/Resuming and does not expose footer actions prematurely.
+    showRunningInUI: !forceStopped && (isRunning || isAutoResuming),
+  };
+}
+
 type QueuedMessage = {
   id: string;
   text: string;
@@ -1378,14 +1403,17 @@ const AssistantChatInner = forwardRef<
   // queueing forever" state where isReconnecting or isRuntimeRunning gets
   // wedged (e.g. after a tab refresh + stop during reconnect).
   const [forceStopped, setForceStopped] = useState(false);
-  // Real running state — drives submission/queue gating. Treat reconnecting
-  // to an active run the same as running, UNLESS the user has explicitly
-  // clicked stop (forceStopped).
-  const isRunning =
-    !forceStopped && (isRuntimeRunning || isReconnecting || optimisticRunning);
-  const textStreaming = isRunning || externalStreaming;
-  // UI-only running state — drives the stop button and thinking indicator.
-  const showRunningInUI = isRunning;
+  // Real running state drives submission/queue gating; UI running also covers
+  // short auto-continuation gaps so the latest assistant message does not flash
+  // into a done state while the agent is still working.
+  const { isRunning, showRunningInUI } = resolveAssistantChatRunningState({
+    forceStopped,
+    isRuntimeRunning,
+    isReconnecting,
+    optimisticRunning,
+    isAutoResuming,
+  });
+  const textStreaming = showRunningInUI || externalStreaming;
   // 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
@@ -2265,6 +2293,8 @@ const AssistantChatInner = forwardRef<
 
   useEffect(() => {
     if (!authError) return;
+    const shouldCaptureStuckAuthCard =
+      authSessionAvailable || authError.sessionExpired;
     // Auto-recovery (`checkAuthSession`) runs immediately + at 250ms. If the
     // card is still showing 3 seconds later, recovery failed and the user
     // is about to hit "Refresh chat" — that's the "Reload UI required"
@@ -2273,6 +2303,7 @@ const AssistantChatInner = forwardRef<
       void (async () => {
         const hasSession = await checkAuthSession();
         if (hasSession) return;
+        if (!shouldCaptureStuckAuthCard) return;
         captureError(new Error("agent-chat:auth_error_card_stuck"), {
           tags: {
             context: "agent-native-chat",
@@ -3211,7 +3242,7 @@ const AssistantChatInner = forwardRef<
     <CheckpointContext.Provider value={checkpointCtx}>
       <MessageActionsContext.Provider value={messageActionsCtx}>
         <ApprovalContext.Provider value={approvalCtx}>
-          <ChatRunningContext.Provider value={isRunning}>
+          <ChatRunningContext.Provider value={showRunningInUI}>
             <TextStreamingContext.Provider value={textStreaming}>
               <div
                 data-agent-empty-state={

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

@@ -807,6 +807,21 @@ function lastActivityTool(
   return undefined;
 }
 
+function formatActivityTrail(
+  trail: readonly AgentActivityTrailEntry[],
+): string | undefined {
+  const items = trail
+    .slice(-8)
+    .map((entry) => {
+      const label = entry.label.replace(/\s+/g, " ").trim();
+      const tool = entry.tool?.replace(/\s+/g, " ").trim();
+      if (label && tool && label !== tool) return `${label} (${tool})`;
+      return label || tool || "";
+    })
+    .filter(Boolean);
+  return items.length > 0 ? items.join(" > ") : undefined;
+}
+
 function lastUnresolvedToolActivity(
   content: ContentPart[],
 ): string | undefined {
@@ -928,9 +943,9 @@ function incrementalActionGuidance(tool: string): string | undefined {
       return "create a compact working v1 with `create-extension`, then use focused `update-extension` edits for refinements";
     case "generate-design":
     case "update-design":
-      return "persist a minimal first version (fewer files) with `generate-design`, then refine individual files with `edit-design` search/replace instead of resending everything";
+      return 'if an existing design file or snapshot is already in history, especially after a Design variant pick, stop retrying `generate-design`: call `get-design-snapshot` for the selected file, then call `edit-design` once on that same `fileId` (`mode: "replace-file"` for a compact full-file replacement, or search/replace for smaller edits). Use `generate-design` only for a brand-new compact first file when no target file exists yet';
     case "present-design-variants":
-      return "call `present-design-variants` with concise labels, descriptions, accent colors, and feature bullets; omit large `content` HTML when needed so the action can render compact representative screens, then refine the chosen direction with `generate-design` or `edit-design`";
+      return 'call `present-design-variants` with concise labels, descriptions, accent colors, and feature bullets; omit large `content` HTML when needed so the action can render compact representative screens. After the user picks a direction, delete unchosen screens, snapshot the selected `fileId`, and refine that same file with `edit-design` (`mode: "replace-file"` for placeholder expansion). Do not call `generate-design` after the variant pick';
     case "create-visual-plan":
     case "create-ui-plan":
     case "create-plan-design":
@@ -1439,6 +1454,7 @@ export function createAgentChatAdapter(
       let visibleContinuationPrefix: ContentPart[] = [];
       let lastAutoContinueReason: string | null = null;
       let lastRecoverableRunError: AgentAutoContinueErrorInfo | null = null;
+      let lastActivityTrail: AgentActivityTrailEntry[] = [];
       const attemptedRunIds: string[] = [];
       let authRecoveryAttempted = false;
       let continuationToolCallCounter = 0;
@@ -1468,6 +1484,9 @@ export function createAgentChatAdapter(
           lastPreparingToolName
             ? `last_preparing_tool: ${lastPreparingToolName}`
             : "",
+          formatActivityTrail(lastActivityTrail)
+            ? `activity_trail: ${formatActivityTrail(lastActivityTrail)}`
+            : "",
           `total_transient_continuations: ${totalTransientContinuationAttempts}`,
           attemptedRunIds.length > 0
             ? `attempted_runs: ${attemptedRunIds.join(", ")}`
@@ -1559,6 +1578,7 @@ export function createAgentChatAdapter(
             lastSeq,
             contentParts: content.length,
             attemptedRunIds: [...attemptedRunIds],
+            activityTrail: [...lastActivityTrail],
             startupRecoveryAttempts,
             staleRunContinuationAttempts,
             stalledTransientContinuationAttempts,
@@ -1867,6 +1887,7 @@ export function createAgentChatAdapter(
           completedToolName?: string;
         } => {
           lastAutoContinueReason = signal.reason;
+          lastActivityTrail = [...signal.activityTrail];
           if (signal.errorInfo) {
             lastRecoverableRunError = signal.errorInfo;
           }