@agent-native/core 0.169.0 → 0.170.0

package/dist/scripts/agent-engines/list-agent-engines.js

@@ -70,8 +70,29 @@ export async function run(args = {}) {
     const currentModel = currentEntry && !envUnavailable
         ? normalizeModelForEngine(currentEntry, currentModelCandidate ?? currentEntry.defaultModel, { preserveCustomModels })
         : (currentModelCandidate ?? DEFAULT_MODEL);
-    const result = {
-        engines: engines.map((e) => ({
+    // Readiness has to be resolved here: `requiredEnvVars` alone cannot see
+    // vault-stored keys or the deploy-injected Builder gateway lane, so a client
+    // that re-derives it from env keys marks working engines unconfigured.
+    const engineEntries = await Promise.all(engines.map(async (e) => {
+        // Resolved per engine, not across the set: one provider whose credential
+        // store is momentarily unreadable must not reject the whole listing. The
+        // chat refresh catches that rejection and renders an empty catalog, so a
+        // single unrelated provider would make every engine unselectable — the
+        // exact symptom this readiness plumbing exists to fix.
+        //
+        // A read error is its own state, left as `configured: undefined` so the
+        // client falls back to its env heuristic. Folding it into `false` would
+        // claim the engine needs an API key when nobody actually knows.
+        let configured;
+        let configuredError;
+        try {
+            configured = await isStoredEngineUsableForRequest({ engine: e.name, model: e.defaultModel }, e);
+        }
+        catch (error) {
+            configuredError =
+                error instanceof Error ? error.message : String(error);
+        }
+        return {
             name: e.name,
             label: e.label,
             description: e.description,
@@ -81,7 +102,12 @@ export async function run(args = {}) {
             requiredEnvVars: e.requiredEnvVars,
             installPackage: e.installPackage,
             packageInstalled: isAgentEnginePackageInstalled(e),
-        })),
+            configured,
+            configuredError,
+        };
+    }));
+    const result = {
+        engines: engineEntries,
         current: envUnavailable
             ? null
             : {

package/dist/scripts/db/check-scoping.js

@@ -12,9 +12,15 @@
  *   pnpm action db-check-scoping [--db path] [--require-org] [--format json]
  */
 import path from "path";
-import { createClient } from "@libsql/client";
-import { getDatabaseUrl, getDatabaseAuthToken } from "../../db/client.js";
+import { getDatabaseUrl } from "../../db/client.js";
 import { parseArgs } from "../utils.js";
+// The `@libsql/client` node entry pulls the `libsql` native addon into whatever
+// graph imports it, and this maintenance script was its only importer in the
+// server bundle — which is how a 9.3MB Linux SQLite driver reached the docs
+// function, a deployment that runs Postgres. `createSqliteScriptClient` reaches
+// the same two backends through dynamic imports instead, so nothing static
+// depends on the native package.
+import { createSqliteScriptClient } from "./sqlite-client.js";
 function isPostgresUrl(url) {
     return url.startsWith("postgres://") || url.startsWith("postgresql://");
 }
@@ -125,10 +131,7 @@ Options:
         }
     }
     else {
-        const client = createClient({
-            url,
-            authToken: getDatabaseAuthToken(),
-        });
+        const client = await createSqliteScriptClient(url);
         try {
             allColumns = await discoverColumnsSqlite(client);
         }

package/dist/secrets/register-framework-secrets.js

@@ -27,7 +27,7 @@ export function registerFrameworkSecrets() {
             id: "google_drive",
             credentialPrefix: "GOOGLE",
             oauthProvider: "google",
-            label: "Google Drive",
+            label: "Google Workspace",
             docsUrl: "https://developers.google.com/identity/protocols/oauth2/web-server",
         },
         {

package/dist/secrets/routes.d.ts

@@ -37,17 +37,17 @@ export declare function createWriteSecretHandler(): import("h3").EventHandlerWit
     ok?: undefined;
     status?: undefined;
 } | {
-    error?: undefined;
     ok: boolean;
     status: string;
+    error?: undefined;
 } | {
     ok?: undefined;
     error: string;
     removed?: undefined;
 } | {
-    error?: undefined;
     ok: boolean;
     removed: boolean;
+    error?: undefined;
 }>>;
 /**
  * POST /_agent-native/secrets/:key/test — validate an optional candidate value
@@ -58,13 +58,13 @@ export declare function createTestSecretHandler(): import("h3").EventHandlerWith
     error: string;
     note?: undefined;
 } | {
-    error?: undefined;
     ok: boolean;
     note?: 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;
+} | {
     ok: boolean;
     removed: boolean;
+    error?: undefined;
 }>>;

package/dist/server/action-discovery.js

@@ -163,6 +163,11 @@ function preserveActionFlags(entry) {
     const out = {};
     if (typeof entry.agentTool === "boolean")
         out.agentTool = entry.agentTool;
+    if (typeof entry.mcpTool === "boolean")
+        out.mcpTool = entry.mcpTool;
+    if (typeof entry.deferLoading === "boolean") {
+        out.deferLoading = entry.deferLoading;
+    }
     if (typeof entry.requiresAuth === "boolean") {
         out.requiresAuth = entry.requiresAuth;
     }

package/dist/server/agent-chat/action-filters-a2a.d.ts

@@ -13,6 +13,18 @@ export declare function filterReadOnlyActions(actions: Record<string, ActionEntr
  *  list (in-app assistant, MCP, A2A, job/trigger runners) or actions prompt.
  *  Default-allow: only an explicit `false` is excluded. */
 export declare function filterAgentTools(actions: Record<string, ActionEntry>): Record<string, ActionEntry>;
+/**
+ * The MCP-only actions: `agentTool: false` paired with an explicit
+ * `mcpTool: true`.
+ *
+ * `filterAgentTools` drops these, which is right for every in-app surface and
+ * wrong for the two external ones. Rather than have the MCP and A2A mounts
+ * read the unfiltered registry — and re-derive which agent-hidden actions are
+ * safe to serve — the plugin re-merges exactly this set into those two mounts.
+ * A caller that wants "everything external" merges this with the agent surface;
+ * nobody has to remember which raw fields make an action MCP-only.
+ */
+export declare function filterMcpOnlyActions(actions: Record<string, ActionEntry>): Record<string, ActionEntry>;
 export declare function filterPublicAgentActions(actions: Record<string, ActionEntry>): Record<string, ActionEntry>;
 /**
  * True when an action takes a free-form query or program as input — raw SQL, a
@@ -137,15 +149,27 @@ export declare function createA2AEngineToolSurface(availableTools: EngineTool[],
 export declare function isSelectedA2AReceiver(selectedReceiverApp: string | undefined, appId: string | undefined): boolean;
 export declare function buildSelectedA2AReceiverContext(appId: string): string;
 /**
- * The first-request tool catalog: an explicit `initialToolNames` verbatim, or
- * the app's OWN actions by default.
+ * The first-request tool catalog, in precedence order:
+ *
+ *  1. An explicit `initialToolNames`, plus every action that declares
+ *     `deferLoading: false`. The configured list stays authoritative — an
+ *     action it names is never dropped by a `deferLoading: true` — so a
+ *     template can annotate its actions before deleting the array, not after.
+ *  2. Otherwise, the actions that declared `deferLoading: false`, if any did.
+ *  3. Otherwise, the app's OWN actions, minus any marked `deferLoading: true`.
+ *
+ * Step 2 is what makes `deferLoading` a replacement for the array rather than
+ * a second copy of it: opting a few starter actions out of deferral on an app
+ * with no configured list defers everything else, instead of leaving the whole
+ * registry in and the annotation decorative.
  *
  * "Its own actions" excludes the framework kits. They arrive in this same
  * registry through `autoDiscoverActions` -> `mergeCoreSharingActions`, so the
  * plain `Object.keys` default promoted ~45 sharing/review/history/flag schemas
  * into every app's first request whether or not the app had those surfaces. They
  * remain in `availableTools` and are still found by `tool-search`; an app that
- * wants one on turn one names it in `initialToolNames`.
+ * wants one on turn one sets `deferLoading: false` or names it in
+ * `initialToolNames`.
  */
 export declare function resolveInitialToolNames(templateActions: Record<string, ActionEntry>, configured?: string[]): string[];
 export {};

package/dist/server/agent-chat/action-filters-a2a.js

@@ -1,6 +1,7 @@
 import { getHeader } from "h3";
 import { appendA2AArtifactLinks, extractA2APersistedMutationReceipts, } from "../../a2a/artifact-response.js";
 import { collectFinalResponseTextFromAgentEvents } from "../../a2a/response-text.js";
+import { isActionExposedToExternalAgents } from "../../action.js";
 import { resolveMainChatMaxOutputTokens } from "../../agent/engine/output-tokens.js";
 import { filterInitialEngineTools, resolveAgentRequestReasoningEffort, } from "../../agent/production-agent.js";
 import { runAgentLoopDirectWithSoftTimeout } from "../../agent/run-loop-with-resume.js";
@@ -25,6 +26,20 @@ export function filterReadOnlyActions(actions) {
 export function filterAgentTools(actions) {
     return Object.fromEntries(Object.entries(actions).filter(([, entry]) => entry.agentTool !== false));
 }
+/**
+ * The MCP-only actions: `agentTool: false` paired with an explicit
+ * `mcpTool: true`.
+ *
+ * `filterAgentTools` drops these, which is right for every in-app surface and
+ * wrong for the two external ones. Rather than have the MCP and A2A mounts
+ * read the unfiltered registry — and re-derive which agent-hidden actions are
+ * safe to serve — the plugin re-merges exactly this set into those two mounts.
+ * A caller that wants "everything external" merges this with the agent surface;
+ * nobody has to remember which raw fields make an action MCP-only.
+ */
+export function filterMcpOnlyActions(actions) {
+    return Object.fromEntries(Object.entries(actions).filter(([, entry]) => entry.agentTool === false && entry.mcpTool === true));
+}
 export function filterPublicAgentActions(actions) {
     return Object.fromEntries(Object.entries(actions).filter(([, entry]) => {
         const config = entry.publicAgent;
@@ -80,7 +95,10 @@ export function filterDirectA2AActions(actions, options) {
     const autoReads = options.externalAgents?.authenticatedReads === "auto";
     return Object.fromEntries(Object.entries(actions).filter(([name, entry]) => {
         const exposure = entry.publicAgent;
-        const selected = catalog.has(name) ||
+        // `mcpTool: true` is catalog membership declared beside the action; the
+        // exposure resolver below is the veto no config list can re-open.
+        const selected = entry.mcpTool === true ||
+            catalog.has(name) ||
             (autoReads &&
                 isAuthenticatedReadAction(entry) &&
                 !isAutoReadExcludedActionName(name));
@@ -88,7 +106,7 @@ export function filterDirectA2AActions(actions, options) {
         return (selected &&
             rawQueryAllowed &&
             !denied.has(name) &&
-            entry.agentTool !== false &&
+            isActionExposedToExternalAgents(entry) &&
             entry.readOnly === true &&
             exposure?.expose === true &&
             exposure.readOnly === true &&
@@ -108,7 +126,7 @@ export function filterDelegatedA2ACapabilityActions(actions, options) {
     return Object.fromEntries(Object.entries(actions).filter(([name, entry]) => {
         const exposure = entry.publicAgent;
         return (!denied.has(name) &&
-            entry.agentTool !== false &&
+            isActionExposedToExternalAgents(entry) &&
             entry.readOnly !== true &&
             exposure?.expose === true &&
             exposure.readOnly === false &&
@@ -463,20 +481,41 @@ The caller already selected this app to own the current objective. Start with th
 </selected-a2a-receiver>`;
 }
 /**
- * The first-request tool catalog: an explicit `initialToolNames` verbatim, or
- * the app's OWN actions by default.
+ * The first-request tool catalog, in precedence order:
+ *
+ *  1. An explicit `initialToolNames`, plus every action that declares
+ *     `deferLoading: false`. The configured list stays authoritative — an
+ *     action it names is never dropped by a `deferLoading: true` — so a
+ *     template can annotate its actions before deleting the array, not after.
+ *  2. Otherwise, the actions that declared `deferLoading: false`, if any did.
+ *  3. Otherwise, the app's OWN actions, minus any marked `deferLoading: true`.
+ *
+ * Step 2 is what makes `deferLoading` a replacement for the array rather than
+ * a second copy of it: opting a few starter actions out of deferral on an app
+ * with no configured list defers everything else, instead of leaving the whole
+ * registry in and the annotation decorative.
  *
  * "Its own actions" excludes the framework kits. They arrive in this same
  * registry through `autoDiscoverActions` -> `mergeCoreSharingActions`, so the
  * plain `Object.keys` default promoted ~45 sharing/review/history/flag schemas
  * into every app's first request whether or not the app had those surfaces. They
  * remain in `availableTools` and are still found by `tool-search`; an app that
- * wants one on turn one names it in `initialToolNames`.
+ * wants one on turn one sets `deferLoading: false` or names it in
+ * `initialToolNames`.
  */
 export function resolveInitialToolNames(templateActions, configured) {
+    const entries = Object.entries(templateActions);
+    // A framework-grouped action stays out of the DERIVED set, but an explicit
+    // `deferLoading: false` on one is a declaration, not a leak: it is the same
+    // opt-in `initialToolNames` already gave apps for these names.
+    const eager = entries
+        .filter(([, entry]) => entry.deferLoading === false)
+        .map(([name]) => name);
     if (configured)
-        return configured;
-    return Object.entries(templateActions)
-        .filter(([name, entry]) => !isFrameworkGroupedAction(name, entry))
+        return [...new Set([...configured, ...eager])];
+    if (eager.length > 0)
+        return eager;
+    return entries
+        .filter(([name, entry]) => !isFrameworkGroupedAction(name, entry) && entry.deferLoading !== true)
         .map(([name]) => name);
 }

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

@@ -6,6 +6,7 @@ import { appendA2AArtifactLinks, buildA2ARecoverableArtifactMessage, } from "../
 import { hasConfiguredA2ASecret, isLoopbackAddress, isTrustedLocalRuntime, } from "../a2a/auth-policy.js";
 import { sanitizeA2ACorrelationId, sanitizeA2ACorrelationMetadata, } from "../a2a/correlation.js";
 import { createA2AApproval, updateTaskStatusMessage, } from "../a2a/task-store.js";
+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";
@@ -14,7 +15,6 @@ import { SYSTEM_PROMPT_CACHE_SPLIT } from "../agent/engine/prompt-cache.js";
 import { PROVIDER_TO_ENV } from "../agent/engine/provider-env-vars.js";
 import { hostedHarnessSystemPrompt } from "../agent/harness/hosted.js";
 import { createProductionAgentHandler, actionsToEngineTools, executeAgentToolCall, filterActionsByAllowedNames, normalizeAgentActionSurfaceResolution, readPersistedActionSurface, toolCallCacheKey, getActiveRunForThreadAsync, abortRunDurably, abortTurnDurably, subscribeToRun, } from "../agent/production-agent.js";
-import { clientAbortReason } from "../agent/run-loop-with-resume.js";
 import { callerHasRunAccess, callerHasThreadAccess, } from "../agent/run-ownership.js";
 import { markTurnAborted, readBackgroundRunClaim } from "../agent/run-store.js";
 import { buildCurrentTimeUserContext, buildRuntimeContextPrompt, } from "../agent/runtime-context.js";
@@ -33,6 +33,7 @@ import { filterFrameworkToolGroups, resolveFrameworkTools, } from "../framework-
 import { verifyInternalToken, extractBearerToken, } from "../integrations/internal-token.js";
 import { RECURRING_JOBS_SWEEP_PATH, RECURRING_JOBS_SWEEP_TOKEN_SUBJECT, } from "../jobs/scheduler-dispatch.js";
 import { McpClientManager, mcpToolsToActionEntries, syncMcpActionEntries, mountMcpServersRoutes, mountMcpHubRoutes, buildMergedConfig, startMcpConfigRefresh, getHubStatus, isHubServeEnabled, } from "../mcp-client/index.js";
+import { declaredMcpToolNames } from "../mcp/build-server.js";
 import { setProgressPreListHook } from "../progress/store.js";
 import { getSkillNameFromPath } from "../resources/metadata.js";
 import { resourceList, resourceListAccessible, resourceGet, ensurePersonalDefaults, SHARED_OWNER, WORKSPACE_OWNER, } from "../resources/store.js";
@@ -113,7 +114,7 @@ import { buildSystemManifestSections, setContextXraySystemSections, } from "../a
 // the ones that were already part of the public surface) so
 // `createAgentChatPlugin` below stays a thinner orchestrator.
 // ---------------------------------------------------------------------------
-import { buildSelectedA2AReceiverContext, createA2AEngineToolSurface, DEFAULT_DELEGATED_MAX_ITERATIONS, DEFAULT_DELEGATED_MAX_RUN_INPUT_TOKENS, DEFAULT_DELEGATED_MAX_TOOL_RESULT_CHARS, filterAgentTools, filterPublicAgentActions, filterDirectA2AActions, filterReadOnlyActions, isSelectedA2AReceiver, resolveInitialToolNames, runA2AAgentLoop, runMCPAgentLoop, assembleA2AFinalResponse, buildPublicAgentA2ASkills, buildAuthenticatedAgentA2ASkills, resolveArtifactBaseUrl, } from "./agent-chat/action-filters-a2a.js";
+import { buildSelectedA2AReceiverContext, createA2AEngineToolSurface, DEFAULT_DELEGATED_MAX_ITERATIONS, DEFAULT_DELEGATED_MAX_RUN_INPUT_TOKENS, DEFAULT_DELEGATED_MAX_TOOL_RESULT_CHARS, filterAgentTools, filterMcpOnlyActions, filterPublicAgentActions, filterDirectA2AActions, filterReadOnlyActions, isSelectedA2AReceiver, resolveInitialToolNames, runA2AAgentLoop, runMCPAgentLoop, assembleA2AFinalResponse, buildPublicAgentA2ASkills, buildAuthenticatedAgentA2ASkills, resolveArtifactBaseUrl, } from "./agent-chat/action-filters-a2a.js";
 import { createBuilderBrowserTool, createTeamTools, } from "./agent-chat/browser-team-tools.js";
 import { createDataWidgetActionEntries, createFrameworkContextEntry, createRefreshScreenEntry, createUrlTools, } from "./agent-chat/context-tools.js";
 import { _agentChatPromptSectionsForTests, buildFrameworkPrompts, buildSchemaBlock, collectFiles, corpusToolNamesTaughtByPrompt, generateActionsPrompt, generateCorpusToolsPrompt, } from "./agent-chat/framework-prompts.js";
@@ -708,6 +709,17 @@ export function createAgentChatPlugin(options) {
             // whatever `generateCorpusToolsPrompt` teaches by name for this request.
             const templateInitialToolNames = resolveInitialToolNames(templateScripts, options?.initialToolNames);
             const discoveredActions = filterFrameworkToolGroups(filterAgentTools(discoveredActionsAll), disabledFrameworkGroups);
+            // MCP-only actions: `agentTool: false` with an explicit `mcpTool: true`.
+            // `filterAgentTools` above just dropped them — correctly, since the app's
+            // own agent must not see them — so the external surfaces below re-merge
+            // this set instead of reading the unfiltered registries. Keep it OUT of
+            // `allScripts`, the chat/A2A/ask_app loops, and every prompt: an
+            // `ask_app` run is the app's own agent, which `agentTool: false` already
+            // answered. Only the direct MCP and A2A tool surfaces get these.
+            const mcpOnlyActions = filterFrameworkToolGroups(filterMcpOnlyActions({
+                ...discoveredActionsAll,
+                ...templateScriptsAll,
+            }), disabledFrameworkGroups);
             // Per-request owner is read from the AsyncLocalStorage run context
             // (populated by prepareRun). Module-scope `let` would race across
             // concurrent requests on a long-lived Node process — overlapping
@@ -1146,6 +1158,14 @@ export function createAgentChatPlugin(options) {
                     ...devRunCodeTool,
                 })
                 : undefined;
+            // The surface external agents get: everything the app's agent has, plus
+            // the MCP-only actions the agent filter removed. The agent sets win on a
+            // name collision, which by construction cannot happen — an action is in
+            // one set or the other, never both.
+            const externalActions = { ...mcpOnlyActions, ...allScripts };
+            const externalFullActions = mcpFullActions
+                ? { ...mcpOnlyActions, ...mcpFullActions }
+                : undefined;
             const { mountA2A } = await import("../a2a/server.js");
             mountA2A(nitroApp, {
                 appId: options?.appId,
@@ -1153,13 +1173,13 @@ export function createAgentChatPlugin(options) {
                     ? options.appId.charAt(0).toUpperCase() + options.appId.slice(1)
                     : "Agent",
                 description: `Agent-native ${options?.appId ?? "app"} agent`,
-                skills: buildPublicAgentA2ASkills(allScripts),
-                authenticatedSkills: buildAuthenticatedAgentA2ASkills(mcpFullActions ?? allScripts, mcpOptions),
+                skills: buildPublicAgentA2ASkills(externalActions),
+                authenticatedSkills: buildAuthenticatedAgentA2ASkills(externalFullActions ?? externalActions, mcpOptions),
                 publicSkillsOnly: true,
                 streaming: true,
                 durableBackgroundRuns: options?.durableBackgroundRuns,
                 executeReadOnlyAction: async ({ action, input, invocationId }) => {
-                    const actions = filterDirectA2AActions(mcpFullActions ?? allScripts, mcpOptions);
+                    const actions = filterDirectA2AActions(externalFullActions ?? externalActions, mcpOptions);
                     const entry = actions[action];
                     if (!entry) {
                         return {
@@ -1188,7 +1208,7 @@ export function createAgentChatPlugin(options) {
                 },
                 executeApproval: async (approval) => {
                     const result = await executeAgentToolCall({
-                        actions: mcpFullActions ?? allScripts,
+                        actions: externalFullActions ?? externalActions,
                         name: approval.tool,
                         input: approval.input,
                         callId: approval.callId,
@@ -1523,7 +1543,14 @@ export function createAgentChatPlugin(options) {
                         });
                     const a2aToolSurface = createA2AEngineToolSurface(actionsToEngineTools(a2aActions), effectiveInitialToolNames, {
                         receiverOwnsObjective,
-                        localCapabilityNames: mcpOptions.connectorCatalog,
+                        // Same curated set the MCP mount serves: config names plus the
+                        // actions that declare `mcpTool: true` themselves.
+                        localCapabilityNames: [
+                            ...new Set([
+                                ...(mcpOptions.connectorCatalog ?? []),
+                                ...declaredMcpToolNames(a2aActions),
+                            ]),
+                        ],
                     });
                     // Precise current time rides the user message (not the cached
                     // system-prompt prefix) — same pattern as the interactive handler.
@@ -1848,8 +1875,8 @@ export function createAgentChatPlugin(options) {
                         `Agent-native ${options?.appId ?? "app"} agent`,
                     websiteUrl: mcpOptions.websiteUrl,
                     icons: mcpOptions.icons,
-                    actions: allScripts,
-                    productionActions: mcpFullActions,
+                    actions: externalActions,
+                    productionActions: externalFullActions,
                     ...(mcpOptions.catalog ? { catalogMode: mcpOptions.catalog } : {}),
                     ...(mcpOptions.builtinCrossAppTools !== undefined
                         ? { builtinCrossAppTools: mcpOptions.builtinCrossAppTools }

package/dist/server/agent-discovery.js

@@ -40,6 +40,8 @@ export function normalizeAgentId(id) {
         normalized === "asset") {
         return "assets";
     }
+    if (normalized === "videos")
+        return "clips";
     return normalized;
 }
 const WORKSPACE_APPS_ENV_KEY = "AGENT_NATIVE_WORKSPACE_APPS_JSON";
@@ -67,8 +69,11 @@ export function parseWorkspaceAppMetadataSettings(raw) {
         ? record.apps
         : {};
     const apps = {};
-    for (const [id, value] of Object.entries(rawApps)) {
-        if (!id.trim() || !value || typeof value !== "object")
+    const canonicalIds = new Set();
+    for (const [rawId, value] of Object.entries(rawApps)) {
+        const id = rawId.trim();
+        const normalizedId = id ? normalizeAgentId(id) : "";
+        if (!normalizedId || !value || typeof value !== "object")
             continue;
         const item = value;
         const override = {};
@@ -89,8 +94,14 @@ export function parseWorkspaceAppMetadataSettings(raw) {
             override.updatedAt = updatedAt;
         if (updatedBy)
             override.updatedBy = updatedBy;
-        if (Object.keys(override).length > 0)
-            apps[id.trim()] = override;
+        if (Object.keys(override).length > 0) {
+            const isCanonical = id.toLowerCase() === normalizedId;
+            if (isCanonical || !canonicalIds.has(normalizedId)) {
+                apps[normalizedId] = override;
+            }
+            if (isCanonical)
+                canonicalIds.add(normalizedId);
+        }
     }
     return { apps };
 }
@@ -110,7 +121,7 @@ export async function writeWorkspaceAppMetadataOverride(input) {
     const key = workspaceAppMetadataSettingsKey();
     if (!key)
         throw new Error("no authenticated user");
-    const appId = input.appId.trim();
+    const appId = normalizeAgentId(input.appId);
     if (!appId)
         throw new Error("appId is required");
     const { getSetting, putSetting } = await import("../settings/index.js");
@@ -145,7 +156,7 @@ export async function writeWorkspaceAppMetadataOverride(input) {
     return current;
 }
 export function applyWorkspaceAppMetadataOverride(app, settings) {
-    const override = settings.apps[app.id];
+    const override = settings.apps[normalizeAgentId(app.id)] ?? settings.apps[app.id];
     if (!override)
         return app;
     const name = cleanOptionalText(override.name);
@@ -244,21 +255,20 @@ export async function discoverAgents(selfAppId, options) {
                     continue;
                 const manifestId = normalizeAgentId(manifest.id);
                 // If the resource override carries a localhost URL but we're running
-                // in production (e.g. a stale dev-time seed got promoted to the prod
+                // in a hosted runtime (e.g. a stale dev-time seed got promoted to the prod
                 // DB), fall back to the matching built-in's prod URL instead of
                 // letting the override win — otherwise outbound `call-agent` fetches
                 // from a serverless function would target localhost and fail with
                 // "fetch failed" instantly. The override still wins for non-localhost
                 // URLs (the supported case for self-hosted custom agents).
                 let url = manifest.url;
-                const isProduction = typeof process !== "undefined" &&
-                    process.env?.NODE_ENV === "production";
-                if (isProduction &&
-                    typeof url === "string" &&
-                    /^https?:\/\/(localhost|127\.0\.0\.1|0\.0\.0\.0)(:|\/|$)/.test(url)) {
+                const isHosted = isHostedRuntime();
+                if (isHosted && typeof url === "string" && isLoopbackUrl(url)) {
                     const builtin = agentsById.get(manifestId);
                     if (builtin?.url)
                         url = builtin.url;
+                    else
+                        continue;
                 }
                 const builtin = agentsById.get(manifestId);
                 if (options?.preferLocalUrls && builtin) {
@@ -327,10 +337,19 @@ function hostnameFromUrlLike(value) {
 }
 function isLoopbackUrl(value) {
     const hostname = hostnameFromUrlLike(value);
-    return (hostname === "localhost" ||
-        hostname === "127.0.0.1" ||
-        hostname === "0.0.0.0" ||
-        hostname === "::1");
+    if (!hostname)
+        return false;
+    const normalized = hostname.replace(/^\[|\]$/g, "");
+    if (normalized === "localhost" ||
+        normalized.startsWith("127.") ||
+        normalized === "0.0.0.0" ||
+        normalized === "::1") {
+        return true;
+    }
+    const mapped = normalized.match(/^::ffff:([0-9a-f]{1,4}):([0-9a-f]{1,4})$/i);
+    if (!mapped)
+        return false;
+    return Number.parseInt(mapped[1], 16) >>> 8 === 0x7f;
 }
 function hasPublicRuntimeUrl() {
     // Intentionally omit generic `URL` / `DEPLOY_URL` here. Platforms that set
@@ -353,6 +372,8 @@ function hasPublicRuntimeUrl() {
     });
 }
 function isHostedRuntime() {
+    if (process.env.NETLIFY_LOCAL === "true")
+        return false;
     return (process.env.NODE_ENV === "production" ||
         !!process.env.NETLIFY ||
         !!process.env.AWS_LAMBDA_FUNCTION_NAME ||
@@ -412,7 +433,8 @@ function parseWorkspaceAppsManifest(parsed) {
         if (!entry || typeof entry !== "object")
             return null;
         const e = entry;
-        const id = typeof e.id === "string" ? e.id.trim() : "";
+        const rawId = typeof e.id === "string" ? e.id.trim() : "";
+        const id = rawId ? normalizeAgentId(rawId) : "";
         const pathValue = typeof e.path === "string" ? e.path.trim() : "";
         if (!id || !pathValue.startsWith("/"))
             return null;
@@ -498,11 +520,11 @@ function readWorkspaceAppsFromFilesystem() {
             return null;
         const routeAccess = workspaceAppRouteAccessFromPackageJson(pkg);
         return {
-            id: entry.name,
+            id: normalizeAgentId(entry.name),
             name: pkg.displayName || titleCase(entry.name),
             description: pkg.description || "",
             path: `/${entry.name}`,
-            isDispatch: entry.name === "dispatch",
+            isDispatch: normalizeAgentId(entry.name) === "dispatch",
             audience: workspaceAppAudienceFromPackageJson(pkg) ??
                 DEFAULT_WORKSPACE_APP_AUDIENCE,
             publicPaths: routeAccess.publicPaths ?? [],
@@ -550,8 +572,9 @@ async function discoverWorkspaceAgents(selfAppId, options) {
     if (!workspaceApps)
         return [];
     const metadataSettings = await readWorkspaceAppMetadataSettings();
+    const normalizedSelfAppId = selfAppId ? normalizeAgentId(selfAppId) : "";
     return workspaceApps
-        .filter((app) => app.id !== selfAppId)
+        .filter((app) => normalizeAgentId(app.id) !== normalizedSelfAppId)
         .map((app) => {
         const withOverride = applyWorkspaceAppMetadataOverride(app, metadataSettings);
         const builtin = BUILTIN_AGENTS.find((agent) => agent.id === withOverride.id);

package/dist/server/auth.js

@@ -4056,6 +4056,24 @@ async function mountBetterAuthRoutes(app, options) {
             return { error: authError.message };
         }
     }));
+    // Better Auth redirects new magic-link users through this small public
+    // callback so first-run onboarding is marked only for newly created users.
+    // Keep this before the generic magic-link handler for runtimes whose
+    // app.use() middleware paths match descendants as prefixes.
+    app.use("/_agent-native/auth/magic-link/new-user", defineEventHandler(async (event) => {
+        if (!isReadMethod(event)) {
+            setResponseStatus(event, 405);
+            return { error: "Method not allowed" };
+        }
+        const query = getQuery(event);
+        const rawReturn = Array.isArray(query.return)
+            ? query.return[0]
+            : query.return;
+        if (await getSession(event)) {
+            setFirstRunOnboardingCookie(event);
+        }
+        return redirectWithStagedCookies(event, safeReturnPath(rawReturn), 302);
+    }));
     // Passwordless login via Better Auth's rate-limited magic-link plugin.
     app.use("/_agent-native/auth/magic-link", defineEventHandler(async (event) => {
         if (getMethod(event) === "GET") {
@@ -4313,22 +4331,6 @@ async function mountBetterAuthRoutes(app, options) {
             headers: { "Content-Type": "text/html; charset=utf-8" },
         });
     }));
-    // Better Auth redirects new magic-link users through this small public
-    // callback so first-run onboarding is marked only for newly created users.
-    app.use("/_agent-native/auth/magic-link/new-user", defineEventHandler(async (event) => {
-        if (!isReadMethod(event)) {
-            setResponseStatus(event, 405);
-            return { error: "Method not allowed" };
-        }
-        const query = getQuery(event);
-        const rawReturn = Array.isArray(query.return)
-            ? query.return[0]
-            : query.return;
-        if (await getSession(event)) {
-            setFirstRunOnboardingCookie(event);
-        }
-        return redirectWithStagedCookies(event, safeReturnPath(rawReturn), 302);
-    }));
     // Auth guard — stored both in framework middleware registry AND in
     // _authGuardFn so the server middleware can enforce it on ALL routes.
     const loginHtmlConfig = getOnboardingLoginHtmlConfig(options, authLoginMode);