@agent-native/core 0.144.3 → 0.145.1

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

@@ -75,7 +75,7 @@ export declare function createCustomProviderRegistrationAction<TSchema extends Z
         user: "user";
     }>>;
 }, z.core.$strip>>, {
-    id?: undefined;
+    message?: undefined;
     deleted?: undefined;
     found?: undefined;
     providers: {
@@ -90,19 +90,20 @@ export declare function createCustomProviderRegistrationAction<TSchema extends Z
     count: number;
     provider?: undefined;
     registered?: undefined;
+    id?: undefined;
     label?: undefined;
-    message?: undefined;
 } | {
-    id?: undefined;
+    message?: undefined;
     deleted?: undefined;
     providers?: undefined;
     count?: undefined;
     found: boolean;
     provider: import("../custom-registry.js").CustomProviderConfig;
     registered?: undefined;
+    id?: undefined;
     label?: undefined;
-    message?: undefined;
 } | {
+    message?: undefined;
     deleted?: undefined;
     providers?: undefined;
     count?: undefined;
@@ -111,8 +112,8 @@ export declare function createCustomProviderRegistrationAction<TSchema extends Z
     id: string;
     registered?: undefined;
     label?: undefined;
-    message?: undefined;
 } | {
+    message?: undefined;
     found?: undefined;
     providers?: undefined;
     count?: undefined;
@@ -121,7 +122,6 @@ export declare function createCustomProviderRegistrationAction<TSchema extends Z
     id: string;
     registered?: undefined;
     label?: undefined;
-    message?: undefined;
 } | {
     deleted?: undefined;
     found?: undefined;

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

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

package/dist/resources/store.d.ts

@@ -1,5 +1,5 @@
 import { isLocalWorkspaceResourceId } from "../local-artifacts/index.js";
-import type { StoreWriteOptions } from "../settings/store.js";
+import { type StoreWriteOptions } from "../settings/store.js";
 export declare const SHARED_OWNER = "__shared__";
 export declare const WORKSPACE_OWNER = "__workspace__";
 /**

package/dist/resources/store.js

@@ -4,6 +4,7 @@ import { ensureColumnExists, ensureIndexExists, ensureTableExists, } from "../db
 import { widenIntColumnsToBigInt } from "../db/widen-columns.js";
 import { canUseLocalWorkspaceResourcePath, deleteLocalWorkspaceResource, isLocalWorkspaceResourceId, isLocalWorkspaceResourcesEnabled, listLocalWorkspaceResources, localWorkspaceResourcePathFromId, readLocalWorkspaceResource, writeLocalWorkspaceResource, } from "../local-artifacts/index.js";
 import { getRequestOrgId, getRequestUserEmail, } from "../server/request-context.js";
+import { getSetting, putSetting, } from "../settings/store.js";
 import { emitResourceChange, emitResourceDelete } from "./emitter.js";
 export const SHARED_OWNER = "__shared__";
 export const WORKSPACE_OWNER = "__workspace__";
@@ -570,14 +571,34 @@ async function grantedWorkspaceResourceByPath(path, options) {
         return null;
     }
 }
-async function cleanupExpiredAgentScratchResources(client) {
+/**
+ * Expire agent scratch resources, WITHOUT blocking the read that triggered it.
+ *
+ * This is garbage collection, not part of any read's answer: a caller asking for
+ * one resource does not need yesterday's expired scratch rows gone first. Awaiting
+ * it made every read path issue a `DELETE` before its own `SELECT` — double the
+ * round trips, unservable by a replica, taking row locks inside a request a user
+ * is waiting on, and (since nothing caught it) able to fail the read outright.
+ *
+ * The throttle is a module-scope timestamp, so it starts at 0 in a fresh isolate
+ * and the first resource read after every cold start still triggers one sweep.
+ * That is why the index below exists, and why this must not be awaited.
+ */
+function scheduleExpiredAgentScratchCleanup(client) {
     const now = Date.now();
     if (now - _lastScratchCleanupAt < SCRATCH_CLEANUP_INTERVAL_MS)
         return;
     _lastScratchCleanupAt = now;
-    await client.execute({
+    void client
+        .execute({
         sql: `DELETE FROM resources WHERE visibility = ? AND expires_at IS NOT NULL AND expires_at <= ?`,
         args: ["agent_scratch", now],
+    })
+        .catch((err) => {
+        // Say so rather than swallowing: scratch rows accumulating forever is a
+        // slow leak nobody would otherwise notice.
+        // coercion-ok: failed GC degrades storage over time, never read correctness
+        console.warn("[resources] expired agent-scratch cleanup failed; will retry on a later read:", err?.message ?? err);
     });
 }
 async function ensureTable() {
@@ -655,7 +676,7 @@ async function _doEnsureTable() {
         "updated_at",
         "expires_at",
     ]);
-    // `cleanupExpiredAgentScratchResources` filters on exactly these two columns
+    // `scheduleExpiredAgentScratchCleanup` filters on exactly these two columns
     // and, without this, full-scans `resources` — a table shared by every
     // template and read from agent discovery, docs, chat scratch and remote-agent
     // manifests. Its 60s throttle is a module-scope timestamp that starts at 0 in
@@ -669,7 +690,20 @@ async function _doEnsureTable() {
         // coercion-ok: absence of an index degrades latency, never correctness
         console.warn("[resources] could not ensure resources_visibility_expires_idx; scratch cleanup will full-scan:", err?.message ?? err);
     });
-    // Seed default shared resources if they don't exist (INSERT OR IGNORE to avoid race conditions)
+    // Seed default shared resources if they don't exist (INSERT OR IGNORE to avoid
+    // race conditions).
+    //
+    // Guarded by a durable marker: `_doEnsureTable` runs once per PROCESS, which on
+    // serverless is once per cold start, so this block was issuing ~10 writes and
+    // 2 migration scans per container to insert rows that had existed since day
+    // one (53,785 of them in one production sample). The marker makes it once per
+    // database, matching what the comments here already assumed.
+    //
+    // Consequence worth knowing: a default resource the user DELETES is no longer
+    // recreated on the next cold start. That silent resurrection was never
+    // intended — see `RESOURCE_SEED_VERSION` to force a re-seed.
+    if (await alreadySeeded(SHARED_SEED_KEY))
+        return;
     const now = Date.now();
     const seedSql = isPostgres()
         ? `INSERT INTO resources (id, path, owner, content, mime_type, size, created_at, updated_at) VALUES (?, ?, ?, ?, ?, ?, ?, ?) ON CONFLICT (path, owner) DO NOTHING`
@@ -797,8 +831,54 @@ async function _doEnsureTable() {
     catch {
         // Migration best-effort
     }
+    await markSeeded(SHARED_SEED_KEY);
 }
+/**
+ * Bump when a default resource is ADDED, or when existing seed content must
+ * reach databases that already ran an earlier seed.
+ *
+ * The marker below records which version a database has been seeded at, so the
+ * seed runs once per database instead of once per process. Without a version, a
+ * newly added default would never reach an already-seeded deployment.
+ */
+const RESOURCE_SEED_VERSION = 1;
+/**
+ * Per-process memo ON TOP of the durable marker, so a warm process doesn't even
+ * pay the marker read. The durable marker is what makes this correct across cold
+ * starts; this only avoids a repeat lookup within one process.
+ */
 const _personalSeeded = new Set();
+function personalSeedKey(owner) {
+    return `resources-seeded:personal:v${RESOURCE_SEED_VERSION}:${owner.toLowerCase()}`;
+}
+const SHARED_SEED_KEY = `resources-seeded:shared:v${RESOURCE_SEED_VERSION}`;
+/**
+ * Has this database already been seeded at the current version?
+ *
+ * A failed marker read returns `false` — "seed again" — because the seeds are
+ * `ON CONFLICT DO NOTHING` and therefore idempotent. Guessing "already seeded"
+ * on an unreadable marker would skip seeding a fresh database and leave it
+ * without its default AGENTS.md / LEARNINGS.md, which is not recoverable by
+ * retrying a read.
+ */
+async function alreadySeeded(key) {
+    try {
+        const row = await getSetting(key);
+        return row?.at !== undefined;
+    }
+    catch {
+        // coercion-ok: "not seeded" is the SAFE answer, and it is not indistinguishable from success — it re-runs an idempotent ON CONFLICT DO NOTHING seed, exactly the pre-marker behaviour. Guessing "already seeded" would leave a fresh database permanently without its default AGENTS.md / LEARNINGS.md, which no retry recovers.
+        return false;
+    }
+}
+async function markSeeded(key) {
+    try {
+        await putSetting(key, { at: Date.now() });
+    }
+    catch {
+        // coercion-ok: the marker is an optimization, not state anything reads for correctness. Failing to write it costs one repeat idempotent seed on the next cold start — the pre-marker behaviour — and the seed itself already succeeded, so there is no failure to report to the caller.
+    }
+}
 /**
  * Seed personal AGENTS.md and LEARNINGS.md for a user if they don't exist.
  * Called when listing resources or from the agent chat plugin.
@@ -810,6 +890,14 @@ export async function ensurePersonalDefaults(owner) {
         return;
     }
     await ensureTable();
+    // The in-memory Set resets on every cold start, so on serverless this seed ran
+    // its 5 writes per container per owner, forever. The durable marker is what
+    // actually makes it once-per-owner.
+    const seedKey = personalSeedKey(owner);
+    if (await alreadySeeded(seedKey)) {
+        _personalSeeded.add(owner);
+        return;
+    }
     const client = getDbExec();
     const now = Date.now();
     const seedSql = isPostgres()
@@ -886,6 +974,7 @@ export async function ensurePersonalDefaults(owner) {
     // retries instead of permanently skipping seeding. Seeds use INSERT OR IGNORE
     // / ON CONFLICT DO NOTHING, so a concurrent re-run is harmless.
     _personalSeeded.add(owner);
+    await markSeeded(seedKey);
 }
 function rowToResource(row) {
     return {
@@ -932,7 +1021,7 @@ export async function resourceGet(id, options) {
         return localWorkspaceResourceById(id);
     }
     const client = getDbExec();
-    await cleanupExpiredAgentScratchResources(client);
+    scheduleExpiredAgentScratchCleanup(client);
     const { rows } = await client.execute({
         sql: `SELECT * FROM resources WHERE id = ?`,
         args: [id],
@@ -949,7 +1038,7 @@ export async function resourceGetByPath(owner, path, options) {
             return local;
     }
     const client = getDbExec();
-    await cleanupExpiredAgentScratchResources(client);
+    scheduleExpiredAgentScratchCleanup(client);
     const { rows } = await client.execute({
         sql: `SELECT * FROM resources WHERE owner = ? AND path = ?`,
         args: [owner, path],
@@ -1165,7 +1254,7 @@ export async function resourceDeleteByPath(owner, path) {
 export async function resourceList(owner, pathPrefix, options) {
     await ensureTable();
     const client = getDbExec();
-    await cleanupExpiredAgentScratchResources(client);
+    scheduleExpiredAgentScratchCleanup(client);
     const visibilitySql = scratchFilterSql(options);
     if (pathPrefix) {
         const { rows } = await client.execute({

package/dist/secrets/routes.d.ts

@@ -34,37 +34,37 @@ 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;
 } | {
+    error?: undefined;
     ok: boolean;
     status: string;
-    error?: undefined;
 } | {
+    ok?: undefined;
     error: string;
     removed?: undefined;
-    ok?: undefined;
 } | {
+    error?: undefined;
     ok: boolean;
     removed: boolean;
-    error?: undefined;
 }>>;
 /**
  * POST /_agent-native/secrets/:key/test — validate an optional candidate value
  * 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;
 } | {
+    error?: undefined;
     ok: boolean;
     note?: undefined;
-    error?: 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;
 } | {
+    error?: undefined;
     ok: boolean;
     removed: boolean;
-    error?: 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;
     /**

package/dist/server/agent-chat/prompt-resources.d.ts

@@ -1,3 +1,4 @@
+import { type FrameworkToolGroup } from "../../framework-tools.js";
 import type { ContextGovernanceTier, ContextManifestSourceRef, ContextSystemProvenance } from "../../shared/context-xray.js";
 export declare const COMPACT_PROMPT_RESOURCE_MAX_CHARS = 6000;
 export interface PromptContextProviderContext {
@@ -89,4 +90,6 @@ export declare function resourceScopeForOwner(owner: string, currentOwner?: stri
  * AGENTS.md and restarting the server is all it takes; Vite HMR invalidates
  * the bundle in dev so changes land instantly.
  */
-export declare function loadResourcesForPrompt(owner: string, compact?: boolean, selfAppId?: string, orgId?: string | null): Promise<string>;
+export declare function loadResourcesForPrompt(owner: string, compact?: boolean, selfAppId?: string, orgId?: string | null, opts?: {
+    disabledFrameworkGroups?: ReadonlySet<FrameworkToolGroup>;
+}): Promise<string>;

package/dist/server/agent-chat/prompt-resources.js

@@ -1,3 +1,4 @@
+import { frameworkGroupEnabled, } from "../../framework-tools.js";
 import { getFrontmatterValue, getSkillNameFromPath, parseFrontmatter, } from "../../resources/metadata.js";
 import { ensurePersonalDefaults, organizationIdFromResourceOwner, resourceGet, resourceGetByPath, resourceList, resourceListAccessible, SHARED_OWNER, sharedResourceOwner, WORKSPACE_OWNER, } from "../../resources/store.js";
 import { discoverAgents } from "../agent-discovery.js";
@@ -600,7 +601,7 @@ async function loadResourceIndexForPrompt(owner, scope) {
  * AGENTS.md and restarting the server is all it takes; Vite HMR invalidates
  * the bundle in dev so changes land instantly.
  */
-export async function loadResourcesForPrompt(owner, compact = false, selfAppId, orgId = getRequestOrgId() ?? null) {
+export async function loadResourcesForPrompt(owner, compact = false, selfAppId, orgId = getRequestOrgId() ?? null, opts) {
     await ensurePersonalDefaults(owner);
     const sections = [];
     const addSection = (content, governance = "inherited") => {
@@ -774,7 +775,12 @@ export async function loadResourcesForPrompt(owner, compact = false, selfAppId,
         orgId,
     }));
     try {
-        const agents = (await discoverAgents(selfAppId)).slice(0, 30);
+        // Both tools this block names by name come from the `workspaceApps` group.
+        // With that group off there is no `call-agent` to delegate through, so the
+        // block would only teach a capability the request cannot carry.
+        const agents = frameworkGroupEnabled(opts?.disabledFrameworkGroups, "workspaceApps")
+            ? (await discoverAgents(selfAppId)).slice(0, 30)
+            : [];
         if (agents.length > 0) {
             const lines = agents.map((agent) => `- ${agent.name} (${agent.id}) — ${agent.description || "Connected A2A app"}`);
             // Nothing else in the prompt or the initial tool surface tells the agent