@agent-native/core 0.145.5 → 0.145.7

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

package/dist/server/db-pressure.d.ts

@@ -0,0 +1,38 @@
+/** Counters taken in one shot from `pg_stat_activity`. */
+export interface DbPressureCounters {
+    connections: number;
+    idleInTxn: number;
+    oldestIdleTxnS: number;
+    maxSameQuery: number;
+    /** Round-trip of this statement on an already-open connection. */
+    trivialQueryMs: number;
+}
+/**
+ * Measured counters, or an explicit reason they could not be taken.
+ *
+ * A monitor must never read "not measured" as "healthy", so the two are
+ * different shapes rather than an empty warning list.
+ */
+export type DbPressure = ({
+    measured: true;
+    warnings: string[];
+} & DbPressureCounters) | {
+    measured: false;
+    reason: string;
+};
+export declare const MAX_IDLE_TXN_AGE_S = 60;
+export declare const MAX_TRIVIAL_QUERY_MS = 1000;
+export declare const MAX_SAME_QUERY_CONCURRENCY = 10;
+export declare const DB_PRESSURE_SQL = "\nSELECT\n  count(*)::int AS connections,\n  count(*) FILTER (WHERE state = 'idle in transaction')::int AS idle_in_txn,\n  coalesce(round(max(extract(epoch from (now() - state_change)))\n    FILTER (WHERE state = 'idle in transaction'))::int, 0) AS oldest_idle_txn_s,\n  coalesce((\n    SELECT max(c) FROM (\n      SELECT count(*)::int AS c FROM pg_stat_activity\n      WHERE pid <> pg_backend_pid()\n        AND state = 'active'\n        AND query <> ''\n      GROUP BY left(query, 60)\n    ) q\n  ), 0)::int AS max_same_query\nFROM pg_stat_activity\nWHERE pid <> pg_backend_pid()";
+/** Reasons this database looks pressured, or [] when it looks fine. */
+export declare function dbPressureWarnings(p: DbPressureCounters): string[];
+/**
+ * Read the pressure counters. Postgres-only: `pg_stat_activity` does not exist
+ * on SQLite/libSQL/D1, and a dialect that cannot answer reports `measured:
+ * false` rather than a clean-looking zero.
+ */
+export declare function probeDbPressure(exec: {
+    execute: (sql: string) => Promise<unknown>;
+}, dialect: string, options?: {
+    trivialQueryMs?: number;
+}): Promise<DbPressure>;

package/dist/server/db-pressure.js

