@agent-native/core 0.119.3 → 0.119.5

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.3",
+  "version": "0.119.5",
   "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/engine/index.ts

@@ -25,6 +25,8 @@ export {
   getConfiguredEngineNameForRequest,
   getStoredModelForEngine,
   normalizeModelForEngine,
+  resolveEnginePreservesCustomModels,
+  type NormalizeModelOptions,
   detectEngineFromEnv,
   detectEngineFromEnvForRequest,
   detectEngineFromUserSecrets,

package/src/agent/engine/registry.ts

@@ -96,6 +96,42 @@ function packageNameFromInstallSpecifier(specifier: string): string | null {
   return versionIndex === -1 ? trimmed : trimmed.slice(0, versionIndex);
 }
 
+/**
+ * True only when there is positive evidence this module is executing from a
+ * bundled serverless function where optional dependencies were inlined into the
+ * bundle and are therefore NOT resolvable via `require.resolve` — even though
+ * the dynamic `import()` the engine uses to load them still works.
+ *
+ * Deliberately narrow. The Nitro Vercel/Netlify presets (which agent-native's
+ * own `deploy` command emits) inline optional peers and always set these env
+ * markers, so they are a reliable signal. Other serverless runtimes — a
+ * container on Cloud Run / Google Cloud Functions (`K_SERVICE` /
+ * `FUNCTION_TARGET`), or a plain AWS Lambda — commonly ship a real
+ * `node_modules` where `require.resolve` is authoritative; there a resolve miss
+ * means the package is genuinely absent and must NOT be masked. Those runtimes
+ * are still covered *when the code is actually bundled*, via the module-path
+ * check below, which stays false for a normal `node_modules` layout.
+ */
+function isBundledServerlessRuntime(): boolean {
+  const env = process.env;
+  // Nitro's Vercel/Netlify presets inline optional peers into the function
+  // bundle; these platforms always set these markers.
+  if (env.VERCEL || env.NETLIFY) return true;
+  // Otherwise require direct evidence that this module is running from inside a
+  // bundle output directory (Vercel's `/var/task`, Nitro's `.output/server`,
+  // inlined `_libs`). This is the real signal that `require.resolve` cannot be
+  // trusted; it stays false for normal `node_modules` layouts (dev, tests, and
+  // container/Lambda/Cloud Run deploys that ship their dependencies), so a
+  // genuine "package not installed" miss still surfaces there.
+  try {
+    return /[\\/](?:_libs|\.vercel|\.netlify|\.output)[\\/]|\/var\/task\//.test(
+      import.meta.url ?? "",
+    );
+  } catch {
+    return false;
+  }
+}
+
 function canResolvePackage(packageName: string): boolean {
   const cached = _packageAvailabilityCache.get(packageName);
   if (cached !== undefined) return cached;
@@ -104,7 +140,15 @@ function canResolvePackage(packageName: string): boolean {
     require.resolve(packageName);
     available = true;
   } catch {
-    available = false;
+    // Bundled serverless runtimes (e.g. Nitro on Vercel/Netlify) inline optional
+    // provider packages into the function bundle, so require.resolve cannot find
+    // them even though the dynamic `import()` the engine actually uses to load
+    // them works. Treat them as available there and let the engine's own import
+    // be the real gate — it already fails with a clear "pnpm add …" message when
+    // the package is genuinely missing. Without this, every engine-usability
+    // gate rejects the AI-SDK engines at runtime and the agent silently falls
+    // back to the native Anthropic engine.
+    available = isBundledServerlessRuntime();
   }
   _packageAvailabilityCache.set(packageName, available);
   return available;
@@ -179,17 +223,41 @@ function findLatestSupportedVersionMatch(
   return best?.model;
 }
 
+export interface NormalizeModelOptions {
+  /**
+   * Force unrecognized (custom) model IDs to be kept verbatim, as if
+   * `engine.preserveCustomModels` were set on a live engine instance.
+   *
+   * The settings actions call `normalizeModelForEngine` with a static registry
+   * ENTRY, which never carries the runtime `preserveCustomModels` flag — that
+   * is only set on the engine INSTANCE created with an OpenAI-compatible
+   * `baseUrl`. They resolve the capability with
+   * {@link resolveEnginePreservesCustomModels} and pass it here so a gateway
+   * model (e.g. an Ollama `gemma4`) is not rewritten to the OpenAI default on
+   * save/read. First-party OpenAI (no gateway) leaves this unset, so an unknown
+   * or invalid model still normalizes to a supported one.
+   */
+  preserveCustomModels?: boolean;
+}
+
 export function normalizeModelForEngine(
   engine: Pick<
     AgentEngine,
     "name" | "defaultModel" | "supportedModels" | "preserveCustomModels"
   >,
   model: string | null | undefined,
+  options: NormalizeModelOptions = {},
 ): string {
   const candidate = typeof model === "string" ? model.trim() : "";
   if (!candidate) return engine.defaultModel;
 
-  if (engine.preserveCustomModels) return candidate;
+  // Preserve custom IDs verbatim BEFORE any catalog/version matching, so a
+  // version-shaped gateway model that happens to share a family with a
+  // built-in model (e.g. `gpt-5.4` on an OpenAI-compatible endpoint) is not
+  // rewritten to a catalog entry.
+  if (engine.preserveCustomModels || options.preserveCustomModels) {
+    return candidate;
+  }
 
   if (engine.supportedModels.length === 0) return candidate;
 
@@ -203,6 +271,31 @@ export function normalizeModelForEngine(
   );
 }
 
+/**
+ * Whether models saved or read for this engine ENTRY should be preserved
+ * verbatim instead of normalized against the built-in catalog.
+ *
+ * `normalizeModelForEngine` honors a live engine's `preserveCustomModels`, but
+ * that flag is only set on an AI SDK engine INSTANCE when the OpenAI provider
+ * is pointed at an OpenAI-compatible gateway (a custom base URL — e.g. Ollama
+ * Cloud or LiteLLM), whose model IDs are not in the built-in OpenAI catalog.
+ * The static registry entry the settings actions pass to
+ * `normalizeModelForEngine` cannot carry that runtime flag, so this async
+ * helper reproduces the same decision — `ai-sdk:openai` AND a resolved base URL
+ * — from the request's stored/deploy config. First-party OpenAI (no gateway)
+ * returns false so an unknown/invalid model still normalizes to a supported one.
+ */
+export async function resolveEnginePreservesCustomModels(
+  entry: Pick<AgentEngineEntry, "name">,
+): Promise<boolean> {
+  if (entry.name !== "ai-sdk:openai") return false;
+  try {
+    return Boolean(await resolveOpenAiBaseUrl());
+  } catch {
+    return false;
+  }
+}
+
 function assertAgentEnginePackageInstalled(entry: AgentEngineEntry): void {
   if (isAgentEnginePackageInstalled(entry)) return;
   const installHint = entry.installPackage

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 {