@agent-native/core 0.173.2-nightly-20260825163448 → 0.174.0

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

@@ -9,7 +9,7 @@ import { createA2AApproval, updateTaskStatusMessage, } from "../a2a/task-store.j
 import { clientAbortReason } from "../agent/abort-reasons.js";
 import { canUpdateAgentAppModelDefaultSettings, normalizeAgentAppModelDefaultAppId, readAgentAppModelDefaultSettings, resetAgentAppModelDefaultSettings, writeAgentAppModelDefaultSettings, } from "../agent/app-model-defaults.js";
 import { DEFAULT_ANTHROPIC_MODEL } from "../agent/default-model.js";
-import { AGENT_CHAT_BACKGROUND_RUN_FIELD, AGENT_CHAT_PROCESS_RUN_PATH, backgroundRunMarkerExpectsBackgroundRuntime, isInBackgroundFunctionRuntime, prepareProcessRunRequest, } from "../agent/durable-background.js";
+import { AGENT_CHAT_BACKGROUND_RUN_FIELD, AGENT_CHAT_PROCESS_RUN_PATH, backgroundRunMarkerExpectsBackgroundRuntime, isAgentChatDurableBackgroundEnabled, isInBackgroundFunctionRuntime, prepareProcessRunRequest, } from "../agent/durable-background.js";
 import { resolveEngine, createAnthropicEngine, getStoredModelForEngine, normalizeModelForEngine, resolveDelegatedRunModel, getAgentEngineEntry, isAgentEnginePackageInstalled, isStoredEngineUsableForRequest, listAgentEngines, registerBuiltinEngines, } from "../agent/engine/index.js";
 import { SYSTEM_PROMPT_CACHE_SPLIT } from "../agent/engine/prompt-cache.js";
 import { PROVIDER_TO_ENV } from "../agent/engine/provider-env-vars.js";
@@ -153,6 +153,18 @@ export { resolveRecurringJobsBuildMarker };
 export { scheduledTriggerAvailability };
 export { shouldDisableRecurringJobsRuntime };
 export { finalizeClaimedAgentChatProcessRunFailure };
