@agent-native/core 0.121.1 → 0.122.0

package/src/client/sse-event-processor.ts

@@ -625,6 +625,9 @@ function isAutoRecoverableError(ev: SSEEvent, errMsg: string): boolean {
     code === "unauthorized" ||
     code === "authentication_error" ||
     code === "permission_error" ||
+    code === "builder_auth_error" ||
+    // The account cannot use this model; another POST picks the same one.
+    code === "builder_model_unauthorized" ||
     code === "http_401" ||
     code === "http_403" ||
     code === "rate_limit_exceeded" ||

package/src/data-widgets/index.ts

@@ -282,6 +282,47 @@ export function isDataWidgetResult(value: unknown): value is DataWidgetResult {
   return normalizeDataWidgetResult(value) !== null;
 }
 
+export const DATA_WIDGET_MAX_ROWS = 50;
+export const DATA_WIDGET_MAX_CHART_POINTS = 200;
+
+// Widget rows arrive as tool-call arguments the model decodes token by token, so an
+// uncapped table costs minutes of wall clock before anything renders. Clamp server-side
+// rather than rejecting: the model has already paid for the tokens by the time we see them.
+export function clampDataWidgetRows(
+  result: DataWidgetResult,
+): DataWidgetResult {
+  const source = result as Partial<DataInsightsWidgetResult>;
+  const table = source.table;
+  const chartSeries = source.chartSeries;
+
+  const clampedTable =
+    table && table.rows.length > DATA_WIDGET_MAX_ROWS
+      ? {
+          ...table,
+          rows: table.rows.slice(0, DATA_WIDGET_MAX_ROWS),
+          totalRows: table.totalRows ?? table.rows.length,
+          sampledRows: DATA_WIDGET_MAX_ROWS,
+          truncated: true,
+        }
+      : table;
+
+  const clampedChart =
+    chartSeries && chartSeries.data.length > DATA_WIDGET_MAX_CHART_POINTS
+      ? {
+          ...chartSeries,
+          data: chartSeries.data.slice(0, DATA_WIDGET_MAX_CHART_POINTS),
+          sampled: true,
+        }
+      : chartSeries;
+
+  if (clampedTable === table && clampedChart === chartSeries) return result;
+  return {
+    ...result,
+    ...(clampedTable ? { table: clampedTable } : {}),
+    ...(clampedChart ? { chartSeries: clampedChart } : {}),
+  } as DataWidgetResult;
+}
+
 const dataTableColumnSchema = z
   .object({
     key: z.string().min(1),

package/src/deploy/build.ts

@@ -36,10 +36,8 @@ import {
 } from "../integrations/integration-durable-dispatch-config.js";
 import { normalizeAppBasePath } from "../server/app-base-path.js";
 import {
-  DEFAULT_SSR_CDN_CACHE_CONTROL,
-  DEFAULT_SSR_NETLIFY_CDN_CACHE_CONTROL,
   DEFAULT_SPECULATION_RULES_PATH,
-  DEFAULT_SSR_CACHE_CONTROL,
+  resolveSsrCacheHeaders,
 } from "../shared/cache-control.js";
 import { mcpEmbedStaticAssetRouteRules } from "../shared/mcp-embed-headers.js";
 import {
@@ -698,6 +696,9 @@ export function generateWorkerEntry(
   options: GenerateWorkerEntryOptions = {},
 ): string {
   const includeReactRouterSsr = options.includeReactRouterSsr ?? true;
+  // The worker ships as a static bundle with no access to runtime env, so the
+  // deployment-wide SSR cache policy is baked in from this build's env.
+  const ssrCacheHeaders = resolveSsrCacheHeaders();
   const routeImports: string[] = [];
   const routeRegistrations: string[] = [];
 
@@ -984,9 +985,10 @@ function injectHeadScript(html, script) {
   return html.slice(0, headCloseIdx) + script + html.slice(headCloseIdx);
 }
 
-const DEFAULT_SSR_CACHE_CONTROL = ${JSON.stringify(DEFAULT_SSR_CACHE_CONTROL)};
-const DEFAULT_SSR_CDN_CACHE_CONTROL = ${JSON.stringify(DEFAULT_SSR_CDN_CACHE_CONTROL)};
-const DEFAULT_SSR_NETLIFY_CDN_CACHE_CONTROL = ${JSON.stringify(DEFAULT_SSR_NETLIFY_CDN_CACHE_CONTROL)};
+// Resolved from AGENT_NATIVE_SSR_CACHE at build time.
+const SSR_CACHE_CONTROL = ${JSON.stringify(ssrCacheHeaders["cache-control"])};
+const SSR_CDN_CACHE_CONTROL = ${JSON.stringify(ssrCacheHeaders["cdn-cache-control"])};
+const SSR_NETLIFY_CDN_CACHE_CONTROL = ${JSON.stringify(ssrCacheHeaders["netlify-cdn-cache-control"])};
 const DEFAULT_SPECULATION_RULES_PATH = ${JSON.stringify(DEFAULT_SPECULATION_RULES_PATH)};
 const IMMUTABLE_ASSET_CACHE_CONTROL = ${JSON.stringify(IMMUTABLE_ASSET_CACHE_CONTROL)};
 const IMMUTABLE_ASSET_PATHS = new Set(${JSON.stringify(
@@ -1084,13 +1086,13 @@ function applyDefaultSsrCacheHeader(headers, status, pathname) {
     else headers.delete("vary");
   }
 
-  headers.set("cache-control", DEFAULT_SSR_CACHE_CONTROL);
-  headers.set("cdn-cache-control", DEFAULT_SSR_CDN_CACHE_CONTROL);
+  headers.set("cache-control", SSR_CACHE_CONTROL);
+  headers.set("cdn-cache-control", SSR_CDN_CACHE_CONTROL);
   // Netlify function responses are dynamic by default and can otherwise show
   // Cache-Status fwd=bypass even with Cache-Control: public. Keep this
   // Netlify-specific header so SSR HTML/.data are served from the shared
   // durable CDN cache instead of stampeding origin — for every visitor.
-  headers.set("netlify-cdn-cache-control", DEFAULT_SSR_NETLIFY_CDN_CACHE_CONTROL);
+  headers.set("netlify-cdn-cache-control", SSR_NETLIFY_CDN_CACHE_CONTROL);
 }
 
 function applyDefaultSpeculationRulesHeader(headers, status, basePath) {

package/src/integrations/webhook-handler.ts

@@ -8,6 +8,7 @@ import {
   type A2AToolResultSummary,
 } from "../a2a/artifact-response.js";
 import { collectFinalResponseTextFromAgentEvents } from "../a2a/response-text.js";
+import { isInBackgroundFunctionRuntime } from "../agent/durable-background.js";
 import {
   formatLlmCredentialErrorMessage,
   isLlmCredentialError,
@@ -41,7 +42,11 @@ import {
   threadDataToEngineMessages,
 } from "../agent/thread-data-builder.js";
 import { attachToolSearch } from "../agent/tool-search.js";
-import { createThread, getThread } from "../chat-threads/store.js";
+import {
+  createThread,
+  getThread,
+  grantThreadUserShare,
+} from "../chat-threads/store.js";
 import { updateThreadData } from "../chat-threads/store.js";
 import { isLocalDatabase } from "../db/client.js";
 import { getOrgA2ASecret, resolveOrgIdForEmail } from "../org/context.js";
@@ -88,6 +93,20 @@ const DEFERRED_RESPONSE_DISPATCH_SETTLE_WAIT_MS = 1_500;
 const DEFERRED_RESPONSE_MAX_HANDLER_MS = 2_500;
 const EMPTY_INTEGRATION_RESPONSE_MESSAGE =
   "The model finished without a visible answer. Try again, or open the thread in Dispatch to inspect the run.";
+const CUTOFF_INTEGRATION_RESPONSE_MESSAGE =
+  "I ran out of time on this one before I could write up an answer — it needed more research than a single run allows. " +
+  "Open the thread in Dispatch to see what I gathered, or ask me again in smaller pieces (one source at a time works best).";
+
+/**
+ * True when the run stopped at a continuation boundary rather than finishing:
+ * the run-manager's soft timeout emits `auto_continue` and aborts the loop, and
+ * the loop itself emits one when it hits an internal step budget. The run's
+ * status is still "completed", so without this check a cut-off research request
+ * is reported to the user as a model that answered with nothing.
+ */
+function endedAtContinuationBoundary(run: ActiveRun): boolean {
+  return run.events.some((runEvent) => runEvent.event.type === "auto_continue");
+}
 
 type ToolDoneEvent = {
   type: "tool_done";
@@ -789,6 +808,29 @@ async function processIncomingMessage(
     await releaseApplicableIntegrationBudgets(budgetReservations.reservations);
     throw error;
   }
+
+  // Channel conversations run as the integration service principal, so the
+  // thread is owned by `integration@<platform>` and not by the human who asked.
+  // The "Open thread" deep link we hand back would then 404 for them and the
+  // chat surface would silently render an empty new chat, so grant each
+  // verified participant an explicit share on the thread they are driving.
+  if (
+    incoming.senderVerified === true &&
+    incoming.senderEmail &&
+    incoming.senderEmail.trim().toLowerCase() !== ownerEmail.toLowerCase()
+  ) {
+    await grantThreadUserShare(
+      threadId,
+      incoming.senderEmail,
+      "editor",
+      ownerEmail,
+    ).catch((error) => {
+      console.warn(
+        `[integrations] Could not grant ${incoming.platform} sender access to thread ${threadId}:`,
+        error instanceof Error ? error.message : error,
+      );
+    });
+  }
   const existingMessages: EngineMessage[] = [];
   if (thread?.threadData) {
     existingMessages.push(...threadDataToEngineMessages(thread.threadData));
@@ -1051,7 +1093,10 @@ async function processIncomingMessage(
                 "directly is the most reliable way to get an answer right now.";
             } else {
               responseText =
-                verifiedMutationReceipt ?? EMPTY_INTEGRATION_RESPONSE_MESSAGE;
+                verifiedMutationReceipt ??
+                (endedAtContinuationBoundary(completedRun)
+                  ? CUTOFF_INTEGRATION_RESPONSE_MESSAGE
+                  : EMPTY_INTEGRATION_RESPONSE_MESSAGE);
             }
           }
           if (approval?.type === "approval_required") {
@@ -1346,13 +1391,22 @@ async function processIncomingMessage(
           resolve(outcome);
         }
       },
-      // Integration workers are ordinary self-dispatched serverless requests,
-      // not a Netlify background-function route. Without the hosted soft
-      // timeout, a wedged model connection can outlive the worker and leave
-      // Slack's native stream in "working" forever when the host kills the
-      // process. Checkpoint at the foreground-safe boundary so onComplete can
-      // always close the provider progress surface before the function wall.
-      { useHostedSoftTimeoutDefault: true },
+      // Without the hosted soft timeout, a wedged model connection can outlive
+      // the worker and leave Slack's native stream in "working" forever when
+      // the host kills the process. Checkpoint at the safe boundary so
+      // onComplete can always close the provider progress surface first.
+      //
+      // Which boundary that is depends on where this task is actually running:
+      // when durable dispatch routes it to the emitted `-background` function
+      // it has ~15min, and clamping it to the 40s foreground budget anyway cut
+      // off every research-shaped request (multi-source sweeps, long tool
+      // chains) with no visible answer. `isInBackgroundFunctionRuntime()` is
+      // the runtime proof — never a config guess — so the wider ceiling is
+      // taken only where the ~60s synchronous wall genuinely does not apply.
+      {
+        useHostedSoftTimeoutDefault: true,
+        backgroundFunction: isInBackgroundFunctionRuntime(),
+      },
     );
   });
 }

package/src/org/auto-join-domain.ts

@@ -14,9 +14,10 @@ export interface AutoJoinDomainOptions {
   /**
    * The signup hook should not clobber an org selected by an invite flow, but
    * request-time org resolution may need to move an existing account from a
-   * personal workspace into its newly matched company org.
+   * personal workspace into its newly matched company org. `"never"` joins
+   * without touching `active-org-id` — the caller decides activation itself.
    */
-  activateJoinedOrg?: "if-missing" | "always";
+  activateJoinedOrg?: "if-missing" | "always" | "never";
 }
 
 /**
@@ -96,7 +97,7 @@ export async function autoJoinDomainMatchingOrgs(
   // one, unless the caller is request-time org resolution intentionally moving
   // an existing account into its newly matched company org.
   let activeOrgId: string | null = null;
-  if (joined[0]) {
+  if (joined[0] && options.activateJoinedOrg !== "never") {
     try {
       const existing = await getUserSetting(email, "active-org-id");
       const hasActive = Boolean(existing?.orgId);

package/src/org/context.ts

@@ -20,12 +20,33 @@ function normalizeOrgRole(value: unknown): OrgRole | null {
     : null;
 }
 
-function isLikelyPersonalWorkspace(
-  membership: { orgName: string },
-  email: string,
-  session: { name?: string } | null,
-): boolean {
-  return membership.orgName.trim() === defaultOrgName(email, session);
+function emailDomainOf(email: string): string | null {
+  return email.split("@")[1]?.toLowerCase() || null;
+}
+
+/**
+ * A workspace the user owns that nobody else has joined is a default/personal
+ * workspace whatever it happens to be named, so moving the user into their
+ * company org is safe. An org with other members is a team they deliberately
+ * belong to — join the domain org in the background but leave them there.
+ */
+async function isSoloOwnedWorkspace(
+  exec: ReturnType<typeof getDbExec>,
+  orgId: string,
+  memberships: MembershipRow[],
+): Promise<boolean> {
+  const membership = memberships.find((m) => m.orgId === orgId);
+  if (!membership || membership.role !== "owner") return false;
+  try {
+    const { rows } = await exec.execute({
+      sql: `SELECT COUNT(*) AS "memberCount" FROM org_members WHERE org_id = ?`,
+      args: [orgId],
+    });
+    const row = rows[0] as any;
+    return Number(row?.memberCount ?? row?.membercount ?? 0) <= 1;
+  } catch {
+    return false;
+  }
 }
 
 function autoCreateDefaultOrgEnabled(): boolean {
@@ -61,7 +82,12 @@ export async function getOrgContext(event: H3Event): Promise<OrgContext> {
   return (ctx.__anOrgContextCache ??= resolveOrgContextUncached(event));
 }
 
-type MembershipRow = { orgId: string; role: OrgRole; orgName: string };
+type MembershipRow = {
+  orgId: string;
+  role: OrgRole;
+  orgName: string;
+  allowedDomain: string | null;
+};
 
 const MEMBERSHIPS_CACHE_KEY = "__anOrgMembershipsCache";
 const ACTIVE_ORG_SETTING_CACHE_KEY = "__anActiveOrgSettingCache";
@@ -157,17 +183,26 @@ async function resolveOrgContextUncached(event: H3Event): Promise<OrgContext> {
     return { email, orgId: null, orgName: null, role: null };
   }
 
-  const shouldTryDomainAutoJoin =
-    memberships.length === 0 ||
-    (memberships.length === 1 &&
-      isLikelyPersonalWorkspace(memberships[0], email, session));
   const activeOrgSetting = await loadActiveOrgSettingForEvent(event, email);
-  if (activeOrgSetting?.orgId === null) {
-    return { email, orgId: null, orgName: null, role: null };
-  }
-  if (activeOrgSetting?.orgId) {
+  const explicitPersonal = activeOrgSetting?.orgId === null;
+
+  const emailDomain = emailDomainOf(email);
+  // Membership in a domain-matched org is the only durable "already joined"
+  // signal. Recognizing the personal workspace by its *name* instead breaks the
+  // moment the provider display name or the workspace name changes, which
+  // strands an existing user in Personal with no way into their company org.
+  const shouldTryDomainAutoJoin =
+    !explicitPersonal &&
+    emailDomain !== null &&
+    !memberships.some((m) => m.allowedDomain?.toLowerCase() === emailDomain);
+
+  if (
+    !explicitPersonal &&
+    activeOrgSetting?.orgId &&
+    !shouldTryDomainAutoJoin
+  ) {
     const active = memberships.find((m) => m.orgId === activeOrgSetting.orgId);
-    if (active && !shouldTryDomainAutoJoin) {
+    if (active) {
       return {
         email,
         orgId: active.orgId,
@@ -182,30 +217,63 @@ async function resolveOrgContextUncached(event: H3Event): Promise<OrgContext> {
     : null;
 
   if (shouldTryDomainAutoJoin) {
+    const membershipsBeforeJoin = memberships;
     const joined = await autoJoinDomainMatchingOrgs(email, {
-      activateJoinedOrg: "always",
+      activateJoinedOrg: "never",
     });
-    if (joined.joined.length > 0) {
+    const joinedOrgId = joined.joined[0]?.orgId ?? null;
+    if (joinedOrgId) {
       const refreshed = await loadMemberships(exec, email);
       if (refreshed !== null) {
         memberships = refreshed;
         updateMembershipsForEvent(event, email, refreshed);
       }
-    }
 
-    if (joined.activeOrgId) {
-      const active = memberships.find((m) => m.orgId === joined.activeOrgId);
-      if (active) {
-        return {
-          email,
-          orgId: active.orgId,
-          orgName: active.orgName,
-          role: active.role,
-        };
+      const currentOrgId =
+        activeOrgSetting?.orgId ??
+        sessionOrgId ??
+        membershipsBeforeJoin[0]?.orgId ??
+        null;
+      const shouldActivate =
+        !explicitPersonal &&
+        (currentOrgId === null ||
+          (await isSoloOwnedWorkspace(
+            exec,
+            currentOrgId,
+            membershipsBeforeJoin,
+          )));
+
+      if (shouldActivate) {
+        await putUserSetting(email, "active-org-id", { orgId: joinedOrgId });
+        const active = memberships.find((m) => m.orgId === joinedOrgId);
+        if (active) {
+          return {
+            email,
+            orgId: active.orgId,
+            orgName: active.orgName,
+            role: active.role,
+          };
+        }
       }
     }
   }
 
+  if (explicitPersonal) {
+    return { email, orgId: null, orgName: null, role: null };
+  }
+
+  if (activeOrgSetting?.orgId) {
+    const active = memberships.find((m) => m.orgId === activeOrgSetting.orgId);
+    if (active) {
+      return {
+        email,
+        orgId: active.orgId,
+        orgName: active.orgName,
+        role: active.role,
+      };
+    }
+  }
+
   if (sessionOrgId) {
     const active =
       sessionMembership ?? memberships.find((m) => m.orgId === sessionOrgId);
@@ -247,24 +315,25 @@ async function resolveOrgContextUncached(event: H3Event): Promise<OrgContext> {
 async function loadMemberships(
   exec: ReturnType<typeof getDbExec>,
   email: string,
-): Promise<Array<{
-  orgId: string;
-  role: OrgRole;
-  orgName: string;
-}> | null> {
+): Promise<MembershipRow[] | null> {
   try {
     const { rows } = await exec.execute({
-      sql: `SELECT m.org_id AS "orgId", m.role AS role, o.name AS "orgName"
+      sql: `SELECT m.org_id AS "orgId", m.role AS role, o.name AS "orgName",
+                   o.allowed_domain AS "allowedDomain"
             FROM org_members m
             INNER JOIN organizations o ON m.org_id = o.id
             WHERE LOWER(m.email) = ?`,
       args: [email.toLowerCase()],
     });
-    return rows.map((r: any) => ({
-      orgId: String(r.orgId ?? r.org_id),
-      role: String(r.role) as OrgRole,
-      orgName: String(r.orgName ?? r.org_name),
-    }));
+    return rows.map((r: any) => {
+      const domain = r.allowedDomain ?? r.allowed_domain;
+      return {
+        orgId: String(r.orgId ?? r.org_id),
+        role: String(r.role) as OrgRole,
+        orgName: String(r.orgName ?? r.org_name),
+        allowedDomain: domain ? String(domain) : null,
+      };
+    });
   } catch {
     // Tables may not exist yet on first boot before migrations finish.
     return null;

package/src/org/index.ts

@@ -28,6 +28,11 @@ export {
   createOrganization,
 } from "./context.js";
 
+export {
+  implicitServiceOrgRole,
+  parseServiceIdentityEmail,
+} from "./service-identity.js";
+
 export { acceptPendingInvitationsForEmail } from "./accept-pending.js";
 export type { AcceptPendingResult } from "./accept-pending.js";
 

package/src/org/service-identity.ts

@@ -0,0 +1,60 @@
+/**
+ * Implicit org membership for synthetic service-token identities.
+ *
+ * Org service tokens authenticate as `svc-<name>@service.<orgId>` and are
+ * deliberately never inserted into `org_members` (see
+ * `mcp/actions/service-token-access.ts`), so any template that authorizes by
+ * looking up a physical membership row rejects them. The ownable/sharing layer
+ * already admits them via the signed `org_id` claim; this closes the gap for
+ * the role-lookup layer.
+ *
+ * Two constraints are load-bearing and must survive future edits:
+ *
+ * 1. The implicit role is always `member`, never admin or owner. Member-gated
+ *    actions (create/read org data) work; admin-gated ones (invite/remove
+ *    members, change roles, org settings, minting further service tokens) stay
+ *    closed, so a leaked service token cannot escalate.
+ * 2. `requestOrgId` must independently agree with the target org. The email
+ *    alone is not proof: a human account registered under a `@service.<orgId>`
+ *    address would otherwise mint itself membership. A signed-in user's request
+ *    org id is membership-derived through `getOrgContext`, so a non-member
+ *    cannot present the target org id, while a service token carries it in its
+ *    signed `org_id` claim.
+ */
+import type { OrgRole } from "./types.js";
+
+const SERVICE_IDENTITY_PATTERN = /^svc-([a-z0-9-]+)@service\.(.+)$/;
+
+/**
+ * Parse `svc-<name>@service.<orgId>` into its parts, or null when the address
+ * is not a service identity. Counterpart to `serviceIdentityEmail()` in
+ * `mcp/connect-store.ts`.
+ */
+export function parseServiceIdentityEmail(
+  email: string | null | undefined,
+): { serviceName: string; orgId: string } | null {
+  const trimmed = email?.trim();
+  if (!trimmed) return null;
+  const match = SERVICE_IDENTITY_PATTERN.exec(trimmed.toLowerCase());
+  if (!match) return null;
+  const orgId = trimmed.slice(trimmed.length - match[2].length);
+  if (!orgId) return null;
+  return { serviceName: match[1], orgId };
+}
+
+/**
+ * Resolve the implicit org role for a service-token caller, or null when the
+ * caller is not a service identity acting for the org it was minted against.
+ */
+export function implicitServiceOrgRole(params: {
+  email: string | null | undefined;
+  orgId: string | null | undefined;
+  requestOrgId: string | null | undefined;
+}): OrgRole | null {
+  const orgId = params.orgId?.trim();
+  if (!orgId) return null;
+  if (params.requestOrgId?.trim() !== orgId) return null;
+  const parsed = parseServiceIdentityEmail(params.email);
+  if (!parsed || parsed.orgId !== orgId) return null;
+  return "member";
+}

package/src/provider-api/index.ts

@@ -396,6 +396,7 @@ export interface ProviderApiConfig {
   placeholders?: readonly ProviderApiPlaceholder[];
   examples?: readonly ProviderApiExample[];
   notes?: readonly string[];
+  accessErrorGuidance?: string;
   corpusRecipes?: readonly ProviderApiCorpusRecipe[];
   templateUses?: readonly WorkspaceConnectionTemplateUse[];
 }
@@ -1326,6 +1327,11 @@ const PROVIDER_CONFIGS: Record<ProviderApiId, ProviderApiConfig> = {
     defaultHeaders: { "Notion-Version": "2026-03-11" },
     templateUses: ["analytics", "brain", "content", "dispatch"],
     examples: [{ label: "Search", method: "POST", path: "/search", body: {} }],
+    notes: [
+      "The name GET /users/me returns is the label whoever minted the token typed into Notion, so it often names an unrelated product or team. Call it the Notion-side integration label and never restate it as the workspace, app, or product the user is currently in.",
+    ],
+    accessErrorGuidance:
+      "Notion 401/403/404 on a specific page or database usually means that object was never shared with the integration, not that the id is wrong or the key is invalid. Fix: open the page or database in Notion, then ••• → Connections → add the integration. When naming the integration, describe it as the Notion-side integration label from GET /users/me and note that it may not match this app or workspace.",
     corpusRecipes: [
       {
         label: "Search a Notion data source with complete cursor coverage",
@@ -1624,6 +1630,7 @@ export function listProviderApiCatalog(
     defaultHeaders: config.defaultHeaders ?? {},
     examples: config.examples ?? [],
     notes: config.notes ?? [],
+    accessErrorGuidance: config.accessErrorGuidance ?? null,
     corpusRecipes: config.corpusRecipes ?? [],
     templateUses: config.templateUses ?? [],
   }));
@@ -1990,11 +1997,25 @@ export async function executeProviderApiRequest(
       ...(args.connectionId ? { connectionId: args.connectionId } : {}),
     },
     response,
-    guidance:
+    guidance: [
       "This was a raw provider API request. Use provider docs/spec URLs to choose endpoints and include method/path/status plus relevant filters in the methodology. Prefer this escape hatch whenever canned actions are too narrow.",
+      providerAccessErrorGuidance(config, response.status),
+    ]
+      .filter(Boolean)
+      .join(" "),
   };
 }
 
+const PROVIDER_ACCESS_ERROR_STATUSES = new Set([401, 403, 404]);
+
+function providerAccessErrorGuidance(
+  config: ProviderApiConfig,
+  status: number,
+): string | null {
+  if (!PROVIDER_ACCESS_ERROR_STATUSES.has(status)) return null;
+  return config.accessErrorGuidance ?? null;
+}
+
 /**
  * Resolve a provider OAuth token for a trusted server-side integration bridge
  * such as a CRM adapter or Google Picker. Callers must keep the result out of

package/src/scripts/docs/search.ts

@@ -143,7 +143,7 @@ function slugifyDocId(value: string): string {
 
 async function loadAgentBundleDocs(): Promise<DocFull[]> {
   try {
-    const { loadAgentsBundle, getRuntimeSkills } =
+    const { loadAgentsBundle, getRuntimeSkills, skillSubfileDocsSlug } =
       await import("../../server/agents-bundle.js");
     const bundle = await loadAgentsBundle();
     const docs: DocFull[] = [];
@@ -174,6 +174,17 @@ async function loadAgentBundleDocs(): Promise<DocFull[]> {
         description: skill.meta.description,
         body: skill.content,
       });
+      // Progressive-disclosure sub-files (e.g. `references/*.md`) get their
+      // own searchable/readable doc so the "also contains" pointers the
+      // skill prompt block advertises actually resolve to something.
+      for (const [relPath, content] of Object.entries(skill.files)) {
+        docs.push({
+          slug: skillSubfileDocsSlug(skill.meta.name, relPath),
+          title: `Skill: ${skill.meta.name} — ${relPath}`,
+          description: `Reference file from the "${skill.meta.name}" skill (${relPath}).`,
+          body: content,
+        });
+      }
     }
     return docs;
   } catch {