@agent-native/core 0.122.4 → 0.123.0

package/dist/credentials/index.js

@@ -1,3 +1,4 @@
+import { getDbExec } from "../db/client.js";
 import { encryptSecretValue, decryptSecretValue, isEncryptedSecretValue, } from "../secrets/crypto.js";
 import { readAppSecret } from "../secrets/storage.js";
 import { getSetting, putSetting, deleteSetting } from "../settings/store.js";
@@ -68,8 +69,9 @@ export async function resolveCredentialForScope(key, ctx) {
  *   3. org-scoped app_secrets
  *   4. legacy workspace-scoped app_secrets for the org
  *   5. org-scoped legacy settings credential
+ *   6. solo workspace-scoped app_secrets (`solo:<email>`)
  *
- * Without an active org, step 3 is replaced by the solo workspace scope.
+ * Steps 3-5 are skipped without an active org.
  */
 export async function resolveCredential(key, ctx) {
     if (!ctx?.userEmail)
@@ -90,10 +92,117 @@ export async function resolveCredential(key, ctx) {
         const workspaceSecret = await readScopedAppSecret(key, "workspace", ctx.orgId);
         if (workspaceSecret)
             return workspaceSecret;
-        return resolveCredentialForScope(key, { ...ctx, scope: "org" });
+        const orgSetting = await resolveCredentialForScope(key, {
+            ...ctx,
+            scope: "org",
+        });
+        if (orgSetting)
+            return orgSetting;
     }
+    // Solo-workspace fallback: always checked, even when an org id was found
+    // above. A credential written before the user joined/created an org lives
+    // here, and must not become unreachable once that org exists. Last on
+    // purpose — a current org-scoped value always wins over a pre-org one.
     return readScopedAppSecret(key, "workspace", `solo:${ctx.userEmail}`);
 }
+/**
+ * Explain an empty credential lookup when a key of that name is saved in a
+ * scope the caller cannot read.
+ *
+ * Two distinct causes produce the same "the key is right there and it still
+ * says it's missing" report:
+ *
+ *  - Non-interactive runs — integration/webhook deliveries, scheduled jobs,
+ *    automations, and inbound A2A calls — resolve credentials as an owner
+ *    identity rather than as the person who triggered them, so a teammate's
+ *    Personal key is invisible to them even though the vault visibly holds it.
+ *  - The key is saved in a DIFFERENT organization the caller also belongs to.
+ *    Credentials are per-organization, so gaining a second organization (or
+ *    having `active-org-id` repointed at one) orphans every key synced under
+ *    the first. Without this, the only symptom is a missing-env-var error that
+ *    names the key rather than the org mismatch that actually caused it.
+ *
+ * SECURITY: both probes are bounded to organizations the caller is a member
+ * of, report only the scope kind (and, for the cross-org case, the name of an
+ * org the caller already belongs to), and never return the owning account, how
+ * many rows matched, or any part of the value. Without an active org there is
+ * no boundary to bound the probe to, so it declines to answer rather than
+ * revealing that some other tenant holds a key of the same name.
+ *
+ * Returns null when nothing safe and useful can be said.
+ */
+export async function describeCredentialScopeGap(keys, ctx) {
+    if (!ctx?.userEmail || !ctx.orgId)
+        return null;
+    for (const key of keys) {
+        if (await hasForeignPersonalCredentialInOrg(key, ctx)) {
+            return (`A "${key}" key is saved in this workspace with Personal scope. ` +
+                `Personal keys are readable only by their own owner's signed-in sessions, ` +
+                `and this run resolves credentials as the owner identity behind the ` +
+                `integration, job, or automation — so it needs "${key}" saved with ` +
+                `Workspace or Organization scope instead.`);
+        }
+        const holder = await findMemberOrgHoldingCredential(key, ctx);
+        if (holder) {
+            return (`A "${key}" key is saved in the ${holder} organization, but this ` +
+                `request resolved to a different organization you also belong to. ` +
+                `Credentials are scoped per organization and are not shared between ` +
+                `them, so this is an organization mismatch rather than a missing key. ` +
+                `Either switch your active organization back to ${holder}, or save ` +
+                `"${key}" in the organization this request runs in.`);
+        }
+    }
+    return null;
+}
+async function hasForeignPersonalCredentialInOrg(key, ctx) {
+    try {
+        const { rows } = await getDbExec().execute({
+            sql: `SELECT 1 FROM app_secrets s
+              JOIN org_members m ON LOWER(m.email) = LOWER(s.scope_id)
+             WHERE s.key = ? AND s.scope = 'user'
+               AND m.org_id = ? AND LOWER(s.scope_id) <> ?
+             LIMIT 1`,
+            args: [key, ctx.orgId, ctx.userEmail.toLowerCase()],
+        });
+        return rows.length > 0;
+    }
+    catch {
+        // Missing app_secrets/org_members table, or any other read failure — a
+        // diagnostic must never replace the real "not configured" error.
+        return false;
+    }
+}
+/**
+ * Name an organization the caller is a member of that holds this key, other
+ * than the one the request resolved to. Returns a quoted display name, or the
+ * bare word `another` when the org row is unreadable — never an org id, which
+ * would be useless to the person reading the error.
+ */
+async function findMemberOrgHoldingCredential(key, ctx) {
+    try {
+        const { rows } = await getDbExec().execute({
+            sql: `SELECT o.name AS org_name
+              FROM app_secrets s
+              JOIN org_members m ON m.org_id = s.scope_id
+                                AND LOWER(m.email) = ?
+              LEFT JOIN organizations o ON o.id = s.scope_id
+             WHERE s.key = ?
+               AND s.scope IN ('org', 'workspace')
+               AND s.scope_id <> ?
+             LIMIT 1`,
+            args: [ctx.userEmail.toLowerCase(), key, ctx.orgId],
+        });
+        if (rows.length === 0)
+            return null;
+        const name = rows[0].org_name;
+        return typeof name === "string" && name.trim()
+            ? `"${name.trim()}"`
+            : "another";
+    }
+    catch {
+        return null;
+    }
+}
 /**
  * Check if a credential is available for the given context.
  */

package/dist/credentials/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/credentials/index.ts"],"names":[],"mappings":"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","sourcesContent":["import {\n  encryptSecretValue,\n  decryptSecretValue,\n  isEncryptedSecretValue,\n} from \"../secrets/crypto.js\";\nimport { readAppSecret, type SecretRef } from \"../secrets/storage.js\";\nimport { getSetting, putSetting, deleteSetting } from \"../settings/store.js\";\n\nconst SETTING_PREFIX = \"credential:\";\n\nexport interface CredentialContext {\n  userEmail: string;\n  orgId?: string | null;\n}\n\nexport type CredentialStorageScope = \"user\" | \"org\";\n\nfunction userCredentialSettingKey(email: string, key: string): string {\n  return `u:${email.toLowerCase()}:${SETTING_PREFIX}${key}`;\n}\n\nfunction orgCredentialSettingKey(orgId: string, key: string): string {\n  return `o:${orgId}:${SETTING_PREFIX}${key}`;\n}\n\nasync function readCredentialSetting(\n  settingKey: string,\n): Promise<string | undefined> {\n  const setting = await getSetting(settingKey);\n  if (!setting || typeof setting.value !== \"string\") return undefined;\n  const stored = setting.value;\n  // Values written by saveCredential are AES-256-GCM encrypted at rest.\n  // Rows that predate encryption are plaintext — read them transparently\n  // (the migrate-encrypt-credentials script re-encrypts them in place).\n  if (!isEncryptedSecretValue(stored)) return stored;\n  try {\n    return decryptSecretValue(stored);\n  } catch {\n    // Key rotated, corrupt, or tampered row — treat as not set rather than\n    // surfacing ciphertext or throwing into every credential lookup.\n    return undefined;\n  }\n}\n\nasync function readScopedAppSecret(\n  key: string,\n  scope: SecretRef[\"scope\"],\n  scopeId: string,\n): Promise<string | undefined> {\n  try {\n    return (await readAppSecret({ key, scope, scopeId }))?.value;\n  } catch {\n    // Older databases may not have app_secrets yet. Keep the legacy\n    // credential store available while the table bootstraps.\n    return undefined;\n  }\n}\n\n/**\n * Resolve a credential from one explicit legacy SQL credential scope.\n *\n * Prefer `resolveCredential()` for normal app-local credential lookup. This\n * helper exists for workspace connection refs, where a ref can explicitly say\n * \"use the org-scoped key\" and must not accidentally read a user override.\n */\nexport async function resolveCredentialForScope(\n  key: string,\n  ctx: CredentialContext & { scope: CredentialStorageScope },\n): Promise<string | undefined> {\n  if (!ctx?.userEmail) return undefined;\n  if (ctx.scope === \"org\") {\n    if (!ctx.orgId) return undefined;\n    return readCredentialSetting(orgCredentialSettingKey(ctx.orgId, key));\n  }\n  return readCredentialSetting(userCredentialSettingKey(ctx.userEmail, key));\n}\n\n/**\n * Resolve a credential across the encrypted app_secrets store and the legacy\n * settings-backed credential store. User overrides win, followed by the\n * active org/workspace shared value.\n *\n * SECURITY: NEVER reads from process.env. Env vars are global to the\n * deployment and would leak across users in a multi-tenant app.\n *\n * Read order:\n *   1. user-scoped app_secrets\n *   2. user-scoped legacy settings credential\n *   3. org-scoped app_secrets\n *   4. legacy workspace-scoped app_secrets for the org\n *   5. org-scoped legacy settings credential\n *\n * Without an active org, step 3 is replaced by the solo workspace scope.\n */\nexport async function resolveCredential(\n  key: string,\n  ctx: CredentialContext,\n): Promise<string | undefined> {\n  if (!ctx?.userEmail) return undefined;\n\n  const userSecret = await readScopedAppSecret(key, \"user\", ctx.userEmail);\n  if (userSecret) return userSecret;\n\n  const userSetting = await resolveCredentialForScope(key, {\n    ...ctx,\n    scope: \"user\",\n  });\n  if (userSetting) return userSetting;\n\n  if (ctx.orgId) {\n    const orgSecret = await readScopedAppSecret(key, \"org\", ctx.orgId);\n    if (orgSecret) return orgSecret;\n\n    const workspaceSecret = await readScopedAppSecret(\n      key,\n      \"workspace\",\n      ctx.orgId,\n    );\n    if (workspaceSecret) return workspaceSecret;\n\n    return resolveCredentialForScope(key, { ...ctx, scope: \"org\" });\n  }\n\n  return readScopedAppSecret(key, \"workspace\", `solo:${ctx.userEmail}`);\n}\n\n/**\n * Check if a credential is available for the given context.\n */\nexport async function hasCredential(\n  key: string,\n  ctx: CredentialContext,\n): Promise<boolean> {\n  return (await resolveCredential(key, ctx)) !== undefined;\n}\n\n/**\n * Save a credential. By default writes to the per-user store; pass\n * `scope: \"org\"` to write to the active org's shared credentials.\n */\nexport async function saveCredential(\n  key: string,\n  value: string,\n  ctx: CredentialContext & { scope?: \"user\" | \"org\" },\n): Promise<void> {\n  if (!ctx?.userEmail) {\n    throw new Error(\"saveCredential requires CredentialContext with userEmail\");\n  }\n  // Encrypt at rest (AES-256-GCM) so a leaked DB backup / pg_dump / read\n  // replica doesn't expose plaintext keys. resolveCredential decrypts\n  // transparently on read.\n  const encrypted = encryptSecretValue(value);\n  if (ctx.scope === \"org\") {\n    if (!ctx.orgId) {\n      throw new Error(\"saveCredential scope='org' requires orgId\");\n    }\n    await putSetting(orgCredentialSettingKey(ctx.orgId, key), {\n      value: encrypted,\n    });\n    return;\n  }\n  await putSetting(userCredentialSettingKey(ctx.userEmail, key), {\n    value: encrypted,\n  });\n}\n\n/**\n * Delete a credential from the per-user (default) or per-org store.\n */\nexport async function deleteCredential(\n  key: string,\n  ctx: CredentialContext & { scope?: \"user\" | \"org\" },\n): Promise<void> {\n  if (!ctx?.userEmail) {\n    throw new Error(\n      \"deleteCredential requires CredentialContext with userEmail\",\n    );\n  }\n  if (ctx.scope === \"org\") {\n    if (!ctx.orgId) {\n      throw new Error(\"deleteCredential scope='org' requires orgId\");\n    }\n    await deleteSetting(orgCredentialSettingKey(ctx.orgId, key));\n    return;\n  }\n  await deleteSetting(userCredentialSettingKey(ctx.userEmail, key));\n}\n"]}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/credentials/index.ts"],"names":[],"mappings":"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","sourcesContent":["import { getDbExec } from \"../db/client.js\";\nimport {\n  encryptSecretValue,\n  decryptSecretValue,\n  isEncryptedSecretValue,\n} from \"../secrets/crypto.js\";\nimport { readAppSecret, type SecretRef } from \"../secrets/storage.js\";\nimport { getSetting, putSetting, deleteSetting } from \"../settings/store.js\";\n\nconst SETTING_PREFIX = \"credential:\";\n\nexport interface CredentialContext {\n  userEmail: string;\n  orgId?: string | null;\n}\n\nexport type CredentialStorageScope = \"user\" | \"org\";\n\nfunction userCredentialSettingKey(email: string, key: string): string {\n  return `u:${email.toLowerCase()}:${SETTING_PREFIX}${key}`;\n}\n\nfunction orgCredentialSettingKey(orgId: string, key: string): string {\n  return `o:${orgId}:${SETTING_PREFIX}${key}`;\n}\n\nasync function readCredentialSetting(\n  settingKey: string,\n): Promise<string | undefined> {\n  const setting = await getSetting(settingKey);\n  if (!setting || typeof setting.value !== \"string\") return undefined;\n  const stored = setting.value;\n  // Values written by saveCredential are AES-256-GCM encrypted at rest.\n  // Rows that predate encryption are plaintext — read them transparently\n  // (the migrate-encrypt-credentials script re-encrypts them in place).\n  if (!isEncryptedSecretValue(stored)) return stored;\n  try {\n    return decryptSecretValue(stored);\n  } catch {\n    // Key rotated, corrupt, or tampered row — treat as not set rather than\n    // surfacing ciphertext or throwing into every credential lookup.\n    return undefined;\n  }\n}\n\nasync function readScopedAppSecret(\n  key: string,\n  scope: SecretRef[\"scope\"],\n  scopeId: string,\n): Promise<string | undefined> {\n  try {\n    return (await readAppSecret({ key, scope, scopeId }))?.value;\n  } catch {\n    // Older databases may not have app_secrets yet. Keep the legacy\n    // credential store available while the table bootstraps.\n    return undefined;\n  }\n}\n\n/**\n * Resolve a credential from one explicit legacy SQL credential scope.\n *\n * Prefer `resolveCredential()` for normal app-local credential lookup. This\n * helper exists for workspace connection refs, where a ref can explicitly say\n * \"use the org-scoped key\" and must not accidentally read a user override.\n */\nexport async function resolveCredentialForScope(\n  key: string,\n  ctx: CredentialContext & { scope: CredentialStorageScope },\n): Promise<string | undefined> {\n  if (!ctx?.userEmail) return undefined;\n  if (ctx.scope === \"org\") {\n    if (!ctx.orgId) return undefined;\n    return readCredentialSetting(orgCredentialSettingKey(ctx.orgId, key));\n  }\n  return readCredentialSetting(userCredentialSettingKey(ctx.userEmail, key));\n}\n\n/**\n * Resolve a credential across the encrypted app_secrets store and the legacy\n * settings-backed credential store. User overrides win, followed by the\n * active org/workspace shared value.\n *\n * SECURITY: NEVER reads from process.env. Env vars are global to the\n * deployment and would leak across users in a multi-tenant app.\n *\n * Read order:\n *   1. user-scoped app_secrets\n *   2. user-scoped legacy settings credential\n *   3. org-scoped app_secrets\n *   4. legacy workspace-scoped app_secrets for the org\n *   5. org-scoped legacy settings credential\n *   6. solo workspace-scoped app_secrets (`solo:<email>`)\n *\n * Steps 3-5 are skipped without an active org.\n */\nexport async function resolveCredential(\n  key: string,\n  ctx: CredentialContext,\n): Promise<string | undefined> {\n  if (!ctx?.userEmail) return undefined;\n\n  const userSecret = await readScopedAppSecret(key, \"user\", ctx.userEmail);\n  if (userSecret) return userSecret;\n\n  const userSetting = await resolveCredentialForScope(key, {\n    ...ctx,\n    scope: \"user\",\n  });\n  if (userSetting) return userSetting;\n\n  if (ctx.orgId) {\n    const orgSecret = await readScopedAppSecret(key, \"org\", ctx.orgId);\n    if (orgSecret) return orgSecret;\n\n    const workspaceSecret = await readScopedAppSecret(\n      key,\n      \"workspace\",\n      ctx.orgId,\n    );\n    if (workspaceSecret) return workspaceSecret;\n\n    const orgSetting = await resolveCredentialForScope(key, {\n      ...ctx,\n      scope: \"org\",\n    });\n    if (orgSetting) return orgSetting;\n  }\n\n  // Solo-workspace fallback: always checked, even when an org id was found\n  // above. A credential written before the user joined/created an org lives\n  // here, and must not become unreachable once that org exists. Last on\n  // purpose — a current org-scoped value always wins over a pre-org one.\n  return readScopedAppSecret(key, \"workspace\", `solo:${ctx.userEmail}`);\n}\n\n/**\n * Explain an empty credential lookup when a key of that name is saved in a\n * scope the caller cannot read.\n *\n * Two distinct causes produce the same \"the key is right there and it still\n * says it's missing\" report:\n *\n *  - Non-interactive runs — integration/webhook deliveries, scheduled jobs,\n *    automations, and inbound A2A calls — resolve credentials as an owner\n *    identity rather than as the person who triggered them, so a teammate's\n *    Personal key is invisible to them even though the vault visibly holds it.\n *  - The key is saved in a DIFFERENT organization the caller also belongs to.\n *    Credentials are per-organization, so gaining a second organization (or\n *    having `active-org-id` repointed at one) orphans every key synced under\n *    the first. Without this, the only symptom is a missing-env-var error that\n *    names the key rather than the org mismatch that actually caused it.\n *\n * SECURITY: both probes are bounded to organizations the caller is a member\n * of, report only the scope kind (and, for the cross-org case, the name of an\n * org the caller already belongs to), and never return the owning account, how\n * many rows matched, or any part of the value. Without an active org there is\n * no boundary to bound the probe to, so it declines to answer rather than\n * revealing that some other tenant holds a key of the same name.\n *\n * Returns null when nothing safe and useful can be said.\n */\nexport async function describeCredentialScopeGap(\n  keys: readonly string[],\n  ctx: CredentialContext,\n): Promise<string | null> {\n  if (!ctx?.userEmail || !ctx.orgId) return null;\n\n  for (const key of keys) {\n    if (await hasForeignPersonalCredentialInOrg(key, ctx)) {\n      return (\n        `A \"${key}\" key is saved in this workspace with Personal scope. ` +\n        `Personal keys are readable only by their own owner's signed-in sessions, ` +\n        `and this run resolves credentials as the owner identity behind the ` +\n        `integration, job, or automation — so it needs \"${key}\" saved with ` +\n        `Workspace or Organization scope instead.`\n      );\n    }\n\n    const holder = await findMemberOrgHoldingCredential(key, ctx);\n    if (holder) {\n      return (\n        `A \"${key}\" key is saved in the ${holder} organization, but this ` +\n        `request resolved to a different organization you also belong to. ` +\n        `Credentials are scoped per organization and are not shared between ` +\n        `them, so this is an organization mismatch rather than a missing key. ` +\n        `Either switch your active organization back to ${holder}, or save ` +\n        `\"${key}\" in the organization this request runs in.`\n      );\n    }\n  }\n  return null;\n}\n\nasync function hasForeignPersonalCredentialInOrg(\n  key: string,\n  ctx: CredentialContext,\n): Promise<boolean> {\n  try {\n    const { rows } = await getDbExec().execute({\n      sql: `SELECT 1 FROM app_secrets s\n              JOIN org_members m ON LOWER(m.email) = LOWER(s.scope_id)\n             WHERE s.key = ? AND s.scope = 'user'\n               AND m.org_id = ? AND LOWER(s.scope_id) <> ?\n             LIMIT 1`,\n      args: [key, ctx.orgId!, ctx.userEmail.toLowerCase()],\n    });\n    return rows.length > 0;\n  } catch {\n    // Missing app_secrets/org_members table, or any other read failure — a\n    // diagnostic must never replace the real \"not configured\" error.\n    return false;\n  }\n}\n\n/**\n * Name an organization the caller is a member of that holds this key, other\n * than the one the request resolved to. Returns a quoted display name, or the\n * bare word `another` when the org row is unreadable — never an org id, which\n * would be useless to the person reading the error.\n */\nasync function findMemberOrgHoldingCredential(\n  key: string,\n  ctx: CredentialContext,\n): Promise<string | null> {\n  try {\n    const { rows } = await getDbExec().execute({\n      sql: `SELECT o.name AS org_name\n              FROM app_secrets s\n              JOIN org_members m ON m.org_id = s.scope_id\n                                AND LOWER(m.email) = ?\n              LEFT JOIN organizations o ON o.id = s.scope_id\n             WHERE s.key = ?\n               AND s.scope IN ('org', 'workspace')\n               AND s.scope_id <> ?\n             LIMIT 1`,\n      args: [ctx.userEmail.toLowerCase(), key, ctx.orgId!],\n    });\n    if (rows.length === 0) return null;\n    const name = (rows[0] as { org_name?: unknown }).org_name;\n    return typeof name === \"string\" && name.trim()\n      ? `\"${name.trim()}\"`\n      : \"another\";\n  } catch {\n    return null;\n  }\n}\n\n/**\n * Check if a credential is available for the given context.\n */\nexport async function hasCredential(\n  key: string,\n  ctx: CredentialContext,\n): Promise<boolean> {\n  return (await resolveCredential(key, ctx)) !== undefined;\n}\n\n/**\n * Save a credential. By default writes to the per-user store; pass\n * `scope: \"org\"` to write to the active org's shared credentials.\n */\nexport async function saveCredential(\n  key: string,\n  value: string,\n  ctx: CredentialContext & { scope?: \"user\" | \"org\" },\n): Promise<void> {\n  if (!ctx?.userEmail) {\n    throw new Error(\"saveCredential requires CredentialContext with userEmail\");\n  }\n  // Encrypt at rest (AES-256-GCM) so a leaked DB backup / pg_dump / read\n  // replica doesn't expose plaintext keys. resolveCredential decrypts\n  // transparently on read.\n  const encrypted = encryptSecretValue(value);\n  if (ctx.scope === \"org\") {\n    if (!ctx.orgId) {\n      throw new Error(\"saveCredential scope='org' requires orgId\");\n    }\n    await putSetting(orgCredentialSettingKey(ctx.orgId, key), {\n      value: encrypted,\n    });\n    return;\n  }\n  await putSetting(userCredentialSettingKey(ctx.userEmail, key), {\n    value: encrypted,\n  });\n}\n\n/**\n * Delete a credential from the per-user (default) or per-org store.\n */\nexport async function deleteCredential(\n  key: string,\n  ctx: CredentialContext & { scope?: \"user\" | \"org\" },\n): Promise<void> {\n  if (!ctx?.userEmail) {\n    throw new Error(\n      \"deleteCredential requires CredentialContext with userEmail\",\n    );\n  }\n  if (ctx.scope === \"org\") {\n    if (!ctx.orgId) {\n      throw new Error(\"deleteCredential scope='org' requires orgId\");\n    }\n    await deleteSetting(orgCredentialSettingKey(ctx.orgId, key));\n    return;\n  }\n  await deleteSetting(userCredentialSettingKey(ctx.userEmail, key));\n}\n"]}

