@agent-native/core 0.119.2 → 0.119.4

package/dist/server/agent-engine-api-key-route.d.ts

@@ -27,11 +27,11 @@ export declare function resolveAgentEngineApiKeyWriteTarget(event: H3Event, scop
 export declare function createAgentEngineApiKeyHandler(): import("h3").EventHandlerWithFetch<import("h3").EventHandlerRequest, Promise<{
     error: any;
 } | {
-    error?: undefined;
     ok: boolean;
     key: string;
     baseUrlKey?: string;
     scope: AgentEngineApiKeyScope;
+    error?: undefined;
 }>>;
 export {};
 //# sourceMappingURL=agent-engine-api-key-route.d.ts.map

package/dist/server/realtime-token.d.ts

@@ -26,9 +26,9 @@ export declare function createRealtimeTokenHandler(): import("h3").EventHandlerW
     expiresAt?: undefined;
     ttlSeconds?: undefined;
 } | {
-    error?: undefined;
     token: string;
     expiresAt: string;
     ttlSeconds: number;
+    error?: undefined;
 }>>;
 //# sourceMappingURL=realtime-token.d.ts.map

package/dist/server/transcribe-voice.d.ts

@@ -20,7 +20,7 @@ export declare function createTranscribeVoiceHandler(): import("h3").EventHandle
     error: string;
     text?: undefined;
 } | {
-    error?: undefined;
     text: string;
+    error?: undefined;
 }>>;
 //# sourceMappingURL=transcribe-voice.d.ts.map

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@agent-native/core",
-  "version": "0.119.2",
+  "version": "0.119.4",
   "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": {
@@ -362,7 +362,7 @@
     "highlight.js": "^11.11.1",
     "i18next": "26.3.1",
     "isbot": "^5",
-    "jiti": "^2.6.1",
+    "jiti": "^2.7.0",
     "jose": "^6.2.2",
     "linkedom": "0.18.12",
     "lowlight": "^3.3.0",
@@ -370,7 +370,7 @@
     "nanoid": "^5.1.9",
     "next-themes": "^0.4.6",
     "nf3": "0.3.17",
-    "nitro": "3.0.260415-beta",
+    "nitro": "3.0.260610-beta",
     "p-limit": "^7.3.0",
     "prettier": "^3.8.3",
     "react-i18next": "17.0.8",
@@ -390,7 +390,7 @@
     "yjs": "^13.6.31",
     "zod": "^4.3.6",
     "@agent-native/recap-cli": "0.5.1",
-    "@agent-native/toolkit": "^0.10.2"
+    "@agent-native/toolkit": "^0.10.4"
   },
   "devDependencies": {
     "@ai-sdk/anthropic": "^3.0.71",

package/src/agent/production-agent.ts

@@ -7746,18 +7746,6 @@ export function createProductionAgentHandler(
       }).catch(() => {});
     }
 
