@agent-native/core 0.136.5 → 0.137.0

package/dist/onboarding/plugin.js

@@ -7,11 +7,13 @@
  *   POST /_agent-native/onboarding/dismiss            — dismiss the banner
  *   GET  /_agent-native/onboarding/dismissed          — dismissed flag + allComplete
  */
-import { defineEventHandler, getMethod, getQuery, setResponseStatus, } from "h3";
+import { deleteCookie, defineEventHandler, getMethod, getQuery, setResponseStatus, } from "h3";
 import { appStateGet, appStatePut } from "../application-state/store.js";
 import { getSession } from "../server/auth.js";
 import { awaitBootstrap, getH3App, markDefaultPluginProvided, } from "../server/framework-request-handler.js";
 import { runWithRequestContext } from "../server/request-context.js";
+import { FIRST_RUN_ONBOARDING_COOKIE } from "../shared/first-run-onboarding.js";
+import { getOnboardingAppProfile } from "./app-profile.js";
 import { registerDefaultOnboardingSteps } from "./default-steps.js";
 import { listOnboardingSteps } from "./registry.js";
 const ONBOARDING_PREFIX = "/_agent-native/onboarding";
@@ -89,6 +91,7 @@ export function createOnboardingPlugin(options = {}) {
     return async (nitroApp) => {
         markDefaultPluginProvided(nitroApp, "onboarding");
         await awaitBootstrap(nitroApp);
+        const appProfile = getOnboardingAppProfile(options.appId);
         if (!options.skipDefaultSteps) {
             registerDefaultOnboardingSteps();
         }
@@ -178,6 +181,23 @@ export function createOnboardingPlugin(options = {}) {
                 return { dismissed: false, allComplete: false };
             }
         }));
+        // GET /_agent-native/onboarding/profile
+        getH3App(nitroApp).use(`${ONBOARDING_PREFIX}/profile`, defineEventHandler(async (event) => {
+            if (getMethod(event) !== "GET") {
+                setResponseStatus(event, 405);
+                return { error: "Method not allowed" };
+            }
+            return appProfile;
+        }));
+        // POST /_agent-native/onboarding/first-run/complete
+        getH3App(nitroApp).use(`${ONBOARDING_PREFIX}/first-run/complete`, defineEventHandler(async (event) => {
+            if (getMethod(event) !== "POST") {
+                setResponseStatus(event, 405);
+                return { error: "Method not allowed" };
+            }
+            deleteCookie(event, FIRST_RUN_ONBOARDING_COOKIE, { path: "/" });
+            return { ok: true };
+        }));
     };
 }
 /** Default plugin instance — mounted automatically when a template doesn't override. */

package/dist/onboarding/types.d.ts

@@ -84,4 +84,23 @@ export interface OnboardingStepStatus {
     complete: boolean;
     methods: OnboardingMethod[];
 }
+export interface OnboardingCapability {
+    /** Stable capability id used by the profile and analytics. */
+    id: string;
+    /** Short label shown in the setup choice and BYOK list. */
+    label: string;
+    /** Whether this capability blocks the app's normal setup. */
+    required: boolean;
+    /** Whether Builder's managed connection covers this capability. */
+    builderIncluded: boolean;
+    /** Compact description of the key or connection the BYOK path needs. */
+    keySummary: string;
+    /** Hover/focus explanation for why the capability exists. */
+    why: string;
+}
+export interface OnboardingAppProfile {
+    appId: string;
+    appName: string;
+    capabilities: OnboardingCapability[];
+}
 //# sourceMappingURL=types.d.ts.map

package/dist/progress/routes.d.ts

@@ -15,7 +15,7 @@ export declare function createProgressHandler(): import("h3").EventHandlerWithFe
     error: string;
     ok?: undefined;
 } | {
-    error?: undefined;
     ok: boolean;
+    error?: undefined;
 }>>;
 //# sourceMappingURL=routes.d.ts.map

package/dist/provider-api/actions/custom-provider-registration.d.ts

