@agent-native/core 0.145.2 → 0.145.4

package/dist/server/agent-chat/plugin-options.d.ts

@@ -5,6 +5,7 @@ import type { FrameworkToolsConfig } from "../../framework-tools.js";
 import type { ExternalAgentPolicy } from "../../mcp/external-agent-policy.js";
 import type { DatabaseToolsOption } from "../../scripts/db/tool-mode.js";
 import type { PromptExamples } from "../prompts/index.js";
+import type { AgentChatMcpIcon, AgentChatMcpOptions } from "./mcp-options.js";
 /** Shape of a Nitro plugin function: receives the Nitro app instance at
  * startup and may register routes/hooks synchronously or asynchronously. */
 export type NitroPluginDef = (nitroApp: any) => void | Promise<void>;
@@ -51,21 +52,23 @@ export interface AgentChatPluginOptions {
     mentionProviders?: Record<string, MentionProvider> | (() => Record<string, MentionProvider> | Promise<Record<string, MentionProvider>>);
     /** App ID used to exclude self from agent discovery (e.g., "mail", "calendar") */
     appId?: string;
-    /** Optional MCP server branding surfaced during the initialize handshake. */
+    /**
+     * Everything about this app's MCP mount — whether it is mounted, which tools
+     * external callers see, and the branding sent during the `initialize`
+     * handshake. See `AgentChatMcpOptions`.
+     *
+     * Replaces the top-level `disableMcp`, `mcpServerInfo`, `connectorCatalog`,
+     * and `externalAgents`, which stay accepted for one minor. Setting both
+     * forms to disagreeing values throws at plugin init rather than silently
+     * picking one.
+     */
+    mcp?: AgentChatMcpOptions;
+    /** @deprecated Use `mcp.title` / `mcp.description` / `mcp.websiteUrl` / `mcp.icons`. */
     mcpServerInfo?: {
-        /** Human-facing title. Defaults to the capitalized app id/name. */
         title?: string;
-        /** Host-facing description. Defaults to "Agent-native <app> agent". */
         description?: string;
-        /** Canonical app URL. Relative URLs are resolved against the request origin. */
         websiteUrl?: string;
-        /** App icons. Relative `src` values are resolved against the request origin. */
-        icons?: Array<{
-            src: string;
-            mimeType?: string;
-            sizes?: string[];
-            theme?: "light" | "dark";
-        }>;
+        icons?: AgentChatMcpIcon[];
     };
     /**
      * Optional callback to resolve the org ID for the current request.
@@ -330,15 +333,10 @@ export interface AgentChatPluginOptions {
      * claim in their connect-minted JWT) or the deployment-wide
      * `AGENT_NATIVE_MCP_FULL_CATALOG=1` env override.
      *
-     * Declare here rather than in MCPConfig directly; the plugin copies it through.
+     * @deprecated Use `mcp.connectorCatalog`.
      */
     connectorCatalog?: string[];
-    /**
-     * Default authenticated external-agent policy. In `auto` read mode, every
-     * action explicitly marked as GET + readOnly + publicAgent.requiresAuth is
-     * added to the connector surface automatically. Writes remain ask_app-only
-     * unless `writes: "allowlisted"` is explicitly selected.
-     */
+    /** @deprecated Use `mcp.externalAgents`. */
     externalAgents?: ExternalAgentPolicy;
     /**
      * Allow this app's A2A agent to delegate to a different app through the
@@ -359,14 +357,7 @@ export interface AgentChatPluginOptions {
         maxRunInputTokens?: number;
         maxToolResultChars?: number;
     };
-    /**
-     * Skip mounting the remote MCP protocol route.
-     *
-     * Most apps should leave this off so agent chat, A2A, and MCP share one
-     * runtime. Hosted apps with a dedicated early MCP plugin can set this to
-     * true so their external connector does not depend on the heavier chat
-     * plugin initialization path.
-     */
+    /** @deprecated Use `mcp: { enabled: false }`. */
     disableMcp?: boolean;
     /**
      * Code-execution capability for the production agent.

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

@@ -110,6 +110,7 @@ import { createA2AEngineToolSurface, DEFAULT_DELEGATED_MAX_ITERATIONS, DEFAULT_D
 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";
+import { resolveAgentChatMcpOptions } from "./agent-chat/mcp-options.js";
 import { resolveA2AAgentDelegationEnabled, } from "./agent-chat/plugin-options.js";
 import { finalizeClaimedAgentChatProcessRunFailure } from "./agent-chat/process-run-failure.js";
 import { loadResourcesForPrompt, promptResourceManifestSections, resourceScopeForOwner, } from "./agent-chat/prompt-resources.js";
@@ -286,6 +287,11 @@ export function createAgentChatPlugin(options) {
             // here rather than booting with a surface nobody chose.
             const frameworkTools = resolveFrameworkTools(options);
             const disabledFrameworkGroups = frameworkTools.disabledGroups;
+            // Same treatment for the MCP mount: one resolved shape, folding the
+            // deprecated `disableMcp` / `mcpServerInfo` / `connectorCatalog` /
+            // `externalAgents` into `mcp`. A2A reads the same object, so the
+            // connector policy cannot diverge between the two external surfaces.
+            const mcpOptions = resolveAgentChatMcpOptions(options);
             // Build the four assembled system prompt strings. These are static for the
             // lifetime of this plugin instance — examples come from options once at
             // startup, not per-request.
@@ -1055,12 +1061,12 @@ export function createAgentChatPlugin(options) {
                     : "Agent",
                 description: `Agent-native ${options?.appId ?? "app"} agent`,
                 skills: buildPublicAgentA2ASkills(allScripts),
-                authenticatedSkills: buildAuthenticatedAgentA2ASkills(mcpFullActions ?? allScripts, options ?? {}),
+                authenticatedSkills: buildAuthenticatedAgentA2ASkills(mcpFullActions ?? allScripts, mcpOptions),
                 publicSkillsOnly: true,
                 streaming: true,
                 durableBackgroundRuns: options?.durableBackgroundRuns,
                 executeReadOnlyAction: async ({ action, input, invocationId }) => {
-                    const actions = filterDirectA2AActions(mcpFullActions ?? allScripts, options ?? {});
+                    const actions = filterDirectA2AActions(mcpFullActions ?? allScripts, mcpOptions);
                     const entry = actions[action];
                     if (!entry) {
                         return {
@@ -1667,26 +1673,30 @@ export function createAgentChatPlugin(options) {
                         : DEV_FRAMEWORK_PROMPT) + devActionsPrompt;
             // Keep legacy names for the composition below
             const basePrompt = prodPrompt;
-            if (options?.disableMcp !== true) {
+            if (mcpOptions.enabled) {
                 // Mount MCP remote server — same action registry as A2A + agent chat
                 const { mountMCP } = await import("../mcp/server.js");
                 mountMCP(nitroApp, {
                     name: options?.appId
                         ? options.appId.charAt(0).toUpperCase() + options.appId.slice(1)
                         : "Agent",
-                    title: options?.mcpServerInfo?.title,
+                    title: mcpOptions.title,
                     appId: options?.appId,
-                    description: options?.mcpServerInfo?.description ??
+                    description: mcpOptions.description ??
                         `Agent-native ${options?.appId ?? "app"} agent`,
-                    websiteUrl: options?.mcpServerInfo?.websiteUrl,
-                    icons: options?.mcpServerInfo?.icons,
+                    websiteUrl: mcpOptions.websiteUrl,
+                    icons: mcpOptions.icons,
                     actions: allScripts,
                     productionActions: mcpFullActions,
-                    ...(options?.connectorCatalog
-                        ? { connectorCatalog: options.connectorCatalog }
+                    ...(mcpOptions.catalog ? { catalogMode: mcpOptions.catalog } : {}),
+                    ...(mcpOptions.builtinCrossAppTools !== undefined
+                        ? { builtinCrossAppTools: mcpOptions.builtinCrossAppTools }
                         : {}),
-                    ...(options?.externalAgents
-                        ? { externalAgents: options.externalAgents }
+                    ...(mcpOptions.connectorCatalog
+                        ? { connectorCatalog: mcpOptions.connectorCatalog }
+                        : {}),
+                    ...(mcpOptions.externalAgents
+                        ? { externalAgents: mcpOptions.externalAgents }
                         : {}),
                     askAgent: async (message) => {
                         const ownerEmail = getRequestUserEmail();

package/dist/server/index.d.ts

@@ -32,6 +32,7 @@ export { createObservationalMemoryPlugin, defaultObservationalMemoryPlugin, } fr
 export { createGoogleAuthPlugin, type GoogleAuthPluginOptions, } from "./google-auth-plugin.js";
 export type { GoogleAuthMode } from "./google-auth-mode.js";
 export { createAgentChatPlugin, defaultAgentChatPlugin, refreshGlobalMcpManager, type AgentChatPluginOptions, } from "./agent-chat-plugin.js";
+export type { AgentChatMcpIcon, AgentChatMcpOptions, } from "./agent-chat/mcp-options.js";
 export { configureAgentNativeEmbeddedEnvironment, createAgentNativeEmbeddedAuthOptions, createAgentNativeEmbeddedPlugin, mountAgentNativeEmbedded, normalizeAgentNativeEmbeddedSession, type AgentNativeEmbeddedAuthOptions, type AgentNativeEmbeddedGetSession, type AgentNativeEmbeddedHostSession, type AgentNativeEmbeddedPluginOptions, } from "./embedded.js";
 export { createThread, getThread, listThreads, updateThreadData, deleteThread, setThreadArchived, setThreadPinned, setThreadScope, type ChatThread, type ChatThreadScope, type ChatThreadSummary, type ListThreadsOptions, } from "../chat-threads/store.js";
 export { createResourcesPlugin, defaultResourcesPlugin, } from "./resources-plugin.js";
@@ -52,6 +53,8 @@ export { getH3App, awaitBootstrap, markDefaultPluginProvided, type H3AppShim, }
 export { fireInternalDispatch, resolveSelfDispatchBaseUrl, type FireInternalDispatchOptions, } from "./self-dispatch.js";
 export { extractBearerToken as extractInternalBearerToken, verifyInternalToken, } from "../integrations/internal-token.js";
 export { autoDiscoverActions, autoDiscoverScripts, loadActionsFromStaticRegistry, mergeCoreSharingActions, registerPackageActions, } from "./action-discovery.js";
+export { attachToolSearch, createToolSearchEntry, searchToolRegistry, TOOL_SEARCH_ACTION_NAME, } from "../agent/tool-search.js";
+export { filterFrameworkToolGroups, frameworkGroupEnabled, resolveFrameworkTools, FRAMEWORK_TOOL_GROUPS, type FrameworkToolGroup, type FrameworkToolsConfig, type FrameworkToolsOption, type ResolvedFrameworkTools, } from "../framework-tools.js";
 export { registerPromptContextProvider, type PromptContextProvider, type PromptContextProviderContext, type PromptContextProviderContribution, } from "./agent-chat/prompt-resources.js";
 export { mountActionRoutes, type MountActionRoutesOptions, type ActionRouteAuthAdapter, type ActionRouteResolvedCaller, } from "./action-routes.js";
 export { AGENT_RUN_OWNER_CONTEXT_KEY, seedAgentRunOwnerContext, type AgentRunOwnerContext, } from "./agent-run-context.js";

package/dist/server/index.js

@@ -53,6 +53,13 @@ export { getH3App, awaitBootstrap, markDefaultPluginProvided, } from "./framewor
 export { fireInternalDispatch, resolveSelfDispatchBaseUrl, } from "./self-dispatch.js";
 export { extractBearerToken as extractInternalBearerToken, verifyInternalToken, } from "../integrations/internal-token.js";
 export { autoDiscoverActions, autoDiscoverScripts, loadActionsFromStaticRegistry, mergeCoreSharingActions, registerPackageActions, } from "./action-discovery.js";
+// A standalone `mountMCP` plugin has to compose the same action surface the
+// agent-chat plugin does. Without these, the only way to build one was to
+// hand-roll a copy — which is how a template ends up with a `tool-search` that
+// drifts from the framework's, and an MCP mount that silently ignores
+// `frameworkTools`.
+export { attachToolSearch, createToolSearchEntry, searchToolRegistry, TOOL_SEARCH_ACTION_NAME, } from "../agent/tool-search.js";
+export { filterFrameworkToolGroups, frameworkGroupEnabled, resolveFrameworkTools, FRAMEWORK_TOOL_GROUPS, } from "../framework-tools.js";
 export { registerPromptContextProvider, } from "./agent-chat/prompt-resources.js";
 export { mountActionRoutes, } from "./action-routes.js";
 export { AGENT_RUN_OWNER_CONTEXT_KEY, seedAgentRunOwnerContext, } from "./agent-run-context.js";

package/dist/server/poll.d.ts

@@ -114,6 +114,15 @@ export interface AppSyncStateOptions {
      * Postgres only; ignored on SQLite.
      */
     dbAssignedVersions?: boolean;
+    /**
+     * TTL for a cached ALLOW decision. Defaults to 30s.
+     *
+     * `invalidateCollabAccessCache` only reaches the in-process default instance,
+     * so a gateway holding per-app instances cannot be told a share was revoked
+     * and serves its cached ALLOW until this lapses. Shorten it to bound that
+     * window, at the cost of more `can-see` round-trips per shared resource.
+     */
+    accessAllowTtlMs?: number;
 }
 /**
  * Per-app change-tracking state and read path. One instance per deployed app.
@@ -180,7 +189,9 @@ export declare class AppSyncState {
     private readonly accessInFlight;
     /** Per-resource generation bumped when shares/visibility change. */
     private readonly accessInvalidationEpoch;