-    // The background worker must AWAIT the run to completion before returning,
-    // or Netlify freezes/kills the function the instant the handler returns and
-    // the detached run dies mid-turn (mirrors the agent-teams processor, which
-    // wraps startRun in `await new Promise(resolve => startRun(..., onComplete:
-    // () => resolve()))`). We resolve this when the run's onComplete fires.
-    let resolveBackgroundRunDone: (() => void) | null = null;
-    const backgroundRunDone = isBackgroundWorker
-      ? new Promise<void>((resolve) => {
-          resolveBackgroundRunDone = resolve;
-        })
-      : null;
-
     const baseHandleRunComplete =
       options.onRunComplete || trackedProgressRunId
         ? async (run: ActiveRun) => {
@@ -7771,119 +7759,114 @@ export function createProductionAgentHandler(
           }
         : undefined;
 
-    // Wrap so the background worker is unblocked even when there is no app
-    // onRunComplete / tracked-progress callback configured. Also installed for
-    // a foreground run eligible for self-chain — that path needs this same
-    // wrapper to fire the continuation dispatch below.
+    // Install the completion callback for background continuation even when
+    // there is no app onRunComplete / tracked-progress callback configured.
+    // The foreground self-chain path uses the same continuation dispatch.
     const handleRunComplete =
       isBackgroundWorker || foregroundSelfChainEligible || baseHandleRunComplete
         ? async (run: ActiveRun) => {
-            try {
-              // DIAGNOSTIC: a background worker that completed in an errored
-              // state threw inside the loop. Record it (with the last error
-              // event's message when available) so the failure cause is
-              // readable from the client. Skipped for clean completions and for
-              // recoverable soft-timeout boundaries (those chain a continuation
-              // below, they did not "throw").
-              if (
-                isBackgroundWorker &&
-                run.status === "errored" &&
-                !willChainBackgroundContinuation(run)
-              ) {
-                const errEvent = [...run.events]
-                  .reverse()
-                  .find((e) => e.event.type === "error")?.event as
-                  | { error?: string; errorCode?: string }
-                  | undefined;
-                await recordRunDiagnostic(
-                  run.runId,
-                  RUN_DIAG_STAGE.workerThrew,
-                  errEvent?.errorCode || errEvent?.error
-                    ? `${errEvent.errorCode ?? ""} ${errEvent.error ?? ""}`.trim()
-                    : "run ended in errored state",
-                ).catch(() => {});
-              }
-              // Persist the (partial) assistant turn to thread_data FIRST — the
-              // server-driven continuation below rebuilds from it, so it must be
-              // committed before we re-fire.
-              await baseHandleRunComplete?.(run);
-
-              // Server-driven background→background continuation. If this chunk
-              // hit its soft-timeout still unfinished (ended at an auto_continue
-              // / loop_limit / recoverable boundary), chain the next chunk by
-              // re-firing the `_process-run` self-dispatch with mode "continue"
-              // (carried as internalContinuation + an incremented count),
-              // instead of relying on the client to re-POST. Mirrors the
-              // agent-teams `fireInternalDispatch({ body: { mode: "continue" }})`
-              // chain. Bounded by MAX_BACKGROUND_RUN_CONTINUATIONS. Aborted /
-              // user-stopped runs do NOT chain.
-              // 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)) {
-                // Full handoff discipline lives in
-                // `chainServerDrivenContinuation` (exported + unit-tested):
-                // per-turn SQL run budget, successor row PRE-INSERTED before
-                // the dispatch, fully awaited dispatch with retries, loud
-                // diag/terminal marking on failure. Never throws.
-                await chainServerDrivenContinuation({
-                  event,
-                  run,
-                  effectiveThreadId,
-                  effectiveTurnId,
-                  requestBody: body as unknown as Record<string, unknown>,
-                  backgroundContinuationCount,
-                  // Re-evaluate the durable gate rather than keying off
-                  // isBackgroundWorker: a successor chunk of a FOREGROUND
-                  // self-chain re-enters as a worker too, and must keep
-                  // chaining via the regular function — the Netlify
-                  // `-background` function is only emitted into the deploy
-                  // output when the durable flag is on.
-                  //
-                  // `&& !runsInBackgroundFunction`: a worker PROVEN to already
-                  // be executing inside the real `-background` function must
-                  // never dispatch back to that same function's own URL — a
-                  // background function invoking itself by URL from inside a
-                  // live invocation is a documented Netlify platform
-                  // limitation (404), unlike the initial foreground→background
-                  // dispatch or a worker that landed on the regular function
-                  // (a genuinely different function calling the background
-                  // one, which works). This only changes the dispatch TARGET
-                  // for that one proven-in-bg-function case — by this point
-                  // (with the in-process resumable-error resume above) it is
-                  // reached only when the chunk genuinely exhausted its
-                  // budget, so falling back to the regular `_process-run`
-                  // function (40s clamp) here is the correct, safe target.
-                  chainViaDurableBackground:
-                    isAgentChatDurableBackgroundEnabled({
-                      appOptIn: options.durableBackgroundRuns,
-                    }) && !runsInBackgroundFunction,
-                  // Only changes the retry BUDGET, never the dispatch target
-                  // above: a worker proven in a real background function has
-                  // minutes of remaining wall clock and no connected-client
-                  // fallback, so it must not be demoted to the foreground's
-                  // 2-attempt budget just because it was forced onto the
-                  // regular-function dispatch target. See
-                  // `resolveContinuationDispatchBudget`.
-                  workerProvenInBackgroundFunction: runsInBackgroundFunction,
-                });
-              }
-            } finally {
-              resolveBackgroundRunDone?.();
+            // DIAGNOSTIC: a background worker that completed in an errored
+            // state threw inside the loop. Record it (with the last error
+            // event's message when available) so the failure cause is
+            // readable from the client. Skipped for clean completions and for
+            // recoverable soft-timeout boundaries (those chain a continuation
+            // below, they did not "throw").
+            if (
+              isBackgroundWorker &&
+              run.status === "errored" &&
+              !willChainBackgroundContinuation(run)
+            ) {
+              const errEvent = [...run.events]
+                .reverse()
+                .find((e) => e.event.type === "error")?.event as
+                | { error?: string; errorCode?: string }
+                | undefined;
+              await recordRunDiagnostic(
+                run.runId,
+                RUN_DIAG_STAGE.workerThrew,
+                errEvent?.errorCode || errEvent?.error
+                  ? `${errEvent.errorCode ?? ""} ${errEvent.error ?? ""}`.trim()
+                  : "run ended in errored state",
+              ).catch(() => {});
+            }
+            // Persist the (partial) assistant turn to thread_data FIRST — the
+            // server-driven continuation below rebuilds from it, so it must be
+            // committed before we re-fire.
+            await baseHandleRunComplete?.(run);
+
+            // Server-driven background→background continuation. If this chunk
+            // hit its soft-timeout still unfinished (ended at an auto_continue
+            // / loop_limit / recoverable boundary), chain the next chunk by
+            // re-firing the `_process-run` self-dispatch with mode "continue"
+            // (carried as internalContinuation + an incremented count),
+            // instead of relying on the client to re-POST. Mirrors the
+            // agent-teams `fireInternalDispatch({ body: { mode: "continue" }})`
+            // chain. Bounded by MAX_BACKGROUND_RUN_CONTINUATIONS. Aborted /
+            // user-stopped runs do NOT chain.
+            // 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)) {
+              // Full handoff discipline lives in
+              // `chainServerDrivenContinuation` (exported + unit-tested):
+              // per-turn SQL run budget, successor row PRE-INSERTED before
+              // the dispatch, fully awaited dispatch with retries, loud
+              // diag/terminal marking on failure. Never throws.
+              await chainServerDrivenContinuation({
+                event,
+                run,
+                effectiveThreadId,
+                effectiveTurnId,
+                requestBody: body as unknown as Record<string, unknown>,
+                backgroundContinuationCount,
+                // Re-evaluate the durable gate rather than keying off
+                // isBackgroundWorker: a successor chunk of a FOREGROUND
+                // self-chain re-enters as a worker too, and must keep
+                // chaining via the regular function — the Netlify
+                // `-background` function is only emitted into the deploy
+                // output when the durable flag is on.
+                //
+                // `&& !runsInBackgroundFunction`: a worker PROVEN to already
+                // be executing inside the real `-background` function must
+                // never dispatch back to that same function's own URL — a
+                // background function invoking itself by URL from inside a
+                // live invocation is a documented Netlify platform
+                // limitation (404), unlike the initial foreground→background
+                // dispatch or a worker that landed on the regular function
+                // (a genuinely different function calling the background
+                // one, which works). This only changes the dispatch TARGET
+                // for that one proven-in-bg-function case — by this point
+                // (with the in-process resumable-error resume above) it is
+                // reached only when the chunk genuinely exhausted its
+                // budget, so falling back to the regular `_process-run`
+                // function (40s clamp) here is the correct, safe target.
+                chainViaDurableBackground:
+                  isAgentChatDurableBackgroundEnabled({
+                    appOptIn: options.durableBackgroundRuns,
+                  }) && !runsInBackgroundFunction,
+                // Only changes the retry BUDGET, never the dispatch target
+                // above: a worker proven in a real background function has
+                // minutes of remaining wall clock and no connected-client
+                // fallback, so it must not be demoted to the foreground's
+                // 2-attempt budget just because it was forced onto the
+                // regular-function dispatch target. See
+                // `resolveContinuationDispatchBudget`.
+                workerProvenInBackgroundFunction: runsInBackgroundFunction,
+              });
             }
           }
         : undefined;
