@agent-native/core 0.84.5 → 0.84.7

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: 4906
+- template files: 4907

package/corpus/core/CHANGELOG.md

@@ -1,5 +1,17 @@
 # @agent-native/core
 
+## 0.84.7
+
+### Patch Changes
+
+- ab1e410: Stop repeated agent-chat action-preparation loops with a clear terminal warning, and let Design agents present compact variant directions without streaming large HTML payloads.
+
+## 0.84.6
+
+### Patch Changes
+
+- 126ccac: Claim durable background agent-chat runs before expensive worker setup so hosted apps stay on the 15-minute background-function path instead of falling back to 40-second inline chunks.
+
 ## 0.84.5
 
 ### Patch Changes

package/corpus/core/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@agent-native/core",
-  "version": "0.84.5",
+  "version": "0.84.7",
   "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

@@ -4025,6 +4025,58 @@ export function shouldChainBackgroundContinuation(opts: {
   );
 }
 
+export async function claimBackgroundWorkerRunEarly(opts: {
+  runId: string;
+  threadId?: string | null;
+  markerTurnId?: string | null;
+  requestTurnId?: string | null;
+  continuationCount: number;
+  runsInBackgroundFunction: boolean;
+  deps?: {
+    recordRunDiagnostic?: typeof recordRunDiagnostic;
+    insertRun?: typeof insertRun;
+    claimBackgroundRun?: typeof claimBackgroundRun;
+    updateRunHeartbeat?: typeof updateRunHeartbeat;
+  };
+}): Promise<{ claimed: true } | { claimed: false; skipped: string }> {
+  const record = opts.deps?.recordRunDiagnostic ?? recordRunDiagnostic;
+  const insert = opts.deps?.insertRun ?? insertRun;
+  const claim = opts.deps?.claimBackgroundRun ?? claimBackgroundRun;
+  const heartbeat = opts.deps?.updateRunHeartbeat ?? updateRunHeartbeat;
+  const threadId =
+    typeof opts.threadId === "string" && opts.threadId.trim()
+      ? opts.threadId.trim()
+      : opts.runId;
+  const turnId =
+    typeof opts.markerTurnId === "string" && opts.markerTurnId.trim()
+      ? opts.markerTurnId.trim()
+      : typeof opts.requestTurnId === "string" && opts.requestTurnId.trim()
+        ? opts.requestTurnId.trim()
+        : opts.runId;
+
+  await record(
+    opts.runId,
+    RUN_DIAG_STAGE.workerEntered,
+    `runsInBackgroundFunction=${opts.runsInBackgroundFunction} continuationCount=${opts.continuationCount}`,
+  ).catch(() => {});
+
+  if (opts.continuationCount > 0) {
+    await insert(opts.runId, threadId, turnId, {
+      dispatchMode: "background",
+    }).catch(() => {});
+  }
+
+  const won = await claim(opts.runId);
+  if (!won) {
+    await record(opts.runId, RUN_DIAG_STAGE.workerClaimLost).catch(() => {});
+    return { claimed: false, skipped: "already-claimed" };
+  }
+
+  await record(opts.runId, RUN_DIAG_STAGE.workerClaimed).catch(() => {});
+  await heartbeat(opts.runId).catch(() => {});
+  return { claimed: true };
+}
+
 function progressStepFromAgentChatEvent(event: AgentChatEvent): string | null {
   switch (event.type) {
     case "activity":
@@ -4175,6 +4227,24 @@ export function createProductionAgentHandler(
       Number.isFinite(backgroundRunMarker.continuationCount)
         ? Math.max(0, Math.floor(backgroundRunMarker.continuationCount))
         : 0;
+    let backgroundRunClaimedEarly = false;
+    if (isBackgroundWorker && bgRunId) {
+      const earlyClaim = await claimBackgroundWorkerRunEarly({
+        runId: bgRunId,
+        threadId,
+        markerTurnId:
+          typeof backgroundRunMarker?.turnId === "string"
+            ? backgroundRunMarker.turnId
+            : null,
+        requestTurnId,
+        continuationCount: backgroundContinuationCount,
+        runsInBackgroundFunction,
+      });
+      if (!earlyClaim.claimed) {
+        return { ok: true, skipped: earlyClaim.skipped };
+      }
+      backgroundRunClaimedEarly = true;
+    }
     // The foreground POST decides whether to dispatch into a background
     // function. The background worker itself never re-dispatches.
     const dispatchToBackground =
@@ -5254,48 +5324,37 @@ export function createProductionAgentHandler(
           }
         : undefined;
 
-    // Background worker: claim the pre-inserted run idempotently before
-    // executing. A duplicate Netlify delivery loses the claim and no-ops here,
-    // so the run can never be double-executed. Bump the heartbeat immediately
-    // on entry so a slow cold-start doesn't leave the row looking stale to the
-    // reaper before startRun's 1.5s heartbeat timer takes over.
+    // Background worker: the run was claimed immediately after the authenticated
+    // `_process-run` body was parsed, before owner/model/prompt/tool setup. That
+    // early claim is what lets the foreground subscribe to the real background
+    // worker instead of racing slow setup and falling back to the 40s inline
+    // path. This late block is a defensive fallback for older/custom callers
+    // that somehow reach here without the early claim.
     if (isBackgroundWorker) {
-      // DIAGNOSTIC: the re-entered handler recognized itself as the background
-      // worker. Record the runtime regime too — `isInBackgroundFunctionRuntime()`
-      // reads a globalThis marker set by the bg-fn entry, which may NOT be set in
-      // this isolate; recording the ACTUAL resolved value reveals whether the
-      // worker is on the 13-min `-background` budget or the 40s clamp. This is
-      // the proof the worker reached its own code (vs. dying at auth before it).
-      await recordRunDiagnostic(
-        runId,
-        RUN_DIAG_STAGE.workerEntered,
-        `runsInBackgroundFunction=${runsInBackgroundFunction} continuationCount=${backgroundContinuationCount}`,
-      ).catch(() => {});
-      // A chained continuation chunk's runId was minted by the prior chunk and
-      // never inserted, so insert its background row now (idempotently — a
-      // duplicate Netlify delivery that already inserted it just PK-collides and
-      // the claim below dedups). The first chunk's row was inserted by the
-      // foreground, so skip the insert there.
-      if (isChainedBackgroundContinuation) {
-        await insertRun(runId, effectiveThreadId, effectiveTurnId, {
-          dispatchMode: "background",
-        }).catch(() => {});
-      }
-      const won = await claimBackgroundRun(runId);
-      if (!won) {
-        // Already claimed by an earlier delivery — return a benign ack so
-        // Netlify doesn't retry a successful handoff.
-        await recordRunDiagnostic(runId, RUN_DIAG_STAGE.workerClaimLost).catch(
+      if (!backgroundRunClaimedEarly) {
+        await recordRunDiagnostic(
+          runId,
+          RUN_DIAG_STAGE.workerEntered,
+          `runsInBackgroundFunction=${runsInBackgroundFunction} continuationCount=${backgroundContinuationCount}`,
+        ).catch(() => {});
+        if (isChainedBackgroundContinuation) {
+          await insertRun(runId, effectiveThreadId, effectiveTurnId, {
+            dispatchMode: "background",
+          }).catch(() => {});
+        }
+        const won = await claimBackgroundRun(runId);
+        if (!won) {
+          await recordRunDiagnostic(
+            runId,
+            RUN_DIAG_STAGE.workerClaimLost,
+          ).catch(() => {});
+          return { ok: true, skipped: "already-claimed" };
+        }
+        await recordRunDiagnostic(runId, RUN_DIAG_STAGE.workerClaimed).catch(
           () => {},
         );
-        return { ok: true, skipped: "already-claimed" };
+        await updateRunHeartbeat(runId).catch(() => {});
       }
-      // DIAGNOSTIC: this worker won the claim and now OWNS the run. If a run
-      // ever stalls at this stage it means the loop below failed to start.
-      await recordRunDiagnostic(runId, RUN_DIAG_STAGE.workerClaimed).catch(
-        () => {},
-      );
-      await updateRunHeartbeat(runId).catch(() => {});
     }
 
     // DIAGNOSTIC-ONLY: build the pre-startRun setup-timing breakdown now (so the

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

@@ -64,6 +64,23 @@ export const UNCLAIMED_BACKGROUND_RUN_ERROR_EVENT = {
     "A background-dispatched run was acknowledged (HTTP 202) but its worker never claimed the run, so no progress was produced. The run was reaped early (it had no live worker to protect) so the turn can be retried.",
 } as const;
 
+/**
+ * Terminal error for a background worker that DID claim the run, then failed
+ * during route/handler setup before `startRun` could emit its own error event.
+ * Claimed runs are no longer eligible for foreground inline recovery, so the
+ * route boundary must fail them loudly instead of leaving subscribers to wait
+ * for stale-run recovery.
+ */
+export const CLAIMED_BACKGROUND_WORKER_FAILED_ERROR_EVENT = {
+  type: "error",
+  error:
+    "The background agent worker stopped before it could start the turn. You can retry from the preserved chat context.",
+  errorCode: "background_worker_failed",
+  recoverable: true,
+  details:
+    "The durable background worker claimed the run but threw during setup before it could emit agent events.",
+} as const;
+
 /**
  * Grace period before a never-claimed background run (dispatch_mode still
  * 'background', no worker claim) is treated as a dead handoff and reaped.

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

@@ -93,6 +93,12 @@ const MAX_EMPTY_TRANSIENT_CONTINUATIONS = 3;
 // round re-sending any large pasted payload) before bailing. Catching the
 // repeat ends it in a few rounds with a clear, actionable message instead.
 const MAX_REPEATED_TRANSIENT_CONTINUATIONS = 3;
+// How many consecutive continuations that only reach the SAME "preparing
+// action" activity card we tolerate before giving up. This catches runs that
+// keep timing out while assembling a large tool payload: they are not empty,
+// and the narration may vary enough to bypass the text-repeat guard, but the
+// real tool never starts.
+const MAX_REPEATED_ACTION_PREPARATION_CONTINUATIONS = 3;
 const RETRY_BASE_DELAY_MS = 500;
 const RETRY_MAX_DELAY_MS = 8_000;
 const MAX_HISTORY_ATTACHMENT_CHARS = 60_000;
@@ -782,6 +788,22 @@ function lastActivityTool(
   return undefined;
 }
 
+function lastUnresolvedToolActivity(
+  content: ContentPart[],
+): string | undefined {
+  for (let i = content.length - 1; i >= 0; i--) {
+    const part = content[i];
+    if (
+      part.type === "tool-call" &&
+      part.activity === true &&
+      part.result === undefined
+    ) {
+      return part.toolName;
+    }
+  }
+  return undefined;
+}
+
 function snapshotContent(content: ContentPart[]): ContentPart[] {
   return content.map((part) =>
     part.type === "text" ? { ...part } : { ...part, args: { ...part.args } },
@@ -889,7 +911,7 @@ function incrementalActionGuidance(tool: string): string | undefined {
     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";
     case "present-design-variants":
-      return "save compact but complete variant screens with `present-design-variants` first, keeping each HTML direction focused enough to finish, 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, then refine the chosen direction with `generate-design` or `edit-design`";
     case "create-visual-plan":
     case "create-ui-plan":
     case "create-plan-design":
@@ -1390,6 +1412,9 @@ export function createAgentChatAdapter(
       let repeatedInFlightToolCount = 0;
       let recoveryGaveUpOnInFlightTool = false;
       const MAX_REPEATED_INFLIGHT_TOOL_STALLS = 3;
+      let lastPreparingToolName: string | undefined;
+      let repeatedActionPreparationCount = 0;
+      let recoveryGaveUpOnActionPreparation = false;
       const continuationHistoryFragments: string[] = [];
       const structuredContinuationFragments: AgentChatStructuredMessage[] = [];
       let visibleContinuationPrefix: ContentPart[] = [];
@@ -1420,6 +1445,10 @@ export function createAgentChatAdapter(
           lastInFlightToolName
             ? `last_inflight_tool: ${lastInFlightToolName}`
             : "",
+          `repeated_action_preparation_stalls: ${repeatedActionPreparationCount}`,
+          lastPreparingToolName
+            ? `last_preparing_tool: ${lastPreparingToolName}`
+            : "",
           `total_transient_continuations: ${totalTransientContinuationAttempts}`,
           attemptedRunIds.length > 0
             ? `attempted_runs: ${attemptedRunIds.join(", ")}`
@@ -1436,6 +1465,12 @@ export function createAgentChatAdapter(
         if (recoveryGaveUpOnRepetition) {
           return "The agent got stuck repeating the same response without finishing, so I stopped the automatic retries. This often happens when it tries to re-type a large pasted file into one action — starting a new chat, or asking for a smaller first step, usually gets it unstuck.";
         }
+        if (recoveryGaveUpOnActionPreparation) {
+          const tool = lastPreparingToolName
+            ? ` the ${humanizeActionName(lastPreparingToolName)} action`
+            : " the same action";
+          return `The agent got stuck preparing${tool} input and never started the tool, so I stopped the automatic retries. Try a smaller first step or a more compact version of the request.`;
+        }
         if (
           content.length === 0 &&
           (reason === "run_timeout" ||
@@ -1512,6 +1547,8 @@ export function createAgentChatAdapter(
             repeatedTransientContinuationAttempts,
             repeatedInFlightToolCount,
             lastInFlightToolName,
+            repeatedActionPreparationCount,
+            lastPreparingToolName,
             totalTransientContinuationAttempts,
             ...extra,
           },
@@ -1529,6 +1566,8 @@ export function createAgentChatAdapter(
               repeatedTransientContinuationAttempts,
               repeatedInFlightToolCount,
               lastInFlightToolName,
+              repeatedActionPreparationCount,
+              lastPreparingToolName,
               totalTransientContinuationAttempts,
             },
           },
@@ -1832,8 +1871,13 @@ export function createAgentChatAdapter(
           // for the stalled/empty caps.
           const madeProgress = madeContentProgress || hasInFlightTool;
           const madeDurableToolProgress = visibleContent.some(
-            (part) => part.type === "tool-call" && part.result !== undefined,
+            (part) =>
+              part.type === "tool-call" &&
+              part.activity !== true &&
+              part.result !== undefined,
           );
+          const currentPreparingToolName =
+            lastUnresolvedToolActivity(visibleContent);
           // In-flight tool stall guard. When the same write tool is stuck
           // in-flight because the connection keeps dropping (stream_ended),
           // hasInFlightTool=true keeps madeProgress=true and completely
@@ -1877,6 +1921,27 @@ export function createAgentChatAdapter(
             repeatedInFlightToolCount = 0;
           }
 
+          const isRepeatedActionPreparationCandidate =
+            signal.reason !== "loop_limit" &&
+            currentPreparingToolName !== undefined &&
+            !hasInFlightTool &&
+            !madeDurableToolProgress;
+          if (isRepeatedActionPreparationCandidate) {
+            if (currentPreparingToolName === lastPreparingToolName) {
+              repeatedActionPreparationCount += 1;
+            } else {
+              repeatedActionPreparationCount = 0;
+              lastPreparingToolName = currentPreparingToolName;
+            }
+          } else if (
+            !currentPreparingToolName ||
+            hasInFlightTool ||
+            madeDurableToolProgress
+          ) {
+            repeatedActionPreparationCount = 0;
+            lastPreparingToolName = undefined;
+          }
+
           // Degenerate repetition guard. When the model gets stuck re-streaming
           // the SAME narration every continuation without ever starting or
           // finishing a tool, each round is "new" text — so madeProgress stays
@@ -1925,6 +1990,13 @@ export function createAgentChatAdapter(
               recoveryGaveUpOnInFlightTool = true;
               return { ok: false, resetVisibleContent: false };
             }
+            if (
+              repeatedActionPreparationCount >
+              MAX_REPEATED_ACTION_PREPARATION_CONTINUATIONS
+            ) {
+              recoveryGaveUpOnActionPreparation = true;
+              return { ok: false, resetVisibleContent: false };
+            }
             // Bail fast on a non-advancing repetition loop, well before the
             // stalled/empty/total budgets would (each round otherwise re-sends
             // the whole pasted payload). Tracked separately so it never trips

package/corpus/core/src/server/agent-chat-plugin.ts

@@ -62,7 +62,15 @@ import {
 import { runAgentLoopDirectWithSoftTimeout } from "../agent/run-loop-with-resume.js";
 import { callerOwnsRun, callerOwnsThread } from "../agent/run-ownership.js";
 import type { AgentRunSummary } from "../agent/run-store.js";
-import { readBackgroundRunClaim } from "../agent/run-store.js";
+import {
+  CLAIMED_BACKGROUND_WORKER_FAILED_ERROR_EVENT,
+  ensureTerminalRunEvent,
+  readBackgroundRunClaim,
+  recordRunDiagnostic,
+  RUN_DIAG_STAGE,
+  setRunError,
+  updateRunStatusIfRunning,
+} from "../agent/run-store.js";
 import { buildRuntimeContextPrompt } from "../agent/runtime-context.js";
 import {
   buildAssistantMessage,
@@ -3864,6 +3872,50 @@ export function shouldDisableRecurringJobsRuntime(
   return isLocalRuntime;
 }
 
+type AgentChatProcessRunFailureDeps = {
+  readBackgroundRunClaim?: typeof readBackgroundRunClaim;
+  recordRunDiagnostic?: typeof recordRunDiagnostic;
+  setRunError?: typeof setRunError;
+  updateRunStatusIfRunning?: typeof updateRunStatusIfRunning;
+  ensureTerminalRunEvent?: typeof ensureTerminalRunEvent;
+};
+
+export async function finalizeClaimedAgentChatProcessRunFailure(
+  runId: string,
+  err: unknown,
+  deps: AgentChatProcessRunFailureDeps = {},
+): Promise<boolean> {
+  const readClaim = deps.readBackgroundRunClaim ?? readBackgroundRunClaim;
+  const record = deps.recordRunDiagnostic ?? recordRunDiagnostic;
+  const setError = deps.setRunError ?? setRunError;
+  const updateStatus =
+    deps.updateRunStatusIfRunning ?? updateRunStatusIfRunning;
+  const ensureTerminal = deps.ensureTerminalRunEvent ?? ensureTerminalRunEvent;
+  const message = err instanceof Error ? err.message : String(err);
+
+  await record(runId, RUN_DIAG_STAGE.routeThrew, message).catch(() => {});
+
+  const claim = await readClaim(runId).catch(() => null);
+  if (
+    claim?.status !== "running" ||
+    claim.dispatchMode !== "background-processing"
+  ) {
+    return false;
+  }
+
+  await setError(
+    runId,
+    CLAIMED_BACKGROUND_WORKER_FAILED_ERROR_EVENT.errorCode,
+    `${CLAIMED_BACKGROUND_WORKER_FAILED_ERROR_EVENT.details} setupError=${message}`,
+  ).catch(() => {});
+  await updateStatus(runId, "errored").catch(() => {});
+  await ensureTerminal(
+    runId,
+    CLAIMED_BACKGROUND_WORKER_FAILED_ERROR_EVENT,
+  ).catch(() => {});
+  return true;
+}
+
 export function createAgentChatPlugin(
   options?: AgentChatPluginOptions,
 ): NitroPluginDef {
@@ -8030,17 +8082,10 @@ Non-code requests are still fine on this surface: read data, navigate the UI, su
                 runId: prepared.runId,
               },
             });
-            // DIAGNOSTIC: the worker invocation threw at the route boundary —
-            // record the message so the failure cause is readable client-side.
-            if (diag) {
-              await diag
-                .record(
-                  prepared.runId,
-                  diag.stages.routeThrew,
-                  err instanceof Error ? err.message : String(err),
-                )
-                .catch(() => {});
-            }
+            await finalizeClaimedAgentChatProcessRunFailure(
+              prepared.runId,
+              err,
+            );
             setResponseStatus(event, 500);
             return { error: "process-run failed" };
           }

package/corpus/templates/design/AGENTS.md

@@ -133,9 +133,11 @@ patterns live in `.agents/skills/`.
   write-back remains a localhost/fusion follow-up capability.
 - For multi-variant work, use `present-design-variants` so every candidate is
   saved as a normal overview-board screen and the user gets one inline chat
-  button per screen name. Keep each variant compact: one representative screen
-  or directional snapshot, not a full app per variant. After the user picks,
-  delete the unchosen variant screens before continuing from the kept screen.
+  button per screen name. Keep each variant compact: prefer concise labels,
+  descriptions, accent colors, and feature bullets, and omit full HTML when it
+  would make the tool input too large. The action can render representative
+  screens from direction data. After the user picks, delete the unchosen
+  variant screens before continuing from the kept screen.
 - Use framework sharing actions for design and design-system visibility/grants.
 - `/visual-edit` is a public entry route and public `/design/:id` links may
   render read-only public designs without a session. Do not open anonymous write
@@ -218,10 +220,10 @@ patterns live in `.agents/skills/`.
   register that manifest with `connect-localhost`, call `add-localhost-screens`,
   and open the editor in overview mode.
 - For human-in-the-loop UI exploration, create a design shell, call
-  `present-design-variants` with 2-5 compact, complete HTML directions (three
-  by default), wait for the user to pick one in chat, delete the other
-  generated variant screens with `delete-file`, then use `get-design-snapshot`
-  and `generate-design` or `edit-design` for follow-up refinements.
+  `present-design-variants` with 2-5 concise directions (three by default),
+  wait for the user to pick one in chat, delete the other generated variant
+  screens with `delete-file`, then use `get-design-snapshot` and
+  `generate-design` or `edit-design` for follow-up refinements.
 - If inline chat choice buttons are unavailable, the user can tell you the
   preferred screen name. Do not show a separate variant picker or ask them to
   paste a copyable handoff summary.