@@ -75,6 +75,8 @@ export declare function createCustomProviderRegistrationAction<TSchema extends Z
         user: "user";
     }>>;
 }, z.core.$strip>>, {
+    id?: undefined;
+    provider?: undefined;
     deleted?: undefined;
     found?: undefined;
     providers: {
@@ -87,26 +89,24 @@ export declare function createCustomProviderRegistrationAction<TSchema extends Z
         updatedAt: number;
     }[];
     count: number;
-    provider?: undefined;
     registered?: undefined;
-    id?: undefined;
     label?: undefined;
     message?: undefined;
 } | {
-    deleted?: undefined;
     count?: undefined;
+    id?: undefined;
+    deleted?: undefined;
     providers?: undefined;
     found: boolean;
     provider: import("../custom-registry.js").CustomProviderConfig;
     registered?: undefined;
-    id?: undefined;
     label?: undefined;
     message?: undefined;
 } | {
-    deleted?: undefined;
     count?: undefined;
-    providers?: undefined;
     provider?: undefined;
+    deleted?: undefined;
+    providers?: undefined;
     found: boolean;
     id: string;
     registered?: undefined;
@@ -114,20 +114,20 @@ export declare function createCustomProviderRegistrationAction<TSchema extends Z
     message?: undefined;
 } | {
     count?: undefined;
+    provider?: undefined;
     found?: undefined;
     providers?: undefined;
-    provider?: undefined;
     deleted: boolean;
     id: string;
     registered?: undefined;
     label?: undefined;
     message?: undefined;
 } | {
-    deleted?: undefined;
     count?: undefined;
+    provider?: undefined;
+    deleted?: undefined;
     found?: undefined;
     providers?: undefined;
-    provider?: undefined;
     registered: boolean;
     id: string;
     label: string;

package/dist/provider-api/actions/provider-api.d.ts

@@ -311,9 +311,8 @@ export declare function createProviderApiActions(runtime: Pick<ProviderApiRuntim
         notes?: string | undefined;
         scope?: "org" | "user" | undefined;
     }, {
+        message?: undefined;
         id?: undefined;
-        provider?: undefined;
-        deleted?: undefined;
         found?: undefined;
         providers: {
             id: string;
@@ -325,45 +324,46 @@ export declare function createProviderApiActions(runtime: Pick<ProviderApiRuntim
             updatedAt: number;
         }[];
         count: number;
+        provider?: undefined;
+        deleted?: undefined;
         registered?: undefined;
         label?: undefined;
-        message?: undefined;
     } | {
+        message?: undefined;
         id?: undefined;
-        deleted?: undefined;
         count?: undefined;
         providers?: undefined;
         found: boolean;
         provider: import("../custom-registry.js").CustomProviderConfig;
+        deleted?: undefined;
         registered?: undefined;
         label?: undefined;
-        message?: undefined;
     } | {
-        provider?: undefined;
-        deleted?: undefined;
+        message?: undefined;
         count?: undefined;
         providers?: undefined;
+        provider?: undefined;
         found: boolean;
         id: string;
+        deleted?: undefined;
         registered?: undefined;
         label?: undefined;
-        message?: undefined;
     } | {
-        provider?: undefined;
+        message?: undefined;
         found?: undefined;
         count?: undefined;
         providers?: undefined;
+        provider?: undefined;
         deleted: boolean;
         id: string;
         registered?: undefined;
         label?: undefined;
-        message?: undefined;
     } | {
-        provider?: undefined;
-        deleted?: undefined;
         found?: undefined;
         count?: undefined;
         providers?: undefined;
+        provider?: undefined;
+        deleted?: undefined;
         registered: boolean;
         id: string;
         label: string;

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<{
-    error: string;
     ok?: undefined;
+    error: string;
 } | {
     error?: undefined;
     ok: boolean;

package/dist/server/auth.js

@@ -2,6 +2,7 @@ import crypto from "node:crypto";
 import { defineEventHandler, getMethod, getQuery, getRequestIP, setResponseHeader, setResponseStatus, getCookie, setCookie, deleteCookie, getHeader, } from "h3";
 import { EMBED_START_PATH } from "../shared/embed-auth.js";
 import { EMBED_TARGET_HEADER } from "../shared/embed-auth.js";
+import { FIRST_RUN_ONBOARDING_COOKIE, FIRST_RUN_ONBOARDING_MAX_AGE, } from "../shared/first-run-onboarding.js";
 import { EMBED_TRANSPLANT_HEADER, isMcpEmbedCorsOrigin, MCP_EMBED_CORS_ALLOW_HEADERS, shouldAllowMcpEmbedCredentials, } from "../shared/mcp-embed-headers.js";
 import { isEmbedCapabilityScope, requestHasEmbedAuthMarker, resolveEmbedSessionFromRequest, } from "./embed-session.js";
 // In h3 v2, `event.req` IS the web Request — but in Nitro's dev server (srvx
@@ -1880,6 +1881,14 @@ function crossSiteCookieAttrs(event) {
         ? { sameSite: "none", secure: true, partitioned: true }
         : { sameSite: "lax", secure: false };
 }
+function setFirstRunOnboardingCookie(event) {
+    setCookie(event, FIRST_RUN_ONBOARDING_COOKIE, "1", {
+        ...crossSiteCookieAttrs(event),
+        httpOnly: false,
+        path: "/",
+        maxAge: FIRST_RUN_ONBOARDING_MAX_AGE,
+    });
+}
 export function setFrameworkSessionCookie(event, token) {
     clearFrameworkSessionCookies(event);
     setCookie(event, COOKIE_NAME, token, {
@@ -2293,11 +2302,14 @@ async function mountBetterAuthRoutes(app, options) {
                 if (!googleAccountId) {
                     throw new Error("Could not get Google account id");
                 }
-                await ensureGoogleAuthIdentity({
+                const isNewGoogleUser = await ensureGoogleAuthIdentity({
                     email,
                     accountId: googleAccountId,
                     name: typeof user.name === "string" ? user.name : undefined,
                 });
+                if (isNewGoogleUser === true) {
+                    setFirstRunOnboardingCookie(event);
+                }
                 if (typeof user.picture === "string" && user.picture.trim()) {
                     await putSetting(`avatar:${email}`, {
                         image: user.picture,
@@ -2633,6 +2645,12 @@ async function mountBetterAuthRoutes(app, options) {
                 // Best-effort — don't block the response
             }
         }
+        if (reqPath.includes("/sign-up/email") &&
+            isResponse &&
+            response.status >= 200 &&
+            response.status < 300) {
+            setFirstRunOnboardingCookie(event);
+        }
         return response;
     }));
     // Backward-compat: POST /_agent-native/auth/login
@@ -2721,6 +2739,7 @@ async function mountBetterAuthRoutes(app, options) {
                 body: { email, password, name: email.split("@")[0], callbackURL },
                 headers: event.headers,
             });
+            setFirstRunOnboardingCookie(event);
             return { ok: true };
         }
         catch (e) {
@@ -2939,6 +2958,7 @@ function mountAuthFallbackRoutes(app) {
                 body: { email, password, name: email.split("@")[0] },
                 headers: event.headers,
             });
+            setFirstRunOnboardingCookie(event);
             return { ok: true };
         }
         catch (e) {

package/dist/server/better-auth-instance.d.ts

@@ -193,9 +193,10 @@ export interface GoogleAuthIdentity {
  * Ensure a verified Google identity has a canonical Better Auth user/account
  * before the legacy email-keyed session is issued. This prevents a later
  * password signup from becoming the first canonical identity for that email.
+ * Returns whether this call created the canonical user.
  */
-export declare function ensureGoogleAuthIdentity(identity: GoogleAuthIdentity): Promise<void>;
-export declare function ensureGoogleAuthIdentityWithAdapter(adapter: BetterAuthInternalAdapter, identity: GoogleAuthIdentity): Promise<void>;
+export declare function ensureGoogleAuthIdentity(identity: GoogleAuthIdentity): Promise<boolean>;
+export declare function ensureGoogleAuthIdentityWithAdapter(adapter: BetterAuthInternalAdapter, identity: GoogleAuthIdentity): Promise<boolean>;
 /** Reset for testing */
 export declare function resetBetterAuth(): Promise<void>;
 /**

package/dist/server/better-auth-instance.js

@@ -709,13 +709,14 @@ export async function getBetterAuthInternalAdapter(config) {
  * Ensure a verified Google identity has a canonical Better Auth user/account
  * before the legacy email-keyed session is issued. This prevents a later
  * password signup from becoming the first canonical identity for that email.
+ * Returns whether this call created the canonical user.
  */
 export async function ensureGoogleAuthIdentity(identity) {
     const adapter = await getBetterAuthInternalAdapter();
     if (!adapter) {
         throw new Error("Better Auth internal adapter is unavailable");
     }
-    await ensureGoogleAuthIdentityWithAdapter(adapter, identity);
+    return ensureGoogleAuthIdentityWithAdapter(adapter, identity);
 }
 export async function ensureGoogleAuthIdentityWithAdapter(adapter, identity) {
     const email = identity.email.trim().toLowerCase();
@@ -731,13 +732,13 @@ export async function ensureGoogleAuthIdentityWithAdapter(adapter, identity) {
         if (!existing || linkedAccount.userId !== existing.user.id) {
             throw new Error("Google account is already linked to another user");
         }
-        return;
+        return false;
     }
     if (!existing) {
         if (adapter.createOAuthUser) {
             try {
                 await adapter.createOAuthUser({ email, name, emailVerified: true }, { providerId: "google", accountId });
-                return;
+                return true;
             }
             catch (error) {
                 // A concurrent first sign-in may have won the unique-email race. Only
@@ -754,7 +755,7 @@ export async function ensureGoogleAuthIdentityWithAdapter(adapter, identity) {
                     if (linkedAccount.userId !== existing.user.id) {
                         throw new Error("Google account is already linked to another user");
                     }
-                    return;
+                    return false;
                 }
             }
         }
@@ -769,7 +770,7 @@ export async function ensureGoogleAuthIdentityWithAdapter(adapter, identity) {
                 providerId: "google",
                 accountId,
             });
-            return;
+            return true;
         }
     }
     if (!existing) {
@@ -777,7 +778,7 @@ export async function ensureGoogleAuthIdentityWithAdapter(adapter, identity) {
     }
     const alreadyLinked = existing.accounts.some((account) => account.providerId === "google" && account.accountId === accountId);
     if (alreadyLinked)
-        return;
+        return false;
     // A password signup reserves the email before verification. If that row is
     // credential-only, remove the unverified credential and promote the same
     // canonical user to the verified Google identity. Any other linked account
@@ -793,13 +794,14 @@ export async function ensureGoogleAuthIdentityWithAdapter(adapter, identity) {
             email,
             accountId,
         });
-        return;
+        return false;
     }
     await adapter.linkAccount({
         userId: existing.user.id,
         providerId: "google",
         accountId,
     });
+    return false;
 }
 /** Reset for testing */
 export async function resetBetterAuth() {

package/dist/server/email-markdown.js

@@ -25,14 +25,9 @@ function inlineMarkdown(value) {
             trailing = url.slice(-1) + trailing;
             url = url.slice(0, -1);
         }
-        let label = "Open link";
-        const normalizedUrl = url.replace(/&/g, "&");
-        if (URL.canParse(normalizedUrl)) {
-            const host = new URL(normalizedUrl).hostname.replace(/^www\./, "");
-            if (host)
-                label = `Open ${host}`;
-        }
-        return `${prefix}<a href="${url}" style="color:${EMAIL_TEXT};text-decoration:underline;">${label}</a>${trailing}`;
+        // A bare URL stays its own link text: a recipient who cannot read the
+        // destination cannot tell a digest link from a phishing one.
+        return `${prefix}<a href="${url}" style="color:${EMAIL_TEXT};text-decoration:underline;">${url}</a>${trailing}`;
     });
     html = html
         .replace(/`([^`]+)`/g, `<code style="background:${EMAIL_CODE};padding:2px 5px;border-radius:4px;font-size:0.92em;">$1</code>`)

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

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

package/dist/shared/first-run-onboarding.d.ts

@@ -0,0 +1,3 @@
+export declare const FIRST_RUN_ONBOARDING_COOKIE = "agent-native-first-run";
+export declare const FIRST_RUN_ONBOARDING_MAX_AGE: number;
+//# sourceMappingURL=first-run-onboarding.d.ts.map

package/dist/shared/first-run-onboarding.js

@@ -0,0 +1,3 @@
+export const FIRST_RUN_ONBOARDING_COOKIE = "agent-native-first-run";
+export const FIRST_RUN_ONBOARDING_MAX_AGE = 24 * 60 * 60;
+//# sourceMappingURL=first-run-onboarding.js.map

package/dist/triggers/index.d.ts

@@ -2,4 +2,7 @@ export type { TriggerFrontmatter, TriggerDispatchContext } from "./types.js";
 export { initTriggerDispatcher, refreshEventSubscriptions, parseTriggerFrontmatter, buildTriggerContent, type TriggerDispatcherDeps, } from "./dispatcher.js";
 export { evaluateCondition, __clearConditionCache, } from "./condition-evaluator.js";
 export { createAutomationToolEntries } from "./actions.js";
+export { defineAutomation, listAutomationDefinitions, updateAutomation, type AutomationActor, type AutomationDefinition, } from "../automations/service.js";
+export { queueAutomationRunNow } from "../jobs/run-now.js";
+export { listAutomationRuns } from "../jobs/run-history.js";
 //# sourceMappingURL=index.d.ts.map

package/dist/triggers/index.js

@@ -1,4 +1,9 @@
 export { initTriggerDispatcher, refreshEventSubscriptions, parseTriggerFrontmatter, buildTriggerContent, } from "./dispatcher.js";
 export { evaluateCondition, __clearConditionCache, } from "./condition-evaluator.js";
 export { createAutomationToolEntries } from "./actions.js";
+// Template-native automation surfaces use the same organization-scoped
+// service and run history as the framework Agent page.
+export { defineAutomation, listAutomationDefinitions, updateAutomation, } from "../automations/service.js";
+export { queueAutomationRunNow } from "../jobs/run-now.js";
+export { listAutomationRuns } from "../jobs/run-history.js";
 //# sourceMappingURL=index.js.map

package/docs/content/cross-app-sso.mdx

@@ -15,6 +15,32 @@ This is the same trust primitive [A2A](/docs/a2a-protocol) and [External Agents]
 
 </Callout>
 
+## What the user sees {#user-flow}
+
+Cross-App SSO should feel like moving between products in one workspace, not
+creating a second account. For example:
+
+1. Sign in to [Dispatch](https://dispatch.agent-native.com), or to any app
+   that already uses the workspace identity.
+2. Open [Mail](https://mail.agent-native.com), [Calendar](https://calendar.agent-native.com),
+   or another enabled app in a new tab.
+3. The app sends the browser to Dispatch only if it does not already have a
+   Dispatch session. If the session exists, the redirect is effectively
+   invisible.
+4. Return to the app already signed in, with the same email, records, and org
+   context as before.
+
+The important distinction is that this is **one sign-in, not one shared
+cookie**. Each separately hosted app still creates and owns its own local
+session. Dispatch proves the user's identity at the app's front door, and the
+app then continues with its normal local auth and access checks.
+
+For a product walkthrough, record this exact sequence: sign in once in
+Dispatch, open two other hosted apps, show that neither asks for credentials,
+then sign out of one app and show that the other app's session is independent.
+That last step makes the security boundary visible: SSO removes repeated
+logins without turning every app into one shared session store.
+
 ## What & why {#what-why}
 
 Per-app user stores mean there is no single place a browser cookie could live that every app trusts. The federation model instead names one app — **Dispatch** — as the identity authority. Any other app can delegate "who is this person?" to Dispatch, get back a short-lived signed assertion of the user's verified email, and then **link that to its own local account by email**.

package/package.json

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