+/**
+ * The model this mount runs with, when the caller does not pass one per request.
+ *
+ * The plugin option is the top layer because it is per-mount; `agent.model`
+ * (`AGENT_MODEL`) is the declared layer below it, so a deployment can pin a
+ * model without editing app source. Read through here rather than off
+ * `options` directly — every raw `options?.model` site is a place the declared
+ * field silently does nothing.
+ */
+export function resolveConfiguredAgentModel(options) {
+    return options?.model ?? getAppConfig().agent.model;
+}
 export function resolveInteractiveAgentRunOptions(options) {
     return {
         runSoftTimeoutMs: options?.runSoftTimeoutMs,
@@ -1427,7 +1439,7 @@ export function createAgentChatPlugin(options) {
                     // below so it stays out of every identity/access path.
                     const a2aCallerModelHint = correlation.callerModel;
                     const model = resolveDelegatedRunModel(a2aEngine, {
-                        explicitModel: options?.model,
+                        explicitModel: resolveConfiguredAgentModel(options),
                         storedModel: a2aStoredModel,
                         callerModelHint: a2aCallerModelHint,
                     });
@@ -1444,7 +1456,7 @@ export function createAgentChatPlugin(options) {
                         // label is derived from what actually won — reporting
                         // "caller-hint" for a rejected hint would send the next person
                         // debugging this in exactly the wrong direction.
-                        `modelSource=${options?.model
+                        `modelSource=${resolveConfiguredAgentModel(options)
                             ? "configured"
                             : a2aStoredModel
                                 ? "stored"
@@ -1682,8 +1694,9 @@ export function createAgentChatPlugin(options) {
                         // `runSoftTimeoutMs` resolves to 0 and the wrapper degrades to a
                         // bare `runAgentLoop` — no resume at all on a delegated turn.
                         useHostedDefault: true,
-                        backgroundFunction: options?.durableBackgroundRuns === true &&
-                            isInBackgroundFunctionRuntime(),
+                        backgroundFunction: isAgentChatDurableBackgroundEnabled({
+                            appOptIn: options?.durableBackgroundRuns,
+                        }) && isInBackgroundFunctionRuntime(),
                     }, {
                         telemetry: {
                             runId: context.taskId,
@@ -1913,7 +1926,7 @@ export function createAgentChatPlugin(options) {
                             apiKeyEnvVar: ownerApiKey.apiKeyEnvVar,
                             appId: options?.appId,
                         });
-                        const mcpModelCandidate = options?.model ??
+                        const mcpModelCandidate = resolveConfiguredAgentModel(options) ??
                             (await getStoredModelForEngine(mcpEngine, {
                                 appId: options?.appId,
                             })) ??
@@ -2038,8 +2051,9 @@ export function createAgentChatPlugin(options) {
                             // Same as the A2A call site: without this a hosted app that
                             // never configured `runSoftTimeoutMs` gets no resume at all.
                             useHostedDefault: true,
-                            backgroundFunction: options?.durableBackgroundRuns === true &&
-                                isInBackgroundFunctionRuntime(),
+                            backgroundFunction: isAgentChatDurableBackgroundEnabled({
+                                appOptIn: options?.durableBackgroundRuns,
+                            }) && isInBackgroundFunctionRuntime(),
                         }, {
                             telemetry: {
                                 runId: mcpRunId,
@@ -2141,62 +2155,56 @@ export function createAgentChatPlugin(options) {
                 // queued-message save can clobber the assistant message we just
                 // appended here, or vice versa.
                 await withThreadDataLock(threadId, async () => {
+                    const thread = await getThread(threadId);
+                    if (!thread) {
+                        throw new Error(`Agent chat thread ${threadId} was not found while saving run ${run.runId}.`);
+                    }
+                    const assistantMsg = buildAssistantMessage(run.events ?? [], run.runId, {
+                        suppressInternalContinuation: true,
+                        turnId: typeof run.turnId === "string" && run.turnId
+                            ? run.turnId
+                            : undefined,
+                        runDurationMs: typeof run.startedAt === "number" &&
+                            Number.isFinite(run.startedAt)
+                            ? Math.max(0, Date.now() - run.startedAt)
+                            : undefined,
+                    });
+                    if (!assistantMsg) {
+                        // No content produced — just bump timestamp
+                        await updateThreadData(threadId, thread.threadData, thread.title, thread.preview, thread.messageCount);
+                        return;
+                    }
+                    // Parse existing thread_data, append assistant message only if
+                    // the frontend hasn't already saved it (avoids duplicates when
+                    // the client is still connected during a normal flow).
+                    let repo;
                     try {
-                        const thread = await getThread(threadId);
-                        if (!thread) {
-                            throw new Error(`Agent chat thread ${threadId} was not found while saving run ${run.runId}.`);
-                        }
-                        const assistantMsg = buildAssistantMessage(run.events ?? [], run.runId, {
-                            suppressInternalContinuation: true,
-                            turnId: typeof run.turnId === "string" && run.turnId
-                                ? run.turnId
-                                : undefined,
-                            runDurationMs: typeof run.startedAt === "number" &&
-                                Number.isFinite(run.startedAt)
-                                ? Math.max(0, Date.now() - run.startedAt)
-                                : undefined,
-                        });
-                        if (!assistantMsg) {
-                            // No content produced — just bump timestamp
-                            await updateThreadData(threadId, thread.threadData, thread.title, thread.preview, thread.messageCount);
-                            return;
-                        }
-                        // Parse existing thread_data, append assistant message only if
-                        // the frontend hasn't already saved it (avoids duplicates when
-                        // the client is still connected during a normal flow).
-                        let repo;
-                        try {
-                            repo = JSON.parse(thread.threadData || "{}");
-                        }
-                        catch {
-                            repo = {};
-                        }
-                        if (!Array.isArray(repo.messages))
-                            repo.messages = [];
-                        repo = foldAssistantTurn(repo, assistantMsg, {
-                            runId: run.runId,
-                            turnId: typeof run.turnId === "string" && run.turnId
-                                ? run.turnId
-                                : undefined,
-                        });
-                        // Store debug metadata so we can inspect what the LLM actually
-                        // received (system prompt, model, engine) when diagnosing issues.
-                        const runCtx = getRequestRunContext();
-                        const debug = {
-                            runId: run.runId,
-                            systemPrompt: runCtx?.systemPrompt,
-                            model: runCtx?.model ?? resolvedModel,
-                            engine: runCtx?.engine?.name ?? "unknown",
-                            timestamp: Date.now(),
-                        };
-                        repo = appendThreadDebugHistory(repo, debug);
-                        const meta = extractThreadMeta(repo);
-                        await updateThreadData(threadId, JSON.stringify(repo), meta.title || thread.title, meta.preview || thread.preview, repo.messages.length);
+                        repo = JSON.parse(thread.threadData || "{}");
                     }
-                    catch (err) {
-                        // Run completion is only successful once thread_data is durable.
-                        throw err;
+                    catch {
+                        repo = {};
                     }
+                    if (!Array.isArray(repo.messages))
+                        repo.messages = [];
+                    repo = foldAssistantTurn(repo, assistantMsg, {
+                        runId: run.runId,
+                        turnId: typeof run.turnId === "string" && run.turnId
+                            ? run.turnId
+                            : undefined,
+                    });
+                    // Store debug metadata so we can inspect what the LLM actually
+                    // received (system prompt, model, engine) when diagnosing issues.
+                    const runCtx = getRequestRunContext();
+                    const debug = {
+                        runId: run.runId,
+                        systemPrompt: runCtx?.systemPrompt,
+                        model: runCtx?.model ?? resolvedModel,
+                        engine: runCtx?.engine?.name ?? "unknown",
+                        timestamp: Date.now(),
+                    };
+                    repo = appendThreadDebugHistory(repo, debug);
+                    const meta = extractThreadMeta(repo);
+                    await updateThreadData(threadId, JSON.stringify(repo), meta.title || thread.title, meta.preview || thread.preview, repo.messages.length);
                 });
                 // Keep SQL run completion gated only on durable thread data. Follow-up
                 // hooks are useful, but they should never leave agent_runs stuck
@@ -2382,7 +2390,7 @@ export function createAgentChatPlugin(options) {
             // Each run gets its own send function, keyed by threadId so concurrent
             // requests for different threads don't clobber each other.
             const _runSendByThread = new Map();
-            const resolvedModel = options?.model ?? DEFAULT_ANTHROPIC_MODEL;
+            const resolvedModel = resolveConfiguredAgentModel(options) ?? DEFAULT_ANTHROPIC_MODEL;
             // The action set a sub-agent inherits. Shared between the spawn-time team
             // tool and the `_process-run` processor route below so the durable run
             // executes with exactly the tools the orchestrator intended.
@@ -2844,7 +2852,7 @@ Non-code requests are still fine on this surface: read data, navigate the UI, su
                         modelOverlay +
                         runtimeContext);
                 },
-                model: options?.model,
+                model: resolveConfiguredAgentModel(options),
                 appId: options?.appId,
                 hostedHarnessConfig,
                 apiKey: options?.apiKey,
@@ -2947,7 +2955,7 @@ Non-code requests are still fine on this surface: read data, navigate the UI, su
                             extra +
                             runtimeContextForEvent(event));
                     },
-                    model: options?.model,
+                    model: resolveConfiguredAgentModel(options),
                     appId: options?.appId,
                     apiKey: options?.apiKey,
                     ...resolveInteractiveAgentRunOptions(options),
@@ -3127,7 +3135,7 @@ Non-code requests are still fine on this surface: read data, navigate the UI, su
                             modelOverlay +
                             runtimeContext);
                     },
-                    model: options?.model,
+                    model: resolveConfiguredAgentModel(options),
                     appId: options?.appId,
                     apiKey: options?.apiKey,
                     ...resolveInteractiveAgentRunOptions(options),
@@ -5213,7 +5221,7 @@ Non-code requests are still fine on this surface: read data, navigate the UI, su
                         ...(job?.meta.mcpTools ?? []),
                     ],
                     apiKey: options?.apiKey,
-                    model: options?.model,
+                    model: resolveConfiguredAgentModel(options),
                     appId: options?.appId,
                 };
                 runNowSchedulerDeps = schedulerDeps;
@@ -5645,7 +5653,7 @@ Non-code requests are still fine on this surface: read data, navigate the UI, su
                             ...(automation?.meta.mcpTools ?? []),
                         ],
                         apiKey: options?.apiKey,
-                        model: options?.model,
+                        model: resolveConfiguredAgentModel(options),
                         appId: options?.appId,
                     });
                     if (process.env.DEBUG)

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

