@agent-native/core 0.0.0-beta-20260820194548 → 0.0.0-beta-20260820200358

package/dist/agent/index.d.ts

@@ -1,4 +1,4 @@
-export { createProductionAgentHandler, type ActionEntry, type ScriptEntry, type ProductionAgentOptions, type AgentActionSurface, type AgentActionSurfaceDetails, type AgentLoopFinalResponseGuard, type AgentLoopFinalResponseGuardContext, type AgentLoopFinalResponseGuardResult, type AgentLoopToolCallSummary, type AgentLoopToolResultSummary, } from "./production-agent.js";
+export { createProductionAgentHandler, type ActionEntry, type ScriptEntry, type ProductionAgentOptions, type AgentActionSurface, type DefaultAgentActionSurface, type AgentActionSurfaceResolution, type AgentActionSurfaceDetails, type AgentLoopFinalResponseGuard, type AgentLoopFinalResponseGuardContext, type AgentLoopFinalResponseGuardResult, type AgentLoopToolCallSummary, type AgentLoopToolResultSummary, } from "./production-agent.js";
 export { type ActionTool, type ScriptTool, type AgentMessage, type AgentChatRequest, type AgentChatEvent, type AgentChatAttachment, type AgentChatReference, type MentionProvider, type MentionProviderItem, } from "./types.js";
 export { TripWire, type Processor, type ProcessorState, type ProcessorAbort, type ProcessOutputStreamArgs, type ProcessOutputStepArgs, type ProcessOutputResultArgs, } from "./processors.js";
 export { DEFAULT_MODEL } from "./default-model.js";

package/dist/agent/production-agent.d.ts

@@ -259,6 +259,14 @@ export type AgentExecutionMode = "act" | "plan";
 export interface AgentActionSurface {
     allowedActionNames: readonly string[];
 }
