@agent-native/core 0.136.4 → 0.137.0

package/dist/onboarding/app-profile.js

@@ -0,0 +1,378 @@
+const LLM_CAPABILITY = {
+    id: "llm",
+    label: "AI model",
+    required: true,
+    builderIncluded: true,
+    keySummary: "One model key: Anthropic, OpenAI, Gemini, Groq, Mistral, or Cohere",
+    why: "The agent uses a language model to understand requests and produce answers.",
+};
+const PROFILES = {
+    analytics: {
+        appId: "analytics",
+        appName: "Analytics",
+        capabilities: [
+            LLM_CAPABILITY,
+            {
+                id: "data-sources",
+                label: "Data sources",
+                required: false,
+                builderIncluded: false,
+                keySummary: "Connectors are added individually in Settings",
+                why: "Only needed for the services you want to query, such as GA4, Stripe, or HubSpot.",
+            },
+            {
+                id: "replay-storage",
+                label: "Replay storage",
+                required: false,
+                builderIncluded: true,
+                keySummary: "S3-compatible bucket, access key, and secret",
+                why: "Only needed when session replay is enabled so recordings can be stored.",
+            },
+        ],
+    },
+    assets: {
+        appId: "assets",
+        appName: "Assets",
+        capabilities: [
+            {
+                id: "media-generation",
+                label: "Image and video generation",
+                required: true,
+                builderIncluded: true,
+                keySummary: "Gemini for video, or OpenAI / Gemini for images",
+                why: "These providers create the images and videos requested in the app.",
+            },
+            {
+                id: "file-storage",
+                label: "Media storage",
+                required: true,
+                builderIncluded: true,
+                keySummary: "S3-compatible endpoint, bucket, access key, and secret",
+                why: "Generated files need a durable place to live before they can be shared.",
+            },
+        ],
+    },
+    brain: {
+        appId: "brain",
+        appName: "Brain",
+        capabilities: [
+            LLM_CAPABILITY,
+            {
+                id: "embeddings",
+                label: "Embeddings",
+                required: false,
+                builderIncluded: true,
+                keySummary: "Gemini, Cohere, or Voyage key",
+                why: "Embeddings improve semantic search. Keyword search still works without them.",
+            },
+            {
+                id: "source-connections",
+                label: "Source connections",
+                required: false,
+                builderIncluded: false,
+                keySummary: "Slack, Granola, or GitHub connection",
+                why: "Only needed for the sources you want to ingest into your knowledge base.",
+            },
+        ],
+    },
+    calendar: {
+        appId: "calendar",
+        appName: "Calendar",
+        capabilities: [
+            LLM_CAPABILITY,
+            {
+                id: "google-calendar",
+                label: "Google Calendar",
+                required: false,
+                builderIncluded: false,
+                keySummary: "Connect Google Calendar with OAuth",
+                why: "Calendar access is an OAuth connection, not an API key to paste.",
+            },
+            {
+                id: "calendar-connectors",
+                label: "Other calendar connections",
+                required: false,
+                builderIncluded: false,
+                keySummary: "Zoom, CRM, or enrichment connection",
+                why: "Only needed for the provider features you turn on.",
+            },
+        ],
+    },
+    chat: {
+        appId: "chat",
+        appName: "Chat",
+        capabilities: [LLM_CAPABILITY],
+    },
+    clips: {
+        appId: "clips",
+        appName: "Clips",
+        capabilities: [
+            LLM_CAPABILITY,
+            {
+                id: "video-storage",
+                label: "Video storage",
+                required: true,
+                builderIncluded: true,
+                keySummary: "S3 endpoint, bucket, access key, and secret",
+                why: "Recorded videos need durable storage before they can be played back or shared.",
+            },
+            {
+                id: "transcription",
+                label: "Transcription",
+                required: false,
+                builderIncluded: true,
+                keySummary: "Groq or Google Speech key",
+                why: "Transcription powers captions, titles, summaries, and searchable chapters. Native capture still works without it.",
+            },
+        ],
+    },
+    content: {
+        appId: "content",
+        appName: "Content",
+        capabilities: [
+            LLM_CAPABILITY,
+            {
+                id: "media-storage",
+                label: "Media storage",
+                required: false,
+                builderIncluded: true,
+                keySummary: "Builder file storage or S3-compatible storage",
+                why: "Only needed for documents that contain uploaded images, video, or audio.",
+            },
+            {
+                id: "notion",
+                label: "Notion",
+                required: false,
+                builderIncluded: false,
+                keySummary: "Connect Notion with OAuth",
+                why: "Only needed if you want to import or sync workspace content from Notion.",
+            },
+        ],
+    },
+    crm: {
+        appId: "crm",
+        appName: "CRM",
+        capabilities: [
+            LLM_CAPABILITY,
+            {
+                id: "crm-connection",
+                label: "CRM connection",
+                required: false,
+                builderIncluded: false,
+                keySummary: "Connect HubSpot or Salesforce",
+                why: "Connections are shared securely with CRM; no provider token needs to be pasted here.",
+            },
+        ],
+    },
+    design: {
+        appId: "design",
+        appName: "Design",
+        capabilities: [
+            LLM_CAPABILITY,
+            {
+                id: "assets-library",
+                label: "Assets library",
+                required: false,
+                builderIncluded: true,
+                keySummary: "Connect the Assets app",
+                why: "Only needed when designs use managed images or other media assets.",
+            },
+            {
+                id: "figma",
+                label: "Figma",
+                required: false,
+                builderIncluded: false,
+                keySummary: "Figma personal access token",
+                why: "Only needed to read or update files in Figma.",
+            },
+            {
+                id: "github",
+                label: "GitHub",
+                required: false,
+                builderIncluded: false,
+                keySummary: "GitHub token",
+                why: "Only needed when designs are connected to a repository.",
+            },
+        ],
+    },
+    dispatch: {
+        appId: "dispatch",
+        appName: "Dispatch",
+        capabilities: [
+            LLM_CAPABILITY,
+            {
+                id: "workspace-connections",
+                label: "Workspace connections",
+                required: false,
+                builderIncluded: false,
+                keySummary: "Connect providers from the workspace registry",
+                why: "Dispatch uses shared connections so provider tokens never need to be pasted into this app.",
+            },
+        ],
+    },
+    factory: {
+        appId: "factory",
+        appName: "Factory",
+        capabilities: [
+            {
+                id: "builder-executor",
+                label: "Builder executor",
+                required: true,
+                builderIncluded: true,
+                keySummary: "Connect Builder for managed agent runs",
+                why: "The executor runs approved code and review workflows for Factory items.",
+            },
+            {
+                id: "triage-connections",
+                label: "Triage connections",
+                required: false,
+                builderIncluded: false,
+                keySummary: "GitHub, Slack, or Sentry connection",
+                why: "Only needed for the feedback source you want Factory to monitor.",
+            },
+        ],
+    },
+    forms: {
+        appId: "forms",
+        appName: "Forms",
+        capabilities: [
+            LLM_CAPABILITY,
+            {
+                id: "file-storage",
+                label: "File storage",
+                required: false,
+                builderIncluded: true,
+                keySummary: "Builder file storage or S3-compatible storage",
+                why: "Text-only forms work without storage. Add it when a form accepts file uploads.",
+            },
+        ],
+    },
+    macros: {
+        appId: "macros",
+        appName: "Macros",
+        capabilities: [
+            LLM_CAPABILITY,
+            {
+                id: "transcription",
+                label: "Transcription",
+                required: false,
+                builderIncluded: true,
+                keySummary: "Groq or Google Speech key",
+                why: "Voice input uses transcription. Text entry always works without it.",
+            },
+        ],
+    },
+    mail: {
+        appId: "mail",
+        appName: "Mail",
+        capabilities: [
+            LLM_CAPABILITY,
+            {
+                id: "gmail",
+                label: "Gmail",
+                required: true,
+                builderIncluded: false,
+                keySummary: "Google OAuth client ID and secret",
+                why: "Mail needs OAuth access to read, send, and organize the mailbox.",
+            },
+            {
+                id: "attachment-storage",
+                label: "Attachment storage",
+                required: false,
+                builderIncluded: true,
+                keySummary: "Builder file storage or S3-compatible storage",
+                why: "Only needed when attachments need to be retained outside Gmail.",
+            },
+        ],
+    },
+    plan: {
+        appId: "plan",
+        appName: "Plan",
+        capabilities: [
+            LLM_CAPABILITY,
+            {
+                id: "plan-assets",
+                label: "Plan asset storage",
+                required: false,
+                builderIncluded: true,
+                keySummary: "Builder file storage or S3-compatible storage",
+                why: "Only needed for screenshots and other visual plan assets.",
+            },
+            {
+                id: "google-sign-in",
+                label: "Google sign-in",
+                required: false,
+                builderIncluded: false,
+                keySummary: "Google OAuth client ID and secret",
+                why: "Only needed when Google sign-in is enabled for the deployment.",
+            },
+        ],
+    },
+    slides: {
+        appId: "slides",
+        appName: "Slides",
+        capabilities: [
+            LLM_CAPABILITY,
+            {
+                id: "image-generation",
+                label: "Image generation",
+                required: false,
+                builderIncluded: true,
+                keySummary: "Gemini or OpenAI key",
+                why: "Only needed when slides generate images instead of using uploaded assets.",
+            },
+            {
+                id: "reference-storage",
+                label: "Reference file storage",
+                required: false,
+                builderIncluded: true,
+                keySummary: "Builder file storage or S3-compatible storage",
+                why: "Only needed for uploaded reference files and presentation assets.",
+            },
+            {
+                id: "google-docs",
+                label: "Google Docs",
+                required: false,
+                builderIncluded: false,
+                keySummary: "Connect Google Docs with OAuth",
+                why: "Only needed to import source material from Google Drive or Docs.",
+            },
+        ],
+    },
+    tasks: {
+        appId: "tasks",
+        appName: "Tasks",
+        capabilities: [LLM_CAPABILITY],
+    },
+};
+const FALLBACK_PROFILE = {
+    appId: "app",
+    appName: "Your app",
+    capabilities: [LLM_CAPABILITY],
+};
+function normalizeAppId(value) {
+    const normalized = value?.trim().toLowerCase() ?? "";
+    if (!normalized)
+        return "app";
+    return (normalized
+        .replace(/^@[^/]+\//, "")
+        .replace(/^agent-native-/, "")
+        .replace(/[^a-z0-9-]/g, "-")
+        .replace(/-+/g, "-")
+        .replace(/^-|-$/g, "") || "app");
+}
+export function resolveOnboardingAppId(explicit) {
+    return normalizeAppId(explicit ??
+        process.env.AGENT_NATIVE_APP_ID ??
+        process.env.APP_ID ??
+        process.env.npm_package_name);
+}
+export function getOnboardingAppProfile(appId) {
+    const resolvedId = resolveOnboardingAppId(appId);
+    const profile = PROFILES[resolvedId] ?? FALLBACK_PROFILE;
+    return {
+        ...profile,
+        capabilities: profile.capabilities.map((capability) => ({ ...capability })),
+    };
+}
+//# sourceMappingURL=app-profile.js.map

package/dist/onboarding/index.d.ts

@@ -6,7 +6,8 @@
  * hook polls them — see `@agent-native/core/client/onboarding`.
  */
 export { registerOnboardingStep, listOnboardingSteps } from "./registry.js";
-export type { OnboardingStep, OnboardingMethod, OnboardingMethodBadge, OnboardingFormField, OnboardingStepStatus, } from "./types.js";
+export type { OnboardingStep, OnboardingMethod, OnboardingMethodBadge, OnboardingFormField, OnboardingStepStatus, OnboardingCapability, OnboardingAppProfile, } from "./types.js";
+export { getOnboardingAppProfile, resolveOnboardingAppId, } from "./app-profile.js";
 export { createOnboardingPlugin, defaultOnboardingPlugin, type OnboardingPluginOptions, } from "./plugin.js";
 export { registerDefaultOnboardingSteps } from "./default-steps.js";
 //# sourceMappingURL=index.d.ts.map

package/dist/onboarding/index.js

@@ -6,6 +6,7 @@
  * hook polls them — see `@agent-native/core/client/onboarding`.
  */
 export { registerOnboardingStep, listOnboardingSteps } from "./registry.js";
+export { getOnboardingAppProfile, resolveOnboardingAppId, } from "./app-profile.js";
 export { createOnboardingPlugin, defaultOnboardingPlugin, } from "./plugin.js";
 export { registerDefaultOnboardingSteps } from "./default-steps.js";
 //# sourceMappingURL=index.js.map

package/dist/onboarding/plugin.d.ts

@@ -11,6 +11,8 @@ type NitroPluginDef = (nitroApp: any) => void | Promise<void>;
 export interface OnboardingPluginOptions {
     /** Skip registering the built-in default steps (llm, database, auth). */
     skipDefaultSteps?: boolean;
+    /** App id used to select the app-specific first-run capability profile. */
+    appId?: string;
 }
 export declare function createOnboardingPlugin(options?: OnboardingPluginOptions): NitroPluginDef;
 /** Default plugin instance — mounted automatically when a template doesn't override. */

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/secrets/routes.d.ts

@@ -50,8 +50,8 @@ export declare function createWriteSecretHandler(): import("h3").EventHandlerWit
     removed: boolean;
 }>>;
 /**
- * POST /_agent-native/secrets/:key/test — re-run the validator against the
- * current stored value without changing anything. Useful for the "Test" button.
+ * 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;