@@ -34,10 +34,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/core-routes/mcp-connect-options.d.ts

@@ -0,0 +1,70 @@
+/**
+ * Everything the core-routes plugin can configure about its MCP *connect*
+ * surface, in one object.
+ *
+ * This is deliberately not the same object as `AgentChatMcpOptions`. That one
+ * owns the protocol mount — which tools an external caller sees. This one owns
+ * how a caller gets a token in the first place: the browser Connect page, the
+ * CLI device-code flow, and the OAuth endpoints. They live in different plugins
+ * because core-routes is the light one; an app can serve MCP from it without
+ * paying for chat plugin initialization, which is what `mcp.enabled: false` on
+ * the chat side exists for.
+ *
+ * Before this existed the settings were four flat `mcpConnect*` keys, two of
+ * which only restated app identity the config schema already declares.
+ */
+export interface CoreRoutesMcpOptions {
+    /**
+     * Mount the `/mcp/connect` routes (browser Connect page + CLI device-code
+     * flow that mints per-user, revocable MCP tokens) and the standard
+     * remote-MCP OAuth endpoints under `/mcp/oauth`. The legacy
+     * `/_agent-native/mcp` aliases follow this same switch. Defaults to `true` —
+     * the routes are session-gated where they approve user access, and token
+     * endpoints are protected by single-use codes / refresh tokens.
+     */
+    connect?: boolean;
+    /**
+     * Explicit MCP server id returned in copyable config and device-flow grants.
+     *
+     * Only needed when the id a client should key this server by differs from
+     * this app's own identity. Otherwise it derives from `app.id` /
+     * `app.template` / `app.slug`, which covers every first-party template with
+     * no configuration at all.
+     */
+    serverName?: string;
+}
+/** The legacy top-level keys `mcp` replaces. */
+export interface CoreRoutesMcpLegacyInput {
+    /** @deprecated Use `mcp.connect: false`. */
+    disableMcpConnect?: boolean;
+    /** @deprecated Use `mcp.serverName`. */
+    mcpConnectServerName?: string;
+    /**
+     * @deprecated Set `app.id` in `defineAppConfig()` (env alias
+     * `AGENT_NATIVE_APP_ID`). App identity is one declared field, not a
+     * per-surface option.
+     */
+    mcpConnectAppId?: string;
+    /**
+     * @deprecated Set `app.name` in `defineAppConfig()` (env alias `APP_NAME`).
+     * Unset, it resolves from this app's package.json.
+     */
+    mcpConnectAppName?: string;
+    mcp?: CoreRoutesMcpOptions;
+}
+export interface ResolvedCoreRoutesMcp {
+    connect: boolean;
+    serverName: string | undefined;
+    /** Passed through to the connect/OAuth handlers as their app identity. */
+    appId: string | undefined;
+    appName: string | undefined;
+}
+/**
+ * Collapse the nested `mcp` option and the legacy top-level keys into the one
+ * shape the plugin threads into the connect and OAuth handlers.
+ *
+ * `appId` and `appName` fall through to the declared config fields rather than
+ * defaulting here, so the connect page, the OAuth consent screen, and the
+ * runtime config report cannot disagree about what this app is called.
+ */
+export declare function resolveCoreRoutesMcpOptions(input: CoreRoutesMcpLegacyInput | undefined): ResolvedCoreRoutesMcp;

