@agent-native/core 0.144.2 → 0.145.0

package/dist/server/prompts/framework-core.js

@@ -5,8 +5,9 @@
  * Shared rules (8-9, 12-13) are imported from shared-rules.ts so the
  * compact variant uses the same text and the two can never drift.
  */
+import { frameworkGroupEnabled, } from "../../framework-tools.js";
 import { hasDatabaseReadTools, hasDatabaseWriteTools, } from "../../scripts/db/tool-mode.js";
-import { sharedRule8, SHARED_RULE_9, SHARED_RULE_14, SHARED_RULE_15, SHARED_RULE_AGENT_WARNINGS, } from "./shared-rules.js";
+import { sharedRule8, SHARED_RULE_9, sharedRule14, SHARED_RULE_15, SHARED_RULE_AGENT_WARNINGS, } from "./shared-rules.js";
 /**
  * Build the full FRAMEWORK_CORE prompt string.
  *
@@ -40,6 +41,33 @@ export function buildFrameworkCore(examples, options) {
     const actionSurface = options?.extensionTools === true
         ? "this app's registered actions, extensions, and connected MCP tools"
         : "this app's registered actions and connected MCP tools";
+    const groupOn = (group) => frameworkGroupEnabled(options?.disabledFrameworkGroups, group);
+    const resourcesSection = groupOn("resources")
+        ? `### Resources
+
+You have access to a Resources system for persistent notes and context files.
+Use the \`resources\` tool to manage resources: \`action: "list"\`, \`"read"\`, \`"effective"\`, \`"write"\`, \`"promote"\`, or \`"delete"\`.
+Resources can be workspace defaults inherited from Dispatch, shared organization/app overrides, or personal overrides. By default, resources are personal. Workspace-scope resources are read-only from app agents; create shared or personal resources to override or narrow them.
+
+When the user gives instructions that should apply to all users/sessions, update the shared "AGENTS.md" resource.
+
+Workspace resources are user-facing by default. If you need temporary working files, use the \`resources\` tool with \`visibility: "agent_scratch"\`; scratch resources are hidden from the Workspace view by default and expire automatically. Use \`visibility: "workspace"\` only when the user explicitly asked to save/create/manage that file, or for durable control files such as \`AGENTS.md\`, \`LEARNINGS.md\`, \`memory/\`, \`skills/\`, \`jobs/\`, or \`agents/\`. If a scratch result becomes useful to the user, call \`resources\` with \`action: "promote"\` or rewrite it with \`visibility: "workspace"\`.
+`
+        : "";
+    const extendedCapabilityClauses = [
+        "inline embeds (`embed` fenced code block)",
+        groupOn("chat") ? "chat history search (`chat-history`)" : "",
+        groupOn("automation") ? "recurring jobs (`manage-jobs`)" : "",
+        "connecting Builder.io (`connect-builder`)",
+        "browser automation (`set-browser-control`/`activate-browser`)",
+        "structured memory (`save-memory`/`delete-memory`)",
+    ].filter(Boolean);
+    const extendedCapabilitiesList = `${extendedCapabilityClauses.slice(0, -1).join(", ")}, and ${extendedCapabilityClauses.at(-1)}`;
+    const callAgentSection = groupOn("workspaceApps")
+        ? `
+**call-agent** messages a DIFFERENT deployed app's agent over A2A — never use it for your own actions or to call yourself. For brand-consistent generated media when this app has no native generation action, call agent "assets".
+`
+        : "";
     return `
 ### How You Work
 
@@ -78,7 +106,7 @@ ${SHARED_RULE_9}
 **Downloadable files** — When the user asks you to create or export a file, deliver it in the same chat turn. For compact tabular results, prefer \`render-data-widget\` so the user gets the native Download CSV action without a second stored copy. For a complete or durable file written through \`workspaceWrite\`, use a normal non-\`scratch/\` path and then call \`show-workspace-file\` with that path so chat renders a direct download card. Never finish by giving filesystem paths or telling the user to navigate elsewhere to find the file.
 10. **Your tool list is not the whole surface** — Most app actions and connected MCP tools load on demand, so search the live registry with \`tool-search\` before concluding a capability doesn't exist.
 11. **Relative dates use runtime context** — The \`<runtime-context>\` block gives the authoritative current date/time. Resolve "today", "yesterday", "last week", and similar phrases to explicit calendar dates before querying data or creating artifacts. When answering factual questions, include the exact date or date range you used.
-${SHARED_RULE_14}
+${sharedRule14(options)}
 ${SHARED_RULE_15}
 ${SHARED_RULE_AGENT_WARNINGS}
 
@@ -86,22 +114,11 @@ ${SHARED_RULE_AGENT_WARNINGS}
 
 Gather context efficiently: when you need several independent read-only lookups (reading state, querying different tables, searching, fetching unrelated records), issue those tool calls together in one batch rather than one at a time. Keep mutating actions ordered and sequential — anything that creates, updates, deletes, sends, or publishes runs one at a time so each can be confirmed before the next, and so writes that depend on each other stay consistent.
 
-### Resources
-
-You have access to a Resources system for persistent notes and context files.
-Use the \`resources\` tool to manage resources: \`action: "list"\`, \`"read"\`, \`"effective"\`, \`"write"\`, \`"promote"\`, or \`"delete"\`.
-Resources can be workspace defaults inherited from Dispatch, shared organization/app overrides, or personal overrides. By default, resources are personal. Workspace-scope resources are read-only from app agents; create shared or personal resources to override or narrow them.
-
-When the user gives instructions that should apply to all users/sessions, update the shared "AGENTS.md" resource.
-
-Workspace resources are user-facing by default. If you need temporary working files, use the \`resources\` tool with \`visibility: "agent_scratch"\`; scratch resources are hidden from the Workspace view by default and expire automatically. Use \`visibility: "workspace"\` only when the user explicitly asked to save/create/manage that file, or for durable control files such as \`AGENTS.md\`, \`LEARNINGS.md\`, \`memory/\`, \`skills/\`, \`jobs/\`, or \`agents/\`. If a scratch result becomes useful to the user, call \`resources\` with \`action: "promote"\` or rewrite it with \`visibility: "workspace"\`.
-
+${resourcesSection}
 ### Extended Capabilities
 
-You also have tools for inline embeds (\`embed\` fenced code block), chat history search (\`chat-history\`), recurring jobs (\`manage-jobs\`), connecting Builder.io (\`connect-builder\`), browser automation (\`set-browser-control\`/\`activate-browser\`), and structured memory (\`save-memory\`/\`delete-memory\`). Call \`get-framework-context\` with the matching key — it lists its own topics — for full instructions before non-trivial work in any of these areas.
+You also have tools for ${extendedCapabilitiesList}. Call \`get-framework-context\` with the matching key — it lists its own topics — for full instructions before non-trivial work in any of these areas.
 
 **Agent teams:** default to doing the work yourself in this thread, but treat "background agent", "sub-agent", "parallel", "batch", "kick off", "run the rest", and "queued items" as delegation intent when the user is asking you to start or continue independent work items. Delegate ONE sub-agent for self-contained heavy work (deep research, long multi-step generation, noisy scans); fan out to MULTIPLE only for genuinely independent units; never parallelize tightly-coupled work; cap fan-out around 3. After \`spawn\`, say the task started/running, not completed; use \`status\`/\`read-result\` before claiming delegated work is done. Give every sub-agent a self-contained brief (objective, the specific context/IDs it needs, output format, boundaries), then read all results and synthesize one integrated answer. Full details: \`get-framework-context\` key \`agent-teams\`.
-
-**call-agent** messages a DIFFERENT deployed app's agent over A2A — never use it for your own actions or to call yourself. For brand-consistent generated media when this app has no native generation action, call agent "assets".
-`;
+${callAgentSection}`;
 }

package/dist/server/prompts/index.d.ts

@@ -4,5 +4,5 @@
  */
 export { buildFrameworkCore } from "./framework-core.js";
 export { buildFrameworkCoreCompact } from "./framework-core-compact.js";
