@agent-native/core 0.132.2 → 0.133.0

package/corpus/core/src/agent/thread-data-builder.ts

@@ -1,4 +1,8 @@
 import type { ActionChatUIConfig } from "../action-ui.js";
+import {
+  formatChatErrorText,
+  normalizeChatError,
+} from "../client/error-format.js";
 import {
   isCredentialGapCodeAgentEvent,
   normalizeCodeAgentTranscript,
@@ -140,12 +144,29 @@ export function buildAssistantMessage(
     }
   };
 
+  // Index of the last event that is not a `clear`. Everything after it is a
+  // trailing run of clears with no successor chunk to re-emit what they wipe.
+  let lastNonClearIndex = events.length - 1;
+  while (
+    lastNonClearIndex >= 0 &&
+    events[lastNonClearIndex]?.event.type === "clear"
+  ) {
+    lastNonClearIndex -= 1;
+  }
+
   for (const [index, { event }] of events.entries()) {
     if (event.type === "clear") {
       // A live stream always follows `clear` with the chunk that re-emits the
       // wiped content. A rebuild has no successor, so applying a TRAILING
       // clear can only destroy the transcript permanently.
-      if (index === events.length - 1) continue;
+      //
+      // The whole trailing RUN has to be skipped, not just the final element:
+      // each failed engine attempt emits one `clear`, so three failed attempts
+      // in a row is the common shape, and skipping only the last still applied
+      // the other two. When the run made no tool calls that emptied `content`
+      // entirely and this builder returned null — the user's message was left
+      // with no assistant reply at all.
+      if (index > lastNonClearIndex) continue;
       clearAssistantDraftContent(content);
       continue;
     }
@@ -248,13 +269,24 @@ export function buildAssistantMessage(
       if (event.errorCode === "run_timeout" && event.recoverable) {
         continue;
       }
+      // Mirror the live client (client/sse-event-processor.ts): route the raw
+      // provider/engine string through the same friendly-copy layer before it
+      // ever becomes persisted chat text, and keep the raw text only in
+      // `details`. Without this, a rebuild (background run, reconnect, poller,
+      // webhook turn) dumps whatever the provider sent — a JSON error body, an
+      // SSL handshake failure — straight into the user-visible transcript.
+      const normalized = normalizeChatError(event.error, event.errorCode);
       runError = {
-        message: event.error,
+        message: normalized.message,
         ...(event.errorCode ? { errorCode: event.errorCode } : {}),
-        ...(event.details ? { details: event.details } : {}),
+        ...((event.details ?? normalized.details)
+          ? { details: event.details ?? normalized.details }
+          : {}),
         ...(event.recoverable ? { recoverable: event.recoverable } : {}),
       };
-      appendText(`${content.length > 0 ? "\n\n" : ""}Error: ${event.error}`);
+      appendText(
+        `${content.length > 0 ? "\n\n" : ""}${formatChatErrorText(event.error, event.upgradeUrl, event.errorCode)}`,
+      );
       continue;
     }
 

package/corpus/core/src/cli/templates-meta.ts

@@ -254,6 +254,19 @@ export const TEMPLATES: TemplateMeta[] = [
     hidden: true,
     defaultMode: "dev",
   },
+  {
+    name: "factory",
+    label: "Factory",
+    hint: "Build agent factories with gates you control",
+    icon: "Users",
+    color: "#7C3AED",
+    colorRgb: "124 58 237",
+    devPort: 8108,
+    prodUrl: "https://agent-native-factory.netlify.app",
+    hidden: true,
+    defaultMode: "dev",
+    core: false,
+  },
 ];
 
 /** Return templates visible in user-facing pickers (excludes hidden). */

package/corpus/core/src/cli/workspace-dev.ts