+    private readonly accessAllowTtlMs;
     constructor(options?: AppSyncStateOptions);
+    private accessCacheTtl;
     /**
      * Durable-event id. Deterministic (hash of logical identity + `dedupeKey`,
      * excluding the per-instance `version`) when the instance opts in AND a

package/dist/server/poll.js

@@ -153,9 +153,6 @@ function accessCacheKey(userEmail, orgId, resourceType, resourceId) {
 function accessResourceKey(resourceType, resourceId) {
     return `${resourceType}|${resourceId}`;
 }
-function accessCacheTtl(allowed) {
-    return allowed ? ACCESS_CACHE_TTL_MS : ACCESS_CACHE_DENY_TTL_MS;
-}
 function extensionTargetKey(target) {
     if (target.owner)
         return `owner:${target.owner}`;
@@ -291,14 +288,19 @@ export class AppSyncState {
     accessInFlight = new Set();
     /** Per-resource generation bumped when shares/visibility change. */
     accessInvalidationEpoch = new Map();
+    accessAllowTtlMs;
     constructor(options = {}) {
         this.getDb = options.getDb ?? getDbExec;
         this.isPg = options.isPostgres ?? isPostgres;
         this.resolveAccessFn = options.resolveAccess ?? defaultResolveAccess;
         this.deterministicEventIds = options.deterministicEventIds ?? false;
         this.dbAssignedVersions = options.dbAssignedVersions ?? false;
+        this.accessAllowTtlMs = options.accessAllowTtlMs ?? ACCESS_CACHE_TTL_MS;
         this.pollEmitter.setMaxListeners(0);
     }
