@agent-native/core 0.145.4 → 0.145.6

package/dist/provider-api/corpus-jobs.js

@@ -202,7 +202,7 @@ export function createProviderCorpusJobAction(options) {
             "Use this for broad provider searches, cross-source joins, transcript/message/ticket/issue/document scans, batch endpoint walks, and absence-sensitive questions that may exceed one tool call. " +
             "The job is generic: paginated-search walks any paginated provider endpoint; batch-search walks a supplied id/record list or staged dataset through any provider endpoint by injecting each batch into a query param or request body path. " +
             "Every provider request still goes through provider-api-request credentials, host allow-listing, SSRF blocking, secret redaction, and provider quota cooldown. " +
-            "When status is paused or quota_wait, call operation=continue with the jobId after the indicated time/budget. Report coverage counts, pagination status, and any remaining gaps.",
+            "When status is paused or quota_wait, call operation=continue with the jobId after the indicated time/budget. Report coverage counts, paginationComplete, and any remaining gaps; a max-pages stop is not exhaustive.",
         schema: ProviderCorpusJobSchema,
         http: false,
         run: async (args) => runProviderCorpusJobAction(args, options),
@@ -826,6 +826,7 @@ function jobStatus(job) {
     const nextResumeAtIso = job.nextResumeAt
         ? new Date(job.nextResumeAt).toISOString()
         : null;
+    const coverage = paginationCoverage(job);
     return {
         job: jobSummary(job),
         source: jobSourceSummary(job),
@@ -837,6 +838,7 @@ function jobStatus(job) {
             totalHits: job.totalHits,
             storedHits: job.storedHits,
             truncatedHits: job.totalHits > job.storedHits,
+            ...coverage,
         },
         checkpoint: job.checkpoint,
         error: job.error,
@@ -898,6 +900,13 @@ function jobSummary(job) {
     };
 }
 function nextAction(job) {
+    const coverage = paginationCoverage(job);
+    if (job.mode === "paginated-search" && !coverage.paginationComplete) {
+        if (coverage.paginationStopReason === "max-pages") {
+            return `Pagination stopped at maxPages for this job. Start a new job with a larger pagination.maxPages before treating the results as exhaustive; stored hits are readable with operation="results", jobId="${job.id}".`;
+        }
+        return `Pagination coverage is incomplete${coverage.paginationStopReason ? ` (${coverage.paginationStopReason})` : ""}. Do not treat the stored hits as exhaustive; inspect the provider checkpoint or start a new bounded job before making coverage-sensitive claims. Stored hits are readable with operation="results", jobId="${job.id}".`;
+    }
     if (job.status === "completed") {
         return `Read all stored hits with operation="results", jobId="${job.id}".`;
     }
@@ -915,6 +924,27 @@ function nextAction(job) {
     }
     return `Check status with operation="status", jobId="${job.id}".`;
 }
+function paginationCoverage(job) {
+    const stopReason = typeof job.checkpoint.stoppedReason === "string"
+        ? job.checkpoint.stoppedReason
+        : null;
+    if (job.mode !== "paginated-search") {
+        return {
+            paginationComplete: job.status === "completed",
+            paginationStopReason: stopReason,
+        };
+    }
+    return {
+        paginationComplete: [
+            "empty-page",
+            "no-next-cursor",
+            "repeated-cursor",
+            "short-page",
+            "single-page",
+        ].includes(stopReason ?? ""),
+        paginationStopReason: stopReason,
+    };
+}
 function extractItemsArray(body, itemsPath, wrapObjectFallback) {
     if (Array.isArray(body))
         return body;

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

@@ -43,6 +43,8 @@ export interface ProviderApiRequestArgs {
     body?: unknown;
     auth?: "default" | "none";
     timeoutMs?: number;
+    /** Internal cancellation signal for trusted server-side callers. */
+    signal?: AbortSignal;
     maxBytes?: number;
     connectionId?: string | null;
     accountId?: string | null;

package/dist/provider-api/index.js

@@ -1307,6 +1307,7 @@ export async function executeProviderApiRequest(args, runtime) {
                 body: pageBody,
                 maxBytes: effectiveMaxBytes,
                 timeoutMs: clampTimeout(args.timeoutMs),
+                signal: args.signal,
                 secretValues: auth.secretValues,
                 quota: {
                     identity: quotaIdentity,
@@ -1352,6 +1353,7 @@ export async function executeProviderApiRequest(args, runtime) {
         body,
         maxBytes: effectiveMaxBytes,
         timeoutMs: clampTimeout(args.timeoutMs),
+        signal: args.signal,
         secretValues: auth.secretValues,
         quota: {
             identity: quotaIdentity,
@@ -2058,6 +2060,7 @@ async function executeCustomProviderApiRequest(args, customConfig, runtime) {
                 body: pageBody,
                 maxBytes: effectiveMaxBytes,
                 timeoutMs: clampTimeout(args.timeoutMs),
+                signal: args.signal,
                 secretValues: auth.secretValues,
                 quota: {
                     identity: quotaIdentity,
@@ -2099,6 +2102,7 @@ async function executeCustomProviderApiRequest(args, customConfig, runtime) {
         body,
         maxBytes: effectiveMaxBytes,
         timeoutMs: clampTimeout(args.timeoutMs),
+        signal: args.signal,
         secretValues: auth.secretValues,
         quota: {
             identity: quotaIdentity,
@@ -3724,7 +3728,9 @@ async function fetchWithTimeout(optionsUrl, options) {
                 method,
                 headers: options.headers,
                 body: options.body,
-                signal: controller.signal,
+                signal: options.signal
+                    ? AbortSignal.any([options.signal, controller.signal])
+                    : controller.signal,
                 redirect: "manual",
             };
             if (dispatcher)

package/dist/secrets/routes.d.ts

@@ -37,17 +37,17 @@ export declare function createWriteSecretHandler(): import("h3").EventHandlerWit
     ok?: undefined;
     status?: undefined;
 } | {
-    error?: undefined;
     ok: boolean;
     status: string;
+    error?: undefined;
 } | {
     ok?: undefined;
     error: string;
     removed?: undefined;
 } | {
-    error?: undefined;
     ok: boolean;
     removed: boolean;
+    error?: undefined;
 }>>;
 /**
  * POST /_agent-native/secrets/:key/test — validate an optional candidate value
@@ -58,13 +58,13 @@ export declare function createTestSecretHandler(): import("h3").EventHandlerWith
     error: string;
     note?: undefined;
 } | {
-    error?: undefined;
     ok: boolean;
     note?: 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;
+} | {
     ok: boolean;
     removed: boolean;
+    error?: undefined;
 }>>;

package/dist/server/agent-chat/recurring-jobs-runtime.d.ts

@@ -1,4 +1,4 @@
-type RecurringJobsRuntimeEnvKey = "AGENT_NATIVE_DISABLE_RECURRING_JOBS" | "AGENT_NATIVE_ENABLE_LOCAL_RECURRING_JOBS" | "APP_URL" | "BETTER_AUTH_URL" | "DEPLOY_URL" | "NETLIFY" | "NETLIFY_LOCAL" | "NODE_ENV" | "SITE_ID" | "URL" | "VITE_APP_URL" | "VITE_WORKSPACE_GATEWAY_URL" | "WORKSPACE_GATEWAY_URL";
+type RecurringJobsRuntimeEnvKey = "AGENT_NATIVE_DISABLE_RECURRING_JOBS" | "AGENT_NATIVE_ENABLE_LOCAL_RECURRING_JOBS" | "APP_URL" | "BETTER_AUTH_URL" | "CF_PAGES" | "DEPLOY_URL" | "AWS_EXECUTION_ENV" | "AWS_LAMBDA_FUNCTION_NAME" | "NETLIFY" | "NETLIFY_LOCAL" | "NITRO_PRESET" | "NODE_ENV" | "SITE_ID" | "URL" | "VERCEL" | "VITE_APP_URL" | "VITE_WORKSPACE_GATEWAY_URL" | "WORKSPACE_GATEWAY_URL";
 type RecurringJobsRuntimeEnv = Partial<Record<RecurringJobsRuntimeEnvKey, string | undefined>>;
 export declare function shouldDisableRecurringJobsRuntime(env?: RecurringJobsRuntimeEnv): boolean;
 /**

package/dist/server/agent-chat/recurring-jobs-runtime.js

@@ -1,7 +1,7 @@
 // ---------------------------------------------------------------------------
 // Recurring-jobs runtime gating: decide whether this process should run the
-// local recurring-job scheduler loop (disabled by default on hosted runtimes
-// that already run a dedicated sweep, enabled by default for local/dev).
+// local recurring-job scheduler loop (disabled by default on hosted/serverless
+// runtimes, enabled by default for local/dev).
 // ---------------------------------------------------------------------------
 function isTruthyEnv(value) {
     return /^(1|true|yes|on)$/i.test(value?.trim() ?? "");
@@ -33,6 +33,18 @@ function isLoopbackAppUrl(value) {
 export function shouldDisableRecurringJobsRuntime(env = process.env) {
     if (isTruthyEnv(env.AGENT_NATIVE_DISABLE_RECURRING_JOBS))
         return true;
+    // A serverless isolate is not a durable scheduler. Keep this check separate
+    // from the platform-specific scheduler branch below so a new sweep cannot
+    // accidentally start an in-process timer before its platform trigger exists.
+    const isServerlessRuntime = env.NETLIFY_LOCAL !== "true" &&
+        (isTruthyEnv(env.NETLIFY) ||
+            env.NITRO_PRESET === "netlify" ||
+            Boolean(env.AWS_LAMBDA_FUNCTION_NAME) ||
+            env.AWS_EXECUTION_ENV?.startsWith("AWS_Lambda") === true ||
+            isTruthyEnv(env.CF_PAGES) ||
+            isTruthyEnv(env.VERCEL));
+    if (isServerlessRuntime)
+        return true;
     const isLocalRuntime = env.NODE_ENV === "development" ||
         env.NODE_ENV === "test" ||
         [

package/dist/server/agent-chat/script-entries.js

@@ -657,7 +657,18 @@ export async function createAgentEngineScriptEntries(appId) {
             "manage-agent-engine": {
                 tool: mod.tool,
                 planMode: {
-                    effect: (args) => (args.action === "list" ? "read" : "write"),
+                    // Reads, per the tool's own enum: only set/set-app-default/
+                    // reset-app-default mutate. Misclassifying a read here makes every
+                    // call announce a change and bump the global `action` change
+                    // version, which is how the model-picker's catalog read ended up
+                    // recorded as a write for 1,127 identities.
+                    // `allowedValues` stays narrower on purpose — it governs what plan
+                    // mode may run, and `test` spends a live model call.
+                    effect: (args) => args.action === "list" ||
+                        args.action === "test" ||
+                        args.action === "get-app-default"
+                        ? "read"
+                        : "write",
                     allowedValues: { action: ["list"] },
                     description: "Plan mode allows listing available agent engines.",
                 },

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

@@ -4793,8 +4793,8 @@ Non-code requests are still fine on this surface: read data, navigate the UI, su
             }
             // ─── Recurring Jobs Scheduler ──────────────────────────────────────
             // Poll every 60 seconds for due recurring jobs and execute them.
-            // Uses setInterval so it works in all deployment environments without
-            // requiring Nitro experimental tasks configuration.
+            // Long-lived runtimes use setInterval; serverless runtimes rely on a
+            // platform-owned sweep because an invocation cannot own a durable loop.
             try {
                 const { processRecurringJobs } = await import("../jobs/scheduler.js");
                 const schedulerDeps = {

package/dist/server/auth.d.ts

@@ -249,6 +249,7 @@ export declare function setDesktopExchangeError(flowId: string, error: DesktopEx
  */
 export declare function runAuthGuard(event: H3Event): Promise<Response | object | string | void>;
 export declare function shouldBypassAuthForBuilderConnect(event: H3Event, p: string): boolean;
+export declare function isLocalDevAuthAllowed(event: H3Event): boolean;
 /**
  * Get the current auth session for a request.
  *

package/dist/server/auth.js

@@ -57,7 +57,7 @@ import { injectAnalyticsIntoHtml } from "./analytics.js";
 import { getConfiguredAppBasePath } from "./app-base-path.js";
 import { readAnalyticsAnonymousId, signupAttributionFromCookieHeader, } from "./attribution.js";
 import { getAuthLoginMode } from "./auth-login-mode.js";
-import { ensureGoogleAuthIdentity, getBetterAuth, getBetterAuthSync, } from "./better-auth-instance.js";
+import { createBetterAuthSessionForEmail, ensureGoogleAuthIdentity, getBetterAuth, getBetterAuthSync, isDeployPreview, } from "./better-auth-instance.js";
 import { BUILDER_CONNECT_OWNER_COOKIE, BUILDER_CONNECT_PARAM, BUILDER_RELAY_PATH, BUILDER_RELAY_STATE_PARAM, BUILDER_STATE_PARAM, verifyBuilderCallbackStateAndGetOwner, verifyBuilderConnectTokenAndGetOwner, verifyBuilderPreviewRelayStateForCallback, } from "./builder-browser.js";
 import { resolveAuthCookieNamespace } from "./cookie-namespace.js";
 import { getAllowedCorsOrigin, readCorsAllowedOrigins, } from "./cors-origins.js";
@@ -68,6 +68,7 @@ import { isElectron as isElectronRequest, getAppBasePath, getAppUrl, getOrigin,
 // auth.ts), so the guard and the SSO route handler share one validator and
 // can never disagree about whether federated SSO is enabled.
 import { isIdentitySsoEnabled } from "./identity-sso-store.js";
+import { ensureCanonicalUserForLegacySession } from "./legacy-auth-migration.js";
 import { safeOAuthReturnUrl } from "./oauth-return-url.js";
 import { getOnboardingHtml, getResetPasswordHtml, } from "./onboarding-html.js";
 import { captureAuthError } from "./sentry.js";
@@ -202,6 +203,12 @@ async function getLegacyCookieSession(event) {
     for (const { name, value } of getFrameworkSessionCookieEntries(event)) {
         const email = await getSessionEmail(value);
         if (email) {
+            try {
+                await ensureCanonicalUserForLegacySession(email);
+            }
+            catch (error) {
+                console.warn("[auth] legacy session canonical-user backfill failed:", error instanceof Error ? error.message : error);
+            }
             if (name !== COOKIE_NAME)
                 setFrameworkSessionCookie(event, value);
             return { email, token: value };
@@ -1661,6 +1668,78 @@ async function createAutoDevAccountForSession(auth, db) {
     const result = await creationPromise;
     return result?.password ?? null;
 }
+function isHostedPreviewRequest(event) {
+    const host = getRequestHost(event)?.split(",")[0]?.trim().toLowerCase() ?? "";
+    return (host.endsWith(".agent-native.com") ||
+        host.endsWith(".builderio.xyz") ||
+        host.endsWith(".builderio.dev") ||
+        host.endsWith(".builder.codes") ||
+        host.endsWith(".builder.my") ||
+        host.includes("deploy-preview"));
+}
+export function isLocalDevAuthAllowed(event) {
+    const deployPreview = typeof isDeployPreview === "function" && isDeployPreview();
+    return (isDevEnvironment() &&
+        !deployPreview &&
+        !isAuthDisabled() &&
+        process.env.AGENT_NATIVE_DISABLE_AUTO_DEV_ACCOUNT !== "1" &&
+        !isHostedPreviewRequest(event) &&
+        isLoopbackRequest(event));
+}
+async function createOrReuseAutoDevSession(auth, config) {
+    let session = await createBetterAuthSessionForEmail(AUTO_DEV_ACCOUNT_EMAIL, config);
+    if (!session) {
+        session = await createBetterAuthSessionForEmail(LEGACY_AUTO_DEV_ACCOUNT_EMAIL, config);
+    }
+    if (session)
+        return { email: session.email, token: session.token };
+    const db = getDbExec();
+    const { rows: realUsers } = await db.execute({
+        sql: 'SELECT 1 FROM "user" WHERE email NOT IN (?, ?) LIMIT 1',
+        args: [AUTO_DEV_ACCOUNT_EMAIL, LEGACY_AUTO_DEV_ACCOUNT_EMAIL],
+    });
+    if (realUsers.length > 0)
+        return null;
+    const devPassword = await createAutoDevAccountForSession(auth, db);
+    if (!devPassword && !(await hasAutoDevAccountUser(db)))
+        return null;
+    session = await createBetterAuthSessionForEmail(AUTO_DEV_ACCOUNT_EMAIL, config);
+    if (!session) {
+        session = await createBetterAuthSessionForEmail(LEGACY_AUTO_DEV_ACCOUNT_EMAIL, config);
+    }
+    return session ? { email: session.email, token: session.token } : null;
+}
+function createLocalDevAuthHandler(config) {
+    return defineEventHandler(async (event) => {
+        if (getMethod(event) !== "POST") {
+            setResponseStatus(event, 405);
+            return { error: "Method not allowed" };
+        }
+        // This exact route is also allowed through createAuthGuardFn's public auth
+        // route branch. The state-changing handler still owns the full local gate.
+        if (!isLocalDevAuthAllowed(event)) {
+            setResponseStatus(event, 404);
+            return { error: "Not found" };
+        }
+        try {
+            const auth = await getBetterAuth(config);
+            const session = await createOrReuseAutoDevSession(auth, config);
+            if (!session) {
+                setResponseStatus(event, 404);
+                return { error: "Local development sign-in is unavailable" };
+            }
+            setFrameworkSessionCookie(event, session.token);
+            await addSession(session.token, session.email);
+            return authLoginResponse(event, session.token, session.email);
+        }
+        catch {
+            // The local convenience must fail closed without exposing adapter or
+            // generated credential details to the browser or terminal.
+            setResponseStatus(event, 503);
+            return { error: "Local development sign-in is unavailable" };
+        }
+    });
+}
 /**
  * Local-dev convenience: skip the sign-up wall on first run.
  *
@@ -2519,6 +2598,7 @@ async function mountBetterAuthRoutes(app, options) {
     const authLoginMode = typeof getAuthLoginMode === "function"
         ? await getAuthLoginMode()
         : "password";
+    app.use("/_agent-native/auth/local-dev", createLocalDevAuthHandler(betterAuthConfig));
     // Mount Better Auth catch-all handler at /_agent-native/auth/ba/*
     app.use("/_agent-native/auth/ba", defineEventHandler(async (event) => {
         const reqPath = event.url?.pathname ?? event.path ?? "";
@@ -3039,6 +3119,10 @@ async function mountBetterAuthRoutes(app, options) {
 // mountAuthFallbackRoutes — minimal auth endpoints when Better Auth init fails
 // ---------------------------------------------------------------------------
 function mountAuthFallbackRoutes(app) {
+    // Keep the local-dev action available when Better Auth initialization failed
+    // during boot. The handler retries Better Auth lazily and preserves the same
+    // production, preview, and loopback gates as the normal route set.
+    app.use("/_agent-native/auth/local-dev", createLocalDevAuthHandler());
     app.use("/_agent-native/auth/login", defineEventHandler(async (event) => {
         if (getMethod(event) !== "POST") {
             setResponseStatus(event, 405);

package/dist/server/better-auth-instance.d.ts

@@ -184,6 +184,9 @@ export interface BetterAuthInternalAdapter {
     }) => Promise<{
         id: string;
     }>;
+    createSession: (userId: string, dontRememberMe?: boolean) => Promise<{
+        token: string;
+    }>;
     createOAuthUser?: (user: {
         email: string;
         name: string;
@@ -221,6 +224,12 @@ export interface BetterAuthInternalAdapter {
  * shape is unexpected (older/newer Better Auth) so callers can fall back.
  */
 export declare function getBetterAuthInternalAdapter(config?: BetterAuthConfig): Promise<BetterAuthInternalAdapter | undefined>;
+/** Create a real Better Auth session for an existing user without credentials. */
+export declare function createBetterAuthSessionForEmail(email: string, config?: BetterAuthConfig): Promise<{
+    email: string;
+    token: string;
+    userId: string;
+} | null>;
 export interface GoogleAuthIdentity {
     email: string;
     accountId: string;

package/dist/server/better-auth-instance.js

@@ -24,6 +24,7 @@ import { acceptPendingInvitationsForEmail } from "../org/accept-pending.js";
 import { getAuthEmailForUserId, getRequiredAuthProviderForEmail, } from "../org/auth-policy.js";
 import { autoJoinDomainMatchingOrgs } from "../org/auto-join-domain.js";
 import { PASSWORD_MAX_LENGTH, PASSWORD_MIN_LENGTH, } from "../shared/password-policy.js";
+import { formatRuntimeConfigReport, getRuntimeConfigReport, } from "../shared/runtime-config.js";
 import { flushTracking, identify, track } from "../tracking/index.js";
 import { getAppProductionUrl } from "./app-url.js";
 import { readAnalyticsAnonymousId, signupAttributionFromCookieHeader, } from "./attribution.js";
@@ -113,17 +114,12 @@ function resolveAuthSecret() {
     // every deploy that hits it — both are serious enough to fail the boot loudly
     // so the deployer notices.
     if (process.env.NODE_ENV === "production") {
-        const sample = crypto.randomBytes(32).toString("hex");
-        throw new Error("[agent-native] BETTER_AUTH_SECRET is not set. This is required in production " +
-            "so signed session cookies stay valid across deploys. Set it as a deploy " +
-            "environment variable (any 32-byte hex string), e.g.:\n\n" +
-            `  BETTER_AUTH_SECRET=${sample}\n\n` +
-            "Generate your own with `openssl rand -hex 32`. If you already have a " +
-            "running deploy and need to preserve existing sessions, set it to your " +
-            "previously-deployed BETTER_AUTH_SECRET value first, then rotate to a " +
-            "fresh one. Hosted workspace deploys may also " +
-            "set A2A_SECRET; agent-native derives a per-purpose Better Auth secret " +
-            "from that workspace root secret.");
+        const report = getRuntimeConfigReport(process.env, { authEnabled: true, databaseRequired: false }, {
+            environment: "production",
+            phase: "runtime",
+            appName: process.env.APP_NAME,
+        });
+        throw new Error(formatRuntimeConfigReport(report));
     }
     // SECURITY (audit 09 LOW-2): the previous fallback chain
     // (`GOOGLE_CLIENT_SECRET || ACCESS_TOKEN || hardcoded`) reused
@@ -697,6 +693,7 @@ export async function getBetterAuthInternalAdapter(config) {
             typeof ia.findUserByEmail === "function" &&
             typeof ia.linkAccount === "function" &&
             typeof ia.createUser === "function" &&
+            typeof ia.createSession === "function" &&
             typeof ia.findAccountByProviderId === "function") {
             return {
                 ...ia,
@@ -709,6 +706,23 @@ export async function getBetterAuthInternalAdapter(config) {
     }
     return undefined;
 }
+/** Create a real Better Auth session for an existing user without credentials. */
+export async function createBetterAuthSessionForEmail(email, config) {
+    const adapter = await getBetterAuthInternalAdapter(config);
+    if (!adapter)
+        return null;
+    const existing = await adapter.findUserByEmail(email, {
+        includeAccounts: false,
+    });
+    if (!existing)
+        return null;
+    const session = await adapter.createSession(existing.user.id);
+    return {
+        email: existing.user.email,
+        token: session.token,
+        userId: existing.user.id,
+    };
+}
 /**
  * Ensure a verified Google identity has a canonical Better Auth user/account
  * before the legacy email-keyed session is issued. This prevents a later

package/dist/server/core-routes-plugin.d.ts

@@ -3,6 +3,7 @@ import { type DatabaseSchemaHealthResult } from "../db/runtime-diagnostics.js";
 import { type AuthSession } from "./auth.js";
 import { type BuilderConnectTrackingParams, type BuilderRelayCredentials } from "./builder-browser.js";
 import type { EnvKeyConfig } from "./create-server.js";
+import { type DbPressure } from "./db-pressure.js";
 /**
  * The base path prefix for all framework-level routes.
  * All agent-native core routes live under this namespace to avoid
@@ -91,6 +92,11 @@ export interface DbHealthProbeResult {
     };
     /** Optional metadata-only schema compatibility check. */
     schema?: DatabaseSchemaHealthResult;
+    /**
+     * Optional `pg_stat_activity` pressure counters. Present only when asked for,
+     * and shaped so "could not measure" cannot be read as "nothing wrong".
+     */
+    pressure?: DbPressure;
 }
 /**
  * Run a trivial `SELECT 1` to confirm the database is reachable and, as a side
@@ -106,6 +112,7 @@ export declare function runDbHealthProbe(exec?: () => {
     execute: (sql: string) => Promise<unknown>;
 }, options?: {
     schema?: boolean;
+    pressure?: boolean;
 }): Promise<DbHealthProbeResult>;
 interface BuilderWaitlistFormTarget {
     formId: string;

package/dist/server/core-routes-plugin.js

@@ -27,6 +27,7 @@ import { EMPTY_SPECULATION_RULES, resolveSsrCacheHeaders, } from "../shared/cach
 import { EMBED_TARGET_HEADER } from "../shared/embed-auth.js";
 import { llmConnectionTrackingProperties } from "../shared/llm-connection.js";
 import { EMBED_TRANSPLANT_HEADER, isMcpEmbedCorsOrigin, MCP_EMBED_CORS_ALLOW_HEADERS, shouldAllowMcpEmbedCredentials, } from "../shared/mcp-embed-headers.js";
+import { getRuntimeConfigReport } from "../shared/runtime-config.js";
 import { captureException } from "../tracking/error-capture.js";
 import { track } from "../tracking/index.js";
 import { registerBuiltinProviders } from "../tracking/providers.js";
@@ -41,6 +42,7 @@ import { BUILDER_CONNECT_PARAM, BUILDER_CONNECT_OWNER_COOKIE, BUILDER_ENV_KEYS,
 import { captureError, registerErrorCaptureProvider } from "./capture-error.js";
 import { getAllowedCorsOrigin, readCorsAllowedOrigins, } from "./cors-origins.js";
 import { canUseDeployCredentialFallbackForRequest, prefetchSecrets, readDeployCredentialEnv, resolveSecret, } from "./credential-provider.js";
+import { probeDbPressure } from "./db-pressure.js";
 import { resolveDeployEnvironment, resolveServerRelease, } from "./deploy-environment.js";
 import { createEmbedStartRouteHandler } from "./embed-route.js";
 import { shouldReportError } from "./error-noise-filter.js";
@@ -264,6 +266,7 @@ const DB_HEALTH_PROBE_DEADLINE_MS = 5_000;
 export async function runDbHealthProbe(exec = getDbExec, options = {}) {
     const startedAt = Date.now();
     let db = false;
+    let trivialQueryMs;
     let schema;
     const dbExec = exec();
     let dbTimedOut = false;
@@ -278,8 +281,10 @@ export async function runDbHealthProbe(exec = getDbExec, options = {}) {
             timer = setTimeout(() => reject(new Error("db probe deadline")), DB_HEALTH_PROBE_DEADLINE_MS);
         });
         try {
+            const trivialQueryStartedAt = Date.now();
             await Promise.race([dbExec.execute("SELECT 1"), deadline]);
             db = true;
+            trivialQueryMs = Date.now() - trivialQueryStartedAt;
         }
         finally {
             if (timer)
@@ -296,6 +301,14 @@ export async function runDbHealthProbe(exec = getDbExec, options = {}) {
         });
     }
     const database = getDatabaseRuntimeFingerprint();
+    // Measured on the connection `SELECT 1` just warmed, so the number reflects
+    // the database's own load rather than a serverless cold start.
+    let pressure;
+    if (options.pressure) {
+        pressure = db
+            ? await probeDbPressure(dbExec, database.dialect, { trivialQueryMs })
+            : { measured: false, reason: "database unreachable" };
+    }
     return {
         ok: true,
         ready: db && (!schema || schema.ok),
@@ -312,6 +325,7 @@ export async function runDbHealthProbe(exec = getDbExec, options = {}) {
             netlifyDatabaseUrlConfigured: database.netlifyDatabaseUrlConfigured,
         },
         ...(schema ? { schema } : {}),
+        ...(pressure ? { pressure } : {}),
     };
 }
 const DEFAULT_BUILDER_WAITLIST_FORM_ID = "DYTHuM0jlV";
@@ -809,7 +823,7 @@ export async function readLegacyCoreRouteInitSettings(readSetting = getSetting)
  * Routes:
  *   GET    /_agent-native/poll                          — polling endpoint for change detection
  *   GET    /_agent-native/events (or custom)            — SSE endpoint for real-time sync
- *   GET    /_agent-native/ping                          — health check
+ *   GET    /_agent-native/ping                          — health check; add ?configuration=1 for redacted deploy diagnostics
  *   GET    /_agent-native/health                        — DB liveness probe + scale-to-zero warmup
  *   GET    /_agent-native/env-status                    — env key configuration status (when envKeys provided)
  *   POST   /_agent-native/env-vars                      — compatibility route that saves keys to scoped DB secrets
@@ -1197,9 +1211,30 @@ export function createCoreRoutesPlugin(options = {}) {
             }
             // Ping
             if (!options.disablePing) {
-                getH3App(nitroApp).use(`${P}/ping`, defineEventHandler(() => ({
-                    message: process.env.PING_MESSAGE ?? "pong",
-                })));
+                getH3App(nitroApp).use(`${P}/ping`, defineEventHandler((event) => {
+                    const message = process.env.PING_MESSAGE ?? "pong";
+                    const configuration = event.url?.searchParams.get("configuration") === "1" ||
+                        event.url?.searchParams.get("configuration") === "true";
+                    if (!configuration)
+                        return { message };
+                    // Custom required keys must come from server-side app configuration;
+                    // never let an anonymous caller turn this into an env-name oracle.
+                    const requirements = {
+                        ...(event.url?.searchParams.get("auth") === "0"
+                            ? { authEnabled: false }
+                            : {}),
+                        ...(event.url?.searchParams.get("database") === "0"
+                            ? { databaseRequired: false }
+                            : {}),
+                    };
+                    return {
+                        message,
+                        configuration: getRuntimeConfigReport(process.env, requirements, {
+                            phase: "runtime",
+                            appName: process.env.APP_NAME,
+                        }),
+                    };
+                }));
             }
             // ─── Durable sandbox execution processor ─────────────────────────
             // Self-fired by run-code's background queue (see
@@ -1294,7 +1329,18 @@ export function createCoreRoutesPlugin(options = {}) {
                     const strict = event.url?.searchParams.get("strict") === "1" ||
                         event.url?.searchParams.get("strict") === "true" ||
                         process.env.AGENT_NATIVE_HEALTH_STRICT_SCHEMA === "true";
-                    const result = await runDbHealthProbe(getDbExec, { schema });
+                    // Off by default: the one-minute warm cron does not need it, and
+                    // an extra `pg_stat_activity` read every minute per app is waste.
+                    // Pressure deliberately does NOT change `ready` or the status
+                    // code — a pressured database is still serving, and an uptime
+                    // monitor that pages on it would learn to ignore this route. The
+                    // fleet audit reads the counters and decides.
+                    const pressure = event.url?.searchParams.get("pressure") === "1" ||
+                        event.url?.searchParams.get("pressure") === "true";
+                    const result = await runDbHealthProbe(getDbExec, {
+                        schema,
+                        pressure,
+                    });
                     if (strict && !result.ready)
                         setResponseStatus(event, 503);
                     return result;

package/dist/server/create-server.js

@@ -3,6 +3,7 @@ import { getOrgContext } from "../org/context.js";
 import { readBody } from "../server/h3-helpers.js";
 import { EMBED_TARGET_HEADER } from "../shared/embed-auth.js";
 import { EMBED_TRANSPLANT_HEADER, isMcpEmbedCorsOrigin, MCP_EMBED_CORS_ALLOW_HEADERS, shouldAllowMcpEmbedCredentials, } from "../shared/mcp-embed-headers.js";
+import { getRuntimeConfigReport } from "../shared/runtime-config.js";
 import { getSession } from "./auth.js";
 import { getAllowedCorsOrigin, readCorsAllowedOrigins, } from "./cors-origins.js";
 import { resolveSecret } from "./credential-provider.js";
@@ -107,9 +108,29 @@ export function createServer(options = {}) {
     const router = createRouter();
     // Health check
     if (!options.disablePing) {
-        router.get("/_agent-native/ping", defineEventHandler(() => {
+        router.get("/_agent-native/ping", defineEventHandler((event) => {
             const message = options.pingMessage ?? process.env.PING_MESSAGE ?? "pong";
-            return { message };
+            const configuration = event.url?.searchParams.get("configuration") === "1" ||
+                event.url?.searchParams.get("configuration") === "true";
+            if (!configuration)
+                return { message };
+            // Custom required keys must come from server-side app configuration;
+            // never let an anonymous caller turn this into an env-name oracle.
+            const requirements = {
+                ...(event.url?.searchParams.get("auth") === "0"
+                    ? { authEnabled: false }
+                    : {}),
+                ...(event.url?.searchParams.get("database") === "0"
+                    ? { databaseRequired: false }
+                    : {}),
+            };
+            return {
+                message,
+                configuration: getRuntimeConfigReport(process.env, requirements, {
+                    phase: "runtime",
+                    appName: process.env.APP_NAME,
+                }),
+            };
         }));
     }
     // Env key management routes