@agent-native/core 0.141.7 → 0.144.0

package/dist/integrations/plugin.js

@@ -3,6 +3,7 @@ import { getRequestHeader } from "h3";
 import { createRemoteJWKSet, jwtVerify } from "jose";
 import { AGENT_BACKGROUND_PROCESSOR_FIELD, AGENT_BACKGROUND_PROCESSOR_INTEGRATION, isInBackgroundFunctionRuntime, } from "../agent/durable-background.js";
 import { abortRun } from "../agent/run-manager.js";
+import { isServerlessRuntime } from "../db/client.js";
 import { getOrgContext, resolveOrgIdForEmail } from "../org/context.js";
 import { loadResourcesForPrompt } from "../server/agent-chat-plugin.js";
 import { withConfiguredAppBasePath } from "../server/app-base-path.js";
@@ -2657,12 +2658,14 @@ export function createIntegrationsPlugin(options) {
             setResponseStatus(event, 404);
             return { error: "Not found" };
         }));
-        // Background agent and scheduled recovery functions mount the same Nitro
-        // app, but they are workers rather than hosts for recurring integration
-        // jobs. Starting these timers in every worker multiplies recovery sweeps
-        // and pollers across concurrent runs, exhausting the shared database
-        // precisely while those runs are trying to checkpoint and deliver replies.
-        if (!isInBackgroundFunctionRuntime() && !isInIntegrationRecoveryRuntime()) {
+        // Serverless functions mount the same Nitro app as the durable workers,
+        // but they are not a stable host for recurring integration jobs. Starting
+        // these timers in every cold-started instance multiplies recovery sweeps
+        // and pollers against the shared database; scheduled/background workers
+        // own this work on hosted deployments.
+        if (!isInBackgroundFunctionRuntime() &&
+            !isInIntegrationRecoveryRuntime() &&
+            !isServerlessRuntime()) {
             // ─── Start pending-tasks retry sweeper ────────────────────────
             // Sweeps the integration_pending_tasks queue every 60s and re-fires the
             // processor for any tasks that got stuck (initial dispatch lost or

package/dist/localization/default-messages.d.ts

@@ -923,8 +923,17 @@ declare const messages: {
         presetAuthDescription: string;
         customDescription: string;
         oauthNotice: string;
+        providerSetupRequired: string;
+        providerSetupDescription: string;
+        providerSetupFormDescription: string;
+        continueToConnect: string;
+        setupTitle: string;
         personal: string;
         organization: string;
+        scopeQuestion: string;
+        personalDescription: string;
+        sharedWithWorkspace: string;
+        organizationDescription: string;
         serverNameRequired: string;
         serverName: string;
         url: string;
@@ -955,6 +964,11 @@ declare const messages: {
                 useCase: string;
                 setupNote: string;
             };
+            amplitude: {
+                description: string;
+                useCase: string;
+                setupNote: string;
+            };
             notion: {
                 description: string;
                 useCase: string;
@@ -965,6 +979,11 @@ declare const messages: {
                 useCase: string;
                 setupNote: string;
             };
+            gong: {
+                description: string;
+                useCase: string;
+                setupNote: string;
+            };
             semgrep: {
                 description: string;
                 useCase: string;
@@ -973,6 +992,21 @@ declare const messages: {
                 description: string;
                 useCase: string;
             };
+            apollo: {
+                description: string;
+                useCase: string;
+                setupNote: string;
+            };
+            commonRoom: {
+                description: string;
+                useCase: string;
+                setupNote: string;
+            };
+            exa: {
+                description: string;
+                useCase: string;
+                setupNote: string;
+            };
             supabase: {
                 description: string;
                 useCase: string;
@@ -995,6 +1029,16 @@ declare const messages: {
                 useCase: string;
                 setupNote: string;
             };
+            grafana: {
+                description: string;
+                useCase: string;
+                setupNote: string;
+            };
+            googleWorkspace: {
+                description: string;
+                useCase: string;
+                setupNote: string;
+            };
             gitlab: {
                 description: string;
                 useCase: string;
@@ -1035,6 +1079,11 @@ declare const messages: {
                 useCase: string;
                 setupNote: string;
             };
+            pylon: {
+                description: string;
+                useCase: string;
+                setupNote: string;
+            };
             intercom: {
                 description: string;
                 useCase: string;
@@ -1060,6 +1109,11 @@ declare const messages: {
                 useCase: string;
                 setupNote: string;
             };
+            builder: {
+                description: string;
+                useCase: string;
+                setupNote: string;
+            };
             netlify: {
                 description: string;
                 useCase: string;

package/dist/localization/default-messages.js

@@ -3,6 +3,7 @@
 // can load it during SSR. Do not import core runtime code from src/templates:
 // templates ship as verbatim copy-only scaffolding (.ts), so their compiled
 // .js never exists in dist.
+import { PASSWORD_MIN_LENGTH_MESSAGE } from "../shared/password-policy.js";
 const messages = {
     workspaceFile: {
         download: "Download",
@@ -65,7 +66,7 @@ const messages = {
         passwordNewLabel: "New password",
         passwordConfirmLabel: "Confirm new password",
         passwordPlaceholder: "Enter password",
-        passwordMinLength: "Password must be at least 8 characters",
+        passwordMinLength: PASSWORD_MIN_LENGTH_MESSAGE,
         passwordMismatch: "Passwords do not match",
         passwordSave: "Save password",
         passwordSaving: "Saving...",
@@ -928,8 +929,17 @@ const messages = {
         presetAuthDescription: "Preset values are filled in. Add any required authorization details before connecting.",
         customDescription: "Paste a Streamable HTTP or SSE endpoint and optional headers.",
         oauthNotice: "This provider usually requires an OAuth setup. Follow the provider docs, or add an Authorization header if your endpoint supports token-based access.",
+        providerSetupRequired: "Provider setup required",
+        providerSetupDescription: "Complete the required setup in {{name}} first. Then return here to authorize your account.",
+        providerSetupFormDescription: "Review the provider requirements and open the official setup guide before connecting your account.",
+        continueToConnect: "I've completed setup",
+        setupTitle: "Set up {{name}}",
         personal: "Personal",
         organization: "Organization",
+        scopeQuestion: "Who should be able to use this connection?",
+        personalDescription: "Only you can use this connection.",
+        sharedWithWorkspace: "Shared with workspace",
+        organizationDescription: "Permitted workspace members can use this connection. Provider permissions still apply.",
         serverNameRequired: "Enter an integration name before connecting with OAuth.",
         serverName: "Integration name",
         url: "URL",
@@ -960,6 +970,11 @@ const messages = {
                 useCase: "Product analytics, session replay, qualitative behavior, user research",
                 setupNote: "FullStory MCP is currently beta and requires StoryAI features plus the Model Context Protocol toggle to be enabled by a FullStory organization admin.",
             },
+            amplitude: {
+                description: "Read and work with Amplitude product analytics.",
+                useCase: "Product analytics, charts, dashboards, cohorts, experiments",
+                setupNote: "Amplitude MCP uses OAuth over streaming HTTP. The default endpoint is for US data residency; use Amplitude's EU endpoint when the account requires EU residency.",
+            },
             notion: {
                 description: "Search pages and team knowledge.",
                 useCase: "Documentation, knowledge management, notes, content creation",
@@ -970,6 +985,11 @@ const messages = {
                 useCase: "Meeting notes, recordings, transcripts, action items, follow-ups",
                 setupNote: "The Granola integration uses browser OAuth. Authorize the signed-in Granola account and review which meeting notes and transcripts the agent can access.",
             },
+            gong: {
+                description: "Search Gong calls and generate account and deal insights.",
+                useCase: "Sales calls, transcripts, deal insights, account summaries",
+                setupNote: "Gong requires a tech admin to create an MCP integration and choose personal or shared authorization. The generated client ID and secret must be configured before connecting.",
+            },
             semgrep: {
                 description: "Scan code for security findings.",
                 useCase: "Security scanning, vulnerability detection, code analysis",
@@ -978,6 +998,21 @@ const messages = {
                 description: "Read and write Linear issues.",
                 useCase: "Project management, issue tracking, planning, bug reports",
             },
+            apollo: {
+                description: "Search, enrich, and manage Apollo GTM data.",
+                useCase: "Prospecting, enrichment, contacts, sequences, account research",
+                setupNote: "Apollo MCP uses user OAuth and does not require an Apollo API key. Apollo plan permissions, credits, and the provider's model-training restrictions still apply.",
+            },
+            commonRoom: {
+                description: "Research buyer signals, contacts, and organizations.",
+                useCase: "Buyer intelligence, product signals, intent, contact enrichment",
+                setupNote: "Common Room MCP uses per-user OAuth and respects the authorized user's workspace role. An administrator may need to enable the MCP connection for the instance.",
+            },
+            exa: {
+                description: "Search the web and fetch pages with Exa.",
+                useCase: "Web search, research, code search, page fetching",
+                setupNote: "Exa's remote MCP endpoint supports basic free usage without a key. Add an Exa API key through the provider's header configuration when higher limits or additional tools are needed.",
+            },
             supabase: {
                 description: "Manage data, auth, and backend services.",
                 useCase: "Database, authentication, storage, edge functions",
@@ -1000,6 +1035,16 @@ const messages = {
                 useCase: "DNS, Workers, domains, security, observability, platform APIs",
                 setupNote: "Cloudflare's managed integration directory contains product-specific integrations as well as the broad API integration. Review the scopes and choose the narrowest endpoint that fits your workflow.",
             },
+            grafana: {
+                description: "Query Grafana Cloud metrics, logs, and observability data.",
+                useCase: "Observability, metrics, logs, traces, dashboards",
+                setupNote: "Grafana Cloud MCP is in public preview and requires Grafana Cloud Assistant MCP access. It is hosted Grafana Cloud only; self-hosted Grafana needs the local MCP server.",
+            },
+            googleWorkspace: {
+                description: "Search Google Workspace data through its remote MCP server.",
+                useCase: "Workspace search across Gmail, Drive, Calendar, Chat, Docs, Sheets, Slides",
+                setupNote: "Google Workspace MCP is in Developer Preview. Enable the relevant Google Workspace and MCP APIs, configure an OAuth consent screen and client, then authorize the products you want to use.",
+            },
             gitlab: {
                 description: "Read and manage GitLab projects, issues, and merge requests.",
                 useCase: "Repositories, issues, merge requests, CI/CD, code analytics",
@@ -1038,7 +1083,12 @@ const messages = {
             hubspot: {
                 description: "Search and update HubSpot CRM records through its integration.",
                 useCase: "CRM, contacts, companies, deals, tickets, customer analytics",
-                setupNote: "The HubSpot integration requires a HubSpot Auth App and PKCE. Create the app in the HubSpot Developer Platform before connecting; the existing HubSpot OAuth connector remains available to app actions.",
+                setupNote: "When a workspace-managed HubSpot MCP Auth App is configured, any member can connect a personal HubSpot account with OAuth and PKCE. Otherwise, create the app in the HubSpot Developer Platform before connecting; the existing HubSpot OAuth connector remains available to app actions.",
+            },
+            pylon: {
+                description: "Search and update Pylon support data.",
+                useCase: "Customer support, issues, accounts, contacts, conversations",
+                setupNote: "Enable Pylon MCP access for the relevant users and turn on the MCP server in Pylon before connecting. Pylon requires a Member or Admin seat and uses user OAuth only.",
             },
             intercom: {
                 description: "Search conversations and customer support knowledge.",
@@ -1065,6 +1115,11 @@ const messages = {
                 useCase: "Files, folders, enterprise content, search, collaboration",
                 setupNote: "The Box integration is beta and requires an administrator to enable it. Custom clients also need Box Integration Credentials, a redirect URI, and approved scopes.",
             },
+            builder: {
+                description: "Search Builder Publish and Hybrid Space content.",
+                useCase: "Content models, pages, entries, Publish and Hybrid Spaces",
+                setupNote: "Builder CMS MCP uses OAuth with dynamic client registration. It only connects to Publish or Hybrid Spaces, and the authorization flow asks you to select the Space.",
+            },
             netlify: {
                 description: "Inspect and operate Netlify sites and deployments.",
                 useCase: "Sites, deployments, builds, domains, hosting operations",

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/mcp-client/oauth-routes.d.ts

@@ -23,6 +23,8 @@ export interface McpOAuthRoutesOptions {
 }
 export declare function redirectWithStagedCookies(event: H3Event, location: string): Response;
 export declare function mountMcpOAuthRoutes(nitroApp: any, options: McpOAuthRoutesOptions): void;
+export declare function resolveMcpOAuthScope(serverUrl: URL, requestedScope: unknown): RemoteMcpScope | null;
+export declare function resolveManagedMcpOAuthClient(serverUrl: URL): Promise<StoredOAuthClientInformation | undefined>;
 export declare function setMcpOAuthFlowCookie(event: H3Event, flow: McpOAuthFlow, secure: boolean): void;
 export declare function readMcpOAuthFlowCookie(event: H3Event): McpOAuthFlow | null;
 export declare function clearMcpOAuthFlowCookies(event: H3Event): void;

package/dist/mcp-client/oauth-routes.js

@@ -3,6 +3,7 @@ import { deleteCookie, defineEventHandler, getChunkedCookie, getCookie, getMetho
 import { getOrgContext } from "../org/context.js";
 import { decryptSecretValue, encryptSecretValue } from "../secrets/crypto.js";
 import { getSession, safeReturnPath } from "../server/auth.js";
+import { resolveSecret } from "../server/credential-provider.js";
 import { getH3App } from "../server/framework-request-handler.js";
 import { getAppUrl, resolveOAuthRedirectUri } from "../server/google-oauth.js";
 import { runWithRequestContext } from "../server/request-context.js";
@@ -13,6 +14,21 @@ const FLOW_TTL_SECONDS = 10 * 60;
 const FLOW_COOKIE_CHUNK_SIZE = 2_800;
 const FLOW_COOKIE_MAX_CHUNKS = 8;
 const CHUNKED_COOKIE_PREFIX = "__chunked__";
+const MANAGED_MCP_OAUTH_CLIENTS = [
+    {
+        serverOrigin: "https://mcp.hubspot.com",
+        clientIdKeys: [
+            "HUBSPOT_MCP_CLIENT_ID",
+            "HUBSPOT_INTEGRATION_CLIENT_ID",
+            "HUBSPOT_CLIENT_ID",
+        ],
+        clientSecretKeys: [
+            "HUBSPOT_MCP_CLIENT_SECRET",
+            "HUBSPOT_INTEGRATION_CLIENT_SECRET",
+            "HUBSPOT_CLIENT_SECRET",
+        ],
+    },
+];
 export function redirectWithStagedCookies(event, location) {
     const headers = new Headers({
         Location: location,
@@ -70,7 +86,13 @@ async function handleMcpOAuthStart(event) {
         setResponseStatus(event, 400);
         return { error: "MCP server name is invalid." };
     }
-    const requestedScope = query.scope === "org" ? "org" : "user";
+    const requestedScope = resolveMcpOAuthScope(urlCheck.url, query.scope);
+    if (!requestedScope) {
+        setResponseStatus(event, 400);
+        return {
+            error: "Managed MCP OAuth connections must use personal scope.",
+        };
+    }
     const requestedOrgId = text(query.orgId);
     const org = requestedScope === "org"
         ? await getOrgContext(event).catch(() => null)
@@ -98,12 +120,29 @@ async function handleMcpOAuthStart(event) {
     }
     const state = crypto.randomUUID();
     const safeReturnUrl = returnUrl ? safeReturnPath(returnUrl) : undefined;
+    const requestContext = {
+        userEmail: session.email,
+        orgId: org?.orgId ?? undefined,
+    };
     try {
-        const started = await runWithRequestContext({ userEmail: session.email, orgId: org?.orgId ?? undefined }, () => startMcpOAuthAuthorization({
-            serverUrl: urlCheck.url.toString(),
-            redirectUrl: redirectUri,
-            state,
-        }));
+        const started = await runWithRequestContext(requestContext, async () => {
+            const clientInformation = await resolveManagedMcpOAuthClient(urlCheck.url);
+            if (isManagedMcpOAuthServer(urlCheck.url) && !clientInformation) {
+                return null;
+            }
+            return startMcpOAuthAuthorization({
+                serverUrl: urlCheck.url.toString(),
+                redirectUrl: redirectUri,
+                state,
+                ...(clientInformation ? { clientInformation } : {}),
+            });
+        });
+        if (!started) {
+            setResponseStatus(event, 400);
+            return {
+                error: "HubSpot personal MCP connect is not configured for this workspace. A workspace owner must register the HubSpot MCP Auth App once; after that, any workspace member can connect a personal account.",
+            };
+        }
         const flow = {
             name,
             url: urlCheck.url.toString(),
@@ -132,6 +171,34 @@ async function handleMcpOAuthStart(event) {
         };
     }
 }
+function isManagedMcpOAuthServer(serverUrl) {
+    return MANAGED_MCP_OAUTH_CLIENTS.some((client) => client.serverOrigin === serverUrl.origin);
+}
+export function resolveMcpOAuthScope(serverUrl, requestedScope) {
+    if (isManagedMcpOAuthServer(serverUrl) && requestedScope === "org") {
+        return null;
+    }
+    return requestedScope === "org" ? "org" : "user";
+}
+export async function resolveManagedMcpOAuthClient(serverUrl) {
+    const client = MANAGED_MCP_OAUTH_CLIENTS.find((candidate) => candidate.serverOrigin === serverUrl.origin);
+    if (!client)
+        return undefined;
+    for (let index = 0; index < client.clientIdKeys.length; index += 1) {
+        const [clientId, clientSecret] = await Promise.all([
+            resolveSecret(client.clientIdKeys[index]),
+            resolveSecret(client.clientSecretKeys[index]),
+        ]);
+        if (clientId && clientSecret) {
+            return {
+                client_id: clientId,
+                client_secret: clientSecret,
+                token_endpoint_auth_method: "client_secret_post",
+            };
+        }
+    }
+    return undefined;
+}
 async function handleMcpOAuthCallback(event, options) {
     const session = await getSession(event).catch(() => null);
     if (!session?.email)

package/dist/notifications/routes.d.ts

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

package/dist/observability/routes.d.ts

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

package/dist/onboarding/app-profile.js

@@ -6,6 +6,14 @@ const LLM_CAPABILITY = {
     keySummary: "One model key: Anthropic, OpenAI, Gemini, Groq, Mistral, or Cohere",
     why: "The agent uses a language model to understand requests and produce answers.",
 };
+const DESIGN_SYSTEM_INTELLIGENCE_CAPABILITY = {
+    id: "design-system-intelligence",
+    label: "Design system intelligence",
+    required: false,
+    builderIncluded: true,
+    keySummary: "Builder Design System Intelligence",
+    why: "Uses your brand and design-system guidance to keep generated work on brand.",
+};
 const PROFILES = {
     analytics: {
         appId: "analytics",
@@ -42,6 +50,7 @@ const PROFILES = {
                 keySummary: "Gemini for video, or OpenAI / Gemini for images",
                 why: "These providers create the images and videos requested in the app.",
             },
+            DESIGN_SYSTEM_INTELLIGENCE_CAPABILITY,
             {
                 id: "file-storage",
                 label: "Media storage",
@@ -169,6 +178,7 @@ const PROFILES = {
         appName: "Design",
         capabilities: [
             LLM_CAPABILITY,
+            DESIGN_SYSTEM_INTELLIGENCE_CAPABILITY,
             {
                 id: "assets-library",
                 label: "Assets library",
@@ -313,6 +323,7 @@ const PROFILES = {
         appName: "Slides",
         capabilities: [
             LLM_CAPABILITY,
+            DESIGN_SYSTEM_INTELLIGENCE_CAPABILITY,
             {
                 id: "image-generation",
                 label: "Image generation",

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/resources/store.js

@@ -1,6 +1,6 @@
 import crypto from "crypto";
 import { getDbExec, isPostgres, intType, retryOnDdlRace, } from "../db/client.js";
-import { ensureColumnExists, ensureTableExists } from "../db/ddl-guard.js";
+import { ensureColumnExists, ensureIndexExists, ensureTableExists, } from "../db/ddl-guard.js";
 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";
@@ -655,6 +655,20 @@ async function _doEnsureTable() {
         "updated_at",
         "expires_at",
     ]);
+    // `cleanupExpiredAgentScratchResources` 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
+    // a fresh isolate, so the first resource read after EVERY cold start pays
+    // that scan. Idempotent and dialect-agnostic, per the `performance` skill.
+    await ensureIndexExists("resources_visibility_expires_idx", `CREATE INDEX IF NOT EXISTS resources_visibility_expires_idx ON resources (visibility, expires_at)`).catch((err) => {
+        // An index is an optimization, not a correctness requirement: a
+        // concurrent creator or a permissions edge must not fail table init and
+        // take the app down with it. The scan it avoids is slow, not wrong — but
+        // say so, because "silently slow forever" is the outcome nobody notices.
+        // 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)
     const now = Date.now();
     const seedSql = isPostgres()