@@ -7970,7 +7953,7 @@ export function createProductionAgentHandler(
         )
       : null;
 
-    startRun(
+    const startedRun = startRun(
       runId,
       effectiveThreadId,
       async (rawSend, signal) => {
@@ -8414,9 +8397,8 @@ export function createProductionAgentHandler(
     // Background worker: await the run to completion so Netlify keeps the
     // background function alive for the whole turn (the client is streaming the
     // same events via the foreground POST's cross-isolate SQL subscription).
-    // The onComplete wrapper above resolves `backgroundRunDone`.
     if (isBackgroundWorker) {
-      if (backgroundRunDone) await backgroundRunDone;
+      await startedRun.finalized;
       return { ok: true, runId };
     }
 

package/src/agent/run-manager.ts

@@ -44,6 +44,15 @@ export interface ActiveRun {
   startedAt: number;
 }
 
+export interface StartedRun extends ActiveRun {
+  /**
+   * Resolves after the terminal event and final SQL status have been persisted.
+   * Serverless workers must await this before returning or the runtime can
+   * freeze the isolate between onComplete and terminalization.
+   */
+  finalized: Promise<void>;
+}
+
 const activeRuns = new Map<string, ActiveRun>();
 const threadToRun = new Map<string, string>();
 
@@ -447,7 +456,7 @@ export function startRun(
   ) => Promise<void>,
   onComplete?: (run: ActiveRun) => void | Promise<void>,
   options?: StartRunOptions,
-): ActiveRun {
+): StartedRun {
   // If there's already a run for this thread, abort it
   const existingRunId = threadToRun.get(threadId);
   if (existingRunId) {
@@ -456,7 +465,17 @@ export function startRun(
 
   const abort = new AbortController();
   let softTimedOut = false;
-  const run: ActiveRun = {
+  let resolveFinalized: () => void = () => {};
+  let rejectFinalized: (reason?: unknown) => void = () => {};
+  const finalized = new Promise<void>((resolve, reject) => {
+    resolveFinalized = resolve;
+    rejectFinalized = reject;
+  });
+  // Foreground callers do not await this promise, but terminal persistence
+  // failures must still be observable to background workers without creating
+  // an unhandled rejection in the foreground path.
+  void finalized.catch(() => {});
+  const run: StartedRun = {
     runId,
     threadId,
     turnId: options?.turnId ?? runId,
@@ -465,6 +484,7 @@ export function startRun(
     subscribers: new Set(),
     abort,
     startedAt: Date.now(),
+    finalized,
   };
 
   activeRuns.set(runId, run);
@@ -1039,6 +1059,21 @@ export function startRun(
               "[run-manager] terminal event persistence error:",
               err instanceof Error ? err.message : err,
             );
+            try {
+              await insertRunEvent(
+                runId,
+                terminal.seq,
+                JSON.stringify(terminal.event),
+              );
+              terminalPersistenceError = null;
+            } catch (retryError) {
+              terminalPersistenceError = retryError;
+              captureRunError(retryError, "completion");
+              console.error(
+                "[run-manager] terminal event retry persistence error:",
+                retryError instanceof Error ? retryError.message : retryError,
+              );
+            }
           }
         }
       }
@@ -1112,6 +1147,13 @@ export function startRun(
         await setRunError(runId, errorCode ?? "unknown", errorDetail);
       }
 
+      if (terminalPersistenceError) {
+        const reconciled = await reconcileTerminalRunFromEvents(runId).catch(
+          () => false,
+        );
+        if (!reconciled) throw terminalPersistenceError;
+      }
+
       // 6. Schedule in-memory cleanup + opportunistic old-run pruning.
       setTimeout(() => {
         activeRuns.delete(runId);
@@ -1124,6 +1166,7 @@ export function startRun(
         resolveErroredRunRetentionMs(),
       ).catch(() => {});
     });
+  runPromise.then(resolveFinalized, rejectFinalized);
 
   // On Cloudflare Workers, keep the isolate alive for this run
   try {

package/src/agent/thread-data-builder.ts

@@ -35,6 +35,7 @@ interface BuildAssistantMessageOptions {
    * overwriting the others.
    */
   turnId?: string;
+  runDurationMs?: number;
 }
 
 type AssistantMessage = NonNullable<ReturnType<typeof buildAssistantMessage>>;
@@ -43,6 +44,8 @@ type UserMessage = ReturnType<typeof buildUserMessage>;
 const INTERRUPTED_TOOL_RESULT =
   "Interrupted before this tool returned a result.";
 
+export const ASSISTANT_RUN_DURATION_METADATA_KEY = "agentNativeRunDurationMs";
+
 const MAX_STORED_ATTACHMENT_CHARS = 60_000;
 /**
  * When no file-upload provider is configured we fall back to storing base64
@@ -267,6 +270,13 @@ export function buildAssistantMessage(
   const custom: Record<string, unknown> = {};
   if (options.turnId) custom.turnId = options.turnId;
   if (runId) custom.foldedRunIds = [runId];
+  if (
+    typeof options.runDurationMs === "number" &&
+    Number.isFinite(options.runDurationMs) &&
+    options.runDurationMs >= 0
+  ) {
+    custom[ASSISTANT_RUN_DURATION_METADATA_KEY] = options.runDurationMs;
+  }
   if (continued) custom.continued = true;
   if (runError) {
     custom.runError = {
@@ -462,6 +472,41 @@ function messagesMatch(a: any, b: any): boolean {
   return messageIdentityKeys(a).some((key) => bKeys.has(key));
 }
 
+function preserveAssistantRunDuration(chosenEntry: any, otherEntry: any): any {
+  const chosen = getStoredMessage(chosenEntry);
+  const other = getStoredMessage(otherEntry);
+  if (chosen?.role !== "assistant" || other?.role !== "assistant") {
+    return chosenEntry;
+  }
+
+  const chosenCustom =
+    chosen.metadata?.custom && typeof chosen.metadata.custom === "object"
+      ? (chosen.metadata.custom as Record<string, unknown>)
+      : {};
+  if (assistantRunDurationMs(chosenCustom) != null) return chosenEntry;
+
+  const otherCustom =
+    other.metadata?.custom && typeof other.metadata.custom === "object"
+      ? (other.metadata.custom as Record<string, unknown>)
+      : {};
+  const durationMs = assistantRunDurationMs(otherCustom);
+  if (durationMs == null) return chosenEntry;
+
+  const nextMessage = {
+    ...chosen,
+    metadata: {
+      ...chosen.metadata,
+      custom: {
+        ...chosenCustom,
+        [ASSISTANT_RUN_DURATION_METADATA_KEY]: durationMs,
+      },
+    },
+  };
+  return chosenEntry?.message === undefined
+    ? nextMessage
+    : { ...chosenEntry, message: nextMessage };
+}
+
 function chooseMergedMessageEntry(existingEntry: any, incomingEntry: any): any {
   const existing = getStoredMessage(existingEntry);
   const incoming = getStoredMessage(incomingEntry);
@@ -479,12 +524,19 @@ function chooseMergedMessageEntry(existingEntry: any, incomingEntry: any): any {
   ) {
     const existingWeight = assistantContentWeight(existing.content);
     const incomingWeight = assistantContentWeight(incoming.content);
-    if (existingWeight > incomingWeight) return existingEntry;
-    if (incomingWeight > existingWeight) return incomingEntry;
-    return isTerminalAssistantStatus(existing?.status) &&
-      !isTerminalAssistantStatus(incoming?.status)
-      ? existingEntry
-      : incomingEntry;
+    const chosen =
+      existingWeight > incomingWeight
+        ? existingEntry
+        : incomingWeight > existingWeight
+          ? incomingEntry
+          : isTerminalAssistantStatus(existing?.status) &&
+              !isTerminalAssistantStatus(incoming?.status)
+            ? existingEntry
+            : incomingEntry;
+    return preserveAssistantRunDuration(
+      chosen,
+      chosen === existingEntry ? incomingEntry : existingEntry,
+    );
   }
   if (
     existing?.role === "assistant" &&
@@ -492,9 +544,9 @@ function chooseMergedMessageEntry(existingEntry: any, incomingEntry: any): any {
     isTerminalAssistantStatus(existing?.status) &&
     !isTerminalAssistantStatus(incoming?.status)
   ) {
-    return existingEntry;
+    return preserveAssistantRunDuration(existingEntry, incomingEntry);
   }
-  return incomingEntry;
+  return preserveAssistantRunDuration(incomingEntry, existingEntry);
 }
 
 function normalizeMessageEntry(
@@ -1397,6 +1449,17 @@ function foldedRunIdsOf(message: any): string[] {
     : [];
 }
 
+function assistantRunDurationMs(
+  custom: Record<string, unknown>,
+): number | null {
+  const durationMs = custom[ASSISTANT_RUN_DURATION_METADATA_KEY];
+  return typeof durationMs === "number" &&
+    Number.isFinite(durationMs) &&
+    durationMs >= 0
+    ? durationMs
+    : null;
+}
+
 /** Rough size of an assistant message's content, used only to pick the larger
  *  of two representations of the same chunk so a fold can never shrink. */
 function assistantContentWeight(content: unknown): number {
@@ -1519,6 +1582,20 @@ export function foldAssistantTurn(
     turnId,
     foldedRunIds: mergedFolded,
   };
+  const existingDurationMs = assistantRunDurationMs(existingCustom);
+  const incomingDurationMs = assistantRunDurationMs(incomingCustom);
+  const mergedDurationMs = runAlreadyFolded
+    ? existingDurationMs == null
+      ? incomingDurationMs
+      : incomingDurationMs == null
+        ? existingDurationMs
+        : Math.max(existingDurationMs, incomingDurationMs)
+    : existingDurationMs == null && incomingDurationMs == null
+      ? null
+      : (existingDurationMs ?? 0) + (incomingDurationMs ?? 0);
+  if (mergedDurationMs != null) {
+    mergedCustom[ASSISTANT_RUN_DURATION_METADATA_KEY] = mergedDurationMs;
+  }
   // Only the freshest chunk decides whether the turn is still continuing.
   if (incomingCustom.continued !== true) delete mergedCustom.continued;