@@ -0,0 +1,147 @@
+// Database pressure — the three signals that precede an outage, measured from
+// inside the app that owns the database.
+//
+// The analytics app degraded for hours on 2026-08-06 before it fell over, and
+// every check we had said UP until the moment it said DOWN. What was actually
+// true, and visible in `pg_stat_activity` the whole time:
+//
+//   - 11-20 connections stuck `idle in transaction` up to 283s, left behind by
+//     serverless workers killed mid-transaction. They hold locks; nothing
+//     reaped them.
+//   - `SELECT 1` drifting from ~0.2s to 6s as those locks accumulated.
+//   - 47-56 concurrent copies of one unprojected query, each dragging a JSON
+//     blob per row.
+//
+// None of that is "down". All of it is the hour before down. A monitor that
+// only distinguishes 200 from 500 cannot see any of it.
+//
+// This lives in core rather than in a workstation script because the numbers
+// require a database credential, and the app already has its own. Reading them
+// here means the scheduled fleet audit needs no production credentials at all.
+// `scripts/chat-health.mjs` measures the same three signals locally against
+// every app at once; `db-pressure.spec.ts` pins the two threshold sets equal.
+// Thresholds set from that outage, not intuition. Healthy analytics reads
+// 0 / 128ms / 1; at the point it went down it read 20 / 6000ms / 56.
+export const MAX_IDLE_TXN_AGE_S = 60;
+export const MAX_TRIVIAL_QUERY_MS = 1_000;
+export const MAX_SAME_QUERY_CONCURRENCY = 10;
+/**
+ * A hung probe must not hang the health route — that is the defect that took
+ * the docs site permanently cold. Short because this runs on a connection the
+ * liveness probe just proved is answering.
+ */
+const PRESSURE_PROBE_DEADLINE_MS = 3_000;
+export const DB_PRESSURE_SQL = `
+SELECT
+  count(*)::int AS connections,
+  count(*) FILTER (WHERE state = 'idle in transaction')::int AS idle_in_txn,
+  coalesce(round(max(extract(epoch from (now() - state_change)))
+    FILTER (WHERE state = 'idle in transaction'))::int, 0) AS oldest_idle_txn_s,
+  coalesce((
+    SELECT max(c) FROM (
+      SELECT count(*)::int AS c FROM pg_stat_activity
+      WHERE pid <> pg_backend_pid()
+        AND state = 'active'
+        AND query <> ''
+      GROUP BY left(query, 60)
+    ) q
+  ), 0)::int AS max_same_query
+FROM pg_stat_activity
+WHERE pid <> pg_backend_pid()`;
+/** Reasons this database looks pressured, or [] when it looks fine. */
+export function dbPressureWarnings(p) {
+    const out = [];
+    if (p.idleInTxn > 0 && p.oldestIdleTxnS > MAX_IDLE_TXN_AGE_S) {
+        out.push(`${p.idleInTxn} idle-in-transaction (oldest ${p.oldestIdleTxnS}s) — workers killed mid-transaction still holding locks`);
+    }
+    if (p.trivialQueryMs > MAX_TRIVIAL_QUERY_MS) {
+        out.push(`trivial query took ${p.trivialQueryMs}ms — the database itself is slow, not the app`);
+    }
+    if (p.maxSameQuery >= MAX_SAME_QUERY_CONCURRENCY) {
+        out.push(`${p.maxSameQuery} concurrent copies of one query — a hot path is stampeding`);
+    }
+    return out;
+}
+function readCount(row, key) {
+    const value = row[key];
+    if (typeof value === "number" && Number.isFinite(value))
+        return value;
+    // Some drivers hand back bigint-ish columns as strings.
+    if (typeof value === "string" && value.trim() !== "") {
+        const parsed = Number(value);
+        if (Number.isFinite(parsed))
+            return parsed;
+    }
+    return null;
+}
+/**
+ * Read the pressure counters. Postgres-only: `pg_stat_activity` does not exist
+ * on SQLite/libSQL/D1, and a dialect that cannot answer reports `measured:
+ * false` rather than a clean-looking zero.
+ */
+export async function probeDbPressure(exec, dialect, options = {}) {
+    if (dialect !== "postgres") {
+        return {
+            measured: false,
+            reason: `dialect ${dialect} has no pg_stat_activity`,
+        };
+    }
+    let timer;
+    try {
+        const trivialQueryMs = options.trivialQueryMs ?? (await measureTrivialQuery(exec));
+        const deadline = new Promise((_, reject) => {
+            timer = setTimeout(() => reject(new Error("pressure probe deadline")), PRESSURE_PROBE_DEADLINE_MS);
+        });
+        const result = (await Promise.race([
+            exec.execute(DB_PRESSURE_SQL),
+            deadline,
+        ]));
+        const row = result?.rows?.[0];
+        if (!row) {
+            return { measured: false, reason: "pressure query returned no rows" };
+        }
+        const counters = {
+            connections: readCount(row, "connections") ?? -1,
+            idleInTxn: readCount(row, "idle_in_txn") ?? -1,
+            oldestIdleTxnS: readCount(row, "oldest_idle_txn_s") ?? -1,
+            maxSameQuery: readCount(row, "max_same_query") ?? -1,
+            trivialQueryMs,
+        };
+        if (Object.values(counters).some((n) => n < 0)) {
+            return {
+                measured: false,
+                reason: "pressure query returned unreadable counters",
+            };
+        }
+        return {
+            measured: true,
+            ...counters,
+            warnings: dbPressureWarnings(counters),
+        };
+    }
+    catch (err) {
+        return {
+            measured: false,
+            reason: err instanceof Error ? err.message : String(err),
+        };
+    }
+    finally {
+        if (timer)
+            clearTimeout(timer);
+    }
+}
+async function measureTrivialQuery(exec) {
+    let timer;
+    const startedAt = Date.now();
+    try {
+        const deadline = new Promise((_, reject) => {
+            timer = setTimeout(() => reject(new Error("trivial query deadline")), PRESSURE_PROBE_DEADLINE_MS);
+        });
+        await Promise.race([exec.execute("SELECT 1"), deadline]);
+        return Date.now() - startedAt;
+    }
+    finally {
+        if (timer)
+            clearTimeout(timer);
+    }
+}

package/dist/server/index.d.ts

