@agent-native/core 0.84.39 → 0.84.41

package/corpus/README.md

@@ -27,5 +27,5 @@ rg -n "defineAction|useActionQuery" node_modules/@agent-native/core/corpus
 
 ## Generated Counts
 
-- core files: 2043
+- core files: 2044
 - template files: 4998

package/corpus/core/CHANGELOG.md

@@ -1,5 +1,17 @@
 # @agent-native/core
 
+## 0.84.41
+
+### Patch Changes
+
+- a8548bc: Continue durable background runs when a chunk completes tool calls without final assistant text.
+
+## 0.84.40
+
+### Patch Changes
+
+- 96feefd: Checkpoint agent runs that stall while preparing an action input without streaming bytes.
+
 ## 0.84.39
 
 ### Patch Changes

package/corpus/core/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@agent-native/core",
-  "version": "0.84.39",
+  "version": "0.84.41",
   "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/action-continuation-guidance.ts

@@ -0,0 +1,38 @@
+// Concrete "ship a compact first version, then refine incrementally" guidance
+// keyed by the large-payload action the model was cut off while preparing.
+// A run cut off before the tool starts tends to reassemble the same oversized
+// payload on every continuation; pointing the model at the incremental path is
+// what breaks that loop.
+export function incrementalActionGuidance(tool: string): string | undefined {
+  switch (tool) {
+    case "create-extension":
+    case "update-extension":
+      return "create a compact working v1 with `create-extension`, then use focused `update-extension` edits for refinements";
+    case "generate-design":
+    case "update-design":
+      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 "edit-design":
+      return "retry with a smaller `edit-design` payload: prefer a handful of exact search/replace edits against the already-snapshotted file, and avoid `replacementContent` for a huge full-file rewrite. If a selected variant needs expansion, upgrade the highest-value visible sections first, save once, and summarize any remaining refinements";
+    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. 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":
+    case "create-prototype-plan":
+      return "create the plan with its core sections or first screen, then expand it with `update-visual-plan`/`patch-visual-plan-source` follow-up edits";
+    case "update-visual-plan":
+    case "patch-visual-plan-source":
+      return "apply smaller, targeted `patch-visual-plan-source` edits rather than rewriting the whole plan in one call";
+    case "update-dashboard":
+      return "save a small dashboard first, then add panels one at a time with `update-dashboard` incremental `ops` edits instead of authoring the whole config in one call";
+    default:
+      return undefined;
+  }
+}
+
+export function actionPreparationContinuationNote(tool: string): string {
+  const guidance = incrementalActionGuidance(tool);
+  return guidance
+    ? `\n\nThe previous run was cut off while preparing the \`${tool}\` action input before the action could finish. Avoid spending another whole run assembling one large tool payload - ${guidance}.`
+    : `\n\nThe previous run was cut off while preparing the \`${tool}\` action input before the action could finish. Avoid re-assembling one large tool payload: produce a compact first result you can finish in a single run, then refine it with smaller follow-up edits.`;
+}

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

@@ -44,6 +44,7 @@ import {
   normalizeReasoningEffortForModel,
   type ReasoningEffort,
 } from "../shared/reasoning-effort.js";