+export interface DefaultAgentActionSurface {
+    mode: "default";
+}
+export type AgentActionSurfaceResolution = AgentActionSurface | DefaultAgentActionSurface;
+type NormalizedAgentActionSurface = DefaultAgentActionSurface | {
+    mode: "allowlist";
+    allowedActionNames: string[];
+};
 export interface AgentActionSurfaceDetails {
     event: any;
     ownerEmail: string | null;
@@ -271,10 +279,14 @@ export interface AgentActionSurfaceDetails {
 /** Read a persisted allowlist while preserving legacy absence and failing
  * closed when the field is present but malformed. */
 export declare function readPersistedAllowedActionNames(value: unknown): string[] | undefined;
-export interface PersistedActionSurface {
+export declare function normalizeAgentActionSurfaceResolution(value: unknown): NormalizedAgentActionSurface;
+export type PersistedActionSurface = {
     orgId: string | null;
     allowedActionNames: string[];
-}
+} | {
+    orgId: string | null;
+    mode: "default";
+};
 /** Read a nested persisted action surface. An absent envelope is legacy;
  * a present but invalid envelope is an explicit org-less, empty surface. */
 export declare function readPersistedActionSurface(value: unknown, propertyName: string): PersistedActionSurface | undefined;
@@ -342,11 +354,12 @@ export interface ProductionAgentOptions {
     }>;
     /**
      * Resolve the exact action registry exposed to one interactive agent-chat
-     * request. Returned names are a hard allowlist: omitted actions are absent
-     * from both the provider schemas and the searchable registry. When set, all
-     * allowed actions are loaded directly on the first model request.
+     * request. Return an allowlist to remove omitted actions from both provider
+     * schemas and the searchable registry, or `{ mode: "default" }` to preserve
+     * the normal initial-tool and discovery behavior for that request. Every
+     * allowlisted action is loaded directly on the first model request.
      */
-    resolveActionSurface?: (details: AgentActionSurfaceDetails) => AgentActionSurface | Promise<AgentActionSurface>;
+    resolveActionSurface?: (details: AgentActionSurfaceDetails) => AgentActionSurfaceResolution | Promise<AgentActionSurfaceResolution>;
     /** Optional per-app agent run chunk budget in milliseconds. Defaults to
      *  AGENT_RUN_SOFT_TIMEOUT_MS when set, otherwise no framework-imposed
      *  timeout. When reached, the client receives an internal auto-continuation

package/dist/agent/production-agent.js

@@ -411,13 +411,32 @@ export function readPersistedAllowedActionNames(value) {
     }
     return [...new Set(names)];
 }
+export function normalizeAgentActionSurfaceResolution(value) {
+    if (hasOwn(value, "mode")) {
+        if (value.mode === "default" && !hasOwn(value, "allowedActionNames")) {
+            return { mode: "default" };
+        }
+        throw new Error("resolveActionSurface returned an invalid default surface");
+    }
+    if (!hasOwn(value, "allowedActionNames")) {
+        throw new Error("resolveActionSurface returned an invalid action surface");
+    }
+    const allowedActionNames = value.allowedActionNames;
+    if (!Array.isArray(allowedActionNames) ||
+        !allowedActionNames.every((name) => typeof name === "string")) {
+        throw new Error("resolveActionSurface returned an invalid action surface");
+    }
+    return {
+        mode: "allowlist",
+        allowedActionNames: [...new Set(allowedActionNames)],
+    };
+}
 /** Read a nested persisted action surface. An absent envelope is legacy;
  * a present but invalid envelope is an explicit org-less, empty surface. */
 export function readPersistedActionSurface(value, propertyName) {
     if (!hasOwn(value, propertyName))
         return undefined;
     const surface = value[propertyName];
-    const allowedActionNames = readPersistedAllowedActionNames(surface) ?? [];
     if (!hasOwn(surface, "orgId")) {
         return { orgId: null, allowedActionNames: [] };
     }
@@ -426,6 +445,13 @@ export function readPersistedActionSurface(value, propertyName) {
         (typeof orgId !== "string" || orgId.trim().length === 0)) {
         return { orgId: null, allowedActionNames: [] };
     }
+    if (hasOwn(surface, "mode")) {
+        if (surface.mode === "default" && !hasOwn(surface, "allowedActionNames")) {
+            return { orgId, mode: "default" };
+        }
+        return { orgId: null, allowedActionNames: [] };
+    }
+    const allowedActionNames = readPersistedAllowedActionNames(surface) ?? [];
     return { orgId, allowedActionNames };
 }
 export function filterActionsByAllowedNames(actions, allowedActionNames) {
@@ -6560,6 +6586,7 @@ export function createProductionAgentHandler(options) {
             availableRequestActions = filterActionsByAllowedNames(availableRequestActions, filterHostedHarnessToolNames(Object.keys(availableRequestActions)));
         }
         let surfacedRequestActions = availableRequestActions;
+        let useDefaultRequestActionSurface = !options.resolveActionSurface;
         if (options.resolveActionSurface) {
             const persistedSurface = isBackgroundWorker
                 ? readPersistedActionSurface(body, "__resolvedActionSurface")
@@ -6575,19 +6602,33 @@ export function createProductionAgentHandler(options) {
                     internalContinuation: Boolean(internalContinuation),
                     availableActionNames: Object.keys(availableRequestActions),
                 });
-            surfacedRequestActions = filterActionsByAllowedNames(availableRequestActions, surface.allowedActionNames);
-            if (requestedHostedHarness) {
-                surfacedRequestActions = filterActionsByAllowedNames(surfacedRequestActions, filterHostedHarnessToolNames(Object.keys(surfacedRequestActions)));
-            }
-            const allowedNames = Object.keys(surfacedRequestActions);
+            const normalizedSurface = normalizeAgentActionSurfaceResolution(surface);
             const runCtx = ensureRequestRunContext();
-            if (runCtx)
-                runCtx.allowedActionNames = allowedNames;
-            if (!isBackgroundWorker) {
-                body.__resolvedActionSurface = {
-                    orgId: getRequestOrgId() ?? null,
-                    allowedActionNames: allowedNames,
-                };
+            if (normalizedSurface.mode === "default") {
+                useDefaultRequestActionSurface = true;
+                if (runCtx)
+                    delete runCtx.allowedActionNames;
+                if (!isBackgroundWorker) {
+                    body.__resolvedActionSurface = {
+                        orgId: getRequestOrgId() ?? null,
+                        mode: "default",
+                    };
+                }
+            }
+            else {
+                surfacedRequestActions = filterActionsByAllowedNames(availableRequestActions, normalizedSurface.allowedActionNames);
+                if (requestedHostedHarness) {
+                    surfacedRequestActions = filterActionsByAllowedNames(surfacedRequestActions, filterHostedHarnessToolNames(Object.keys(surfacedRequestActions)));
+                }
+                const allowedNames = Object.keys(surfacedRequestActions);
+                if (runCtx)
+                    runCtx.allowedActionNames = allowedNames;
+                if (!isBackgroundWorker) {
+                    body.__resolvedActionSurface = {
+                        orgId: getRequestOrgId() ?? null,
+                        allowedActionNames: allowedNames,
+                    };
+                }
             }
         }
         // DIAGNOSTIC-ONLY: owner/request context prep (resolveAgentOwnerEmail +
@@ -7075,9 +7116,9 @@ export function createProductionAgentHandler(options) {
             ? createPlanModeActionRegistry(surfacedRequestActions)
             : surfacedRequestActions;
         const availableRequestTools = getEngineTools(requestActions);
-        const initialRequestTools = options.resolveActionSurface
-            ? availableRequestTools
-            : filterInitialEngineTools(availableRequestTools, options.initialToolNames);
+        const initialRequestTools = useDefaultRequestActionSurface
+            ? filterInitialEngineTools(availableRequestTools, options.initialToolNames)
+            : availableRequestTools;
         const requestTools = requestMode === "plan"
             ? preloadPlanModeEngineTools({
                 request: requestMessage,

package/dist/agent/types.d.ts

@@ -208,6 +208,9 @@ export interface AgentChatRequest {
     __resolvedActionSurface?: {
         orgId: string | null;
         allowedActionNames: string[];
+    } | {
+        orgId: string | null;
+        mode: "default";
     };
     /**
      * Stable identity for the logical assistant turn this request belongs to.

package/dist/collab/awareness.d.ts

@@ -62,11 +62,11 @@ export declare const postAwareness: import("h3").EventHandlerWithFetch<import("h
     error: string;
     states?: undefined;
 } | {
+    error?: undefined;
     states: {
         clientId: number;
         state: string;
     }[];
-    error?: undefined;
 }>>;
 /**
  * GET /_agent-native/collab/:docId/users
@@ -77,9 +77,9 @@ export declare const getActiveUsers: import("h3").EventHandlerWithFetch<import("
     error: string;
     users?: undefined;
 } | {
+    error?: undefined;
     users: {
         clientId: number;
         lastSeen: number;
     }[];
-    error?: undefined;
 }>>;

package/dist/index.d.ts

@@ -1,5 +1,5 @@
 export * from "./config.js";
-export { createProductionAgentHandler, type ActionEntry, type ScriptEntry, type ProductionAgentOptions, type AgentActionSurface, type AgentActionSurfaceDetails, type ActionTool, type ScriptTool, type AgentMessage, type AgentChatRequest, type AgentChatEvent, type AgentChatAttachment, DEFAULT_MODEL, TripWire, type Processor, type ProcessorState, type ProcessorAbort, } from "./agent/index.js";
+export { createProductionAgentHandler, type ActionEntry, type ScriptEntry, type ProductionAgentOptions, type AgentActionSurface, type DefaultAgentActionSurface, type AgentActionSurfaceResolution, type AgentActionSurfaceDetails, type ActionTool, type ScriptTool, type AgentMessage, type AgentChatRequest, type AgentChatEvent, type AgentChatAttachment, DEFAULT_MODEL, TripWire, type Processor, type ProcessorState, type ProcessorAbort, } from "./agent/index.js";
 export { defineAction, ActionContractError, isActionContractError, type ActionContractErrorOptions, AgentActionStopError, isAgentActionStopError, type ActionDefinition, type ActionHttpConfig, type AgentActionStopOptions, type PublicAgentActionConfig, type ActionDeepLink, type ActionLinkBuilder, MCP_APP_EXTENSION_ID, MCP_APP_MIME_TYPE, MCP_APP_RESOURCE_URI_META_KEY, type ActionMcpAppConfig, type ActionMcpAppCsp, type ActionMcpAppCspBuilder, type ActionMcpAppHtmlBuilder, type ActionMcpAppPermissions, type ActionMcpAppResourceConfig, type ActionMcpAppResourceMeta, } from "./action.js";
 export * from "./user-profile/index.js";
 export { embedApp, MCP_APP_REQUEST_ORIGIN_CSP_SOURCE, type EmbedAppOptions, } from "./mcp/embed-app.js";

package/dist/notifications/routes.d.ts

@@ -11,14 +11,14 @@
  *   DELETE /_agent-native/notifications/:id         — delete
  */
 export declare function createNotificationsHandler(): import("h3").EventHandlerWithFetch<import("h3").EventHandlerRequest, Promise<"" | import("./types.js").Notification[] | {
+    error?: undefined;
     count: number;
     updated?: undefined;
     ok?: undefined;
-    error?: undefined;
 } | {
+    error?: undefined;
     updated: number;
     ok?: undefined;
-    error?: undefined;
     count?: undefined;
 } | {
     updated?: undefined;
@@ -26,8 +26,8 @@ export declare function createNotificationsHandler(): import("h3").EventHandlerW
     ok?: undefined;
     count?: undefined;
 } | {
+    error?: undefined;
     updated?: undefined;
     ok: boolean;
-    error?: undefined;
     count?: undefined;
 }>>;

package/dist/observability/routes.d.ts

@@ -41,27 +41,27 @@ export declare function createObservabilityHandler(): import("h3").EventHandlerW
     thumbsUpRate: number;
     avgEvalScore: number;
 } | {
-    ok?: undefined;
-    error?: undefined;
     summary: import("./types.js").TraceSummary;
     spans: import("./types.js").TraceSpan[];
     id?: undefined;
-} | {
-    ok?: undefined;
     error?: undefined;
+    ok?: undefined;
+} | {
     summary?: undefined;
     spans?: undefined;
     id: string;
-} | {
+    error?: undefined;
     ok?: undefined;
+} | {
     summary?: undefined;
     spans?: undefined;
     id?: undefined;
     error: any;
+    ok?: undefined;
 } | {
-    error?: undefined;
     summary?: undefined;
     spans?: undefined;
     id?: undefined;
+    error?: undefined;
     ok: boolean;
 }>>;

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

@@ -171,8 +171,9 @@ export interface AgentChatPluginOptions {
     }>;
     /**
      * Resolve the exact native action surface for each interactive chat request.
-     * Omitted names are not sent to the model and are not discoverable through
-     * tool-search. When configured, every allowed action is loaded directly.
+     * Omitted allowlist names are not sent to the model or discoverable through
+     * tool-search. Return `{ mode: "default" }` to keep the normal initial-tool
+     * and discovery behavior for a request instead.
      */
     resolveActionSurface?: ProductionAgentOptions["resolveActionSurface"];
     /**

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

@@ -13,7 +13,7 @@ import { resolveEngine, createAnthropicEngine, getStoredModelForEngine, normaliz
 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, readPersistedActionSurface, toolCallCacheKey, getActiveRunForThreadAsync, abortRunDurably, abortTurnDurably, subscribeToRun, } from "../agent/production-agent.js";
+import { createProductionAgentHandler, actionsToEngineTools, executeAgentToolCall, filterActionsByAllowedNames, normalizeAgentActionSurfaceResolution, readPersistedActionSurface, toolCallCacheKey, getActiveRunForThreadAsync, abortRunDurably, abortTurnDurably, subscribeToRun, } from "../agent/production-agent.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";
@@ -2974,11 +2974,14 @@ Non-code requests are still fine on this surface: read data, navigate the UI, su
                             ...details,
                             availableActionNames: appActionNames,
                         });
+                        const normalizedSurface = normalizeAgentActionSurfaceResolution(surface);
+                        if (normalizedSurface.mode === "default")
+                            return surface;
                         const localActionNames = details.availableActionNames.filter((name) => localDevActionNames.has(name));
                         return {
                             allowedActionNames: [
                                 ...new Set([
-                                    ...surface.allowedActionNames,
+                                    ...normalizedSurface.allowedActionNames,
                                     ...localActionNames,
                                 ]),
                             ],

package/dist/server/index.d.ts

@@ -15,7 +15,7 @@ export { requireEnvKey, type MissingKeyResponse } from "./missing-key.js";
 export { assertCurrentRequestUserIsOrgAdmin, currentRequestUserIsOrgAdmin, } from "./org-admin.js";
 export { verifyCaptcha, type CaptchaVerifyResult } from "./captcha.js";
 export { getLocaleInitScript, parseAcceptLanguage, resolveLocaleFromRequest, type LocaleInitScriptOptions, type ResolveLocaleFromRequestOptions, type ResolvedRequestLocale, } from "../localization/server.js";
-export { createProductionAgentHandler, type ActionEntry, type ScriptEntry, type ProductionAgentOptions, type AgentActionSurface, type AgentActionSurfaceDetails, type ActionTool, type ScriptTool, type AgentMessage, type AgentChatRequest, type AgentChatEvent, type AgentChatAttachment, type AgentChatReference, type MentionProvider, type MentionProviderItem, type AgentLoopFinalResponseGuard, type AgentLoopFinalResponseGuardContext, type AgentLoopFinalResponseGuardResult, type AgentLoopToolCallSummary, type AgentLoopToolResultSummary, } from "../agent/index.js";
+export { createProductionAgentHandler, type ActionEntry, type ScriptEntry, type ProductionAgentOptions, type AgentActionSurface, type DefaultAgentActionSurface, type AgentActionSurfaceResolution, type AgentActionSurfaceDetails, type ActionTool, type ScriptTool, type AgentMessage, type AgentChatRequest, type AgentChatEvent, type AgentChatAttachment, type AgentChatReference, type MentionProvider, type MentionProviderItem, type AgentLoopFinalResponseGuard, type AgentLoopFinalResponseGuardContext, type AgentLoopFinalResponseGuardResult, type AgentLoopToolCallSummary, type AgentLoopToolResultSummary, } from "../agent/index.js";
 export { actionsToEngineTools, executeAgentToolCall, getOwnerActiveApiKey, getOwnerApiKeyForEngine, resolveOwnerEngineApiKey, runAgentLoop, type AgentToolCallExecutionResult, type ExecuteAgentToolCallOptions, type ResolvedOwnerApiKey, } from "../agent/production-agent.js";
 export { mountRealtimeVoiceRoutes, realtimeVoiceSafetyIdentifier, REALTIME_VOICE_MAX_SDP_BYTES, REALTIME_VOICE_MAX_TOOL_BODY_BYTES, REALTIME_VOICE_MAX_TOOL_OUTPUT_CHARS, REALTIME_VOICE_SESSION_PATH, REALTIME_VOICE_TOOL_PATH, type MountRealtimeVoiceRoutesOptions, type RealtimeVoiceRequestContext, type RealtimeVoiceToolExecutionRequest, type RealtimeVoiceToolExecutionResult, } from "./realtime-voice.js";
 export { getStoredModelForEngine, resolveEngine, } from "../agent/engine/index.js";

package/dist/server/realtime-token.d.ts

@@ -26,8 +26,8 @@ export declare function createRealtimeTokenHandler(): import("h3").EventHandlerW
     expiresAt?: undefined;
     ttlSeconds?: undefined;
 } | {
-    error?: undefined;
     token: string;
     expiresAt: string;
     ttlSeconds: number;
+    error?: undefined;
 }>>;

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

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

package/docs/content/agent-surfaces.mdx

@@ -188,6 +188,12 @@ createAgentChatPlugin({
 });
 ```
 
+When the same resolver also handles unrestricted chat, return
+`{ mode: "default" }`. This preserves the normal `initialToolNames` filtering
+and `tool-search` discovery instead of loading every available schema on the
+first model request. The explicit mode is preserved across durable
+continuations.
+
 An empty list exposes no native actions. Unknown names fail the request instead
 of widening access. Every allowed action is loaded directly on the first model
 request; include `tool-search` explicitly only when discovery inside the

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@agent-native/core",
-  "version": "0.0.0-beta-20260820194548",
+  "version": "0.0.0-beta-20260820200358",
   "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": {