+    accessCacheTtl(allowed) {
+        return allowed ? this.accessAllowTtlMs : ACCESS_CACHE_DENY_TTL_MS;
+    }
     /**
      * Durable-event id. Deterministic (hash of logical identity + `dedupeKey`,
      * excluding the per-instance `version`) when the instance opts in AND a
@@ -675,7 +677,8 @@ export class AppSyncState {
             const key = accessCacheKey(userEmail, orgId, event.resourceType, event.resourceId);
             const cached = this.accessCache.get(key);
             const now = Date.now();
-            if (cached && now - cached.checkedAt < accessCacheTtl(cached.allowed)) {
+            if (cached &&
+                now - cached.checkedAt < this.accessCacheTtl(cached.allowed)) {
                 // Fresh, non-expired cache hit → trust the cached decision.
                 return cached.allowed ? "visible" : "hidden";
             }

package/dist/server/realtime-token.js

@@ -28,6 +28,13 @@ import { signRealtimeSubscribeToken } from "./short-lived-token.js";
 export const REALTIME_HMAC_SECRET_ENV = "AGENT_NATIVE_REALTIME_HMAC_SECRET";
 /** Short TTL — validated at connect; the gateway rotates over the stream. */
 const REALTIME_TOKEN_TTL_SECONDS = 600;