+import { actionPreparationContinuationNote } from "./action-continuation-guidance.js";
 import { applyContextDirectives } from "./context-xray/apply-directives.js";
 import { loadContextDirectives } from "./context-xray/directives-store.js";
 import {
@@ -984,6 +985,7 @@ function maxRetriesForError(err: unknown): number {
   return MAX_RETRIES;
 }
 const TOOL_INPUT_ACTIVITY_INTERVAL_MS = 1500;
+const ACTION_PREPARATION_NO_PROGRESS_TIMEOUT_MS = 90_000;
 const MAX_TEXT_ATTACHMENT_CHARS = 60_000;
 const MAX_SELECTION_CONTEXT_CHARS = 8_000;
 const MAX_RESOURCE_INVENTORY_ITEMS = 40;
@@ -1693,11 +1695,13 @@ export type AgentLoopContinuationReason =
   | "max_tokens"
   | "stream_ended"
   | "gateway_timeout"
-  | "network_interrupted";
+  | "network_interrupted"
+  | "no_progress";
 
 export function appendAgentLoopContinuation(
   messages: EngineMessage[],
   reason: AgentLoopContinuationReason,
+  options: { actionPreparationTool?: string } = {},
 ) {
   const note =
     reason === "loop_limit"
@@ -1710,18 +1714,37 @@ export function appendAgentLoopContinuation(
             ? "The previous LLM call hit an upstream gateway timeout before the response finished streaming."
             : reason === "network_interrupted"
               ? "The previous LLM call was cut off by a transport-level interruption (socket dropped, connection reset, or stream closed unexpectedly)."
-              : "The previous run reached an internal execution budget.";
+              : reason === "no_progress"
+                ? "The previous run stopped producing progress events while the connection stayed open."
+                : "The previous run reached an internal execution budget.";
+  const actionInputNote = options.actionPreparationTool
+    ? actionPreparationContinuationNote(options.actionPreparationTool)
+    : "";
   messages.push({
     role: "user",
     content: [
       {
         type: "text",
-        text: `${AGENT_INTERNAL_CONTINUE_PROMPT}\n\nInternal note: ${note}`,
+        text: `${AGENT_INTERNAL_CONTINUE_PROMPT}\n\nInternal note: ${note}${actionInputNote}`,
       },
     ],
   });
 }
 
+function isAgentLoopContinuationReason(
+  reason: unknown,
+): reason is AgentLoopContinuationReason {
+  return (
+    reason === "run_timeout" ||
+    reason === "loop_limit" ||
+    reason === "max_tokens" ||
+    reason === "stream_ended" ||
+    reason === "gateway_timeout" ||
+    reason === "network_interrupted" ||
+    reason === "no_progress"
+  );
+}
+
 /**
  * True when an error thrown by `runAgentLoop` is a recoverable transport- or
  * gateway-level interruption that the agent can resume from rather than a
@@ -2792,6 +2815,15 @@ export async function runAgentLoop(opts: {
         const toolInputNames = new Map<string, string>();
         const toolInputBytes = new Map<string, number>();
         let lastToolInputActivityAt = 0;
+        type ActiveToolInputPreparation = {
+          id: string;
+          toolName?: string;
+          startedAt: number;
+          lastProgressAt: number;
+          bytes: number;
+        };
+        const activeToolInputs = new Map<string, ActiveToolInputPreparation>();
+        let endedForActionPreparationNoProgress = false;
         const sendToolInputActivity = (
           toolName: string | undefined,
           toolInputId?: string,
@@ -2814,8 +2846,65 @@ export async function runAgentLoop(opts: {
             ...(typeof progressBytes === "number" ? { progressBytes } : {}),
           });
         };
+        const resetActiveToolInput = (
+          toolName: string | undefined,
+          toolInputId?: string,
+        ) => {
+          if (toolInputId) {
+            activeToolInputs.delete(toolInputId);
+            return;
+          }
+          if (toolName) {
+            for (const [id, active] of activeToolInputs) {
+              if (active.toolName === toolName) {
+                activeToolInputs.delete(id);
+              }
+            }
+          }
+        };
+        const hasActionPreparationStalled = () => {
+          if (activeToolInputs.size === 0) return false;
+          const now = Date.now();
+          for (const active of activeToolInputs.values()) {
+            if (
+              now - active.lastProgressAt >=
+              ACTION_PREPARATION_NO_PROGRESS_TIMEOUT_MS
+            ) {
+              return true;
+            }
+          }
+          return false;
+        };
+        const trackActiveToolInput = (
+          key: string,
+          toolName: string | undefined,
+          bytes: number,
+        ) => {
+          const now = Date.now();
+          const previous = activeToolInputs.get(key);
+          activeToolInputs.set(key, {
+            id: key,
+            ...((toolName ?? previous?.toolName)
+              ? { toolName: toolName ?? previous?.toolName }
+              : {}),
+            startedAt: previous?.startedAt ?? now,
+            lastProgressAt: now,
+            bytes,
+          });
+        };
+        const clearActiveToolInputs = () => {
+          activeToolInputs.clear();
+        };
 
         for await (const event of eventStream) {
+          if (hasActionPreparationStalled()) {
+            send({
+              type: "auto_continue",
+              reason: "no_progress",
+            });
+            endedForActionPreparationNoProgress = true;
+            break;
+          }
           // In-loop processor seam (stream hook). Each chunk is offered to every
           // processor's `processOutputStream` before the loop handles it. A
           // processor `abort()` throws a TripWire; catch it locally so it is not
@@ -2845,6 +2934,7 @@ export async function runAgentLoop(opts: {
             if (key && event.name) {
               toolInputNames.set(key, event.name);
               toolInputBytes.set(key, 0);
+              trackActiveToolInput(key, event.name, 0);
             }
             sendToolInputActivity(event.name, key, undefined, true);
           } else if (event.type === "tool-input-delta") {
@@ -2859,19 +2949,25 @@ export async function runAgentLoop(opts: {
                 previous +
                 new TextEncoder().encode(event.text ?? "").byteLength;
               toolInputBytes.set(key, progressBytes);
+              if (progressBytes > previous) {
+                trackActiveToolInput(key, toolName, progressBytes);
+              }
             }
             sendToolInputActivity(toolName, key, progressBytes);
           } else if (event.type === "gateway-heartbeat") {
             send({ type: "stream_keepalive" });
           } else if (event.type === "tool-call") {
             // The authoritative tool-call blocks arrive in assistant-content.
+            resetActiveToolInput(event.name, event.id);
           } else if (event.type === "tool-call-error") {
+            resetActiveToolInput(event.name, event.id);
             toolCallErrors.set(event.id, {
               name: event.name,
               input: event.input,
               error: event.error,
             });
           } else if (event.type === "assistant-content") {
+            clearActiveToolInputs();
             assistantContent = event.parts;
           } else if (event.type === "usage") {
             usage.inputTokens += event.inputTokens;
@@ -2889,6 +2985,18 @@ export async function runAgentLoop(opts: {
               });
             }
           }
+          if (hasActionPreparationStalled()) {
+            send({
+              type: "auto_continue",
+              reason: "no_progress",
+            });
+            endedForActionPreparationNoProgress = true;
+            break;
+          }
+        }
+
+        if (endedForActionPreparationNoProgress) {
+          return usage;
         }
 
         break;
@@ -4018,6 +4126,189 @@ function endsAtInternalContinuationBoundary(run: ActiveRun): boolean {
   return last.type === "error" && isRecoverableContinuationError(last);
 }
 
+function isPreparingActionActivityEvent(
+  event: AgentChatEvent,
+): event is Extract<AgentChatEvent, { type: "activity" }> {
+  if (event.type !== "activity") return false;
+  const label = event.label.trim().toLowerCase();
+  return label.startsWith("preparing ") && label.includes(" action");
+}
+
+export function lastUnfinishedPreparingActionToolFromEvents(
+  events: readonly AgentChatEvent[],
+): string | undefined {
+  const active = new Map<
+    string,
+    {
+      id?: string;
+      order: number;
+      tool: string;
+    }
+  >();
+  const idlessToolStarts = new Map<string, number>();
+  const removeOldestMatchingActivePreparation = (
+    tool: string,
+    shouldRemove: (value: {
+      id?: string;
+      order: number;
+      tool: string;
+    }) => boolean = () => true,
+  ) => {
+    let oldest:
+      | {
+          key: string;
+          order: number;
+        }
+      | undefined;
+    for (const [key, value] of active) {
+      if (value.tool !== tool || !shouldRemove(value)) continue;
+      if (!oldest || value.order < oldest.order) {
+        oldest = {
+          key,
+          order: value.order,
+        };
+      }
+    }
+    if (oldest) active.delete(oldest.key);
+    return Boolean(oldest);
+  };
+  const removeMatchingActivePreparation = (event: {
+    id?: string;
+    tool?: string;
+    type: "tool_done" | "tool_start";
+  }) => {
+    const id = event.id?.trim();
+    const tool = event.tool?.trim();
+    if (!tool) return;
+    if (id) {
+      if (!active.delete(`id:${id}`)) {
+        removeOldestMatchingActivePreparation(tool, (value) => !value.id);
+      }
+      return;
+    }
+
+    if (event.type === "tool_start") {
+      if (removeOldestMatchingActivePreparation(tool)) {
+        idlessToolStarts.set(tool, (idlessToolStarts.get(tool) ?? 0) + 1);
+      }
+      return;
+    }
+
+    const startedCount = idlessToolStarts.get(tool) ?? 0;
+    if (startedCount > 0) {
+      if (startedCount === 1) {
+        idlessToolStarts.delete(tool);
+      } else {
+        idlessToolStarts.set(tool, startedCount - 1);
+      }
+      return;
+    }
+    removeOldestMatchingActivePreparation(tool);
+  };
+  events.forEach((event, order) => {
+    if (isPreparingActionActivityEvent(event)) {
+      const tool = event.tool?.trim();
+      if (tool) {
+        const id = event.id?.trim();
+        const key = id ? `id:${id}` : `tool:${tool}:${order}`;
+        active.set(key, {
+          tool,
+          order,
+          ...(id ? { id } : {}),
+        });
+      }
+      return;
+    }
+    if (event.type === "tool_start" || event.type === "tool_done") {
+      removeMatchingActivePreparation(event);
+      return;
+    }
+    if (event.type === "error" && isRecoverableContinuationError(event)) {
+      return;
+    }
+    if (
+      event.type === "clear" ||
+      event.type === "done" ||
+      event.type === "error" ||
+      event.type === "missing_api_key"
+    ) {
+      active.clear();
+      idlessToolStarts.clear();
+    }
+  });
+  let latest:
+    | {
+        order: number;
+        tool: string;
+      }
+    | undefined;
+  for (const value of active.values()) {
+    if (!latest || value.order > latest.order) {
+      latest = value;
+    }
+  }
+  return latest?.tool;
+}
+
+function endsAfterCompletedToolWithoutAssistantFinal(run: ActiveRun): boolean {
+  let completedToolAfterLastAssistantText = false;
+  for (const { event } of run.events) {
+    if (event.type === "text" && event.text.trim().length > 0) {
+      completedToolAfterLastAssistantText = false;
+      continue;
+    }
+    if (event.type === "tool_done" && event.isError !== true) {
+      completedToolAfterLastAssistantText = true;
+      continue;
+    }
+    if (
+      event.type === "clear" ||
+      event.type === "error" ||
+      event.type === "missing_api_key" ||
+      event.type === "auto_continue" ||
+      event.type === "loop_limit"
+    ) {
+      completedToolAfterLastAssistantText = false;
+    }
+  }
+  return completedToolAfterLastAssistantText;
+}
+
+function lastUnfinishedPreparingActionTool(run: ActiveRun): string | undefined {
+  return lastUnfinishedPreparingActionToolFromEvents(
+    run.events.map(({ event }) => event),
+  );
+}
+
+export function backgroundContinuationReasonForRun(
+  run: ActiveRun,
+): AgentLoopContinuationReason {
+  const last = run.events.at(-1)?.event;
+  if (last?.type === "loop_limit") return "loop_limit";
+  if (
+    last?.type === "auto_continue" &&
+    isAgentLoopContinuationReason(last.reason)
+  ) {
+    return last.reason;
+  }
+  if (last?.type === "error" && isRecoverableContinuationError(last)) {
+    return continuationReasonForResumableError(
+      new EngineError(last.error, { errorCode: last.errorCode }),
+    );
+  }
+  if (endsAfterCompletedToolWithoutAssistantFinal(run)) {
+    return "stream_ended";
+  }
+  return "run_timeout";
+}
+
+function endsAtContinuationBoundary(run: ActiveRun): boolean {
+  return (
+    endsAtInternalContinuationBoundary(run) ||
+    endsAfterCompletedToolWithoutAssistantFinal(run)
+  );
+}
+
 /**
  * Hard cap on server-driven background→background continuation chunks for a
  * single logical turn. A `backgroundFunction` run gets a ~13-min soft timeout,
@@ -4030,9 +4321,8 @@ export const MAX_BACKGROUND_RUN_CONTINUATIONS = 20;
 /**
  * Whether the background worker should self-fire the next server-driven
  * continuation chunk. True only when this is a background worker run that ended
- * at a recoverable soft-timeout boundary (not aborted/stopped) and the chain is
- * still under its budget. Extracted so the decision is unit testable without
- * booting the whole handler.
+ * at a recoverable unfinished boundary (not aborted/stopped) and the chain is
+ * still under its budget. Aborted / user-stopped runs do NOT chain.
  */
 export function shouldChainBackgroundContinuation(opts: {
   isBackgroundWorker: boolean;
@@ -4042,7 +4332,7 @@ export function shouldChainBackgroundContinuation(opts: {
   return (
     opts.isBackgroundWorker &&
     opts.run.status !== "aborted" &&
-    endsAtInternalContinuationBoundary(opts.run) &&
+    endsAtContinuationBoundary(opts.run) &&
     opts.continuationCount < MAX_BACKGROUND_RUN_CONTINUATIONS
   );
 }
@@ -4981,7 +5271,19 @@ export function createProductionAgentHandler(
           ?.threadData;
         const resumed = threadDataToEngineMessages(priorThreadData);
         if (resumed.length > 0) {
-          appendAgentLoopContinuation(resumed, "run_timeout");
+          const actionPreparationTool =
+            typeof backgroundRunMarker?.actionPreparationTool === "string" &&
+            backgroundRunMarker.actionPreparationTool.trim()
+              ? backgroundRunMarker.actionPreparationTool.trim()
+              : undefined;
+          const continuationReason = isAgentLoopContinuationReason(
+            backgroundRunMarker?.continuationReason,
+          )
+            ? backgroundRunMarker.continuationReason
+            : "run_timeout";
+          appendAgentLoopContinuation(resumed, continuationReason, {
+            ...(actionPreparationTool ? { actionPreparationTool } : {}),
+          });
           messages.length = 0;
           messages.push(...resumed);
         }
@@ -5173,13 +5475,19 @@ export function createProductionAgentHandler(
           turnId: effectiveTurnId,
         }
       : null;
+    const willChainBackgroundContinuation = (run: ActiveRun) =>
+      shouldChainBackgroundContinuation({
+        isBackgroundWorker,
+        run,
+        continuationCount: backgroundContinuationCount,
+      });
 
     const completeTrackedProgressRun = async (
       run: ActiveRun,
       completionError?: unknown,
     ) => {
       if (!trackedProgressRunId || !trackedProgressOwner) return;
-      if (!completionError && endsAtInternalContinuationBoundary(run)) {
+      if (!completionError && willChainBackgroundContinuation(run)) {
         return;
       }
       const terminalStatus =
@@ -5275,7 +5583,7 @@ export function createProductionAgentHandler(
               if (
                 isBackgroundWorker &&
                 run.status === "errored" &&
-                !endsAtInternalContinuationBoundary(run)
+                !willChainBackgroundContinuation(run)
               ) {
                 const errEvent = [...run.events]
                   .reverse()
@@ -5304,36 +5612,34 @@ export function createProductionAgentHandler(
               // agent-teams `fireInternalDispatch({ body: { mode: "continue" }})`
               // chain. Bounded by MAX_BACKGROUND_RUN_CONTINUATIONS. Aborted /
               // user-stopped runs do NOT chain.
-              if (
-                shouldChainBackgroundContinuation({
-                  // Self-chain server-side for EVERY durable worker, not only the
-                  // ones inside a `-background` function. Server-driven
-                  // continuation is the whole point of durable background: the run
-                  // must survive the client disconnecting (closed tab), so it
-                  // cannot depend on the browser re-POSTing `auto_continue`. A
-                  // worker on the regular ~60s function — a Netlify routing miss,
-                  // or a non-Netlify host (Vercel/Cloudflare/Render/Fly) that
-                  // never emits a `-background` function — checkpoints at the 40s
-                  // soft-timeout and self-dispatches the next 40s chunk; a worker
-                  // in a real `-background` function chains ~13-min chunks. Only
-                  // the per-chunk BUDGET differs by function type (gated by
-                  // `runsInBackgroundFunction` at the startRun call below); the
-                  // continuation itself must stay server-driven on both. (The
-                  // self-chain is only reachable when the initial dispatch already
-                  // succeeded — a dispatch fast-fail degrades to the inline
-                  // foreground fallback, which is not a worker and rides the
-                  // connected client's auto_continue instead.)
-                  isBackgroundWorker,
-                  run,
-                  continuationCount: backgroundContinuationCount,
-                })
-              ) {
+              // Self-chain server-side for EVERY durable worker, not only the
+              // ones inside a `-background` function. Server-driven
+              // continuation is the whole point of durable background: the run
+              // must survive the client disconnecting (closed tab), so it
+              // cannot depend on the browser re-POSTing `auto_continue`. A
+              // worker on the regular ~60s function — a Netlify routing miss,
+              // or a non-Netlify host (Vercel/Cloudflare/Render/Fly) that
+              // never emits a `-background` function — checkpoints at the 40s
+              // soft-timeout and self-dispatches the next 40s chunk; a worker
+              // in a real `-background` function chains ~13-min chunks. Only
+              // the per-chunk BUDGET differs by function type (gated by
+              // `runsInBackgroundFunction` at the startRun call below); the
+              // continuation itself must stay server-driven on both. (The
+              // self-chain is only reachable when the initial dispatch already
+              // succeeded — a dispatch fast-fail degrades to the inline
+              // foreground fallback, which is not a worker and rides the
+              // connected client's auto_continue instead.)
+              if (willChainBackgroundContinuation(run)) {
                 // Mint the next chunk's runId here and sign the dispatch token
                 // over it, so the `_process-run` route's HMAC check and the
                 // worker's run identity agree. Fresh runId (not this chunk's) so
                 // its seq log starts clean; same turnId folds the assistant
                 // message across chunks.
                 const nextRunId = generateRunId();
+                const actionPreparationTool =
+                  lastUnfinishedPreparingActionTool(run);
+                const continuationReason =
+                  backgroundContinuationReasonForRun(run);
                 const continuationDispatchPath =
                   resolveAgentChatProcessRunDispatchPath();
                 const continuationExpectsNetlifyBackgroundFunction =
@@ -5358,6 +5664,10 @@ export function createProductionAgentHandler(
                         runId: nextRunId,
                         turnId: effectiveTurnId,
                         continuationCount: backgroundContinuationCount + 1,
+                        continuationReason,
+                        ...(actionPreparationTool
+                          ? { actionPreparationTool }
+                          : {}),
                         backgroundFunctionRuntimeExpected:
                           continuationExpectsNetlifyBackgroundFunction,
                       },