@agent-native/core 0.141.1 → 0.141.3

package/corpus/README.md

@@ -31,4 +31,4 @@ rg -n "defineAction|useActionQuery" node_modules/@agent-native/core/corpus
 
 ## Generated Counts
 
-- template files: 7643
+- template files: 7644

package/corpus/templates/analytics/changelog/2026-08-05-durable-a2a-workers-avoid-startup-migration-contention.md

@@ -0,0 +1,6 @@
+---
+type: fixed
+date: 2026-08-05
+---
+
+Durable A2A workers now avoid startup migration contention so Analytics requests can complete while rollup maintenance runs separately.

package/corpus/templates/analytics/server/plugins/db.ts

@@ -1,10 +1,12 @@
 import {
+  deferMigration,
   ensureAdditiveColumns,
   getDialect,
   getDbExec,
   isPostgres,
   runMigrations,
 } from "@agent-native/core/db";
+import { isInBackgroundFunctionRuntime } from "@agent-native/core/server";
 
 // Side-effect import: ensures registerShareableResource runs on server
 // startup so the dashboard / analysis share actions know where to dispatch.
@@ -141,7 +143,17 @@ const ANALYTICS_ROLLUP_BACKFILL_STATEMENTS = {
   ],
 } as const;
 
-async function runHistoricalAnalyticsRollupBackfill(): Promise<void> {
+async function runHistoricalAnalyticsRollupBackfill() {
+  // Durable agent workers share this plugin bundle with the regular server,
+  // but they must not become a second migration runner for an expensive
+  // historical scan. The keep-warm/regular server path owns this work.
+  if (isInBackgroundFunctionRuntime()) {
+    console.info(
+      "[db] Deferring historical Analytics rollup backfill from durable background runtime",
+    );
+    return deferMigration();
+  }
+
   const db = getDbExec();
 
   if (isPostgres()) {
@@ -151,11 +163,12 @@ async function runHistoricalAnalyticsRollupBackfill(): Promise<void> {
       );
     }
 
-    await db.transaction(async (tx) => {
+    const result = await db.transaction(async (tx) => {
       // Only one serverless instance should perform the expensive scan. A
-      // try-lock is intentional: competing cold starts fail fast instead of
-      // holding pooled Neon connections while waiting for the winner. The
-      // monotonic rollup upsert below keeps a live increment from being
+      // A try-lock keeps competing cold starts from holding pooled Neon
+      // connections while waiting for the winner. A lock loser defers without
+      // recording the migration so a failed winner can be retried safely.
+      // The monotonic rollup upsert below keeps a live increment from being
       // overwritten if ingest commits during the historical snapshot.
       const lockResult = await tx.execute({
         sql: "SELECT pg_try_advisory_xact_lock(hashtextextended(?, 0::bigint)) AS acquired",
@@ -163,15 +176,16 @@ async function runHistoricalAnalyticsRollupBackfill(): Promise<void> {
       });
       const acquired = lockResult.rows[0]?.acquired;
       if (acquired !== true && acquired !== "t") {
-        throw new Error(
-          "Analytics rollup backfill is already running on another instance",
+        console.info(
+          "[db] Deferring historical Analytics rollup backfill; another instance owns the advisory lock",
         );
+        return deferMigration();
       }
       for (const statement of ANALYTICS_ROLLUP_BACKFILL_STATEMENTS.postgres) {
         await tx.execute(statement);
       }
     });
-    return;
+    return result;
   }
 
   const statements = ANALYTICS_ROLLUP_BACKFILL_STATEMENTS.sqlite;
@@ -1557,6 +1571,9 @@ const runAnalyticsMigrations = runMigrations(
  */
 export default async (nitroApp: any): Promise<void> => {
   await runAnalyticsMigrations(nitroApp);
+  if (isInBackgroundFunctionRuntime()) {
+    return;
+  }
   try {
     if (await repairPersistedFirstPartyDashboardQueries()) {
       console.info(

package/dist/collab/struct-routes.d.ts

@@ -13,8 +13,8 @@
  * Body: { json: any, fieldName?: string, type?: "map"|"array", requestSource?: string }
  */
 export declare const postCollabJson: import("h3").EventHandlerWithFetch<import("h3").EventHandlerRequest, Promise<{
-    error: string;
     ok?: undefined;
+    error: string;
 } | {
     error?: undefined;
     ok: boolean;

package/dist/db/index.d.ts

@@ -21,7 +21,7 @@ export declare function createDb(config: DbConfig): Promise<(import("drizzle-orm
 })>;
 export type DrizzleDb = Awaited<ReturnType<typeof createDb>>;
 export { createGetDb } from "./create-get-db.js";
-export { runMigrations, type MigrationEntry, type MigrationSql, } from "./migrations.js";
+export { deferMigration, MIGRATION_DEFERRED, runMigrations, type MigrationEntry, type MigrationRunResult, type MigrationSql, } from "./migrations.js";
 export { getDbExec, createDbExec, getDatabaseUrl, getDialect, isLocalDatabase, isPostgres, intType, closeDbExec, type DbExec, type DbExecConfig, type DbExecQuery, type DbExecStatement, type Dialect, } from "./client.js";
 export { table, text, integer, now } from "./schema.js";
 export { ensureAdditiveColumns, type EnsureAdditiveColumnsOptions, type EnsureAdditiveColumnsResult, type EnsureAdditiveColumnsLogger, } from "./ensure-additive-columns.js";

package/dist/db/index.js

@@ -20,7 +20,7 @@ export async function createDb(config) {
     throw new Error(`Unsupported driver: ${config.driver}`);
 }
 export { createGetDb } from "./create-get-db.js";
-export { runMigrations, } from "./migrations.js";
+export { deferMigration, MIGRATION_DEFERRED, runMigrations, } from "./migrations.js";
 export { getDbExec, createDbExec, getDatabaseUrl, getDialect, isLocalDatabase, isPostgres, intType, closeDbExec, } from "./client.js";
 export { table, text, integer, now } from "./schema.js";
 export { ensureAdditiveColumns, } from "./ensure-additive-columns.js";

package/dist/db/migrations.d.ts

@@ -53,6 +53,14 @@ export type MigrationSql = string | {
     postgres?: string;
     sqlite?: string;
 };
+/**
+ * A run-only migration can defer its work without recording itself as applied.
+ * This is for serialized backfills where another instance owns the advisory
+ * lock; throwing would turn an expected loser into a startup retry storm.
+ */
+export declare const MIGRATION_DEFERRED: unique symbol;
+export declare function deferMigration(): typeof MIGRATION_DEFERRED;
+export type MigrationRunResult = void | typeof MIGRATION_DEFERRED;
 export interface MigrationEntry {
     version: number;
     sql: MigrationSql;
@@ -68,11 +76,13 @@ export interface MigrationEntry {
      * JS step for a backfill SQL cannot express — e.g. a repair whose value comes
      * from application-level parsing of a stored blob. Runs BEFORE this entry's
      * SQL and before the bookkeeping row is written, so a throw leaves the
-     * migration unrecorded and it retries on the next boot. Pass `sql: {}` for a
-     * run-only entry. Give run-only entries a `name`: the legacy version gate
+     * migration unrecorded and it retries on the next boot. Return
+     * `deferMigration()` when another instance owns a serialized backfill; the
+     * entry stays pending without logging a startup failure. Pass `sql: {}` for
+     * a run-only entry. Give run-only entries a `name`: the legacy version gate
      * would otherwise mark them applied via any later migration's MAX advance.
      */
-    run?: () => Promise<void>;
+    run?: () => Promise<MigrationRunResult>;
 }
 /**
  * Runs a list of migrations against the configured database, gated by a

package/dist/db/migrations.js

@@ -154,6 +154,15 @@ function splitSqlStatements(sql) {
         out.push(tail);
     return out;
 }
+/**
+ * A run-only migration can defer its work without recording itself as applied.
+ * This is for serialized backfills where another instance owns the advisory
+ * lock; throwing would turn an expected loser into a startup retry storm.
+ */
+export const MIGRATION_DEFERRED = Symbol("migration-deferred");
+export function deferMigration() {
+    return MIGRATION_DEFERRED;
+}
 function resolveMigrationSql(sql, pg) {
     if (typeof sql === "string")
         return sql;
@@ -272,8 +281,11 @@ export function runMigrations(migrations, options) {
                     try {
                         // D1 is SQLite-compatible
                         const raw = resolveMigrationSql(m.sql, false);
-                        if (m.run)
-                            await m.run();
+                        const runResult = m.run ? await m.run() : undefined;
+                        if (runResult === MIGRATION_DEFERRED) {
+                            console.info(`[db] Deferred migration ${m.name ? `"${m.name}" ` : ""}v${m.version}; it remains pending for a later boot`);
+                            continue;
+                        }
                         const recordStatements = [
                             m.name
                                 ? d1
@@ -482,8 +494,11 @@ export function runMigrations(migrations, options) {
                     // A throw here escapes to the outer handler with nothing recorded,
                     // so the entry is retried on the next boot rather than being marked
                     // applied against work that never happened.
-                    if (m.run)
-                        await m.run();
+                    const runResult = m.run ? await m.run() : undefined;
+                    if (runResult === MIGRATION_DEFERRED) {
+                        console.info(`[db] Deferred migration ${label}; it remains pending for a later boot`);
+                        continue;
+                    }
                     if (raw == null) {
                         // Dialect-gated migration with no SQL for this dialect; still mark
                         // as applied so we don't retry forever.

package/dist/notifications/routes.d.ts

@@ -13,13 +13,13 @@
 export declare function createNotificationsHandler(): import("h3").EventHandlerWithFetch<import("h3").EventHandlerRequest, Promise<"" | import("./types.js").Notification[] | {
     count: number;
     updated?: undefined;
-    error?: undefined;
     ok?: undefined;
+    error?: undefined;
 } | {
     count?: undefined;
     updated: number;
-    error?: undefined;
     ok?: undefined;
+    error?: undefined;
 } | {
     count?: undefined;
     updated?: undefined;
@@ -28,6 +28,6 @@ export declare function createNotificationsHandler(): import("h3").EventHandlerW
 } | {
     count?: undefined;
     updated?: undefined;
-    error?: undefined;
     ok: boolean;
+    error?: undefined;
 }>>;

package/dist/observability/routes.d.ts

@@ -44,14 +44,14 @@ export declare function createObservabilityHandler(): import("h3").EventHandlerW
     summary: import("./types.js").TraceSummary;
     spans: import("./types.js").TraceSpan[];
     id?: undefined;
-    ok?: undefined;
     error?: undefined;
+    ok?: undefined;
 } | {
     summary?: undefined;
     spans?: undefined;
     id: string;
-    ok?: undefined;
     error?: undefined;
+    ok?: undefined;
 } | {
     summary?: undefined;
     spans?: undefined;
@@ -62,6 +62,6 @@ export declare function createObservabilityHandler(): import("h3").EventHandlerW
     summary?: undefined;
     spans?: undefined;
     id?: undefined;
-    ok: boolean;
     error?: undefined;
+    ok: boolean;
 }>>;

package/dist/progress/routes.d.ts

@@ -15,6 +15,6 @@ export declare function createProgressHandler(): import("h3").EventHandlerWithFe
     error: string;
     ok?: undefined;
 } | {
-    error?: undefined;
     ok: boolean;
+    error?: undefined;
 }>>;

package/dist/resources/handlers.d.ts

@@ -48,8 +48,8 @@ export declare function handleUpdateResource(event: any): Promise<import("./stor
 }>;
 /** DELETE /_agent-native/resources/:id — delete a resource */
 export declare function handleDeleteResource(event: any): Promise<{
-    ok?: undefined;
     error: string;
+    ok?: undefined;
 } | {
     error?: undefined;
     ok: boolean;

package/dist/secrets/routes.d.ts

@@ -34,37 +34,37 @@ export declare function createListSecretsHandler(): import("h3").EventHandlerWit
 /** POST /_agent-native/secrets/:key — write a secret. */
 export declare function createWriteSecretHandler(): import("h3").EventHandlerWithFetch<import("h3").EventHandlerRequest, Promise<{
     error: string;
-    status?: undefined;
     ok?: undefined;
+    status?: undefined;
 } | {
+    error?: undefined;
     ok: boolean;
     status: string;
-    error?: undefined;
 } | {
+    ok?: undefined;
     error: string;
     removed?: undefined;
-    ok?: undefined;
 } | {
+    error?: undefined;
     ok: boolean;
     removed: boolean;
-    error?: undefined;
 }>>;
 /**
  * POST /_agent-native/secrets/:key/test — validate an optional candidate value
  * or the current stored value without changing anything.
  */
 export declare function createTestSecretHandler(): import("h3").EventHandlerWithFetch<import("h3").EventHandlerRequest, Promise<{
+    ok?: undefined;
     error: string;
     note?: undefined;
-    ok?: undefined;
 } | {
+    error?: undefined;
     ok: boolean;
     note?: undefined;
-    error?: undefined;
 } | {
+    error?: undefined;
     ok: boolean;
     note: string;
-    error?: undefined;
 } | {
     note?: undefined;
     ok: boolean;
@@ -95,11 +95,11 @@ export interface AdHocSecretPayload {
 export declare function createAdHocSecretHandler(): import("h3").EventHandlerWithFetch<import("h3").EventHandlerRequest, Promise<AdHocSecretPayload[] | {
     error: string;
 } | {
+    error?: undefined;
     ok: boolean;
     key: string;
-    error?: undefined;
 } | {
+    error?: undefined;
     ok: boolean;
     removed: boolean;
-    error?: undefined;
 }>>;

package/dist/server/agent-chat-plugin.js

@@ -4661,7 +4661,8 @@ Non-code requests are still fine on this surface: read data, navigate the UI, su
                 }
                 return invokeAgentChatHandler(event);
             }));
-            const disableRecurringJobsRuntime = shouldDisableRecurringJobsRuntime();
+            const isBackgroundRuntime = isInBackgroundFunctionRuntime();
+            const disableRecurringJobsRuntime = isBackgroundRuntime || shouldDisableRecurringJobsRuntime();
             // ─── Recurring Jobs Scheduler ──────────────────────────────────────
             // Poll every 60 seconds for due recurring jobs and execute them.
             // Uses setInterval so it works in all deployment environments without
@@ -4720,26 +4721,28 @@ Non-code requests are still fine on this surface: read data, navigate the UI, su
             // A non-Netlify self-dispatch only waits for the request to leave the
             // current invocation. Keep the durable history row as a retryable queue
             // so a frozen serverless handoff is recovered on the next sweep.
-            (() => {
-                let inFlight = false;
-                const sweep = async () => {
-                    if (inFlight)
-                        return;
-                    inFlight = true;
-                    try {
-                        const { redispatchUnclaimedAutomationRuns } = await import("../jobs/run-now.js");
-                        await redispatchUnclaimedAutomationRuns();
-                    }
-                    catch (error) {
-                        console.warn("[automations] queued-run sweep failed; retrying next tick:", error);
-                    }
-                    finally {
-                        inFlight = false;
-                    }
-                };
-                setTimeout(() => void sweep(), 15_000);
-                setInterval(() => void sweep(), 30_000);
-            })();
+            if (!isBackgroundRuntime) {
+                (() => {
+                    let inFlight = false;
+                    const sweep = async () => {
+                        if (inFlight)
+                            return;
+                        inFlight = true;
+                        try {
+                            const { redispatchUnclaimedAutomationRuns } = await import("../jobs/run-now.js");
+                            await redispatchUnclaimedAutomationRuns();
+                        }
+                        catch (error) {
+                            console.warn("[automations] queued-run sweep failed; retrying next tick:", error);
+                        }
+                        finally {
+                            inFlight = false;
+                        }
+                    };
+                    setTimeout(() => void sweep(), 15_000);
+                    setInterval(() => void sweep(), 30_000);
+                })();
+            }
             mcpInitializationPromise = initializeMcpManager().catch((err) => {
                 console.warn(`[mcp-client] deferred initialization failed: ${err?.message ?? err}`);
             });
@@ -4750,6 +4753,8 @@ Non-code requests are still fine on this surface: read data, navigate the UI, su
             // per instance; cheap (one indexed query when no active tasks are found).
             // Throttled by the same per-owner interval guard inside reconcileAgentTeamRunsForOwner.
             (() => {
+                if (isBackgroundRuntime)
+                    return;
                 // Track when this instance last ran the sweep so only one sweep fires
                 // per 2-min window even if multiple timers fire in overlapping invocations.
                 let lastSweep = 0;
@@ -4897,6 +4902,8 @@ Non-code requests are still fine on this surface: read data, navigate the UI, su
             // comment above for why this exists and the timing budget in
             // run-store.ts's `UNCLAIMED_BACKGROUND_RUN_FAST_SWEEP_MS` doc comment.
             (() => {
+                if (isBackgroundRuntime)
+                    return;
                 setTimeout(() => {
                     (async () => {
                         const { UNCLAIMED_BACKGROUND_RUN_FAST_SWEEP_MS } = await import("../agent/run-store.js");
@@ -4942,6 +4949,8 @@ Non-code requests are still fine on this surface: read data, navigate the UI, su
             // still fails loud, and it survives the fast sweep having missed a row
             // entirely (e.g. a restart landed between fast-sweep ticks).
             (() => {
+                if (isBackgroundRuntime)
+                    return;
                 let lastSweep = 0;
                 const SWEEP_INTERVAL_MS = 2 * 60 * 1000;
                 setTimeout(() => {

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

@@ -27,10 +27,10 @@ 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 {};

package/dist/server/index.d.ts

@@ -1,5 +1,5 @@
 export { createServer, type CreateServerOptions, type EnvKeyConfig, } from "./create-server.js";
-export { AGENT_BACKGROUND_PROCESSOR_FIELD, AGENT_BACKGROUND_PROCESSOR_ROUTE, AGENT_BACKGROUND_PROCESSOR_ROUTE_FIELD, dispatchPathTargetsNetlifyBackgroundFunction, resolveDurableBackgroundDispatchPath, } from "../agent/durable-background.js";
+export { AGENT_BACKGROUND_PROCESSOR_FIELD, AGENT_BACKGROUND_PROCESSOR_ROUTE, AGENT_BACKGROUND_PROCESSOR_ROUTE_FIELD, dispatchPathTargetsNetlifyBackgroundFunction, isInBackgroundFunctionRuntime, resolveDurableBackgroundDispatchPath, } from "../agent/durable-background.js";
 export { readBody, readBodyWithSizeLimit, streamFile, DEFAULT_CHAT_MAX_BODY_BYTES, DEFAULT_UPLOAD_MAX_FILE_BYTES, MAX_CHAT_ATTACHMENTS_PER_MESSAGE, isAllowedUploadMimeType, } from "./h3-helpers.js";
 export { buildDeepLink, toAbsoluteOpenUrl, toDesktopOpenUrl, toVsCodeOpenUrl, OPEN_ROUTE_SUBPATH, DESKTOP_OPEN_URL, VSCODE_OPEN_URL, type DeepLinkInput, } from "./deep-link.js";
 export { createOpenRouteHandler, type OpenRouteOptions } from "./open-route.js";
@@ -65,7 +65,7 @@ export { FeatureNotConfiguredError, hasBuilderPrivateKey, isBuilderEnvManaged, g
 export { builderDesignSystemUrl, builderProjectBranchUrl, buildBuilderDesignSystemIndexFiles, createBuilderDesignSystemProxyFields, fetchBuilderDesignSystemDecodeJobStatus, fetchBuilderDesignSystemDocs, getBuilderDesignSystemsBaseUrl, hydrateBuilderDesignSystemReference, indexBuilderDesignSystem, localBuilderDesignSystemId, mimeTypeForBuilderDesignSystemFilename, parseBuilderDesignSystemProxyReference, startBuilderDesignSystemIndex, startBuilderDesignSystemUpload, type BuildBuilderDesignSystemIndexFilesOptions, type BuilderDesignSystemCodeFileInput, type BuilderDesignSystemDecodeJobStatus, type BuilderDesignSystemDocsOptions, type BuilderDesignSystemDocument, type BuilderDesignSystemHydratedReference, type BuilderDesignSystemIndexFile, type BuilderDesignSystemIndexFromSourcesOptions, type BuilderDesignSystemIndexOptions, type BuilderDesignSystemIndexResult, type BuilderDesignSystemUploadAttachment, type BuilderDesignSystemUploadSlot, type BuilderDesignSystemProxyFields, type BuilderDesignSystemProxyFieldsOptions, type BuilderDesignSystemProxyReference, type BuilderDesignSystemSourceKind, } from "./builder-design-systems.js";
 export { getBuilderBranchProjectId, isBuilderBranchingEnabled, requestBuilderBrowserConnection, resolveBuilderBranchProjectId, resolveIsBuilderBranchingEnabled, runBuilderAgent, type RunBuilderAgentResult, } from "./builder-browser.js";
 export { ensureFusionContainer, sendFusionBranchMessage, pushFusionBranch, reserveFusionHostingSlug, deployFusionProject, getFusionDeploys, getFusionBranchEditorUrl, getFusionHostingUrl, type FusionBranchRef, type EnsureFusionContainerResult, type SendFusionMessageResult, } from "./fusion-app.js";
-export { sendEmail, isEmailConfigured, getEmailProvider, type EmailAttachment, type EmailProvider, type SendEmailArgs, } from "./email.js";
+export { sendEmail, isEmailConfigured, getEmailReadiness, getEmailProvider, type EmailAttachment, type EmailReadiness, type EmailProvider, type SendEmailArgs, } from "./email.js";
 export { notifyActivity, runActivityNotification, resolveActivityRecipients, type ActivityDeliveryFailure, type ActivityNotificationResult, type ActivityNotificationStatus, type NotifyActivityInput, type ResolveActivityRecipientsInput, } from "./activity-notifications.js";
 export { renderEmail, emailStrong, emailLink, type RenderEmailArgs, type RenderedEmail, type EmailCta, } from "./email-template.js";
 export { getAppProductionUrl, getFirstPartyProdUrl } from "./app-url.js";

package/dist/server/index.js

@@ -1,5 +1,5 @@
 export { createServer, } from "./create-server.js";
-export { AGENT_BACKGROUND_PROCESSOR_FIELD, AGENT_BACKGROUND_PROCESSOR_ROUTE, AGENT_BACKGROUND_PROCESSOR_ROUTE_FIELD, dispatchPathTargetsNetlifyBackgroundFunction, resolveDurableBackgroundDispatchPath, } from "../agent/durable-background.js";
+export { AGENT_BACKGROUND_PROCESSOR_FIELD, AGENT_BACKGROUND_PROCESSOR_ROUTE, AGENT_BACKGROUND_PROCESSOR_ROUTE_FIELD, dispatchPathTargetsNetlifyBackgroundFunction, isInBackgroundFunctionRuntime, resolveDurableBackgroundDispatchPath, } from "../agent/durable-background.js";
 export { readBody, readBodyWithSizeLimit, streamFile, DEFAULT_CHAT_MAX_BODY_BYTES, DEFAULT_UPLOAD_MAX_FILE_BYTES, MAX_CHAT_ATTACHMENTS_PER_MESSAGE, isAllowedUploadMimeType, } from "./h3-helpers.js";
 export { buildDeepLink, toAbsoluteOpenUrl, toDesktopOpenUrl, toVsCodeOpenUrl, OPEN_ROUTE_SUBPATH, DESKTOP_OPEN_URL, VSCODE_OPEN_URL, } from "./deep-link.js";
 export { createOpenRouteHandler } from "./open-route.js";
@@ -66,7 +66,7 @@ export { FeatureNotConfiguredError, hasBuilderPrivateKey, isBuilderEnvManaged, g
 export { builderDesignSystemUrl, builderProjectBranchUrl, buildBuilderDesignSystemIndexFiles, createBuilderDesignSystemProxyFields, fetchBuilderDesignSystemDecodeJobStatus, fetchBuilderDesignSystemDocs, getBuilderDesignSystemsBaseUrl, hydrateBuilderDesignSystemReference, indexBuilderDesignSystem, localBuilderDesignSystemId, mimeTypeForBuilderDesignSystemFilename, parseBuilderDesignSystemProxyReference, startBuilderDesignSystemIndex, startBuilderDesignSystemUpload, } from "./builder-design-systems.js";
 export { getBuilderBranchProjectId, isBuilderBranchingEnabled, requestBuilderBrowserConnection, resolveBuilderBranchProjectId, resolveIsBuilderBranchingEnabled, runBuilderAgent, } from "./builder-browser.js";
 export { ensureFusionContainer, sendFusionBranchMessage, pushFusionBranch, reserveFusionHostingSlug, deployFusionProject, getFusionDeploys, getFusionBranchEditorUrl, getFusionHostingUrl, } from "./fusion-app.js";
-export { sendEmail, isEmailConfigured, getEmailProvider, } from "./email.js";
+export { sendEmail, isEmailConfigured, getEmailReadiness, getEmailProvider, } from "./email.js";
 export { notifyActivity, runActivityNotification, resolveActivityRecipients, } from "./activity-notifications.js";
 export { renderEmail, emailStrong, emailLink, } from "./email-template.js";
 export { getAppProductionUrl, getFirstPartyProdUrl } from "./app-url.js";

package/docs/content/agent-surfaces.mdx

@@ -6,73 +6,13 @@ search: "agentic app rich chat native chat UI full app automation headless BYO a
 
 # Agent Surfaces
 
-Agent-Native is deliberately composable. Most apps start with chat, add actions,
-render structured results inline, and then grow durable pages around the same
-SQL state. The same action surface can also power embedded sidecars,
-automation-first jobs, external agents, and custom chat runtimes.
-
-The useful way to choose is not by protocol first. Choose the product surface
-you want, then use the matching primitive. New here? Read
-[Key Concepts](/docs/key-concepts) first — it defines the actions, SQL, and
-agent-loop vocabulary this page assumes.
-
-| Surface                       | Use it when                                                                                                 | Start with                                                                                  |
-| ----------------------------- | ----------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------- |
-| **Rich chat on Agent-Native** | You want a standalone or embedded chat backed by the built-in agent loop.                                   | [Chat template](/docs/template-chat), `<AgentChatSurface>`, `<AssistantChat>`               |
-| **Native inline UI**          | Action results should render as first-party tables, charts, cards, approvals, or compact reports in chat.   | [Native Chat UI](/docs/native-chat-ui), `chatUI.renderer`, data widget helpers              |
-| **Generated inline UI**       | The agent should create temporary or reusable controls, pickers, calculators, or visualizers inside chat.   | [Generative UI](/docs/generative-ui), `render-inline-extension`, `create-extension`         |
-| **Full application**          | Humans and agents should share durable screens, data, navigation, and collaboration.                        | Templates, actions, SQL state, context awareness                                            |
-| **Embedded sidecar**          | You already have a SaaS app and want an agent beside it with page context and host commands.                | `createAgentNativeEmbeddedPlugin()`, `AgentNativeEmbedded`                                  |
-| **Automation-first app**      | Jobs, scripts, another app, or another agent should call the work directly without a browser UI.            | `agent-native create --headless`, `defineAction`, `agent-native agent`, HTTP, CLI, MCP, A2A |
-| **Rich chat on your agent**   | You built the agent elsewhere and want Agent-Native's composer, transcript, tool cards, and native widgets. | `AgentChatRuntime`, `<AssistantChat runtime={runtime}>`                                     |
-
-Those are stages and deployment shapes, not separate products. A workflow can
-start in chat, appear as a native table or chart, become a durable page in the
-app, and still run from jobs, scripts, MCP, or A2A without changing the operation
-the agent calls.
-
-## Full-page Manage Agent {#agent-page}
-
-When a full application needs a durable place to inspect and configure its
-agent, mount `AgentTabsPage` at `/agent`. Current templates pair that route
-with an app-navigation entry and pass `agentPageHref="/agent"` to
-`AgentSidebar`; the sidebar's Resources and Settings modes can then link to the
-full page without duplicating those flows.
+A **surface** is the way users (or other systems) interact with your app: a chat window, a dashboard page, a background job, an API call from another agent. Agent-Native lets you mix and match these without rebuilding your core logic, because every surface runs the same underlying actions. If you're new to Agent-Native, read [Key Concepts](/docs/key-concepts) first.
 
-```tsx filename="app/routes/agent.tsx"
-import { AgentTabsPage } from "@agent-native/core/client/agent-chat";
-export default function AgentRoute() {
-  return <AgentTabsPage />;
-}
-```
+## How surfaces relate to each other
 
-The shared page currently provides twelve tabs across two groups:
+The four main product shapes sit on a spectrum from most interactive to fully headless. What makes them composable is that the foundation stays the same throughout: the same actions, the same SQL database, and the same agent loop power every shape. Adding a new surface doesn't mean rewriting what's underneath — you're just adding a new way to reach the same operations.
 
-| Group     | Tab               | Shows                                                                                                                                                                                                                |
-| --------- | ----------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| Resources | **Files**         | The existing `ResourcesPanel` for personal or organization files                                                                                                                                                     |
-| Resources | **Instructions**  | Always-on AGENTS.md-style rules                                                                                                                                                                                      |
-| Resources | **Agents**        | Custom sub-agent profiles                                                                                                                                                                                            |
-| Resources | **Memory**        | Long-term recall notes                                                                                                                                                                                               |
-| Resources | **Skills**        | Reusable workflows                                                                                                                                                                                                   |
-| Resources | **Learnings**     | Corrections and patterns captured over time                                                                                                                                                                          |
-| Resources | **Remote agents** | A2A connections to other agent-native apps — this replaces what the Connections tab used to also show                                                                                                                |
-| Agent     | **Snapshots**     | A scope preview, token budget, ordered system sections grouped by provenance/governance/source, and the latest live-thread snapshot. Renamed from "Context"; old `#context` links redirect here.                     |
-| Agent     | **Connections**   | MCP server management only                                                                                                                                                                                           |
-| Agent     | **Automations**   | Personal and organization Scheduled/Event automations with pause/resume, details, and delete flows. The stable compatibility URL remains `/agent#jobs`.                                                              |
-| Agent     | **Settings**      | Agent model, API keys, limits, voice, and automation settings                                                                                                                                                        |
-| Agent     | **Access**        | The app MCP URL, an A2A agent card when available, and shared setup guides for Claude, ChatGPT, Cursor, Claude Code, Codex, and other clients. Links to `/mcp/connect` for the full connect flow and token fallback. |
-
-The page currently shows personal (`user`-scope) data only — there is no
-page-level Personal/Organization toggle today. The design goal is inspectable,
-attributable, governable context, with capability separated from access:
-Connections describes what the app can call; Access describes how external
-clients connect to it. The page is a thin shell over existing components,
-actions, and access checks—not a new admin console. An organization-scoped
-view, grants, scope editing, revocation UI, and per-iteration provenance
-history are not provided by this page yet.
-
-<Diagram id="doc-block-hvdxgh" title="The surface spectrum" summary={"One action surface, four product shapes — each adds UI without changing the operation underneath."}>
+<Diagram id="doc-block-hvdxgh" title="The surface spectrum" summary={"One action surface, four product shapes, each adding UI without changing the operation underneath."}>
 
 ```html
 <div class="diagram-spectrum">
@@ -130,176 +70,19 @@ history are not provided by this page yet.
 
 </Diagram>
 
-## Automation-first app {#headless}
-
-Use the automation-first path when no one needs a custom browser screen while
-the work runs: scheduled jobs, integrations, backend workflows, CLI loops,
-another agent, or an existing product calling into Agent-Native.
-
-This is the shape to reach for when automation is the product surface. You send
-a request from the terminal, Slack, email, a scheduled job, another agent, or
-Chat — "summarize my unread emails," "post the daily metrics to Slack," "find
-the candidates who replied last week" — and the agent acts and returns the
-result wherever it belongs. It is still a real app, not a stateless prompt:
-actions, auth sessions, app state, thread/run history, settings, credentials,
-and share records all live in SQL.
-
-Pick this pattern when:
-
-- **The work happens in the background.** Most of the value is created while the user isn't looking — triage agents, daily-report agents, on-call responders.
-- **The output leaves the app.** The agent posts to Slack, sends email, or updates a third-party system; there's nothing to browse in-app.
-- **The domain is one-shot.** Research bot, summary generator, report writer — no persistent object that needs a list view.
-- **You're prototyping an automation.** Ship the operation now; add chat or app pages when users need to inspect and steer it.
-
-If your product is built around persistent objects users browse, pivot, and
-share — emails, events, documents, charts — pick a [full application](#full-application)
-or a [template](/docs/cloneable-saas) instead; those add a full UI _plus_ the agent.
-
-### What ships in the box {#in-the-box}
-
-An automation-first app skips dashboard work, and it is channel-agnostic from
-day one — the same agent runs from the web, Slack, Telegram, email, and other
-agents because everything goes through the same actions. The trade-off is there
-is no "browse-everything-at-a-glance" view; if users need that, start from
-[Chat](/docs/template-chat) or add a small status page or list view.
-
-When you add the built-in Chat shell, the framework provides five management
-surfaces you don't have to build: **Chat** (the main input), **Resources**
-(skills, memory, instructions, sub-agents, and connected MCP servers),
-**Automations**, **Thread history**, and **Settings**. Those are usually enough
-— talk to it, see what it's done, configure how it behaves. Reach for
-[Chat](/docs/template-chat) when you're ready to add that browser UI, or the
-[Dispatch template](/docs/template-dispatch) for a workspace-style starting
-point with Slack/Telegram, scheduled jobs, and shared secrets out of the box.
-
-The smallest no-browser local path is a scaffold plus one action:
-
-```bash
-npx @agent-native/core@latest create my-agent --headless
-cd my-agent
-pnpm install
-```
-
-Then define the durable operation:
-
-```ts filename="actions/summarize-week.ts"
-import { defineAction } from "@agent-native/core/action";
-import { z } from "zod";
-
-export default defineAction({
-  description: "Summarize this week's submissions.",
-  readOnly: true,
-  schema: z.object({ formId: z.string() }),
-  run: async ({ formId }) => {
-    return { formId, summary: "34 submissions, up 18% from last week." };
-  },
-});
-```
-
-One action is then callable as:
-
-- **HTTP** — `POST /_agent-native/actions/summarize-week`
-- **CLI** — `pnpm action summarize-week --formId form_123`
-- **App-agent CLI** — `pnpm agent "Summarize form_123"`
-- **MCP** — from Claude, ChatGPT, Codex, Cursor, OpenCode, Copilot, and other MCP hosts
-- **A2A** — from another agent-native app or agent peer
-- **UI** — through `useActionQuery`, `useActionMutation`, or `callAction`
-- **Agent tool** — from the built-in chat loop
-
-<Endpoint id="doc-block-kdx289" title="Calling an action over HTTP" method="POST" path="/_agent-native/actions/summarize-week" summary="Invoke any action by name over HTTP" request={{
-  "contentType": "application/json",
-  "example": "{ \"formId\": \"form_123\" }"
-}} responses={[
-  {
-    "status": "200",
-    "description": "The action's return value as JSON",
-    "example": "{ \"formId\": \"form_123\", \"summary\": \"34 submissions, up 18% from last week.\" }"
-  },
-  {
-    "status": "400",
-    "description": "Input failed schema validation"
-  }
-]}>
-
-Every `defineAction` is auto-mounted at `/_agent-native/actions/<name>`. The JSON body is validated against the action's zod schema before `run` executes. To call it from an external system with a long-lived bearer token, see [HTTP API](/docs/http-api).
-
-</Endpoint>
-
-This is not a no-database or stateless mode. The app-agent loop stores sessions,
-threads, runs, settings, credentials, application state, and share records in
-SQL. Local development defaults to SQLite; hosted automation-first apps should
-use a persistent SQL database.
-
-If you need the whole agent loop headlessly from the project folder, use:
-
-```bash
-pnpm agent "Summarize this week's forms."
-```
-
-If another app or script needs to call the whole agent, use
-`agentNative.invoke("analytics", "...")` or the `agent-native invoke` CLI. That
-keeps cross-app work on the A2A path while local work stays on actions.
-
-Workers, jobs, integration webhooks, and custom hosts can drive the agent loop
-directly through the server API. This is lower-level than actions — you provide
-the engine, model, messages, tools, actions, an event sink, and an abort signal
-yourself:
-
-```ts
-import { runAgentLoop } from "@agent-native/core/server";
+## Choose a starting point
 
-await runAgentLoop({
-  engine,
-  model,
-  systemPrompt,
-  tools,
-  actions,
-  messages,
-  send,
-  signal,
-});
-```
-
-For most apps, scheduled prompts and integration webhooks already call this loop
-for you. Reach for it directly only when building a custom no-browser host, eval
-runner, or server-side orchestration surface — see [Server — Production agent
-handler](/docs/server#agent-handler) for the full signature.
-
-### Running against a folder {#folder-loop}
+Chat is the most common entry point. Apps typically grow inline UI as output gets richer, then add full app pages when users need persistent objects to browse and share. The same actions power the buttons, scheduled jobs, and external agents that come later. Use the Embedded sidecar when adding an agent to a product you already own, or Automation-first for work that runs without a browser. Here's the full picture:
 
-If your goal is "run an agent against this folder," start with the app-agent
-loop in that folder: scaffold the automation-first app, add actions/instructions, run
-`pnpm agent "..."`. That keeps the work inside the same action/runtime/state
-contract the app will use in production.
-
-External coding harnesses are a separate product surface for embedding Claude
-Code, Codex, Pi, Cursor, Mastra, or similar runtimes inside an Agent-Native app.
-Use them when you are building a coding-agent product, not as the default way to
-start a local agent-native workflow.
-
-### Cloud repo access {#cloud-repo-access}
-
-For cloud automation-first apps that need repository access, use the GitHub connector
-plus token CRUD model: list repositories, search files, read files, create or
-edit files, delete files, and revoke access through provider-scoped
-credentials. In local development, set the target repository explicitly:
-
-```bash
-GITHUB_REPOSITORY=owner/repo pnpm agent "Read README.md and suggest the next action."
-```
-
-Do not treat a VM clone or long-lived sandbox checkout as the primary cloud
-repo-access model. Sandboxes still matter for isolated code execution, but
-repository access should be explicit, permissioned, auditable, and revocable
-through the connector layer.
-
-### Sharing sessions and runs {#sharing-runs}
-
-Automation-first sessions and runs are durable objects. Shareability should be
-phased: read/share links first, so teammates can inspect sanitized prompts,
-outputs, and run status; permissioned writable collaboration later, so
-continuing a run, approving actions, editing schedules, or changing
-configuration goes through explicit access checks.
+| Surface                                         | Use it when                                                                    | Start with                                                            |
+| ----------------------------------------------- | ------------------------------------------------------------------------------ | --------------------------------------------------------------------- |
+| **[Rich chat](#rich-chat)**                     | Users talk to the agent, see tool calls, and keep a thread history.            | [Chat template](/docs/template-chat), `<AgentChatSurface>`            |
+| **[Native inline UI](#native-inline-ui)**       | Action results should render as tables, charts, cards, or approvals in chat.   | [Native Chat UI](/docs/native-chat-ui), `chatUI.renderer`             |
+| **[Generated inline UI](#generated-inline-ui)** | The agent should create temporary or reusable controls inside chat on the fly. | [Generative UI](/docs/generative-ui), `render-inline-extension`       |
+| **[Full application](#full-application)**       | Users need durable screens, shared data, navigation, and collaboration.        | Templates, actions, SQL state, context awareness                      |
+| **[Embedded sidecar](#embedded-sidecar)**       | You already have a SaaS app and want an agent beside it with page context.     | `createAgentNativeEmbeddedPlugin()`, `AgentNativeEmbedded`            |
+| **[Automation-first](#headless)**               | Jobs, scripts, or other agents call the work directly with no browser UI.      | `agent-native create --headless`, `defineAction`, HTTP, CLI, MCP, A2A |
+| **[Rich chat on your agent](#byo-agent)**       | You built the agent elsewhere and want Agent-Native's chat UI around it.       | `AgentChatRuntime`, `<AssistantChat runtime={runtime}>`               |
 
 ## Rich chat on Agent-Native {#rich-chat}
 
@@ -382,39 +165,99 @@ React widget, use [Generative UI](/docs/generative-ui): it renders sandboxed
 Alpine/Tailwind UI inline, can read app state and slot context, and can send
 selected values back to chat.
 
-## Rich chat on your agent {#byo-agent}
+## Native inline UI {#native-inline-ui}
 
-Use this path when your agent is already built with another framework or
-runtime and you want Agent-Native's chat UI around it. `AgentChatRuntime` is the
-boundary: your runtime streams normalized events, and Agent-Native renders the
-composer, transcript, tool calls, approvals, native widgets, and app layout.
+Use this when your actions return structured data — a list of records, a chart dataset, a status summary — that should render as a real UI component inside the chat thread rather than a plain text description. You define a `chatUI` renderer on the action, and Agent-Native renders it as a first-party React component: no iframes, no separate rendering path.
 
-```tsx
-import {
-  AssistantChat,
-  createHttpAgentChatRuntime,
-} from "@agent-native/core/client/chat";
+This is the right choice when the output has a clear, reusable shape that you'd design once and use across many agent responses. For controls the agent needs to create dynamically at runtime, see [Generated inline UI](#generated-inline-ui) instead.
 
-const runtime = createHttpAgentChatRuntime({
-  endpoint: "/api/support-agent/chat",
-});
+See [Native Chat UI](/docs/native-chat-ui) for the full renderer API, widget library, and BYO agent runtime integration.
 
-export function SupportAgentChat() {
-  return <AssistantChat runtime={runtime} threadId="support" />;
+## Generated inline UI {#generated-inline-ui}
+
+Use this when the agent needs to create a control that doesn't exist yet as a pre-built widget — a custom form, a picker built around the current context, a one-off calculator. Unlike native widgets, generated UI is composed by the agent at runtime from Alpine.js and Tailwind, runs sandboxed in an iframe, and can send selected values back into the chat thread.
+
+Generated UI can be transient (rendered once and discarded) or saved as a reusable extension that persists for the user.
+
+See [Generative UI](/docs/generative-ui) for the full API, sandbox constraints, and extension persistence model.
+
+## Full application {#full-application}
+
+Use the full app path when users need durable objects and workflows: forms,
+dashboards, calendars, inboxes, editors, documents, assets, or reports.
+
+Full apps add product UI around the same action and agent contract:
+
+<Cards>
+
+### SQL state
+
+App data, navigation, settings, and chat history are all durable. The agent reads and writes the same rows the UI does.
+
+### Context awareness
+
+The agent knows the current route, selection, and focused object, so "edit this" always means the right thing.
+
+### Live sync
+
+Agent changes update the UI in real time, and UI changes update the agent's context. No polling, no refresh.
+
+### Deep links
+
+Action results can open the right app view directly: a chart links to the dashboard, a draft links to the inbox.
+
+### Native chat widgets
+
+Tables, charts, cards, approvals, and typed results render as first-party React components inline in chat.
+
+### Generative UI and extensions
+
+The agent can create inline controls on the fly, and save reusable mini-apps when a workflow needs to persist.
+
+</Cards>
+
+Start from the [Chat template](/docs/template-chat) when you want a minimal app
+around your actions, or from a domain [template](/docs/cloneable-saas) when you
+want a complete product shape.
+
+### Full-page Manage Agent {#agent-page}
+
+Every Agent-Native app eventually needs a place where users can configure their agent: set standing instructions, review what it's done, connect MCP servers, manage automations, and control access. Building that UI from scratch is a lot of work. Agent-Native ships a pre-built full-page component, `AgentTabsPage`, that covers all of it across twelve tabs.
+
+Mount it at `/agent` in your app. Current templates pair that route with an app-navigation entry and pass `agentPageHref="/agent"` to `AgentSidebar`, so the sidebar's Resources and Settings modes can link to the full page without duplicating those flows.
+
+```tsx filename="app/routes/agent.tsx"
+import { AgentTabsPage } from "@agent-native/core/client/agent-chat";
+export default function AgentRoute() {
+  return <AgentTabsPage />;
 }
 ```
 
-Ready-made runtime helpers exist for OpenAI Agents, OpenAI Responses, the Claude
-Agent SDK, the Vercel AI SDK, and AG-UI, plus the normalized HTTP runtime above
-for any other agent (Mastra, Flue, Eve, LangGraph, or a custom service). ACP is
-not the end-user app chat or A2A transport, and Agent-Native does not currently
-claim A2UI support. ACP is supported in one specific place — driving a local
-coding agent (Gemini CLI, Claude Code, …) through the
-[harness layer](/docs/harness-agents#acp), not as the chat runtime here.
+The shared page currently provides twelve tabs across two groups:
 
-[Native Chat UI — BYO agent runtimes](/docs/native-chat-ui#byo-agent-runtimes)
-is the canonical home for the event shapes, the runtime helpers, and `chatUI`
-tool-result metadata. Start there when wiring an external agent into the chat.
+| Group     | Tab               | Shows                                                                                                                                                                                                                |
+| --------- | ----------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| Resources | **Files**         | The existing `ResourcesPanel` for personal or organization files                                                                                                                                                     |
+| Resources | **Instructions**  | Always-on AGENTS.md-style rules                                                                                                                                                                                      |
+| Resources | **Agents**        | Custom sub-agent profiles                                                                                                                                                                                            |
+| Resources | **Memory**        | Long-term recall notes                                                                                                                                                                                               |
+| Resources | **Skills**        | Reusable workflows                                                                                                                                                                                                   |
+| Resources | **Learnings**     | Corrections and patterns captured over time                                                                                                                                                                          |
+| Resources | **Remote agents** | A2A connections to other agent-native apps (replaces what the Connections tab used to show)                                                                                                                          |
+| Agent     | **Snapshots**     | A scope preview, token budget, ordered system sections grouped by provenance/governance/source, and the latest live-thread snapshot. Renamed from "Context"; old `#context` links redirect here.                     |
+| Agent     | **Connections**   | MCP server management only                                                                                                                                                                                           |
+| Agent     | **Automations**   | Personal and organization Scheduled/Event automations with pause/resume, details, and delete flows. The stable compatibility URL remains `/agent#jobs`.                                                              |
+| Agent     | **Settings**      | Agent model, API keys, limits, voice, and automation settings                                                                                                                                                        |
+| Agent     | **Access**        | The app MCP URL, an A2A agent card when available, and shared setup guides for Claude, ChatGPT, Cursor, Claude Code, Codex, and other clients. Links to `/mcp/connect` for the full connect flow and token fallback. |
+
+The page shows personal (`user`-scope) data only. There is no org-level toggle today. It is a thin shell over existing components and access checks, not a new admin console: Connections describes what the app can call; Access describes how external clients connect to it.
+
+Not yet included:
+
+- Organization-scoped view
+- Grants and scope editing
+- Revocation UI
+- Per-iteration provenance history
 
 ## Embedded sidecar {#embedded-sidecar}
 
@@ -456,6 +299,10 @@ export function AppShell({ children }) {
 }
 ```
 
+### How it connects
+
+The two pieces work as a bridge: the host app passes page context (current route, selected text, focused object) into `AgentNativeEmbedded`, and the agent sends commands back out through `onNavigate` and `onRefresh`. The server plugin handles identity — it resolves the host session so the agent acts as the right user without a separate login. Nothing in the host app needs to change; the plugin attaches Agent-Native's routes alongside your existing ones.
+
 <Diagram id="doc-block-27ug5y" title="How the sidecar bridges to a host app" summary={"The plugin mounts Agent-Native routes server-side; the React sidecar streams page context in and host commands out."}>
 
 ```html
@@ -518,46 +365,222 @@ export function AppShell({ children }) {
 See [Embedding SDK](/docs/embedding-sdk) for host auth, database isolation,
 iframe/picker mode, and lower-level bridge APIs.
 
-## Full application {#full-application}
+## Automation-first app {#headless}
 
-Use the full app path when users need durable objects and workflows: forms,
-dashboards, calendars, inboxes, editors, documents, assets, or reports.
+Use the automation-first path when no one needs a custom browser screen while
+the work runs: scheduled jobs, integrations, backend workflows, CLI loops,
+another agent, or an existing product calling into Agent-Native.
 
-Full apps add product UI around the same action and agent contract:
+This is the shape to reach for when automation is the product surface. You send a request from the terminal, Slack, email, a scheduled job, another agent, or Chat ("summarize my unread emails," "post the daily metrics to Slack," "find the candidates who replied last week") and the agent acts and returns the result wherever it belongs. It is still a real app, not a stateless prompt:
+actions, auth sessions, app state, thread/run history, settings, credentials,
+and share records all live in SQL.
 
-- **SQL state** — app data, navigation, settings, and chat history are durable.
-- **Context awareness** — the agent knows the current route, selection, and focused object.
-- **Live sync** — agent changes update the UI, and UI changes update the agent's context.
-- **Deep links** — action results can open the right app view.
-- **Native chat widgets** — tables, charts, cards, approvals, and typed results appear inline.
-- **Generative UI and extensions** — the agent can create inline controls now
-  and save reusable mini-apps when the workflow needs to persist.
+Pick this pattern when:
 
-Start from the [Chat template](/docs/template-chat) when you want a minimal app
-around your actions, or from a domain [template](/docs/cloneable-saas) when you
-want a complete product shape.
+- **The work happens in the background.** Most of the value is created while the user isn't looking: triage agents, daily-report agents, on-call responders.
+- **The output leaves the app.** The agent posts to Slack, sends email, or updates a third-party system; there's nothing to browse in-app.
+- **The domain is one-shot.** Research bot, summary generator, report writer with no persistent object that needs a list view.
+- **You're prototyping an automation.** Ship the operation now; add chat or app pages when users need to inspect and steer it.
+
+If your product is built around persistent objects users browse, pivot, and share (emails, events, documents, charts), pick a [full application](#full-application) or a [template](/docs/cloneable-saas) instead; those add a full UI _plus_ the agent.
+
+### What ships in the box {#in-the-box}
+
+An automation-first app skips dashboard work, and it is channel-agnostic from day one. The same agent runs from the web, Slack, Telegram, email, and other agents because everything goes through the same actions. The trade-off is there is no "browse-everything-at-a-glance" view; if users need that, start from [Chat](/docs/template-chat) or add a small status page or list view.
+
+When you add the built-in Chat shell, the framework provides five management surfaces you don't have to build: **Chat** (the main input), **Resources** (skills, memory, instructions, sub-agents, and connected MCP servers), **Automations**, **Thread history**, and **Settings**. Those are usually enough: talk to it, see what it's done, configure how it behaves. Reach for
+[Chat](/docs/template-chat) when you're ready to add that browser UI, or the
+[Dispatch template](/docs/template-dispatch) for a workspace-style starting
+point with Slack/Telegram, scheduled jobs, and shared secrets out of the box.
+
+The smallest no-browser local path is a scaffold plus one action:
+
+```bash
+npx @agent-native/core@latest create my-agent --headless
+cd my-agent
+pnpm install
+```
+
+Then define the durable operation:
+
+```ts filename="actions/summarize-week.ts"
+import { defineAction } from "@agent-native/core/action";
+import { z } from "zod";
+
+export default defineAction({
+  description: "Summarize this week's submissions.",
+  readOnly: true,
+  schema: z.object({ formId: z.string() }),
+  run: async ({ formId }) => {
+    return { formId, summary: "34 submissions, up 18% from last week." };
+  },
+});
+```
+
+One action is then callable as:
+
+- **HTTP:** `POST /_agent-native/actions/summarize-week`
+- **CLI:** `pnpm action summarize-week --formId form_123`
+- **App-agent CLI:** `pnpm agent "Summarize form_123"`
+- **MCP:** from Claude, ChatGPT, Codex, Cursor, OpenCode, Copilot, and other MCP hosts
+- **A2A:** from another agent-native app or agent peer
+- **UI:** through `useActionQuery`, `useActionMutation`, or `callAction`
+- **Agent tool:** from the built-in chat loop
+
+<Endpoint id="doc-block-kdx289" title="Calling an action over HTTP" method="POST" path="/_agent-native/actions/summarize-week" summary="Invoke any action by name over HTTP" request={{
+  "contentType": "application/json",
+  "example": "{ \"formId\": \"form_123\" }"
+}} responses={[
+  {
+    "status": "200",
+    "description": "The action's return value as JSON",
+    "example": "{ \"formId\": \"form_123\", \"summary\": \"34 submissions, up 18% from last week.\" }"
+  },
+  {
+    "status": "400",
+    "description": "Input failed schema validation"
+  }
+]}>
+
+Every `defineAction` is auto-mounted at `/_agent-native/actions/<name>`. The JSON body is validated against the action's zod schema before `run` executes. To call it from an external system with a long-lived bearer token, see [HTTP API](/docs/http-api).
+
+</Endpoint>
+
+This is not a no-database or stateless mode. The app-agent loop stores sessions,
+threads, runs, settings, credentials, application state, and share records in
+SQL. Local development defaults to SQLite; hosted automation-first apps should
+use a persistent SQL database.
+
+If you need the whole agent loop headlessly from the project folder, use:
+
+```bash
+pnpm agent "Summarize this week's forms."
+```
+
+If another app or script needs to call the whole agent, use
+`agentNative.invoke("analytics", "...")` or the `agent-native invoke` CLI. That
+keeps cross-app work on the A2A path while local work stays on actions.
+
+Workers, jobs, integration webhooks, and custom hosts can drive the agent loop
+directly through the server API. This is lower-level than actions — you provide
+the engine, model, messages, tools, actions, an event sink, and an abort signal
+yourself:
+
+```ts
+import { runAgentLoop } from "@agent-native/core/server";
+
+await runAgentLoop({
+  engine,
+  model,
+  systemPrompt,
+  tools,
+  actions,
+  messages,
+  send,
+  signal,
+});
+```
+
+For most apps, scheduled prompts and integration webhooks already call this loop
+for you. Reach for it directly only when building a custom no-browser host, eval
+runner, or server-side orchestration surface. See [Server: Production agent handler](/docs/server#agent-handler) for the full signature.
+
+### Running against a folder {#folder-loop}
+
+If your goal is "run an agent against this folder," start with the app-agent
+loop in that folder: scaffold the automation-first app, add actions/instructions, run
+`pnpm agent "..."`. That keeps the work inside the same action/runtime/state
+contract the app will use in production.
+
+External coding harnesses are a separate product surface for embedding Claude
+Code, Codex, Pi, Cursor, Mastra, or similar runtimes inside an Agent-Native app.
+Use them when you are building a coding-agent product, not as the default way to
+start a local agent-native workflow.
+
+### Cloud repo access {#cloud-repo-access}
+
+For cloud automation-first apps that need repository access, use the GitHub connector
+plus token CRUD model: list repositories, search files, read files, create or
+edit files, delete files, and revoke access through provider-scoped
+credentials. In local development, set the target repository explicitly:
+
+```bash
+GITHUB_REPOSITORY=owner/repo pnpm agent "Read README.md and suggest the next action."
+```
+
+Do not treat a VM clone or long-lived sandbox checkout as the primary cloud
+repo-access model. Sandboxes still matter for isolated code execution, but
+repository access should be explicit, permissioned, auditable, and revocable
+through the connector layer.
 
-## How to choose {#how-to-choose}
+### Sharing sessions and runs {#sharing-runs}
 
-| If you are thinking...                                           | Choose                    |
-| ---------------------------------------------------------------- | ------------------------- |
-| "I want the framework's agent, but chat should be the main UI."  | Rich chat on Agent-Native |
-| "The action result should be a chart, table, or typed card."     | Native inline UI          |
-| "I want the agent to make an interactive control right now."     | Generated inline UI       |
-| "The agent and UI should evolve together as the product."        | Full application          |
-| "I already have a SaaS app; add an agent beside it."             | Embedded sidecar          |
-| "I need a callable workflow for jobs, scripts, or other agents." | Automation-first app      |
-| "I already have an agent; I need a polished chat UI for it."     | Rich chat on your agent   |
+Automation-first sessions and runs are durable objects. Shareability should be
+phased: read/share links first, so teammates can inspect sanitized prompts,
+outputs, and run status; permissioned writable collaboration later, so
+continuing a run, approving actions, editing schedules, or changing
+configuration goes through explicit access checks.
 
-Keep the contract small: define durable operations as actions, return explicit
-widget results when chat needs rich UI, and add full screens only when users
-need to browse, compare, configure, or collaborate over persistent objects.
+## Rich chat on your agent {#byo-agent}
+
+Use this path when your agent is already built with another framework or
+runtime and you want Agent-Native's chat UI around it. `AgentChatRuntime` is the
+boundary: your runtime streams normalized events, and Agent-Native renders the
+composer, transcript, tool calls, approvals, native widgets, and app layout.
+
+```tsx
+import {
+  AssistantChat,
+  createHttpAgentChatRuntime,
+} from "@agent-native/core/client/chat";
+
+const runtime = createHttpAgentChatRuntime({
+  endpoint: "/api/support-agent/chat",
+});
+
+export function SupportAgentChat() {
+  return <AssistantChat runtime={runtime} threadId="support" />;
+}
+```
+
+Ready-made runtime helpers exist for OpenAI Agents, OpenAI Responses, the Claude
+Agent SDK, the Vercel AI SDK, and AG-UI, plus the normalized HTTP runtime above
+for any other agent (Mastra, Flue, Eve, LangGraph, or a custom service). ACP is
+not the end-user app chat or A2A transport, and Agent-Native does not currently
+claim A2UI support. ACP is supported in one specific place: driving a local
+coding agent (Gemini CLI, Claude Code, …) through the
+[harness layer](/docs/harness-agents#acp), not as the chat runtime here.
+
+[Native Chat UI: BYO agent runtimes](/docs/native-chat-ui#byo-agent-runtimes)
+is the canonical home for the event shapes, the runtime helpers, and `chatUI`
+tool-result metadata. Start there when wiring an external agent into the chat.
 
 ## What's next {#related-docs}
 
-- [**Actions**](/docs/actions) — define the operation once; every surface above calls the same one
-- [**Native Chat UI**](/docs/native-chat-ui) — render typed action results as tables, charts, and cards in chat
-- [**Generative UI**](/docs/generative-ui) — generate transient or persisted sandboxed UI inline in chat
-- [**Automation-First Apps**](/docs/pure-agent-apps) — the full no-browser pattern for jobs, queues, scripts, and external agents
-- [**External Agents**](/docs/external-agents) — connect MCP-compatible hosts to an app
-- [**A2A Protocol**](/docs/a2a-protocol) — call agents from other agent-native apps
+<Cards>
+
+### [Actions](/docs/actions)
+
+Define the operation once. Every surface above calls the same one.
+
+### [Native Chat UI](/docs/native-chat-ui)
+
+Render typed action results as tables, charts, and cards directly in chat.
+
+### [Generative UI](/docs/generative-ui)
+
+Generate transient or persisted sandboxed UI inline in chat.
+
+### [Automation-First Apps](/docs/pure-agent-apps)
+
+The full no-browser pattern for jobs, queues, scripts, and external agents.
+
+### [External Agents](/docs/external-agents)
+
+Connect MCP-compatible hosts to your app as a tool server.
+
+### [A2A Protocol](/docs/a2a-protocol)
+
+Call agents from other agent-native apps over the A2A standard.
+
+</Cards>

package/package.json

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