@@ -712,6 +712,7 @@ export async function runWorkspaceDev(
         name: workspaceApp.name,
         description: workspaceApp.description,
         path: `/${workspaceApp.id}`,
+        port: workspaceApp.port,
         audience: workspaceApp.audience,
         publicPaths: workspaceApp.publicPaths,
         protectedPaths: workspaceApp.protectedPaths,

package/corpus/core/src/client/error-format.ts

@@ -95,6 +95,7 @@ function isProviderAuthenticationError(
     /\b(?:http\s*)?401\b.*\b(?:status|unauthorized|authentication|auth|no body)\b/i.test(
       text,
     ) ||
+    lower.includes("missing authentication header") ||
     lower.includes("invalid x-api-key") ||
     lower.includes("invalid api key") ||
     lower.includes("incorrect api key") ||
@@ -141,6 +142,17 @@ export function normalizeChatError(
     };
   }
 
+  // A model/parameter combination this provider will never accept. Retrying is
+  // pointless and the raw sentence names an API surface the reader has no way
+  // to act on, so say what they can actually change.
+  if (code === "provider_config_error") {
+    return {
+      message:
+        "This model can't use tools with the current settings. Switch models in Settings, then retry.",
+      details: text,
+    };
+  }
+
   if (isProviderRateLimit(text, errorCode)) {
     return {
       message:

package/corpus/core/src/credentials/index.ts

@@ -5,6 +5,7 @@ import {
   isEncryptedSecretValue,
 } from "../secrets/crypto.js";
 import { readAppSecret, type SecretRef } from "../secrets/storage.js";
+import { assertCredentialStoreReadable } from "../server/credential-provider.js";
 import { getSetting, putSetting, deleteSetting } from "../settings/store.js";
 
 const SETTING_PREFIX = "credential:";
@@ -76,6 +77,33 @@ export async function resolveCredentialForScope(
   return readCredentialSetting(userCredentialSettingKey(ctx.userEmail, key));
 }
 
+/**
+ * `ctx.orgId` when the caller supplied one, otherwise the org resolved from
+ * `ctx.userEmail`'s membership. Interactive requests always supply `orgId`
+ * (session/`getOrgContext` backfill it); CLI runs, cron jobs, and any other
+ * caller built straight from `getCredentialContext()` outside a request event
+ * do not, and previously fell through as "no active org" — invisibly skipping
+ * every org-scoped credential a signed-in session could see. Mirrors the
+ * fallback already proven in `resolveSecretDetailed`
+ * (server/credential-provider.ts).
+ */
+async function resolveEffectiveOrgId(
+  ctx: CredentialContext,
+): Promise<{ orgId: string | null; lookupFailed: boolean; cause?: unknown }> {
+  if (ctx.orgId) return { orgId: ctx.orgId, lookupFailed: false };
+  try {
+    const { resolveOrgIdForEmail } = await import("../org/context.js");
+    return {
+      orgId: await resolveOrgIdForEmail(ctx.userEmail),
+      lookupFailed: false,
+    };
+  } catch (cause) {
+    // Membership was unreadable, not merely absent — must not collapse to
+    // "caller has no org", which would silently hide every org-scoped row.
+    return { orgId: null, lookupFailed: true, cause };
+  }
+}
+
 /**
  * Resolve a credential across the encrypted app_secrets store and the legacy
  * settings-backed credential store. User overrides win, followed by the
@@ -92,7 +120,12 @@ export async function resolveCredentialForScope(
  *   5. org-scoped legacy settings credential
  *   6. solo workspace-scoped app_secrets (`solo:<email>`)
  *
- * Steps 3-5 are skipped without an active org.
+ * Steps 3-5 use `ctx.orgId` when given, else the org resolved from
+ * `ctx.userEmail` (see `resolveEffectiveOrgId`), and are skipped only when the
+ * caller truly has no org. A membership lookup that could not be read throws
+ * `CredentialStoreUnavailableError` instead of silently reporting the
+ * credential as unset — "the store didn't answer" and "nothing is saved" are
+ * different outcomes callers must not conflate.
  */
 export async function resolveCredential(
   key: string,
@@ -109,19 +142,20 @@ export async function resolveCredential(
   });
   if (userSetting) return userSetting;
 
-  if (ctx.orgId) {
-    const orgSecret = await readScopedAppSecret(key, "org", ctx.orgId);
+  const orgLookup = await resolveEffectiveOrgId(ctx);
+  assertCredentialStoreReadable(orgLookup);
+  const { orgId } = orgLookup;
+
+  if (orgId) {
+    const orgSecret = await readScopedAppSecret(key, "org", orgId);
     if (orgSecret) return orgSecret;
 
-    const workspaceSecret = await readScopedAppSecret(
-      key,
-      "workspace",
-      ctx.orgId,
-    );
+    const workspaceSecret = await readScopedAppSecret(key, "workspace", orgId);
     if (workspaceSecret) return workspaceSecret;
 
     const orgSetting = await resolveCredentialForScope(key, {
       ...ctx,
+      orgId,
       scope: "org",
     });
     if (orgSetting) return orgSetting;
@@ -156,7 +190,9 @@ export async function resolveCredential(
  * 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.
+ * revealing that some other tenant holds a key of the same name — this
+ * includes callers whose `ctx.orgId` is unset AND whose org could not be
+ * resolved from `ctx.userEmail` (see `resolveEffectiveOrgId`).
  *
  * Returns null when nothing safe and useful can be said.
  */
@@ -164,10 +200,13 @@ export async function describeCredentialScopeGap(
   keys: readonly string[],
   ctx: CredentialContext,
 ): Promise<string | null> {
-  if (!ctx?.userEmail || !ctx.orgId) return null;
+  if (!ctx?.userEmail) return null;
+  const orgLookup = await resolveEffectiveOrgId(ctx);
+  if (orgLookup.lookupFailed || !orgLookup.orgId) return null;
+  const scopedCtx: CredentialContext = { ...ctx, orgId: orgLookup.orgId };
 
   for (const key of keys) {
-    if (await hasForeignPersonalCredentialInOrg(key, ctx)) {
+    if (await hasForeignPersonalCredentialInOrg(key, scopedCtx)) {
       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, ` +
@@ -177,7 +216,7 @@ export async function describeCredentialScopeGap(
       );
     }
 
-    const holder = await findMemberOrgHoldingCredential(key, ctx);
+    const holder = await findMemberOrgHoldingCredential(key, scopedCtx);
     if (holder) {
       return (
         `A "${key}" key is saved in the ${holder} organization, but this ` +

package/corpus/core/src/extensions/url-safety.ts

@@ -167,6 +167,21 @@ function normalizeLookupHostname(hostname: string): string {
   return hostname.toLowerCase().replace(/^\[|\]$/g, "");
 }
 
+function loopbackHostnameVariants(hostname: string): string[] {
+  const normalized = normalizeLookupHostname(hostname);
+  if (
+    normalized !== "localhost" &&
+    normalized !== "127.0.0.1" &&
+    normalized !== "::1"
+  ) {
+    return [normalized];
+  }
+  // Local workspace manifests can identify the same child server as
+  // localhost, 127.0.0.1, or ::1. They are equivalent only for loopback; do
+  // not alias arbitrary private or public hostnames.
+  return ["localhost", "127.0.0.1", "::1"];
+}
+
 function normalizeAllowedPrivateOriginKeys(
   origins: readonly string[],
 ): Set<string> {
@@ -178,7 +193,30 @@ function normalizeAllowedPrivateOriginKeys(
         continue;
       }
       const port = parsed.port || (parsed.protocol === "https:" ? "443" : "80");
-      keys.add(`${normalizeLookupHostname(parsed.hostname)}:${port}`);
+      for (const hostname of loopbackHostnameVariants(parsed.hostname)) {
+        keys.add(`${hostname}:${port}`);
+      }
+    } catch {
+      // coercion-ok: malformed deployment configuration is omitted, preserving the fail-closed private-IP guard.
+    }
+  }
+  return keys;
+}
+
+function normalizeAllowedPrivateOriginOriginKeys(
+  origins: readonly string[],
+): Set<string> {
+  const keys = new Set<string>();
+  for (const origin of origins) {
+    try {
+      const parsed = new URL(origin);
+      if (parsed.protocol !== "http:" && parsed.protocol !== "https:") {
+        continue;
+      }
+      const port = parsed.port || (parsed.protocol === "https:" ? "443" : "80");
+      for (const hostname of loopbackHostnameVariants(parsed.hostname)) {
+        keys.add(`${parsed.protocol}//${hostname}:${port}`);
+      }
     } catch {
       // Ignore malformed deployment configuration and retain the private-IP guard.
     }
@@ -309,21 +347,17 @@ export async function ssrfSafeFetch(
   const dispatcher =
     (await createSsrfSafeDispatcher(options.allowedPrivateOrigins)) ??
     undefined;
-  const allowedPrivateOrigins = new Set(
-    (options.allowedPrivateOrigins ?? [])
-      .map((origin) => {
-        try {
-          return new URL(origin).origin;
-        } catch {
-          return "";
-        }
-      })
-      .filter(Boolean),
+  const allowedPrivateOrigins = normalizeAllowedPrivateOriginOriginKeys(
+    options.allowedPrivateOrigins ?? [],
   );
   const isAllowedPrivateOrigin = (candidate: string): boolean => {
     if (allowedPrivateOrigins.size === 0) return false;
     try {
-      return allowedPrivateOrigins.has(new URL(candidate).origin);
+      const parsed = new URL(candidate);
+      const port = parsed.port || (parsed.protocol === "https:" ? "443" : "80");
+      return allowedPrivateOrigins.has(
+        `${parsed.protocol}//${normalizeLookupHostname(parsed.hostname)}:${port}`,
+      );
     } catch {
       return false;
     }

package/corpus/core/src/integrations/adapters/slack.ts

@@ -11,7 +11,7 @@ import { consumeIntegrationAwaitingInput } from "../awaiting-input-store.js";
 import { createIntegrationControl } from "../controls-store.js";
 import {
   getActiveIntegrationInstallationByKey,
-  getActiveIntegrationInstallationForTenant,
+  listActiveIntegrationInstallationsForTenant,
   listIntegrationInstallations,
   resolveIntegrationTokenBundle,
 } from "../installations-store.js";
@@ -666,13 +666,18 @@ export function slackAdapter(
           channelId: target.destination,
           threadTs: target.threadRef,
           teamId: target.tenantId,
+          installationKey: target.installationKey,
         },
         tenantId: target.tenantId,
         timestamp: Date.now(),
       };
       const token = await resolveBotToken(targetContext);
       if (!token) {
-        console.error("[slack] SLACK_BOT_TOKEN not configured");
+        console.error(
+          "[slack] no bot token for outbound target" +
+            (target.tenantId ? ` (tenant ${target.tenantId})` : "") +
+            "; set SLACK_BOT_TOKEN or pass installationKey to name the app",
+        );
         return;
       }
 
@@ -808,25 +813,42 @@ async function resolveManagedSlackBotToken(
     typeof incoming.platformContext.enterpriseId === "string"
       ? incoming.platformContext.enterpriseId
       : undefined;
+  const installationKeyHint =
+    typeof incoming.platformContext.installationKey === "string"
+      ? incoming.platformContext.installationKey
+      : undefined;
   if (!teamId && !enterpriseId) return undefined;
   try {
-    let installation = apiAppId
+    let installation = installationKeyHint
       ? await getActiveIntegrationInstallationByKey(
           "slack",
-          slackInstallationKey({ teamId, enterpriseId, apiAppId }),
+          installationKeyHint,
         )
       : null;
-    if (!installation && !apiAppId && teamId) {
-      installation = await getActiveIntegrationInstallationForTenant(
+    if (!installation && apiAppId) {
+      installation = await getActiveIntegrationInstallationByKey(
         "slack",
-        teamId,
+        slackInstallationKey({ teamId, enterpriseId, apiAppId }),
       );
     }
-    if (!installation && !apiAppId && enterpriseId) {
-      installation = await getActiveIntegrationInstallationForTenant(
+    if (!installation && !apiAppId) {
+      // Without an app id the tenant can match several connected Slack apps.
+      // Sending as an arbitrary one posts under the wrong bot identity, so
+      // only proceed when the tenant resolves to exactly one installation.
+      const tenant = teamId ?? enterpriseId!;
+      const candidates = await listActiveIntegrationInstallationsForTenant(
         "slack",
-        enterpriseId,
+        tenant,
       );
+      if (candidates.length > 1) {
+        console.error(
+          `[slack] ${candidates.length} connected Slack apps for tenant ${tenant}; ` +
+            `cannot choose one without an app id. Pass installationKey on the outbound target. ` +
+            `Candidates: ${candidates.map((c) => c.installationKey).join(", ")}`,
+        );
+        return undefined;
+      }
+      installation = candidates[0] ?? null;
     }
     const key =
       installation?.installationKey ??

package/corpus/core/src/integrations/google-docs-poller.ts

@@ -1,3 +1,4 @@
+import { isInBackgroundFunctionRuntime } from "../agent/durable-background.js";
 import { createAnthropicEngine } from "../agent/engine/index.js";
 import type { EngineMessage } from "../agent/engine/types.js";
 import {
@@ -518,7 +519,17 @@ async function processComment(
               signal,
             },
             undefined,
-            { useHostedDefault: true },
+            // Same omission the scheduled-job runner had: without this, a
+            // poller-driven reply inherits the interactive clamp (40s soft
+            // timeout, a no-progress backstop at 0.75x that, 6 continuations)
+            // even though no client is waiting on a response. Uses the runtime
+            // check rather than a hardcoded `true` — matching webhook-handler.ts
+            // in this same subsystem — because unlike the job runner there is no
+            // hard-abort cap here to bound a wider ceiling.
+            {
+              useHostedDefault: true,
+              backgroundFunction: isInBackgroundFunctionRuntime(),
+            },
           ),
       );
     },

package/corpus/core/src/integrations/installations-store.ts

@@ -675,3 +675,33 @@ export async function getActiveIntegrationInstallationForTenant(
     ? toSafeInstallation(rowToRaw(rows[0] as Record<string, unknown>))
     : null;
 }
+
+/**
+ * Every connected installation for a tenant, newest first.
+ *
+ * A workspace can legitimately have several apps of the same platform
+ * connected at once (e.g. a product-specific Slack app alongside a generic
+ * one). Callers that cannot name an app id must see that ambiguity rather
+ * than receive an arbitrary winner — picking the most recently updated row
+ * silently sends as whichever app happened to reconnect last.
+ */
+export async function listActiveIntegrationInstallationsForTenant(
+  platform: string,
+  tenantId: string,
+): Promise<IntegrationInstallation[]> {
+  await ensureTable();
+  const { rows } = await getDbExec().execute({
+    sql: `SELECT * FROM ${TABLE}
+      WHERE platform = ? AND (team_id = ? OR enterprise_id = ?)
+        AND status = 'connected'
+      ORDER BY updated_at DESC`,
+    args: [
+      normalizePlatform(platform),
+      required(tenantId, "tenantId"),
+      required(tenantId, "tenantId"),
+    ],
+  });
+  return rows.map((row) =>
+    toSafeInstallation(rowToRaw(row as Record<string, unknown>)),
+  );
+}

package/corpus/core/src/integrations/plugin.ts

@@ -93,7 +93,6 @@ import {
   INTEGRATION_RETRY_SWEEP_TOKEN_SUBJECT,
   integrationDispatchScopeValue,
   isInIntegrationRecoveryRuntime,
-  isIntegrationDurableDispatchConfigured,
   isIntegrationDurableDispatchEnabledForTask,
 } from "./integration-durable-dispatch.js";
 import {
@@ -1787,15 +1786,16 @@ export function createIntegrationsPlugin(
           setResponseStatus(event, 401);
           return { error: "Invalid or expired internal token" };
         }
-        if (!isIntegrationDurableDispatchConfigured()) {
-          return { ok: true, disabled: true };
-        }
         const webhookBaseUrl = getBaseUrl(event);
         const [pendingTasks, campaigns, a2aContinuations] = await Promise.all([
+          // Portable (fire-and-forget) dispatch loses tasks whenever the
+          // self-dispatch POST dies with the container, and the in-process
+          // retry interval does not survive a serverless freeze. Sweeping only
+          // durable scopes left those deployments with no recovery at all, so
+          // the queue is swept regardless of dispatch mode.
           retryStuckPendingTasks({
             webhookBaseUrl,
             limit: 20,
-            durableOnly: true,
           }).catch((error) => {
             console.error(
               "[integrations] Pending-task recovery failed:",

package/corpus/core/src/integrations/types.ts

@@ -163,6 +163,13 @@ export interface OutboundTarget {
   tenantId?: string;
   /** Managed installation id when the caller already resolved it. */
   installationId?: string;
+  /**
+   * Provider installation key identifying which connected app to send as.
+   * Required when a tenant has more than one app of the same platform
+   * connected — without it the adapter cannot tell them apart and refuses to
+   * guess rather than posting under the wrong bot identity.
+   */
+  installationKey?: string;
 }
 
 /**

package/corpus/core/src/integrations/webhook-handler.ts

@@ -606,7 +606,7 @@ async function enqueueAndDispatch(
         ),
       )
     : PROCESSOR_DISPATCH_SETTLE_WAIT_MS;
-  await dispatchPendingIntegrationTask({
+  const outcome = await dispatchPendingIntegrationTask({
     taskId,
     task: {
       platform: incoming.platform,
@@ -617,6 +617,29 @@ async function enqueueAndDispatch(
     baseUrl,
     portableSettleMs: settleWaitMs,
   });
+
+  // A definitive dispatch failure leaves a queued task nobody is running while
+  // the placeholder above already told the user work had started. Say so
+  // instead of leaving that indicator spinning until the sweep — if it runs.
+  if (outcome === "failed") {
+    console.error(
+      `[integrations] dispatch failed for task ${taskId} (${incoming.platform}/${incoming.externalThreadId})`,
+    );
+    try {
+      await options.adapter.sendResponse(
+        {
+          text: "I couldn't start working on that — the request was accepted but never handed off. Please try again.",
+          platformContext: incoming.platformContext,
+        },
+        incoming,
+      );
+    } catch (err) {
+      console.error(
+        "[integrations] failed to report dispatch failure to user:",
+        err,
+      );
+    }
+  }
 }
 
 /**

package/corpus/core/src/jobs/background-automation-runner.ts

@@ -15,6 +15,7 @@ import {
 } from "../agent/production-agent.js";
 import { runAgentLoopDirectWithSoftTimeout } from "../agent/run-loop-with-resume.js";
 import { resolveRunSoftTimeoutMs, startRun } from "../agent/run-manager.js";
+import { claimBackgroundRun, insertRun } from "../agent/run-store.js";
 import { attachToolSearch } from "../agent/tool-search.js";
 import {
   resolveAutomationExecutionIdentity,
@@ -290,8 +291,23 @@ export async function runBackgroundAutomation(
       const systemPrompt = await deps.getSystemPrompt(ownerEmail);
       const thread = await createThread(ownerEmail, { title: threadTitle });
       const runId = createRunId(options.runIdPrefix);
+      // Scheduled work is background work: it has no synchronous serverless
+      // caller waiting on it, so it must not inherit the interactive clamp
+      // (40s soft timeout, a 30s no-progress backstop at 0.75x that, and 6
+      // continuations). A dashboard render or digest legitimately spends
+      // minutes across many tool calls, and dies the first time any gap
+      // between two of them exceeds 30s — recorded as `no_progress` after
+      // several minutes of real work, because the backstop is suspended
+      // while a tool is in flight but not between tools.
+      //
+      // Hardcoded rather than `isInBackgroundFunctionRuntime()` (what
+      // webhook-handler.ts uses): a webhook can arrive on either runtime, but
+      // a scheduler tick never serves a synchronous request, so the
+      // interactive clamp never applies to it. The wider soft ceiling stays
+      // bounded by this runner's own BACKGROUND_RUN_HARD_TIMEOUT_MS abort.
       const softTimeoutMs = resolveRunSoftTimeoutMs(undefined, {
         useHostedDefault: true,
+        backgroundFunction: true,
       });
 
       const usageRef: {
@@ -300,6 +316,26 @@ export async function runBackgroundAutomation(
       let responseText = "";
       let hardAbortTimer: ReturnType<typeof setTimeout> | null = null;
 
+      // This runner executes in-process, synchronously — there is no HTTP
+      // self-dispatch to a separate worker. Self-claim the row into
+      // 'background-processing' right away, exactly like a genuine HTTP
+      // background worker does immediately after its own insert (see
+      // production-agent.ts's `claimBackgroundWorkerRunEarly`). Without this,
+      // the row sits at dispatch_mode='background' for its whole life with no
+      // worker ever claiming it, which is indistinguishable from a lost HTTP
+      // handoff to the unclaimed-background-run sweep — it gets reaped as
+      // "background_worker_never_started" out from under a still-executing
+      // job the moment any single tool call runs past the 25s grace window.
+      await insertRun(runId, thread.id, undefined, {
+        dispatchMode: "background",
+      });
+      const claimedOwnRun = await claimBackgroundRun(runId);
+      if (!claimedOwnRun) {
+        throw new Error(
+          `Background automation "${automation.name}" (run "${runId}") could not claim its own freshly-inserted run row`,
+        );
+      }
+
       await new Promise<void>((resolve, reject) => {
         const activeRun = startRun(
           runId,
@@ -329,6 +365,7 @@ export async function runBackgroundAutomation(
                 runId,
               },
               softTimeoutMs,
+              { backgroundFunction: true },
             );
           },
           async (run) => {
@@ -360,7 +397,7 @@ export async function runBackgroundAutomation(
           },
           {
             softTimeoutMs,
-            dispatchMode: "background",
+            backgroundFunction: true,
             model,
             engineName: engine.name,
           },

package/corpus/core/src/provider-api/index.ts

@@ -3997,8 +3997,14 @@ async function resolveRequiredCredential(options: {
   connectionId?: string | null;
 }): Promise<ProviderApiResolvedCredential> {
   const credential = await resolveOptionalCredential(options);
-  if (!credential?.value) throw new Error(`${options.key} not configured`);
-  return credential;
+  if (credential?.value) return credential;
+  const scopeGap = await describeCredentialScopeGap([options.key], options.ctx)
+    // coercion-ok: only enriches an error we throw either way — losing the scope
+    // hint still surfaces the real "not configured" failure, never a success.
+    .catch(() => null);
+  throw new Error(
+    `${options.key} not configured${scopeGap ? `. ${scopeGap}` : ""}`,
+  );
 }
 
 async function resolveOptionalCredential(options: {

package/corpus/core/src/scripts/call-agent.ts

@@ -30,6 +30,7 @@ import { findAgent, discoverAgents } from "../server/agent-discovery.js";
 import {
   getRequestUserEmail,
   getRequestOrgId,
+  getRequestRunContext,
   isIntegrationCallerRequest,
   getIntegrationRequestContext,
 } from "../server/request-context.js";
@@ -93,8 +94,13 @@ function buildDelegationCorrelation(
   const inheritedDepth = Number.isInteger(context?.delegationDepth)
     ? Math.max(0, Number(context?.delegationDepth))
     : 0;
+  // The model this turn is actually running on, so a receiver with no model of
+  // its own can match the user's selection instead of its own default. A
+  // preference only — the receiver bounds it to its own engine's catalog.
+  const callerModel = getRequestRunContext()?.model?.trim();
   return {
     ...(selfAppId?.trim() ? { callerApp: selfAppId.trim() } : {}),
+    ...(callerModel ? { callerModel } : {}),
     ...(context?.threadId ? { callerThreadId: context.threadId } : {}),
     ...(context?.runId ? { parentRunId: context.runId } : {}),
     ...(context?.turnId ? { parentTurnId: context.turnId } : {}),