package/dist/deploy/build.d.ts

@@ -75,8 +75,9 @@ export declare function findInstalledResvgPackages(nodeModulesRoots: string[]):
  * Reads the same env flag the runtime gate uses
  * (`AGENT_CHAT_DURABLE_BACKGROUND`).
  *
- * DEFAULT-OFF (opt-in), matching the runtime gate (`isFlagEnabled` in
- * durable-background.ts): unset/empty/unknown means DISABLED; an app opts IN
+ * DEFAULT-OFF (opt-in). It IS the runtime gate's flag parse
+ * (`isDurableBackgroundFlagEnabled`), so the two can no longer drift:
+ * unset/empty/unknown means DISABLED; an app opts IN
  * only with an explicit truthy value (`true`/`1`/`yes`/`on`). A premature
  * fleet-wide default-on caused real-user incidents (2026-06-24) before the
  * async worker path was proven, so durable is opt-in until verified live. This
@@ -87,7 +88,10 @@ export declare function findInstalledResvgPackages(nodeModulesRoots: string[]):
  * the worker into the ~13-min timeout regime, the worker would overshoot the
  * ~60s synchronous wall and re-dispatch in a loop. (The runtime now also guards
  * the ~13-min budget on the real function name via `isInBackgroundFunctionRuntime`,
- * so a missing emit degrades to clean 40s-chunked runs rather than the loop.)
+ * so a missing emit does not loop.) A missing emit is NOT benign, though: the
+ * app then runs every turn on the ~60s synchronous wall for the life of the
+ * deploy, so an opted-in build that cannot emit the function FAILS rather than
+ * warning.
  */
 export declare function isDurableBackgroundDeployEnabled(): boolean;
 export declare const NETLIFY_INTEGRATION_RECOVERY_FUNCTION_NAME = "server-integration-recovery";