package/dist/server/core-routes/mcp-connect-options.js

@@ -0,0 +1,77 @@
+/**
+ * Everything the core-routes plugin can configure about its MCP *connect*
+ * surface, in one object.
+ *
+ * This is deliberately not the same object as `AgentChatMcpOptions`. That one
+ * owns the protocol mount — which tools an external caller sees. This one owns
+ * how a caller gets a token in the first place: the browser Connect page, the
+ * CLI device-code flow, and the OAuth endpoints. They live in different plugins
+ * because core-routes is the light one; an app can serve MCP from it without
+ * paying for chat plugin initialization, which is what `mcp.enabled: false` on
+ * the chat side exists for.
+ *
+ * Before this existed the settings were four flat `mcpConnect*` keys, two of
+ * which only restated app identity the config schema already declares.
+ */
+import { getAppConfig } from "../../app-config/index.js";
+const warnedLegacyKeys = new Set();
+/**
+ * Nested value wins, but only when the two forms agree.
+ *
+ * Disagreement throws at plugin init rather than picking a side, the same
+ * contract as `resolveAgentChatMcpOptions` and `resolveFrameworkTools`: an app
+ * that boots with a connect surface nobody chose is how a "why does my client
+ * see the wrong server" report ends up unexplainable.
+ */
+function pick(key, legacyKey, legacyValue, nestedValue) {
+    if (legacyValue === undefined)
+        return nestedValue;
+    if (nestedValue !== undefined && legacyValue !== nestedValue) {
+        throw new Error(`[agent-native] Conflicting core-routes options: \`${legacyKey}: ${JSON.stringify(legacyValue)}\` ` +
+            `and \`mcp.${key}: ${JSON.stringify(nestedValue)}\` disagree. ` +
+            `Remove the deprecated \`${legacyKey}\` and keep \`mcp.${key}\`.`);
+    }
+    if (!warnedLegacyKeys.has(legacyKey)) {
+        warnedLegacyKeys.add(legacyKey);
+        console.warn(`[agent-native] \`${legacyKey}\` is deprecated — use \`mcp: { ${key}: … }\`.`);
+    }
+    return nestedValue ?? legacyValue;
+}
+const warnedIdentityKeys = new Set();
+function warnIdentityOption(legacyKey, field) {
+    if (warnedIdentityKeys.has(legacyKey))
+        return;
+    warnedIdentityKeys.add(legacyKey);
+    console.warn(`[agent-native] \`${legacyKey}\` is deprecated — set \`${field}\` in ` +
+        `defineAppConfig() so every surface reads one app identity.`);
+}
+/**
+ * Collapse the nested `mcp` option and the legacy top-level keys into the one
+ * shape the plugin threads into the connect and OAuth handlers.
+ *
+ * `appId` and `appName` fall through to the declared config fields rather than
+ * defaulting here, so the connect page, the OAuth consent screen, and the
+ * runtime config report cannot disagree about what this app is called.
+ */
+export function resolveCoreRoutesMcpOptions(input) {
+    const mcp = input?.mcp ?? {};
+    // `disableMcpConnect` is the inverse of `connect`, so normalize before
+    // comparing — otherwise `disableMcpConnect: true` + `connect: false` would
+    // read as a conflict.
+    const legacyConnect = input?.disableMcpConnect === undefined
+        ? undefined
+        : !input.disableMcpConnect;
+    if (input?.mcpConnectAppId !== undefined) {
+        warnIdentityOption("mcpConnectAppId", "app.id");
+    }
+    if (input?.mcpConnectAppName !== undefined) {
+        warnIdentityOption("mcpConnectAppName", "app.name");
+    }
+    const app = getAppConfig().app;
+    return {
+        connect: pick("connect", "disableMcpConnect", legacyConnect, mcp.connect) ?? true,
+        serverName: pick("serverName", "mcpConnectServerName", input?.mcpConnectServerName, mcp.serverName),
+        appId: input?.mcpConnectAppId ?? app.id,
+        appName: input?.mcpConnectAppName ?? app.name,
+    };
+}