-export { sharedRule8, SHARED_RULE_9, SHARED_RULE_14, SHARED_RULE_15, type PromptExamples, } from "./shared-rules.js";
+export { sharedRule8, SHARED_RULE_9, sharedRule14, SHARED_RULE_15, type PromptExamples, type SharedRuleOptions, } from "./shared-rules.js";
 export { getModelFamilyOverlay } from "./model-overlays.js";

package/dist/server/prompts/index.js

@@ -4,5 +4,5 @@
  */
 export { buildFrameworkCore } from "./framework-core.js";
 export { buildFrameworkCoreCompact } from "./framework-core-compact.js";
-export { sharedRule8, SHARED_RULE_9, SHARED_RULE_14, SHARED_RULE_15, } from "./shared-rules.js";
+export { sharedRule8, SHARED_RULE_9, sharedRule14, SHARED_RULE_15, } from "./shared-rules.js";
 export { getModelFamilyOverlay } from "./model-overlays.js";

package/dist/server/prompts/shared-rules.d.ts

@@ -7,6 +7,7 @@
  * rule) and 12–13 (planning discipline; collaborate through uncertainty) are
  * reproduced verbatim in both prompts — keep them here.
  */
+import { type FrameworkToolGroup } from "../../framework-tools.js";
 import { type DatabaseToolsOption } from "../../scripts/db/tool-mode.js";
 /**
  * Injectable provider/action examples. Defaults are generic; templates that
@@ -21,6 +22,9 @@ export interface PromptExamples {
 export interface SharedRuleOptions {
     databaseTools?: DatabaseToolsOption;
     extensionTools?: boolean;
+    /** Framework tool groups this app switched off. Any rule naming a group's
+     *  tool must drop that reference — see `frameworkGroupEnabled`. */
+    disabledFrameworkGroups?: ReadonlySet<FrameworkToolGroup>;
 }
 /** Rule 8 — db-* tools are internal only (shared between full and compact). */
 export declare function sharedRule8(examples?: PromptExamples, options?: SharedRuleOptions): string;