+/**
+ * Ceiling on how long one mint can be extended by gateway rotation before the
+ * client must come back through this session-gated endpoint. Without it a single
+ * mint streams forever and logout, session expiry, user deletion and org removal
+ * never reach an open stream.
+ */
+const REALTIME_SESSION_MAX_SECONDS = 15 * 60;
 export function getRealtimeSigningSecret() {
     return process.env[REALTIME_HMAC_SECRET_ENV]?.trim() || undefined;
 }
@@ -76,6 +83,7 @@ export function createRealtimeTokenHandler() {
                 owner: session.email,
                 orgId: requestContext.orgId,
                 ttlSeconds: REALTIME_TOKEN_TTL_SECONDS,
+                absExp: Math.floor(Date.now() / 1000) + REALTIME_SESSION_MAX_SECONDS,
             }, secret);
             const expiresAt = new Date(Date.now() + REALTIME_TOKEN_TTL_SECONDS * 1000).toISOString();
             return { token, expiresAt, ttlSeconds: REALTIME_TOKEN_TTL_SECONDS };

package/dist/server/short-lived-token.d.ts

@@ -82,6 +82,13 @@ export interface RealtimeSubscribeClaims {
     orgId?: string;
     /** Override default TTL (seconds). */
     ttlSeconds?: number;
+    /**
+     * Absolute unix-seconds ceiling, independent of `exp`. The gateway re-signs a
+     * stream's token every few minutes without consulting the app, so `exp` alone
+     * lets one mint be extended forever and a revoked session keeps streaming.
+     * Rotation copies this verbatim and never extends it.
+     */
+    absExp?: number;
 }
 /**
  * Result of {@link verifyRealtimeSubscribeToken}. On success it returns the
@@ -93,6 +100,7 @@ export type RealtimeVerifyResult = {
     owner?: string;
     orgId?: string;
     exp: number;
+    absExp?: number;
 } | {
     ok: false;
     reason: string;

package/dist/server/short-lived-token.js

@@ -182,6 +182,8 @@ export function signRealtimeSubscribeToken(claims, key) {
         payload.owner = claims.owner;
     if (claims.orgId)
         payload.orgId = claims.orgId;
+    if (claims.absExp)
+        payload.absExp = claims.absExp;
     const payloadStr = base64UrlEncode(JSON.stringify(payload));
     return `${payloadStr}.${hmacB64(payloadStr, key)}`;
 }
@@ -218,6 +220,15 @@ export function verifyRealtimeSubscribeToken(token, expected) {
     if (claims.exp * 1000 < Date.now()) {
         return { ok: false, reason: "expired" };
     }
+    if (claims.absExp !== undefined) {
+        if (typeof claims.absExp !== "number") {
+            return { ok: false, reason: "bad_payload" };
+        }
+        // `<=`, not `<`: a ceiling is not valid at the instant it is reached.
+        if (claims.absExp * 1000 <= Date.now()) {
+            return { ok: false, reason: "session_expired" };
+        }
+    }
     if (claims.projectId !== expected.projectId) {
         return { ok: false, reason: "wrong_project" };
     }
@@ -227,6 +238,7 @@ export function verifyRealtimeSubscribeToken(token, expected) {
         owner: claims.owner,
         orgId: claims.orgId,
         exp: claims.exp,
+        absExp: claims.absExp,
     };
 }
 // ── Gateway access-check tokens ──────────────────────────────────────────────

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

@@ -20,6 +20,6 @@ export declare function createTranscribeVoiceHandler(): import("h3").EventHandle
     error: string;
     text?: undefined;
 } | {
-    text: string;
     error?: undefined;
+    text: string;
 }>>;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@agent-native/core",
-  "version": "0.145.2",
+  "version": "0.145.4",
   "description": "Framework for agent-native application development — where AI agents and UI share SQL state, actions, and context",
   "homepage": "https://github.com/BuilderIO/agent-native#readme",
   "bugs": {