package/dist/server/core-routes-plugin.d.ts

@@ -3,6 +3,7 @@ import { type DatabaseSchemaHealthResult } from "../db/runtime-diagnostics.js";
 import { getSetting, deleteSetting, mutateSetting, listSettingsByPrefix } from "../settings/store.js";
 import { type AuthSession } from "./auth.js";
 import { type BuilderConnectTrackingParams, type BuilderRelayCredentials } from "./builder-browser.js";
+import { type CoreRoutesMcpOptions } from "./core-routes/mcp-connect-options.js";
 import type { EnvKeyConfig } from "./create-server.js";
 import { type DbPressure } from "./db-pressure.js";
 /**
@@ -261,20 +262,23 @@ export interface CoreRoutesPluginOptions {
     /** Disable the /_agent-native/embed/start iframe session launcher. */
     disableEmbedRoute?: boolean;
     /**
-     * Disable the /mcp/connect routes (browser Connect page + CLI device-code
-     * flow that mints per-user, revocable MCP tokens) and the standard remote-MCP
-     * OAuth endpoints under /mcp/oauth. The legacy /_agent-native/mcp aliases
-     * are disabled at the same time.
-     * Enabled by default — the routes are session-gated where they approve user
-     * access; token endpoints are protected by single-use codes / refresh
-     * tokens.
+     * Everything about this app's MCP connect surface — whether the Connect page
+     * and OAuth endpoints are mounted, and the server id clients key it by.
+     * See `CoreRoutesMcpOptions`.
+     *
+     * Replaces the top-level `disableMcpConnect`, `mcpConnectServerName`,
+     * `mcpConnectAppId`, and `mcpConnectAppName`, which stay accepted for one
+     * minor. Setting both forms to disagreeing values throws at plugin init
+     * rather than silently picking one.
      */
+    mcp?: CoreRoutesMcpOptions;
+    /** @deprecated Use `mcp.connect: false`. */
     disableMcpConnect?: boolean;
-    /** Canonical app id (e.g. `mail`) for the MCP connect server name. */
-    mcpConnectAppId?: string;
-    /** Explicit MCP server id for copyable config/device-flow grants. */
+    /** @deprecated Use `mcp.serverName`. */
     mcpConnectServerName?: string;
-    /** Human app name shown on the MCP connect page. */
+    /** @deprecated Set `app.id` in `defineAppConfig()`. */
+    mcpConnectAppId?: string;
+    /** @deprecated Set `app.name` in `defineAppConfig()`. */
     mcpConnectAppName?: string;
     /** Per-template override mapping deep-link params → client SPA path.
      *  See `createOpenRouteHandler`. */

package/dist/server/core-routes-plugin.js