@@ -34,14 +38,18 @@ export declare function sharedRule8(examples?: PromptExamples, options?: SharedR
  */
 export declare const SHARED_RULE_9 = "9. **Never fabricate \u2014 verify results, report failures honestly, and recover instead of giving up.**\n   - **Never fabricate factual claims or records** \u2014 do not invent numbers, metrics, records, query results, URLs, citations, source attributions, customer names, dates, or success rates. This applies inside generated artifacts too: decks, documents, reports, dashboards, Slack/email replies, and charts. Only state factual numbers/claims the user provided or you retrieved with an action/tool. If a data source is unavailable, returns no rows, is missing credentials, or has a connection error, say so clearly; do not create placeholder rows or fetch unrelated providers to look complete unless the user explicitly asked you to import/sync/backfill. Prefer qualitative wording, placeholders like `[metric TBD]`, or clearly labeled draft assumptions over plausible-looking facts \u2014 presenting made-up data as real is worse than admitting the limitation.\n   - **Never fabricate success from tool errors** \u2014 when a tool call returns an error (marked `isError: true`, contains \"Command failed\", \"Error:\", or non-zero exit output), the operation FAILED; do not synthesize a success narrative or describe what it \"would have\" produced. Report the failure verbatim (this applies especially to `bash(command=\"pnpm action ...\")` calls). Before telling the user a mutating action (create/update/delete/send/publish) is done, confirm it actually landed \u2014 check the tool result, or read the refreshed `<current-screen>` / re-query the data; having *called* an action is not proof it worked. If a result is ambiguous, check rather than assume.\n   - **Recover instead of giving up** \u2014 treat a failure or ambiguous result as a signal to retry the obvious fix, try an alternate tool or approach, or clearly hand the blocker back with what you tried; never silently give up, and never paper over a failure by claiming success.";
 /**
- * Rule 12 (const name retained as SHARED_RULE_14 for import stability) —
- * Planning and progress. Deliberately states only when to open a progress run;
- * the start/update/complete discipline lives in `manage-progress`'s own tool
+ * Rule 12 (name retained as `sharedRule14` for import stability) — Planning and
+ * progress. Deliberately states only when to open a progress run; the
+ * start/update/complete discipline lives in `manage-progress`'s own tool
  * description (packages/core/src/progress/actions.ts). Re-adding the mechanics
  * here means every turn pays for guidance the model only needs once it has the
  * tool loaded.
+ *
+ * Drops the `manage-progress` reference when the `automation` group is off, so
+ * the rule never names a tool the request does not carry. The planning
+ * discipline itself still applies — only the tool call goes away.
  */
-export declare const SHARED_RULE_14 = "12. **Plan and track multi-step work** \u2014 When a task spans several real steps the user would want to watch, open a `manage-progress` run so the work is visible while it's still in flight, and keep it updated as you go rather than after the fact; the tool's own description carries the full discipline. Skip it for single-action lookups, simple reads, and anything that finishes in one tool call \u2014 never create single-step plans.";
+export declare function sharedRule14(options?: SharedRuleOptions): string;
 /**
  * Rule 14 — Relay agent warnings. Named for what it is rather than its number,
  * since the `SHARED_RULE_14`/`15` names above no longer match theirs.

package/dist/server/prompts/shared-rules.js

@@ -7,6 +7,7 @@
  * rule) and 12–13 (planning discipline; collaborate through uncertainty) are
  * reproduced verbatim in both prompts — keep them here.
  */
+import { frameworkGroupEnabled, } from "../../framework-tools.js";
 import { normalizeDatabaseToolsMode, } from "../../scripts/db/tool-mode.js";
 const DEFAULT_PROVIDER_ACTIONS = [
     "provider-search",
@@ -64,14 +65,23 @@ export const SHARED_RULE_9 = `9. **Never fabricate — verify results, report fa
    - **Never fabricate success from tool errors** — when a tool call returns an error (marked \`isError: true\`, contains "Command failed", "Error:", or non-zero exit output), the operation FAILED; do not synthesize a success narrative or describe what it "would have" produced. Report the failure verbatim (this applies especially to \`bash(command="pnpm action ...")\` calls). Before telling the user a mutating action (create/update/delete/send/publish) is done, confirm it actually landed — check the tool result, or read the refreshed \`<current-screen>\` / re-query the data; having *called* an action is not proof it worked. If a result is ambiguous, check rather than assume.
    - **Recover instead of giving up** — treat a failure or ambiguous result as a signal to retry the obvious fix, try an alternate tool or approach, or clearly hand the blocker back with what you tried; never silently give up, and never paper over a failure by claiming success.`;
 /**
- * Rule 12 (const name retained as SHARED_RULE_14 for import stability) —
- * Planning and progress. Deliberately states only when to open a progress run;
- * the start/update/complete discipline lives in `manage-progress`'s own tool
+ * Rule 12 (name retained as `sharedRule14` for import stability) — Planning and
+ * progress. Deliberately states only when to open a progress run; the
+ * start/update/complete discipline lives in `manage-progress`'s own tool
  * description (packages/core/src/progress/actions.ts). Re-adding the mechanics
  * here means every turn pays for guidance the model only needs once it has the
  * tool loaded.
+ *
+ * Drops the `manage-progress` reference when the `automation` group is off, so
+ * the rule never names a tool the request does not carry. The planning
+ * discipline itself still applies — only the tool call goes away.
  */
-export const SHARED_RULE_14 = `12. **Plan and track multi-step work** — When a task spans several real steps the user would want to watch, open a \`manage-progress\` run so the work is visible while it's still in flight, and keep it updated as you go rather than after the fact; the tool's own description carries the full discipline. Skip it for single-action lookups, simple reads, and anything that finishes in one tool call — never create single-step plans.`;
+export function sharedRule14(options) {
+    if (!frameworkGroupEnabled(options?.disabledFrameworkGroups, "automation")) {
+        return `12. **Plan and track multi-step work** — When a task spans several real steps, work through them in order and tell the user where you are as you go rather than only at the end. Skip ceremony for single-action lookups, simple reads, and anything that finishes in one tool call.`;
+    }
+    return `12. **Plan and track multi-step work** — When a task spans several real steps the user would want to watch, open a \`manage-progress\` run so the work is visible while it's still in flight, and keep it updated as you go rather than after the fact; the tool's own description carries the full discipline. Skip it for single-action lookups, simple reads, and anything that finishes in one tool call — never create single-step plans.`;
+}
 /**
  * Rule 14 — Relay agent warnings. Named for what it is rather than its number,
  * since the `SHARED_RULE_14`/`15` names above no longer match theirs.

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/shared/index.d.ts

@@ -9,6 +9,7 @@ export { llmConnectionTrackingProperties, normalizeLlmConnection, type LlmConnec
 export { DISPATCH_WORKSPACE_ROOT_REDIRECTS, RESERVED_WORKSPACE_APP_IDS, assertValidWorkspaceAppId, getWorkspaceAppIdValidationError, isValidWorkspaceAppIdFormat, } from "./workspace-app-id.js";
 export { DEFAULT_WORKSPACE_APP_AUDIENCE, WORKSPACE_APP_AUDIENCES, normalizeWorkspaceAppAudience, normalizeWorkspaceAppPathList, workspaceAppAudienceFromEnv, workspaceAppAudienceFromPackageJson, workspaceAppRouteAccessFromEnv, workspaceAppRouteAccessFromPackageJson, type WorkspaceAppRouteAccess, type WorkspaceAppRouteAccessFromConfig, type WorkspaceAppAudience, } from "./workspace-app-audience.js";
 export { AGENT_NATIVE_OPEN_PATH, AGENT_SIDEBAR_QUERY_PARAM, AGENT_SIDEBAR_QUERY_VALUE_CLOSED, isAgentNativeOpenDeepLink, withCollapsedAgentSidebarParam, } from "./agent-sidebar-url.js";
+export { createPollEngine, type PollEngineOptions, type PollEngineHandle, } from "./poll-engine.js";
 export { AGENT_NATIVE_DEFAULT_SOCIAL_IMAGE, AGENT_NATIVE_SOCIAL_IMAGE_CACHE_BUSTER, AGENT_NATIVE_SOCIAL_IMAGE_ALT, AGENT_NATIVE_SOCIAL_IMAGE_HEIGHT, AGENT_NATIVE_SOCIAL_IMAGE_PATH, AGENT_NATIVE_SOCIAL_IMAGE_TYPE, AGENT_NATIVE_SOCIAL_IMAGE_WIDTH, defaultSocialImageMeta, withAgentNativeSocialImageCacheBuster, withDefaultSocialImage, type SocialMetaDescriptor, } from "./social-meta.js";
 export { EMBED_MODE_QUERY_PARAM, EMBED_SESSION_COOKIE, EMBED_START_PATH, EMBED_TOKEN_QUERY_PARAM, } from "./embed-auth.js";
 export { AGENT_ACCESS_PARAM, DEFAULT_AGENT_ACCESS_TTL_SECONDS, appendAgentAccessParam, buildAgentAccessApiUrl, buildAgentAccessUrl, normalizeAgentAccessBasePath, normalizeAgentAccessOrigin, scopedAgentAccessResourceId, toAgentAccessUrl, type AgentAccessApiUrlOptions, type AgentAccessResourceScope, type AgentAccessUrlOptions, } from "./agent-access.js";

package/dist/shared/index.js

@@ -9,6 +9,7 @@ export { llmConnectionTrackingProperties, normalizeLlmConnection, } from "./llm-
 export { DISPATCH_WORKSPACE_ROOT_REDIRECTS, RESERVED_WORKSPACE_APP_IDS, assertValidWorkspaceAppId, getWorkspaceAppIdValidationError, isValidWorkspaceAppIdFormat, } from "./workspace-app-id.js";
 export { DEFAULT_WORKSPACE_APP_AUDIENCE, WORKSPACE_APP_AUDIENCES, normalizeWorkspaceAppAudience, normalizeWorkspaceAppPathList, workspaceAppAudienceFromEnv, workspaceAppAudienceFromPackageJson, workspaceAppRouteAccessFromEnv, workspaceAppRouteAccessFromPackageJson, } from "./workspace-app-audience.js";
 export { AGENT_NATIVE_OPEN_PATH, AGENT_SIDEBAR_QUERY_PARAM, AGENT_SIDEBAR_QUERY_VALUE_CLOSED, isAgentNativeOpenDeepLink, withCollapsedAgentSidebarParam, } from "./agent-sidebar-url.js";
+export { createPollEngine, } from "./poll-engine.js";
 export { AGENT_NATIVE_DEFAULT_SOCIAL_IMAGE, AGENT_NATIVE_SOCIAL_IMAGE_CACHE_BUSTER, AGENT_NATIVE_SOCIAL_IMAGE_ALT, AGENT_NATIVE_SOCIAL_IMAGE_HEIGHT, AGENT_NATIVE_SOCIAL_IMAGE_PATH, AGENT_NATIVE_SOCIAL_IMAGE_TYPE, AGENT_NATIVE_SOCIAL_IMAGE_WIDTH, defaultSocialImageMeta, withAgentNativeSocialImageCacheBuster, withDefaultSocialImage, } from "./social-meta.js";
 export { EMBED_MODE_QUERY_PARAM, EMBED_SESSION_COOKIE, EMBED_START_PATH, EMBED_TOKEN_QUERY_PARAM, } from "./embed-auth.js";
 export { AGENT_ACCESS_PARAM, DEFAULT_AGENT_ACCESS_TTL_SECONDS, appendAgentAccessParam, buildAgentAccessApiUrl, buildAgentAccessUrl, normalizeAgentAccessBasePath, normalizeAgentAccessOrigin, scopedAgentAccessResourceId, toAgentAccessUrl, } from "./agent-access.js";

package/dist/shared/poll-engine.d.ts

@@ -0,0 +1,49 @@
+/**
+ * Shared recurring-poll engine used by both `usePollLoop` (client) and
+ * `startIntervalJob` (server) so every polling loop in the codebase gets the
+ * same three properties for free instead of hand-rolling them per call site:
+ *
+ * 1. Never overlaps: the next attempt is scheduled via `setTimeout` only
+ *    after the current one settles, not on a fixed `setInterval` cadence.
+ *    This also avoids the latency `setInterval` + skip-if-busy introduces —
+ *    a skipped tick there means waiting a full extra cadence before the next
+ *    retry; here the gap after completion is always exactly `intervalMs`.
+ * 2. Never stalls silently: every attempt is bounded by a timeout (paired
+ *    with an `AbortController` so a `fetch` can actually cancel, not just be
+ *    abandoned), and that timeout reports through `onError` the moment it
+ *    fires. An attempt that ignores its `signal` keeps holding the loop —
+ *    reported, not hidden — because releasing the slot to the next attempt
+ *    would trade a visible stall for a silent overlap.
+ * 3. Never double-fires: a single internal in-flight flag, owned by this
+ *    engine rather than duplicated in every caller.
+ */
+export interface PollEngineOptions {
+    /** Delay in ms before the next attempt. Evaluated fresh before each schedule. */
+    intervalMs: number | (() => number);
+    /** Per-attempt timeout. Default: `Math.max(timeoutFloorMs, intervalMs * 4)`. */
+    timeoutMs?: number | (() => number);
+    /** Floor used by the default `timeoutMs`. Default: 10_000. */
+    timeoutFloorMs?: number;
+    /** Called when an attempt throws or times out. Default: swallow. */
+    onError?: (err: unknown) => void;
+    /** Run the first attempt immediately on `start()`. Default: true. */
+    leading?: boolean;
+}
+export interface PollEngineHandle {
+    /** Arm the loop. No-op if already running. */
+    start(): void;
+    /** Halt the loop and abort any in-flight attempt; its eventual settlement is a no-op. */
+    stop(): void;
+    /** Cancel the pending wait and run now. No-op if not running or an attempt is already in flight. */
+    pollNow(): void;
+    /**
+     * Re-arm the pending wait using a freshly resolved `intervalMs`, without
+     * running an attempt. Use this when `intervalMs` is a function whose
+     * result can change externally (e.g. tab visibility) — otherwise a
+     * change only takes effect the next time an attempt completes. No-op if
+     * there's no pending wait (not running, or an attempt is in flight).
+     */
+    reschedule(): void;
+    readonly isRunning: boolean;
+}
+export declare function createPollEngine(attempt: (signal: AbortSignal) => Promise<void>, options: PollEngineOptions): PollEngineHandle;

package/dist/shared/poll-engine.js

@@ -0,0 +1,148 @@
+/**
+ * Shared recurring-poll engine used by both `usePollLoop` (client) and
+ * `startIntervalJob` (server) so every polling loop in the codebase gets the
+ * same three properties for free instead of hand-rolling them per call site:
+ *
+ * 1. Never overlaps: the next attempt is scheduled via `setTimeout` only
+ *    after the current one settles, not on a fixed `setInterval` cadence.
+ *    This also avoids the latency `setInterval` + skip-if-busy introduces —
+ *    a skipped tick there means waiting a full extra cadence before the next
+ *    retry; here the gap after completion is always exactly `intervalMs`.
+ * 2. Never stalls silently: every attempt is bounded by a timeout (paired
+ *    with an `AbortController` so a `fetch` can actually cancel, not just be
+ *    abandoned), and that timeout reports through `onError` the moment it
+ *    fires. An attempt that ignores its `signal` keeps holding the loop —
+ *    reported, not hidden — because releasing the slot to the next attempt
+ *    would trade a visible stall for a silent overlap.
+ * 3. Never double-fires: a single internal in-flight flag, owned by this
+ *    engine rather than duplicated in every caller.
+ */
+const DEFAULT_TIMEOUT_FLOOR_MS = 10_000;
+function resolve(value) {
+    return typeof value === "function" ? value() : value;
+}
+function maybeUnref(timer) {
+    if (timer &&
+        typeof timer === "object" &&
+        "unref" in timer &&
+        typeof timer.unref === "function") {
+        timer.unref();
+    }
+}
+export function createPollEngine(attempt, options) {
+    const timeoutFloorMs = options.timeoutFloorMs ?? DEFAULT_TIMEOUT_FLOOR_MS;
+    const getTimeoutMs = () => options.timeoutMs != null
+        ? resolve(options.timeoutMs)
+        : Math.max(timeoutFloorMs, resolve(options.intervalMs) * 4);
+    const onError = options.onError ?? (() => { });
+    const leading = options.leading ?? true;
+    let generation = 0;
+    let running = false;
+    let inFlight = false;
+    let timer = null;
+    let activeController = null;
+    function clearTimer() {
+        if (timer != null) {
+            clearTimeout(timer);
+            timer = null;
+        }
+    }
+    function schedule(gen) {
+        clearTimer();
+        timer = setTimeout(() => {
+            timer = null;
+            void tick(gen);
+        }, resolve(options.intervalMs));
+        maybeUnref(timer);
+    }
+    async function tick(gen) {
+        if (gen !== generation || !running)
+            return;
+        if (inFlight) {
+            // An attempt from a superseded generation is still settling — stop()
+            // aborted it but the caller has not returned yet. Its own `finally`
+            // sees a stale generation and will not reschedule, so re-arming here
+            // is what keeps a stop()/start() cycle (tab hidden then visible) from
+            // leaving the engine alive-but-timerless, i.e. permanently dead.
+            schedule(gen);
+            return;
+        }
+        inFlight = true;
+        const controller = new AbortController();
+        activeController = controller;
+        const timeoutMs = getTimeoutMs();
+        const abortTimer = setTimeout(() => controller.abort(), timeoutMs);
+        maybeUnref(abortTimer);
+        let reported = false;
+        const report = (err) => {
+            if (reported)
+                return;
+            reported = true;
+            onError(err);
+        };
+        // The attempt is retained separately from the timeout race below. The
+        // timeout reports a slow attempt immediately, but the in-flight slot is
+        // only released once the attempt itself settles: releasing on the
+        // timeout would let the next tick start while an attempt that ignores
+        // `signal` is still doing work, which is the overlap (duplicate external
+        // requests, racing writes) this engine exists to prevent. An attempt that
+        // never settles blocks further attempts by design — `onError` has already
+        // fired, so it is loud rather than silent.
+        const settled = Promise.resolve()
+            .then(() => attempt(controller.signal))
+            .then(() => { }, (err) => report(err));
+        try {
+            await Promise.race([
+                settled,
+                new Promise((_, reject) => {
+                    controller.signal.addEventListener("abort", () => reject(new Error(`poll attempt timed out after ${timeoutMs}ms`)), { once: true });
+                }),
+            ]);
+        }
+        catch (err) {
+            report(err);
+        }
+        finally {
+            await settled;
+            clearTimeout(abortTimer);
+            if (activeController === controller)
+                activeController = null;
+            inFlight = false;
+            if (gen === generation && running)
+                schedule(gen);
+        }
+    }
+    return {
+        start() {
+            if (running)
+                return;
+            running = true;
+            generation++;
+            const gen = generation;
+            if (leading)
+                void tick(gen);
+            else
+                schedule(gen);
+        },
+        stop() {
+            running = false;
+            generation++;
+            clearTimer();
+            activeController?.abort();
+        },
+        pollNow() {
+            if (!running || inFlight)
+                return;
+            clearTimer();
+            void tick(generation);
+        },
+        reschedule() {
+            if (!running || inFlight || timer == null)
+                return;
+            schedule(generation);
+        },
+        get isRunning() {
+            return running;
+        },
+    };
+}

package/dist/templates/default/.agents/skills/internationalization/SKILL.md

@@ -29,6 +29,11 @@ Templates use `app/i18n/`:
 Use BCP-47 filenames from the supported set: `en-US`, `zh-CN`, `es-ES`,
 `fr-FR`, `de-DE`, `ja-JP`, `ko-KR`, `pt-BR`, `hi-IN`, `ar-SA`.
 
+If an app only ships translations for a subset of that set, set
+`supportedLocales` on the `AgentNativeI18nCatalog` to that subset. Without it,
+`<LanguagePicker />` lists every framework-supported locale regardless of
+whether `loadMessages` can actually resolve it.
+
 ## UI Pattern
 
 - Wrap apps with `AppProviders i18n={{ catalog: i18nCatalog }}`.

package/dist/templates/workspace-core/.agents/skills/extensions/SKILL.md

@@ -217,9 +217,12 @@ POST /_agent-native/extensions
 
 HTTP creation is disabled by default. The host app must set
 `extensionTools: true` on `createCoreRoutesPlugin()` as well as
-`createAgentChatPlugin()`; otherwise authenticated collection `POST` requests
-return `403` while existing extension runtime, read, edit, and deep-link routes
-remain available for compatibility.
+`frameworkTools: { extensions: true }` on `createAgentChatPlugin()`; otherwise
+authenticated collection `POST` requests return `403` while existing extension
+runtime, read, edit, and deep-link routes remain available for compatibility.
+(`extensionTools` on the agent-chat plugin is the deprecated spelling of
+`frameworkTools.extensions`; the core-routes option keeps its own name because
+it gates route mounting rather than agent tools.)
 
 The action accepts:
 

package/dist/templates/workspace-core/.agents/skills/internationalization/SKILL.md

@@ -29,6 +29,11 @@ Templates use `app/i18n/`:
 Use BCP-47 filenames from the supported set: `en-US`, `zh-CN`, `es-ES`,
 `fr-FR`, `de-DE`, `ja-JP`, `ko-KR`, `pt-BR`, `hi-IN`, `ar-SA`.
 
+If an app only ships translations for a subset of that set, set
+`supportedLocales` on the `AgentNativeI18nCatalog` to that subset. Without it,
+`<LanguagePicker />` lists every framework-supported locale regardless of
+whether `loadMessages` can actually resolve it.
+
 ## UI Pattern
 
 - Wrap apps with `AppProviders i18n={{ catalog: i18nCatalog }}`.

package/dist/tracking/providers.js

@@ -38,7 +38,16 @@ function setTimer(t) {
 function enqueue(url, body, headers, options) {
     const queue = getQueue();
     queue.push({ url, body, headers });
-    if (options?.flushImmediately || queue.length >= MAX_BATCH_SIZE) {
+    // The batch timer is unref'd so it never keeps a long-lived server alive —
+    // but on Netlify/Vercel/Lambda the execution environment can freeze the
+    // moment the event loop looks empty, which is exactly when an unref'd timer
+    // doesn't count. Without a signal, a warm container freezing between
+    // invocations never fires that timer, silently dropping every provider's
+    // queued events for a request that ends in a crash. Default to flushing
+    // synchronously with the response in that environment; a caller (e.g.
+    // Agent Native Analytics' flush-mode override) can still force either way.
+    const flushImmediately = options?.flushImmediately ?? isServerlessRuntime();
+    if (flushImmediately || queue.length >= MAX_BATCH_SIZE) {
         void drainQueue();
     }
     else if (!getTimer()) {

package/docs/content/deployment.mdx

@@ -580,16 +580,19 @@ Rotate signing/session keys by replacing the env var on every instance and redep
 
 ## Production Agent Tools {#production-agent-tools}
 
-Production agents get the app's registered actions plus framework tools from
-the agent chat plugin. SQL inspection is enabled by default, while database
-writes go through typed app actions unless the app explicitly opts into raw
-write tools:
+Production agents get the app's registered actions plus the framework's own
+tools. `frameworkTools` selects which of those framework tools this app exposes.
+Every group defaults to today's behavior, so omitting the option changes
+nothing:
 
 ```ts filename="server/plugins/agent-chat.ts"
 export default createAgentChatPlugin({
-  // Default: "read"
-  databaseTools: "read", // "write" | "read" | "off"
-  extensionTools: true,
+  frameworkTools: {
+    database: "read", // "write" | "read" | "off" — default "read"
+    extensions: true, // default false
+    sharing: false, // this app has no share surface
+    review: false,
+  },
 });
 ```
 
@@ -599,17 +602,48 @@ export default createCoreRoutesPlugin({
 });
 ```
 
-- `databaseTools: "read"` — default. Registers only `db-schema` and `db-query`;
+`database` and `extensions` accept the values the old top-level flags did:
+
+- `database: "read"` — default. Registers only `db-schema` and `db-query`;
   agents inspect data with SQL but must use typed app actions for writes.
-- `databaseTools: "write"` or `true` — additionally registers `db-exec` and
+- `database: "write"` or `true` — additionally registers `db-exec` and
   `db-patch` for deliberate raw SQL maintenance. Writes are scoped to the
   current user/org and schema changes are blocked.
-- `databaseTools: "off"` or `false` — removes raw database tools from the
+- `database: "off"` or `false` — removes raw database tools from the
   agent surface so the app's actions are the only data access path.
-- `extensionTools: true` — opts the app into framework extension-management
+- `extensions: true` — opts the app into framework extension-management
   actions and prompt guidance (`create-extension`, `update-extension`, etc.).
-  Set it on both plugins to also allow authenticated REST creation. Extensions
-  are disabled by default.
+  Set `extensionTools: true` on the core-routes plugin as well to allow
+  authenticated REST creation. Extensions are disabled by default.
+
+The remaining groups are booleans, all on by default: `sharing`, `review`,
+`history`, `featureFlags`, `localization`, `audit`, `contextXray`,
+`userProfile`, `automation`, `docs`, `resources`, `web`, `workspaceApps`,
+`chat`, and `email`. Use `frameworkTools: "minimal"` to turn every group off at
+once for a voice-first or single-purpose app, or
+`frameworkTools: { preset: "minimal", resources: true }` to keep just one — an
+explicit group key always wins over the preset.
+
+Switching a group off removes it from the **agent** surfaces only: interactive
+chat, MCP, A2A, and background runs. The matching HTTP action routes stay
+mounted, because the UI reaches them through client hooks — disabling `sharing`
+must not 404 a share dialog that is still on screen. Weigh that parity cost
+before using it: the framework's contract is that anything the UI can do the
+agent can do, so `sharing: false` alongside a visible share button is a
+deliberate break, and only makes sense when the app has no such surface at all.
+
+Framework tools are no longer promoted into the first model request by default,
+independent of this option. They stay in the searchable registry and load
+through `tool-search`, or immediately if the app names them in
+`initialToolNames`.
+
+<Callout tone="warning">
+  The top-level `databaseTools` and `extensionTools` options are deprecated in
+  favor of `frameworkTools.database` and `frameworkTools.extensions`. They are
+  still honored, but setting a top-level flag and its `frameworkTools`
+  equivalent to conflicting values throws at plugin startup rather than booting
+  with a tool surface nobody chose.
+</Callout>
 
 ## Production Code Execution {#production-code-execution}
 

package/docs/content/key-concepts.mdx

@@ -254,12 +254,19 @@ pnpm action db-query --sql "SELECT * FROM forms"
 ```
 
 The production agent chat plugin defaults raw SQL tools to read-only
-(`databaseTools: "read"`), so agents inspect app-owned data with `db-schema` /
-`db-query` and perform writes through typed app actions. Set
-`databaseTools: "write"` (or `true`) only for deliberate maintenance surfaces
-that should also expose scoped `db-exec` / `db-patch`; set
-`databaseTools: "off"` / `false` to require typed app actions for all data
-access.
+(`frameworkTools: { database: "read" }`), so agents inspect app-owned data with
+`db-schema` / `db-query` and perform writes through typed app actions. Set
+`database: "write"` (or `true`) only for deliberate maintenance surfaces that
+should also expose scoped `db-exec` / `db-patch`; set `database: "off"` /
+`false` to require typed app actions for all data access.
+
+`frameworkTools` governs the rest of the framework's own tools the same way —
+sharing, review comments, version history, feature flags, localization, audit,
+context X-Ray, profile, automations, docs, resources, web, cross-app delegation,
+chat, and email. See
+[Production Agent Tools](/docs/deployment#production-agent-tools) for the full
+list, the `"minimal"` preset, and why disabling a group leaves its HTTP routes
+mounted.
 
 ## Agent chat bridge {#agent-chat-bridge}
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@agent-native/core",
-  "version": "0.144.2",
+  "version": "0.145.0",
   "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": {
@@ -72,6 +72,7 @@
     "./server/request-context": "./dist/server/request-context.js",
     "./server/design-token-utils": "./dist/server/design-token-utils.js",
     "./server/poll": "./dist/server/poll.js",
+    "./server/interval-job": "./dist/server/interval-job.js",
     "./server/sse": "./dist/server/sse.js",
     "./server/short-lived-token": "./dist/server/short-lived-token.js",
     "./integrations": "./dist/integrations/index.js",

package/src/templates/default/.agents/skills/internationalization/SKILL.md

@@ -29,6 +29,11 @@ Templates use `app/i18n/`:
 Use BCP-47 filenames from the supported set: `en-US`, `zh-CN`, `es-ES`,
 `fr-FR`, `de-DE`, `ja-JP`, `ko-KR`, `pt-BR`, `hi-IN`, `ar-SA`.
 
+If an app only ships translations for a subset of that set, set
+`supportedLocales` on the `AgentNativeI18nCatalog` to that subset. Without it,
+`<LanguagePicker />` lists every framework-supported locale regardless of
+whether `loadMessages` can actually resolve it.
+
 ## UI Pattern
 
 - Wrap apps with `AppProviders i18n={{ catalog: i18nCatalog }}`.

package/src/templates/workspace-core/.agents/skills/extensions/SKILL.md

@@ -217,9 +217,12 @@ POST /_agent-native/extensions
 
 HTTP creation is disabled by default. The host app must set
 `extensionTools: true` on `createCoreRoutesPlugin()` as well as
-`createAgentChatPlugin()`; otherwise authenticated collection `POST` requests
-return `403` while existing extension runtime, read, edit, and deep-link routes
-remain available for compatibility.
+`frameworkTools: { extensions: true }` on `createAgentChatPlugin()`; otherwise
+authenticated collection `POST` requests return `403` while existing extension
+runtime, read, edit, and deep-link routes remain available for compatibility.
+(`extensionTools` on the agent-chat plugin is the deprecated spelling of
+`frameworkTools.extensions`; the core-routes option keeps its own name because
+it gates route mounting rather than agent tools.)
 
 The action accepts: