@agent-native/core 0.144.2 → 0.145.0

package/dist/mcp/screen-memory-stdio.d.ts

@@ -137,13 +137,13 @@ export declare function screenMemoryMcpToolDefinitions(): ({
     inputSchema: {
         type: string;
         properties: {
+            count?: undefined;
             query?: undefined;
             minutes?: undefined;
             limit?: undefined;
             clientHint?: undefined;
             timestamp?: undefined;
             chapterId?: undefined;
-            count?: undefined;
             startAt?: undefined;
             endAt?: undefined;
             reason?: undefined;
@@ -159,6 +159,7 @@ export declare function screenMemoryMcpToolDefinitions(): ({
     inputSchema: {
         type: string;
         properties: {
+            count?: undefined;
             query: {
                 type: string;
                 description: string;
@@ -174,7 +175,6 @@ export declare function screenMemoryMcpToolDefinitions(): ({
             clientHint?: undefined;
             timestamp?: undefined;
             chapterId?: undefined;
-            count?: undefined;
             startAt?: undefined;
             endAt?: undefined;
             reason?: undefined;
@@ -190,6 +190,7 @@ export declare function screenMemoryMcpToolDefinitions(): ({
     inputSchema: {
         type: string;
         properties: {
+            count?: undefined;
             minutes: {
                 type: string;
                 description: string;
@@ -199,7 +200,6 @@ export declare function screenMemoryMcpToolDefinitions(): ({
             clientHint?: undefined;
             timestamp?: undefined;
             chapterId?: undefined;
-            count?: undefined;
             startAt?: undefined;
             endAt?: undefined;
             reason?: undefined;
@@ -216,6 +216,7 @@ export declare function screenMemoryMcpToolDefinitions(): ({
         type: string;
         required: string[];
         properties: {
+            count?: undefined;
             query: {
                 type: string;
                 description: string;
@@ -234,7 +235,6 @@ export declare function screenMemoryMcpToolDefinitions(): ({
             };
             timestamp?: undefined;
             chapterId?: undefined;
-            count?: undefined;
             startAt?: undefined;
             endAt?: undefined;
             reason?: undefined;
@@ -250,6 +250,7 @@ export declare function screenMemoryMcpToolDefinitions(): ({
         type: string;
         required: string[];
         properties: {
+            count?: undefined;
             query?: undefined;
             minutes?: undefined;
             limit?: undefined;
@@ -263,7 +264,6 @@ export declare function screenMemoryMcpToolDefinitions(): ({
                 description: string;
             };
             chapterId?: undefined;
-            count?: undefined;
             startAt?: undefined;
             endAt?: undefined;
             includeMicrophone?: undefined;
@@ -314,13 +314,13 @@ export declare function screenMemoryMcpToolDefinitions(): ({
         type: string;
         required: string[];
         properties: {
+            count?: undefined;
             query?: undefined;
             minutes?: undefined;
             limit?: undefined;
             clientHint?: undefined;
             timestamp?: undefined;
             chapterId?: undefined;
-            count?: undefined;
             startAt: {
                 type: string;
                 description: string;
@@ -349,13 +349,13 @@ export declare function screenMemoryMcpToolDefinitions(): ({
         type: string;
         required: string[];
         properties: {
+            count?: undefined;
             query?: undefined;
             minutes?: undefined;
             limit?: undefined;
             clientHint?: undefined;
             timestamp?: undefined;
             chapterId?: undefined;
-            count?: undefined;
             startAt?: undefined;
             endAt?: undefined;
             reason?: undefined;

package/dist/notifications/routes.d.ts

@@ -16,18 +16,18 @@ export declare function createNotificationsHandler(): import("h3").EventHandlerW
     error?: undefined;
     ok?: undefined;
 } | {
+    count?: undefined;
     updated: number;
     error?: undefined;
     ok?: undefined;
-    count?: undefined;
 } | {
+    count?: undefined;
     updated?: undefined;
     error: string;
     ok?: undefined;
-    count?: undefined;
 } | {
+    count?: undefined;
     updated?: undefined;
     error?: undefined;
     ok: boolean;
-    count?: undefined;
 }>>;

package/dist/oauth-tokens/google-refresh.js

@@ -11,8 +11,11 @@
  * server plugin (see `templates/mail/server/plugins/oauth-refresh.ts`).
  */
 import { resolveGoogleProviderCredentialCandidates } from "../server/google-oauth-credentials.js";
+import { startIntervalJob } from "../server/interval-job.js";
 import { listOAuthAccounts, saveOAuthTokens } from "./store.js";
 const GOOGLE_TOKEN_URL = "https://oauth2.googleapis.com/token";
+/** Bounds each per-account refresh call — this loop runs sequentially over every expiring account. */
+const REFRESH_REQUEST_TIMEOUT_MS = 15_000;
 async function refreshOne(refreshToken) {
     const credentialCandidates = resolveGoogleProviderCredentialCandidates();
     if (!credentialCandidates.length) {
@@ -30,6 +33,7 @@ async function refreshOne(refreshToken) {
                 client_secret: credentials.clientSecret,
                 grant_type: "refresh_token",
             }),
+            signal: AbortSignal.timeout(REFRESH_REQUEST_TIMEOUT_MS),
         });
         lastStatusText = res.statusText;
         data = (await res.json());
@@ -91,7 +95,6 @@ export async function refreshExpiringGoogleTokens(opts = {}) {
     }
 }
 let _started = false;
-let _timer;
 /**
  * Start the refresh loop. Idempotent — calling more than once is a no-op,
  * so multiple plugins/templates loading this in the same process are safe.
@@ -108,25 +111,15 @@ export function startGoogleTokenRefreshLoop(opts = {}) {
     }
     const intervalMs = opts.intervalMs ?? 20 * 60 * 1000;
     const bufferMs = opts.bufferMs ?? 15 * 60 * 1000;
-    // Kick off an initial pass shortly after startup (not immediately — the DB
+    // Kick off the first pass shortly after startup (not immediately — the DB
     // may still be initializing).
-    const initialTimer = setTimeout(() => {
-        refreshExpiringGoogleTokens({ bufferMs }).catch((err) => {
-            console.error("[google-refresh] initial pass failed:", err);
+    const startupTimer = setTimeout(() => {
+        startIntervalJob(() => refreshExpiringGoogleTokens({ bufferMs }), {
+            intervalMs,
+            onError: (err) => {
+                console.error("[google-refresh] refresh pass failed:", err);
+            },
         });
     }, 30_000);
-    _timer = setInterval(() => {
-        refreshExpiringGoogleTokens({ bufferMs }).catch((err) => {
-            console.error("[google-refresh] interval pass failed:", err);
-        });
-    }, intervalMs);
-    // Don't let either timer keep the process alive on its own.
-    if (typeof initialTimer === "object" &&
-        initialTimer &&
-        "unref" in initialTimer) {
-        initialTimer.unref();
-    }
-    if (typeof _timer === "object" && _timer && "unref" in _timer) {
-        _timer.unref();
-    }
+    startupTimer.unref?.();
 }

package/dist/observability/routes.d.ts

@@ -42,22 +42,22 @@ export declare function createObservabilityHandler(): import("h3").EventHandlerW
     avgEvalScore: number;
 } | {
     error?: undefined;
+    ok?: 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;
-    ok?: undefined;
 } | {
+    ok?: undefined;
     summary?: undefined;
     spans?: undefined;
     id?: undefined;
     error: any;
-    ok?: undefined;
 } | {
     error?: undefined;
     summary?: undefined;

package/dist/progress/routes.d.ts

@@ -15,6 +15,6 @@ export declare function createProgressHandler(): import("h3").EventHandlerWithFe
     error: string;
     ok?: undefined;
 } | {
-    ok: boolean;
     error?: undefined;
+    ok: boolean;
 }>>;

package/dist/provider-api/actions/custom-provider-registration.d.ts

@@ -76,7 +76,7 @@ export declare function createCustomProviderRegistrationAction<TSchema extends Z
     }>>;
 }, z.core.$strip>>, {
     deleted?: undefined;
-    id?: undefined;
+    found?: undefined;
     providers: {
         id: string;
         label: string;
@@ -88,24 +88,24 @@ export declare function createCustomProviderRegistrationAction<TSchema extends Z
     }[];
     count: number;
     provider?: undefined;
-    found?: undefined;
     registered?: undefined;
+    id?: undefined;
     label?: undefined;
     message?: undefined;
 } | {
     deleted?: undefined;
-    count?: undefined;
-    id?: undefined;
     providers?: undefined;
+    count?: undefined;
     found: boolean;
     provider: import("../custom-registry.js").CustomProviderConfig;
     registered?: undefined;
+    id?: undefined;
     label?: undefined;
     message?: undefined;
 } | {
     deleted?: undefined;
-    count?: undefined;
     providers?: undefined;
+    count?: undefined;
     provider?: undefined;
     found: boolean;
     id: string;
@@ -113,10 +113,10 @@ export declare function createCustomProviderRegistrationAction<TSchema extends Z
     label?: undefined;
     message?: undefined;
 } | {
-    count?: undefined;
+    found?: undefined;
     providers?: undefined;
+    count?: undefined;
     provider?: undefined;
-    found?: undefined;
     deleted: boolean;
     id: string;
     registered?: undefined;
@@ -124,10 +124,10 @@ export declare function createCustomProviderRegistrationAction<TSchema extends Z
     message?: undefined;
 } | {
     deleted?: undefined;
-    count?: undefined;
+    found?: undefined;
     providers?: undefined;
+    count?: undefined;
     provider?: undefined;
-    found?: undefined;
     registered: boolean;
     id: string;
     label: string;

package/dist/provider-api/actions/provider-api.d.ts

@@ -311,10 +311,10 @@ export declare function createProviderApiActions(runtime: Pick<ProviderApiRuntim
         notes?: string | undefined;
         scope?: "org" | "user" | undefined;
     }, {
-        message?: undefined;
         id?: undefined;
         provider?: undefined;
         deleted?: undefined;
+        found?: undefined;
         providers: {
             id: string;
             label: string;
@@ -325,45 +325,45 @@ export declare function createProviderApiActions(runtime: Pick<ProviderApiRuntim
             updatedAt: number;
         }[];
         count: number;
-        found?: undefined;
         registered?: undefined;
         label?: undefined;
-    } | {
         message?: undefined;
-        count?: undefined;
+    } | {
         id?: undefined;
         deleted?: undefined;
+        count?: undefined;
         providers?: undefined;
         found: boolean;
         provider: import("../custom-registry.js").CustomProviderConfig;
         registered?: undefined;
         label?: undefined;
-    } | {
         message?: undefined;
-        count?: undefined;
+    } | {
         provider?: undefined;
         deleted?: undefined;
+        count?: undefined;
         providers?: undefined;
         found: boolean;
         id: string;
         registered?: undefined;
         label?: undefined;
-    } | {
         message?: undefined;
-        count?: undefined;
+    } | {
         provider?: undefined;
-        providers?: undefined;
         found?: undefined;
+        count?: undefined;
+        providers?: undefined;
         deleted: boolean;
         id: string;
         registered?: undefined;
         label?: undefined;
+        message?: undefined;
     } | {
-        count?: undefined;
         provider?: undefined;
         deleted?: undefined;
-        providers?: undefined;
         found?: undefined;
+        count?: undefined;
+        providers?: undefined;
         registered: boolean;
         id: string;
         label: string;

package/dist/resources/handlers.d.ts

@@ -48,8 +48,8 @@ export declare function handleUpdateResource(event: any): Promise<import("./stor
 }>;
 /** DELETE /_agent-native/resources/:id — delete a resource */
 export declare function handleDeleteResource(event: any): Promise<{
-    error: string;
     ok?: undefined;
+    error: string;
 } | {
     error?: undefined;
     ok: boolean;

package/dist/secrets/routes.d.ts

@@ -34,16 +34,16 @@ export declare function createListSecretsHandler(): import("h3").EventHandlerWit
 /** POST /_agent-native/secrets/:key — write a secret. */
 export declare function createWriteSecretHandler(): import("h3").EventHandlerWithFetch<import("h3").EventHandlerRequest, Promise<{
     error: string;
-    status?: undefined;
     ok?: undefined;
+    status?: undefined;
 } | {
     ok: boolean;
     status: string;
     error?: undefined;
 } | {
+    ok?: undefined;
     error: string;
     removed?: undefined;
-    ok?: undefined;
 } | {
     ok: boolean;
     removed: boolean;
@@ -54,9 +54,9 @@ export declare function createWriteSecretHandler(): import("h3").EventHandlerWit
  * or the current stored value without changing anything.
  */
 export declare function createTestSecretHandler(): import("h3").EventHandlerWithFetch<import("h3").EventHandlerRequest, Promise<{
+    ok?: undefined;
     error: string;
     note?: undefined;
-    ok?: undefined;
 } | {
     ok: boolean;
     note?: undefined;

package/dist/server/action-discovery.d.ts

@@ -26,6 +26,7 @@
  * ```
  */
 import type { ActionEntry } from "../agent/production-agent.js";
+import type { FrameworkToolGroup } from "../framework-tools.js";
 /**
  * Register a map of actions contributed by a published package.
  *
@@ -80,6 +81,32 @@ export declare function loadActionsFromStaticRegistry(modules: Record<string, un
  *   passing to `createAgentChatPlugin({ actions })`.
  */
 export declare function autoDiscoverActions(from: string): Promise<Record<string, ActionEntry>>;
+/**
+ * Which `frameworkTools` switch owns each framework action kit.
+ *
+ * The group is stamped onto the entry as `frameworkGroup`, which is what lets
+ * one filter subtract a whole kit from every agent tool surface at once — the
+ * plugin spreads these registries at thirteen composition sites, and a
+ * per-site condition would be the same omission waiting to happen thirteen
+ * times. The tag also keeps these ~45 schemas out of the DEFAULT first-request
+ * tool list; they stay reachable through `tool-search`.
+ *
+ * Anything absent from this map is always-on and must be listed in
+ * `ALWAYS_ON_CORE_ACTIONS` instead. `action-discovery.spec.ts` fails when a new
+ * core action appears in neither, so "always-on" stays a decision someone made
+ * rather than the default that happens when a map goes un-updated.
+ */
+export declare const CORE_ACTION_GROUPS: Record<string, FrameworkToolGroup>;
+/**
+ * Core actions with no `frameworkTools` switch, and why:
+ *
+ * - `upload-image` is load-bearing for ordinary work.
+ * - The email catalog is mounted everywhere on purpose so Dispatch can ask any
+ *   app what it sends without that app opting in (see its comment below). It is
+ *   a read surface, not the `email` group's send capability.
+ * - MCP tools and org service tokens are already governed by `disableMcp`.
+ */
+export declare const ALWAYS_ON_CORE_ACTIONS: ReadonlySet<string>;
 export declare function mergeCoreSharingActions(registry: Record<string, ActionEntry>): Promise<void>;
 /** @deprecated Use `autoDiscoverActions` instead */
 export declare const autoDiscoverScripts: typeof autoDiscoverActions;

package/dist/server/action-discovery.js

@@ -497,6 +497,92 @@ export async function autoDiscoverActions(from) {
     }
     return registry;
 }
+/**
+ * Which `frameworkTools` switch owns each framework action kit.
+ *
+ * The group is stamped onto the entry as `frameworkGroup`, which is what lets
+ * one filter subtract a whole kit from every agent tool surface at once — the
+ * plugin spreads these registries at thirteen composition sites, and a
+ * per-site condition would be the same omission waiting to happen thirteen
+ * times. The tag also keeps these ~45 schemas out of the DEFAULT first-request
+ * tool list; they stay reachable through `tool-search`.
+ *
+ * Anything absent from this map is always-on and must be listed in
+ * `ALWAYS_ON_CORE_ACTIONS` instead. `action-discovery.spec.ts` fails when a new
+ * core action appears in neither, so "always-on" stays a decision someone made
+ * rather than the default that happens when a map goes un-updated.
+ */
+export const CORE_ACTION_GROUPS = {
+    "share-resource": "sharing",
+    "unshare-resource": "sharing",
+    "list-resource-shares": "sharing",
+    "set-resource-visibility": "sharing",
+    "create-agent-resource-link": "sharing",
+    "get-feature-flags": "featureFlags",
+    "list-feature-flags": "featureFlags",
+    "set-feature-flag": "featureFlags",
+    "list-recurring-jobs": "automation",
+    "manage-recurring-job": "automation",
+    "run-automation-now": "automation",
+    "list-automation-runs": "automation",
+    "list-automations": "automation",
+    "manage-automation": "automation",
+    "context-manifest-get": "contextXray",
+    "context-preview-get": "contextXray",
+    "context-pin": "contextXray",
+    "context-evict": "contextXray",
+    "context-restore": "contextXray",
+    "context-report": "contextXray",
+    "get-localization-preference": "localization",
+    "set-localization-preference": "localization",
+    // Profile, credentials, and appearance share one switch: an app that hides
+    // its profile surface from the agent hides password management with it.
+    "get-user-profile": "userProfile",
+    "update-user-profile": "userProfile",
+    "get-auth-methods": "userProfile",
+    "set-password": "userProfile",
+    "change-password": "userProfile",
+    "change-appearance": "userProfile",
+    "list-audit-events": "audit",
+    "get-audit-event": "audit",
+    "export-audit-events": "audit",
+    "create-resource-version": "history",
+    "list-resource-versions": "history",
+    "get-resource-version": "history",
+    "restore-resource-version": "history",
+    "list-resource-history": "history",
+    "list-review-comments": "review",
+    "create-review-comment": "review",
+    "reply-review-comment": "review",
+    "resolve-review-thread": "review",
+    "delete-review-comment": "review",
+    "consume-review-feedback": "review",
+    "get-review-feedback": "review",
+    "set-review-status": "review",
+    "send-review-thread-to-agent": "review",
+};
+/**
+ * Core actions with no `frameworkTools` switch, and why:
+ *
+ * - `upload-image` is load-bearing for ordinary work.
+ * - The email catalog is mounted everywhere on purpose so Dispatch can ask any
+ *   app what it sends without that app opting in (see its comment below). It is
+ *   a read surface, not the `email` group's send capability.
+ * - MCP tools and org service tokens are already governed by `disableMcp`.
+ */
+export const ALWAYS_ON_CORE_ACTIONS = new Set([
+    "upload-image",
+    "list-transactional-emails",
+    "render-transactional-email-preview",
+    "list-email-log",
+    "list-email-activity",
+    "list-email-engagement",
+    "create-org-service-token",
+    "list-org-service-tokens",
+    "revoke-org-service-token",
+    "list-mcp-tools",
+    "call-mcp-tool",
+]);
 export async function mergeCoreSharingActions(registry) {
     const entries = [
         ["share-resource", () => import("../sharing/actions/share-resource.js")],
@@ -732,6 +818,9 @@ export async function mergeCoreSharingActions(registry) {
                     // actions' `toolCallable: false` (audit-H5) is dropped and the
                     // tools-iframe bridge 403 in action-routes.ts never fires.
                     ...preserveActionFlags(def),
+                    ...(CORE_ACTION_GROUPS[name]
+                        ? { frameworkGroup: CORE_ACTION_GROUPS[name] }
+                        : {}),
                 };
             }
         }

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

@@ -117,5 +117,16 @@ export declare function createA2AEngineToolSurface(availableTools: EngineTool[],
     tools: EngineTool[];
     availableTools: EngineTool[];
 };
+/**
+ * The first-request tool catalog: an explicit `initialToolNames` verbatim, or
+ * the app's OWN actions by default.
+ *
+ * "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`.
+ */
 export declare function resolveInitialToolNames(templateActions: Record<string, ActionEntry>, configured?: string[]): string[];
 export {};

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

@@ -5,6 +5,7 @@ import { resolveMainChatMaxOutputTokens } from "../../agent/engine/output-tokens
 import { filterInitialEngineTools, resolveAgentRequestReasoningEffort, } from "../../agent/production-agent.js";
 import { runAgentLoopDirectWithSoftTimeout } from "../../agent/run-loop-with-resume.js";
 import { resolveRunSoftTimeoutMs } from "../../agent/run-manager.js";
+import { isFrameworkGroupedAction } from "../../framework-tools.js";
 import { isAuthenticatedReadAction, isAutoReadExcludedActionName, } from "../../mcp/build-server.js";
 import { withConfiguredAppBasePath } from "../app-base-path.js";
 // ---------------------------------------------------------------------------
@@ -389,6 +390,21 @@ export function createA2AEngineToolSurface(availableTools, initialToolNames) {
         availableTools,
     };
 }
+/**
+ * The first-request tool catalog: an explicit `initialToolNames` verbatim, or
+ * the app's OWN actions by default.
+ *
+ * "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`.
+ */
 export function resolveInitialToolNames(templateActions, configured) {
-    return configured ?? Object.keys(templateActions);
+    if (configured)
+        return configured;
+    return Object.entries(templateActions)
+        .filter(([, entry]) => !isFrameworkGroupedAction(entry))
+        .map(([name]) => name);
 }

package/dist/server/agent-chat/framework-prompts.d.ts

@@ -1,4 +1,5 @@
 import type { ActionEntry } from "../../agent/production-agent.js";
+import type { FrameworkToolGroup } from "../../framework-tools.js";
 import type { DatabaseToolsOption } from "../../scripts/db/tool-mode.js";
 import { type PromptExamples } from "../prompts/index.js";
 import { resolveInitialToolNames } from "./action-filters-a2a.js";
@@ -15,6 +16,7 @@ import { createDataWidgetActionEntries } from "./context-tools.js";
 export declare function buildFrameworkPrompts(examples?: PromptExamples, options?: {
     databaseTools?: DatabaseToolsOption;
     extensionTools?: boolean;
+    disabledFrameworkGroups?: ReadonlySet<FrameworkToolGroup>;
 }): {
     FRAMEWORK_CORE: string;
     FRAMEWORK_CORE_COMPACT: string;

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

@@ -1,6 +1,7 @@
 import type { ActionEntry } from "../../agent/production-agent.js";
 import type { AgentLoopFinalResponseGuard } from "../../agent/production-agent.js";
 import type { AgentChatAttachment, AgentChatReference, MentionProvider } from "../../agent/types.js";
+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";
@@ -236,6 +237,29 @@ export interface AgentChatPluginOptions {
      * Defaults to `false`.
      */
     nativeActionsInDev?: boolean;
+    /**
+     * Which of the framework's OWN agent tools this app exposes — raw SQL,
+     * extensions, sharing, review comments, version history, feature flags,
+     * localization, audit, context X-Ray, profile, automations, docs, resources,
+     * web, cross-app delegation, chat, email.
+     *
+     * Every group defaults to today's behavior, so omitting this leaves the tool
+     * surface unchanged. `"minimal"` (or `{ preset: "minimal" }`) turns them all
+     * off for voice-first and single-purpose apps; an explicit group key wins over
+     * the preset.
+     *
+     * Disabling a group removes it from the AGENT surfaces only — chat, MCP, A2A,
+     * background runs. The matching HTTP action routes stay mounted because the UI
+     * reaches them through client hooks. Weigh the parity cost first: the
+     * framework's contract is that anything the UI can do, the agent can do, so
+     * `sharing: false` alongside a visible `ShareButton` is a deliberate break and
+     * only makes sense when the app has no such surface.
+     *
+     * Independent of this option, framework tools are no longer promoted into the
+     * first model request by default — they are reachable through `tool-search`,
+     * or by naming them in `initialToolNames`.
+     */
+    frameworkTools?: FrameworkToolsConfig;
     /**
      * Expose raw SQL/native database tools to the app agent.
      *
@@ -244,6 +268,9 @@ export interface AgentChatPluginOptions {
      * `true`) to expose `db-exec`/`db-patch` for scoped raw SQL maintenance.
      * Set to `"off"` (also `false`) for chat-first apps that want agents to use
      * typed actions only.
+     *
+     * @deprecated Use `frameworkTools: { database: … }`. Still honored for one
+     * minor; setting both to conflicting values throws at plugin init.
      */
     databaseTools?: DatabaseToolsOption;
     /**
@@ -252,6 +279,9 @@ export interface AgentChatPluginOptions {
      * false. Set to true for apps that intentionally let the LLM create or
      * manage sandboxed extension mini-apps. Core extension routes may still be
      * mounted for compatibility and app-owned surfaces.
+     *
+     * @deprecated Use `frameworkTools: { extensions: … }`. Still honored for one
+     * minor; setting both to conflicting values throws at plugin init.
      */
     extensionTools?: boolean;
     /**