@@ -40,11 +40,11 @@ import { createAutomationsHandler } from "../triggers/routes.js";
 import { createAgentEngineApiKeyHandler } from "./agent-engine-api-key-route.js";
 import { readAnalyticsClientPlatformHeader, readBrowserSessionIdHeader, } from "./agent-run-context.js";
 import { getConfiguredAppBasePath, stripAppBasePath } from "./app-base-path.js";
-import { getAppName } from "./app-name.js";
 import { getSession } from "./auth.js";
 import { BUILDER_CONNECT_PARAM, BUILDER_ENV_KEYS, BUILDER_OPENER_PARAM, BUILDER_RELAY_FLOW_HEADER, BUILDER_RELAY_SIGNATURE_HEADER, BUILDER_RELAY_STATE_PARAM, BUILDER_RELAY_TIMESTAMP_HEADER, appendBuilderConnectToken, builderConnectTrackingProperties, createBuilderConnectState, createBuilderBrowserCallbackErrorPage, createBuilderBrowserCallbackPage, createBuilderRelayRequest, getBuilderConnectTrackingParams, getBuilderBrowserOriginForEvent, getBuilderBrowserStatusForEvent, isBuilderConnectCallbackUrlAllowed, isSignedBuilderConnectState, normalizeBuilderAgentContext, resolveBuilderBranchProjectId, resolveBuilderConnectCallbackUrl, resolveBuilderPreviewRelayParentOrigin, runBuilderAgent, verifyBuilderRelayRequest, verifyBuilderPreviewRelayStateForCallback, verifyBuilderConnectTokenAndGetOwner, } from "./builder-browser.js";
 import { BUILDER_OAUTH_SCOPE, deleteBuilderOAuthSession, finishBuilderOAuthAuthorization, hasBuilderOAuthSession, resolveBuilderOAuthRequestAccess, startBuilderOAuthAuthorization, } from "./builder-oauth.js";
 import { captureError, registerErrorCaptureProvider } from "./capture-error.js";
+import { resolveCoreRoutesMcpOptions, } from "./core-routes/mcp-connect-options.js";
 import { getAllowedCorsOrigin, readCorsAllowedOrigins, } from "./cors-origins.js";
 import { canUseDeployCredentialFallbackForRequest, prefetchSecrets, readDeployCredentialEnv, resolveSecret, } from "./credential-provider.js";
 import { probeDbPressure } from "./db-pressure.js";
@@ -3038,7 +3038,8 @@ export function createCoreRoutesPlugin(options = {}) {
                 setResponseStatus(event, 405);
                 return { error: "Method not allowed" };
             }));