@@ -162,6 +166,13 @@ export declare function emitSingleTemplateNetlifyKeepWarmFunction(projectCwd: st
  * inline 40s synchronous run (see production-agent.ts).
  */
 export declare function emitSingleTemplateNetlifyBackgroundFunction(projectCwd: string): void;
+/**
+ * Prove the artifact Netlify will scan actually landed. A partial copy (the
+ * entry without its handler bundle) deploys as a function that 500s on every
+ * invocation, which looks exactly like "no background function" at runtime.
+ * Exported so the workspace deploy asserts the same shape.
+ */
+export declare function assertEmittedBackgroundFunctionOnDisk(destDir: string, functionName: string): void;
 export declare function emitSingleTemplateNetlifyIntegrationRecoveryFunction(projectCwd: string): void;
 /**
  * Nitro receives the React Router SSR build as prebuilt chunks, so its normal

package/dist/deploy/build.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"build.d.ts","sourceRoot":"","sources":["../../src/deploy/build.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"build.d.ts","sourceRoot":"","sources":["../../src/deploy/build.ts"],"names":[],"mappings":"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"}

package/dist/deploy/build.js

@@ -17,7 +17,7 @@ import fs from "fs";
 import { createRequire } from "module";
 import path from "path";
 import { fileURLToPath } from "url";
-import { AGENT_BACKGROUND_FUNCTION_NAME, AGENT_BACKGROUND_PROCESSOR_A2A, AGENT_BACKGROUND_PROCESSOR_FIELD, AGENT_BACKGROUND_PROCESSOR_INTEGRATION, AGENT_BACKGROUND_PROCESSOR_ROUTE, AGENT_BACKGROUND_PROCESSOR_ROUTE_FIELD, AGENT_CHAT_PROCESS_RUN_PATH, } from "../agent/durable-background.js";
+import { AGENT_BACKGROUND_FUNCTION_NAME, AGENT_BACKGROUND_FUNCTION_URL_PATH, AGENT_BACKGROUND_PROCESSOR_A2A, AGENT_BACKGROUND_PROCESSOR_FIELD, AGENT_BACKGROUND_PROCESSOR_INTEGRATION, AGENT_BACKGROUND_PROCESSOR_ROUTE, AGENT_BACKGROUND_PROCESSOR_ROUTE_FIELD, AGENT_CHAT_PROCESS_RUN_PATH, isDurableBackgroundFlagEnabled, } from "../agent/durable-background.js";
 import { INTEGRATION_RETRY_SWEEP_PATH, INTEGRATION_RETRY_SWEEP_TOKEN_SUBJECT, isIntegrationDurableDispatchConfigured, } from "../integrations/integration-durable-dispatch-config.js";
 import { normalizeAppBasePath } from "../server/app-base-path.js";
 import { DEFAULT_SPECULATION_RULES_PATH, resolveSsrCacheHeaders, } from "../shared/cache-control.js";
@@ -1926,8 +1926,9 @@ export function findInstalledResvgPackages(nodeModulesRoots) {
  * Reads the same env flag the runtime gate uses
  * (`AGENT_CHAT_DURABLE_BACKGROUND`).
  *
- * DEFAULT-OFF (opt-in), matching the runtime gate (`isFlagEnabled` in
- * durable-background.ts): unset/empty/unknown means DISABLED; an app opts IN
+ * DEFAULT-OFF (opt-in). It IS the runtime gate's flag parse
+ * (`isDurableBackgroundFlagEnabled`), so the two can no longer drift:
+ * unset/empty/unknown means DISABLED; an app opts IN
  * only with an explicit truthy value (`true`/`1`/`yes`/`on`). A premature
  * fleet-wide default-on caused real-user incidents (2026-06-24) before the
  * async worker path was proven, so durable is opt-in until verified live. This
@@ -1938,14 +1939,21 @@ export function findInstalledResvgPackages(nodeModulesRoots) {
  * the worker into the ~13-min timeout regime, the worker would overshoot the
  * ~60s synchronous wall and re-dispatch in a loop. (The runtime now also guards
  * the ~13-min budget on the real function name via `isInBackgroundFunctionRuntime`,
- * so a missing emit degrades to clean 40s-chunked runs rather than the loop.)
+ * so a missing emit does not loop.) A missing emit is NOT benign, though: the
+ * app then runs every turn on the ~60s synchronous wall for the life of the
+ * deploy, so an opted-in build that cannot emit the function FAILS rather than
+ * warning.
  */
 export function isDurableBackgroundDeployEnabled() {
-    const raw = process.env.AGENT_CHAT_DURABLE_BACKGROUND;
-    if (raw == null)
-        return false;
-    const v = raw.trim().toLowerCase();
-    return v === "1" || v === "true" || v === "yes" || v === "on";
+    return isDurableBackgroundFlagEnabled();
+}
+/**
+ * True when this build MUST ship the `-background` function: either the chat
+ * opt-in or the integration durable dispatch depends on it at runtime.
+ */
+function isDurableBackgroundEmitRequired() {
+    return (isDurableBackgroundDeployEnabled() ||
+        isIntegrationDurableDispatchDeployEnabled());
 }
 export const NETLIFY_INTEGRATION_RECOVERY_FUNCTION_NAME = "server-integration-recovery";
 export function isIntegrationDurableDispatchDeployEnabled() {
@@ -1969,7 +1977,16 @@ export function emitSingleTemplateNetlifyKeepWarmFunction(projectCwd) {
     const dest = path.join(internalDir, NETLIFY_KEEP_WARM_FUNCTION_NAME);
     fs.rmSync(dest, { recursive: true, force: true });
     fs.mkdirSync(dest, { recursive: true });
+    // The background Lambda is a SEPARATE container from `server`: warming the
+    // health route never touches it, so it cold-started on essentially every
+    // dispatch (18.4s observed to reach the agent loop). A POST with no runId is
+    // rejected by the `_process-run` route before any DB work, so this only keeps
+    // the container alive.
+    const backgroundWarmPath = isDurableBackgroundEmitRequired()
+        ? JSON.stringify(AGENT_BACKGROUND_FUNCTION_URL_PATH)
+        : "null";
     const entry = `const HEALTH_PATH = "/_agent-native/health";
+const BACKGROUND_WARM_PATH = ${backgroundWarmPath};
 const REQUEST_TIMEOUT_MS = 25_000;
 
 function siteOrigin(request) {
@@ -1978,8 +1995,31 @@ function siteOrigin(request) {
   return new URL(request.url).origin;
 }
 
+async function warmBackgroundFunction(origin) {
+  if (!BACKGROUND_WARM_PATH) return;
+  const url = new URL(BACKGROUND_WARM_PATH, origin);
+  try {
+    // Best-effort: an unwarmed background function is a latency problem, not a
+    // reason to fail the scheduled run that also warms the server + database.
+    const response = await fetch(url, {
+      method: "POST",
+      headers: {
+        "content-type": "application/json",
+        "user-agent": "agent-native-netlify-keep-warm",
+      },
+      body: "{}",
+      signal: AbortSignal.timeout(REQUEST_TIMEOUT_MS),
+    });
+    console.log("[agent-native-keep-warm] Warmed", url.toString(), response.status);
+  } catch (error) {
+    console.warn("[agent-native-keep-warm] Background warm failed:", url.toString(), error);
+  }
+}
+
 export default async function handler(request) {
-  const url = new URL(HEALTH_PATH, siteOrigin(request));
+  const origin = siteOrigin(request);
+  const backgroundWarm = warmBackgroundFunction(origin);
+  const url = new URL(HEALTH_PATH, origin);
   let response;
   try {
     response = await fetch(url, {
@@ -2001,6 +2041,7 @@ export default async function handler(request) {
     );
   }
 
+  await backgroundWarm;
   console.log("[agent-native-keep-warm] Warmed", url.toString());
   return new Response(null, { status: 204 });
 }
@@ -2081,10 +2122,14 @@ export function emitSingleTemplateNetlifyBackgroundFunction(projectCwd) {
     const internalDir = path.join(projectCwd, ".netlify", "functions-internal");
     const serverDir = path.join(internalDir, "server");
     if (!fs.existsSync(path.join(serverDir, "main.mjs"))) {
-        // Nitro output layout differs from what we expected — skip rather than
-        // guess. The single-function deploy is unaffected.
-        console.warn("[build] Durable-background emit skipped: expected Nitro Netlify function " +
-            "at .netlify/functions-internal/server/main.mjs was not found.");
+        // Nitro output layout differs from what we expected — cannot guess.
+        const message = "Durable-background emit skipped: expected Nitro Netlify function " +
+            "at .netlify/functions-internal/server/main.mjs was not found.";
+        // Shipping without the function when the runtime depends on it is worse
+        // than a red build: the deploy silently loses the 15-min budget forever.
+        if (isDurableBackgroundEmitRequired())
+            throw new Error(`[build] ${message}`);
+        console.warn(`[build] ${message}`);
         return;
     }
     const backgroundName = AGENT_BACKGROUND_FUNCTION_NAME;
@@ -2215,6 +2260,7 @@ export const config = {
 };
 `;
     fs.writeFileSync(path.join(dest, `${backgroundName}.mjs`), entry);
+    assertEmittedBackgroundFunctionOnDisk(dest, backgroundName);
     console.log(`[build] Emitted durable-background function "${backgroundName}" into the ` +
         `scanned dir .netlify/functions-internal with config { background:true } ` +
         `and NO custom path — reachable at its default url ` +
@@ -2223,6 +2269,21 @@ export const config = {
         `verification of Netlify async (202) invocation — see ` +
         `docs/design/durable-agent-runs.md.`);
 }
+/**
+ * Prove the artifact Netlify will scan actually landed. A partial copy (the
+ * entry without its handler bundle) deploys as a function that 500s on every
+ * invocation, which looks exactly like "no background function" at runtime.
+ * Exported so the workspace deploy asserts the same shape.
+ */
+export function assertEmittedBackgroundFunctionOnDisk(destDir, functionName) {
+    const missing = [`${functionName}.mjs`, "main.mjs"].filter((file) => !fs.existsSync(path.join(destDir, file)));
+    if (missing.length === 0)
+        return;
+    throw new Error(`[build] Durable-background function "${functionName}" was not fully emitted — ` +
+        `missing ${missing.join(", ")} in ${destDir}. Netlify would deploy without ` +
+        "the 15-min background function and every agent turn would silently run on " +
+        "the synchronous function wall.");
+}
 export function emitSingleTemplateNetlifyIntegrationRecoveryFunction(projectCwd) {
     const internalDir = path.join(projectCwd, ".netlify", "functions-internal");
     const serverDir = path.join(internalDir, "server");
@@ -2494,8 +2555,7 @@ export function assertSingleTemplateNetlifyBuildOutput(projectCwd) {
     if (bundledVitestRuntime.length > 0) {
         failures.push(`Netlify server bundle contains Vitest test runtime code: ${bundledVitestRuntime.join(", ")}`);
     }
-    if (isDurableBackgroundDeployEnabled() ||
-        isIntegrationDurableDispatchDeployEnabled()) {
+    if (isDurableBackgroundEmitRequired()) {
         const backgroundDir = path.join(internalDir, AGENT_BACKGROUND_FUNCTION_NAME);
         const backgroundEntryPath = path.join(backgroundDir, `${AGENT_BACKGROUND_FUNCTION_NAME}.mjs`);
         if (!fs.existsSync(backgroundEntryPath)) {
@@ -3069,14 +3129,11 @@ export default bundle;
         // bundle, so the chat `_process-run` POST lands on Netlify's async (15-min)
         // function. When not opted in this is a no-op and the single-function
         // deploy is byte-for-byte unchanged.
-        if (isDurableBackgroundDeployEnabled() ||
-            isIntegrationDurableDispatchDeployEnabled()) {
-            try {
-                emitSingleTemplateNetlifyBackgroundFunction(cwd);
-            }
-            catch (err) {
-                console.warn("[build] Failed to emit durable-background Netlify function (non-fatal):", err instanceof Error ? err.message : err);
-            }
+        // NOT wrapped in try/catch: this block only runs when the runtime depends
+        // on the function, and a swallowed failure ships an app that loses the
+        // background budget for the life of the deploy with nothing in the log.
+        if (isDurableBackgroundEmitRequired()) {
+            emitSingleTemplateNetlifyBackgroundFunction(cwd);
         }
         if (isIntegrationDurableDispatchDeployEnabled()) {
             try {