@@ -37,6 +37,7 @@ export { configureAgentNativeEmbeddedEnvironment, createAgentNativeEmbeddedAuthO
 export { createThread, getThread, listThreads, updateThreadData, deleteThread, setThreadArchived, setThreadPinned, setThreadScope, type ChatThread, type ChatThreadScope, type ChatThreadSummary, type ListThreadsOptions, } from "../chat-threads/store.js";
 export { createResourcesPlugin, defaultResourcesPlugin, } from "./resources-plugin.js";
 export { createCoreRoutesPlugin, defaultCoreRoutesPlugin, FRAMEWORK_ROUTE_PREFIX, type CoreRoutesPluginOptions, } from "./core-routes-plugin.js";
+export { buildRuntimeConfigPrompt, formatRuntimeConfigReport, getRuntimeConfigReport, parseRuntimeConfigReport, runtimeConfigRequirementsFromSearchParams, type RuntimeConfigEnvironment, type RuntimeConfigIssue, type RuntimeConfigIssueCode, type RuntimeConfigIssueSeverity, type RuntimeConfigPhase, type RuntimeConfigReport, type RuntimeConfigRequirements, } from "../shared/runtime-config.js";
 export { AGENT_NATIVE_OG_IMAGE_CACHE_CONTROL, AGENT_NATIVE_OG_IMAGE_HEIGHT, AGENT_NATIVE_OG_IMAGE_NETLIFY_CACHE_CONTROL, AGENT_NATIVE_OG_IMAGE_WIDTH, agentNativeOgImageResponseHeaders, createAgentNativeOgImageHandler, renderAgentNativeOgImagePng, renderAgentNativeOgImageSvg, type AgentNativeOgImageInput, } from "./social-og-image.js";
 export { OG_FONT_FAMILY, resolveOgFontFiles } from "./og-fonts.js";
 export { createBrowserSessionActionEntries, type CreateBrowserSessionActionEntriesOptions, } from "../browser-sessions/actions.js";

package/dist/server/index.js

@@ -38,6 +38,7 @@ export { configureAgentNativeEmbeddedEnvironment, createAgentNativeEmbeddedAuthO
 export { createThread, getThread, listThreads, updateThreadData, deleteThread, setThreadArchived, setThreadPinned, setThreadScope, } from "../chat-threads/store.js";
 export { createResourcesPlugin, defaultResourcesPlugin, } from "./resources-plugin.js";
 export { createCoreRoutesPlugin, defaultCoreRoutesPlugin, FRAMEWORK_ROUTE_PREFIX, } from "./core-routes-plugin.js";
+export { buildRuntimeConfigPrompt, formatRuntimeConfigReport, getRuntimeConfigReport, parseRuntimeConfigReport, runtimeConfigRequirementsFromSearchParams, } from "../shared/runtime-config.js";
 export { AGENT_NATIVE_OG_IMAGE_CACHE_CONTROL, AGENT_NATIVE_OG_IMAGE_HEIGHT, AGENT_NATIVE_OG_IMAGE_NETLIFY_CACHE_CONTROL, AGENT_NATIVE_OG_IMAGE_WIDTH, agentNativeOgImageResponseHeaders, createAgentNativeOgImageHandler, renderAgentNativeOgImagePng, renderAgentNativeOgImageSvg, } from "./social-og-image.js";
 export { OG_FONT_FAMILY, resolveOgFontFiles } from "./og-fonts.js";
 export { createBrowserSessionActionEntries, } from "../browser-sessions/actions.js";

package/dist/server/legacy-auth-migration.d.ts

@@ -0,0 +1,10 @@
+/**
+ * Backfill the canonical Better Auth user for a verified legacy session.
+ *
+ * Older OAuth sessions were keyed by email in the framework `sessions` table
+ * before every deployment required a Better Auth `user` row. Keep the legacy
+ * session as the authentication proof, and use Better Auth's adapter only to
+ * create the missing canonical user. Do not invent a provider account: the
+ * next provider sign-in owns that link.
+ */
+export declare function ensureCanonicalUserForLegacySession(email: string): Promise<boolean>;

package/dist/server/legacy-auth-migration.js

@@ -0,0 +1,37 @@
+import { getBetterAuthInternalAdapter } from "./better-auth-instance.js";
+/**
+ * Backfill the canonical Better Auth user for a verified legacy session.
+ *
+ * Older OAuth sessions were keyed by email in the framework `sessions` table
+ * before every deployment required a Better Auth `user` row. Keep the legacy
+ * session as the authentication proof, and use Better Auth's adapter only to
+ * create the missing canonical user. Do not invent a provider account: the
+ * next provider sign-in owns that link.
+ */
+export async function ensureCanonicalUserForLegacySession(email) {
+    const normalizedEmail = email.trim().toLowerCase();
+    if (!normalizedEmail || !normalizedEmail.includes("@"))
+        return false;
+    const adapter = await getBetterAuthInternalAdapter();
+    if (!adapter) {
+        throw new Error("Better Auth internal adapter is unavailable");
+    }
+    const findExisting = () => adapter.findUserByEmail(normalizedEmail, { includeAccounts: false });
+    if (await findExisting())
+        return false;
+    try {
+        await adapter.createUser({
+            email: normalizedEmail,
+            name: normalizedEmail.split("@")[0] || "User",
+            emailVerified: true,
+        });
+        return true;
+    }
+    catch (error) {
+        // A concurrent request may have created the same canonical user. Treat
+        // that race as success only after the adapter can read the winner.
+        if (await findExisting())
+            return false;
+        throw error;
+    }
+}