-            if (!options.disableMcpConnect) {
+            const mcpConnect = resolveCoreRoutesMcpOptions(options);
+            if (mcpConnect.connect) {
                 getH3App(nitroApp).use("/.well-known/oauth-protected-resource", defineEventHandler((event) => handleMcpOAuthProtectedResourceMetadata(event)));
                 getH3App(nitroApp).use("/.well-known/oauth-authorization-server", defineEventHandler((event) => handleMcpOAuthAuthorizationServerMetadata(event)));
                 getH3App(nitroApp).use("/.well-known/openid-configuration", defineEventHandler((event) => handleMcpOAuthAuthorizationServerMetadata(event)));
@@ -3046,8 +3047,8 @@ export function createCoreRoutesPlugin(options = {}) {
                     getH3App(nitroApp).use(`${mcpRoutePrefix}/oauth`, defineEventHandler(async (event) => {
                         const subpath = event.url?.pathname || "";
                         return handleMcpOAuth(event, subpath, {
-                            appId: options.mcpConnectAppId,
-                            appName: options.mcpConnectAppName ?? getAppName(),
+                            appId: mcpConnect.appId,
+                            appName: mcpConnect.appName,
                         });
                     }));
                 }
@@ -3061,9 +3062,9 @@ export function createCoreRoutesPlugin(options = {}) {
                 // The auth guard bypasses ONLY the page + device/start + device/poll
                 // (see createAuthGuardFn in auth.ts).
                 const mcpConnectOpts = {
-                    appId: options.mcpConnectAppId,
-                    appName: options.mcpConnectAppName ?? getAppName(),
-                    serverName: options.mcpConnectServerName,
+                    appId: mcpConnect.appId,
+                    appName: mcpConnect.appName,
+                    serverName: mcpConnect.serverName,
                 };
                 for (const mcpRoutePrefix of MCP_ROUTE_PREFIXES) {
                     getH3App(nitroApp).use(`${mcpRoutePrefix}/connect`, defineEventHandler(async (event) => {

package/dist/server/edge.d.ts

@@ -5,6 +5,7 @@ export { runFrameworkReleaseMigrations } from "./release-migrations.js";
 export { createAgentChatPlugin, defaultAgentChatPlugin, refreshGlobalMcpManager, type AgentChatPluginOptions, } from "./agent-chat-plugin.js";
 export { createContextXrayPlugin, defaultContextXrayPlugin, } from "../agent/context-xray/plugin.js";
 export { createCoreRoutesPlugin, defaultCoreRoutesPlugin, FRAMEWORK_ROUTE_PREFIX, type CoreRoutesPluginOptions, } from "./core-routes-plugin.js";
+export type { CoreRoutesMcpOptions } from "./core-routes/mcp-connect-options.js";
 export { createIntegrationsPlugin, defaultIntegrationsPlugin, enqueueRemoteCommand, slackAdapter, telegramAdapter, whatsappAdapter, discordAdapter, microsoftTeamsAdapter, emailAdapter, assertPlatformCapability, type PlatformAdapter, type IncomingMessage, type OutgoingMessage, type PlatformAdapterCapabilities, type ImmediateWebhookResponse, type IntegrationStatus, type IntegrationsPluginOptions, BUILT_IN_INTEGRATION_CATALOG, INTEGRATION_CATEGORIES, getIntegrationCatalogEntry, listBuiltInChannelIntegrations, listIntegrationCatalog, type BuiltInChannelId, type ChannelCapabilities, type IntegrationAvailability, type IntegrationCatalogEntry, type IntegrationCategory, type IntegrationCredentialRequirement, type IntegrationIconKey, type IntegrationSupportMaturity, } from "../integrations/index.js";
 export { createObservationalMemoryPlugin, defaultObservationalMemoryPlugin, } from "../agent/observational-memory/plugin.js";
 export { createOnboardingPlugin, defaultOnboardingPlugin, } from "../onboarding/plugin.js";

package/dist/server/email-template.js

@@ -1,3 +1,4 @@
+import { getAppConfig } from "../app-config/index.js";
 /**
  * Reusable dark-themed HTML email template.
  *
@@ -17,7 +18,6 @@
  *     footer: "If you weren't expecting this, ignore this email.",
  *   });
  */
-import { getAppName } from "./app-name.js";
 export const AGENT_NATIVE_EMAIL_LOGO_CONTENT_ID = "agent-native-logo";
 function escapeHtml(s) {
     return s
@@ -57,7 +57,7 @@ function sanitizeLogoUrl(input) {
 export function renderEmail(args) {
     const preheader = args.preheader || "";
     const brand = sanitizeHexColor(args.brandColor);
-    const brandName = args.brandName?.trim() || getAppName() || "Agent Native";
+    const brandName = args.brandName?.trim() || getAppConfig().app.name || "Agent Native";
     const logoSrc = sanitizeLogoUrl(args.brandLogoUrl) ??
         `cid:${AGENT_NATIVE_EMAIL_LOGO_CONTENT_ID}`;
     // Monochrome default: near-white button with dark text. Brand override:

package/dist/server/email-templates.js

@@ -10,7 +10,7 @@
  * confirmation), add it here rather than inlining `renderEmail` at the call
  * site — keeps the transactional look-and-feel consistent.
  */
-import { getAppName, getAppSlug, getAppDescription } from "./app-name.js";
+import { getAppConfig } from "../app-config/index.js";
 import { renderEmail, emailStrong } from "./email-template.js";
 /** Shared reply-to for the framework's transactional emails. */
 export const AGENT_NATIVE_REPLY_TO = "agent-native@builder.io";
@@ -23,7 +23,7 @@ function stripCrlf(s) {
     return s.replace(/[\r\n]+/g, " ").trim();
 }
 function resolveAppName() {
-    return stripCrlf(getAppName() || "Agent Native");
+    return stripCrlf(getAppConfig().app.name || "Agent Native");
 }
 /**
  * Recipient-facing brand for auth emails. Only a recognized first-party
@@ -31,7 +31,7 @@ function resolveAppName() {
  * own name so its users aren't told they signed up for an Agent Native app.
  */
 function resolveBrand(slug) {
-    const appName = getAppName();
+    const appName = getAppConfig().app.name;
     if (!appName)
         return "Agent Native";
     return slug ? `Agent-Native ${stripCrlf(appName)}` : stripCrlf(appName);
@@ -74,10 +74,10 @@ const VERIFY_EMAIL_DESCRIPTIONS = {
 };
 export function renderVerifySignupEmail(args) {
     const email = stripCrlf(args.email);
-    const slug = getAppSlug();
+    const slug = getAppConfig().app.slug;
     const brand = resolveBrand(slug);
     const description = slug
-        ? (VERIFY_EMAIL_DESCRIPTIONS[slug] ?? getAppDescription())
+        ? (VERIFY_EMAIL_DESCRIPTIONS[slug] ?? getAppConfig().app.description)
         : undefined;
     const paragraphs = [
         `Thanks for signing up for ${emailStrong(brand)}. To finish creating your account, confirm that ${emailStrong(email)} is your email address.`,
@@ -105,7 +105,7 @@ export function renderVerifySignupEmail(args) {
 }
 export function renderMagicLinkEmail(args) {
     const email = stripCrlf(args.email);
-    const slug = getAppSlug();
+    const slug = getAppConfig().app.slug;
     const brand = resolveBrand(slug);
     const { html, text } = renderEmail({
         brandName: brand,
@@ -131,7 +131,7 @@ export function renderResetPasswordEmail(args) {
     const email = stripCrlf(args.email);
     // Match the verification email branding so password resets are clearly tied
     // to the specific app. No value pitch here — it's a security email.
-    const slug = getAppSlug();
+    const slug = getAppConfig().app.slug;
     const brand = resolveBrand(slug);
     const { html, text } = renderEmail({
         brandName: brand,

package/dist/server/email.js

@@ -9,9 +9,9 @@
  * With neither provider configured, `sendEmail` logs the message to the console
  * so the reset-password flow still works end-to-end for local development.
  */
+import { getAppConfig } from "../app-config/index.js";
 import { FAVICON_PNG_BASE64 } from "../assets/branding/favicon-base64.js";
 import { getScopedEmailProviderCategory, recordEmailSend, } from "../email-catalog/log.js";
-import { getAppSlug } from "./app-name.js";
 import { resolveSecret } from "./credential-provider.js";
 import { AGENT_NATIVE_EMAIL_LOGO_CONTENT_ID } from "./email-template.js";
 import { getRequestOrgId } from "./request-context.js";
@@ -236,7 +236,7 @@ async function deliverEmail(args, signal) {
         const orgId = args.orgId ?? getRequestOrgId();
         const categories = [
             args.templateId,
-            args.app ?? getAppSlug(),
+            args.app ?? getAppConfig().app.slug,
             args.templateId && orgId
                 ? getScopedEmailProviderCategory(args.templateId, orgId)
                 : undefined,
@@ -300,7 +300,7 @@ async function sendEmailWithSignal(args, signal) {
     catch (error) {
         await recordEmailSend({
             templateId: args.templateId,
-            app: args.app ?? getAppSlug() ?? "unknown",
+            app: args.app ?? getAppConfig().app.slug ?? "unknown",
             orgId: args.orgId ?? getRequestOrgId(),
             recipient: args.to,
             sender: outcome?.from ?? args.from ?? "unknown",
@@ -313,7 +313,7 @@ async function sendEmailWithSignal(args, signal) {
     }
     await recordEmailSend({
         templateId: args.templateId,
-        app: args.app ?? getAppSlug() ?? "unknown",
+        app: args.app ?? getAppConfig().app.slug ?? "unknown",
         orgId: args.orgId ?? getRequestOrgId(),
         recipient: args.to,
         sender: outcome.from,

package/dist/server/google-oauth.js

@@ -8,9 +8,9 @@
  */
 import crypto from "node:crypto";
 import { getHeader, getQuery, setResponseStatus, setResponseHeader, } from "h3";
+import { getAppConfig } from "../app-config/index.js";
 import { normalizeAnalyticsAnonymousId } from "../shared/analytics-anonymous-id.js";
 import { getAppBasePathFromViteEnv } from "./app-base-path.js";
-import { getAppName } from "./app-name.js";
 import { readAnalyticsAnonymousId, signupAttributionFromCookieHeader, } from "./attribution.js";
 import { addSession, getSession, getSessionMaxAge, hasLegacySessionForEmail, safeReturnPath, setFrameworkSessionCookie, } from "./auth.js";
 import { hasBetterAuthUserEmail, trackSignupEvent, } from "./better-auth-instance.js";
@@ -731,7 +731,7 @@ export function oauthDesktopExchangePage(message = "Returning to the app...", cl
 }
 // ─── Internal ────────────────────────────────────────────────────────────────
 function resolveOAuthAppName(explicit) {
-    const raw = explicit || getAppName() || "Agent Native";
+    const raw = explicit || getAppConfig().app.name || "Agent Native";
     if (!/^[a-z0-9_-]+$/.test(raw))
         return raw;
     return raw