@agent-native/core 0.129.1 → 0.130.0

package/corpus/core/src/server/embed-session.ts

@@ -15,6 +15,7 @@ import {
   EMBED_MODE_QUERY_PARAM,
   EMBED_SESSION_COOKIE,
   EMBED_TARGET_HEADER,
+  EMBED_TARGET_QUERY_PARAM,
   EMBED_TOKEN_QUERY_PARAM,
 } from "../shared/embed-auth.js";
 import { normalizeAppPath } from "../shared/sign-in-journey.js";
@@ -24,6 +25,7 @@ import { getWorkspaceA2ADerivedSecret } from "./derived-secret.js";
 const TOKEN_KIND = "agent-native-embed-session";
 const DEFAULT_TOKEN_TTL_SECONDS = 60 * 60;
 const DEFAULT_TICKET_TTL_SECONDS = 5 * 60;
+const EMBED_CAPABILITY_SCOPE_PREFIX = "capability:";
 const CONTROL_CHARS = new RegExp("[\\u0000-\\u001f\\u007f]");
 const OPEN_ROUTE_PATH = "/_agent-native/open";
 const OPEN_ROUTE_VIEW_PATHS: Record<string, string> = {
@@ -114,6 +116,34 @@ export type ResolvedEmbedSession = {
   scope?: string;
 };
 
+/**
+ * Capability embed scopes authorize one narrow, non-identity operation. They
+ * must never be promoted into the ticket owner's authenticated browser
+ * session: the owner claim only records who minted the capability.
+ */
+export function isEmbedCapabilityScope(
+  scope: string | undefined | null,
+): boolean {
+  return (
+    typeof scope === "string" && scope.startsWith(EMBED_CAPABILITY_SCOPE_PREFIX)
+  );
+}
+
+export function resolvedEmbedCapabilityScope(
+  session: ResolvedEmbedSession | null,
+): string | undefined {
+  const scope = session?.scope;
+  if (
+    !isEmbedCapabilityScope(scope) ||
+    !scope ||
+    scope.length > 512 ||
+    CONTROL_CHARS.test(scope)
+  ) {
+    return undefined;
+  }
+  return scope;
+}
+
 async function ensureTable(): Promise<void> {
   if (!_initPromise) {
     _initPromise = (async () => {
@@ -394,7 +424,12 @@ function headerTargetPathname(event: H3Event): string | null {
   if (typeof direct === "string") return pathnameFromPath(direct);
   try {
     const raw = getHeader(event, EMBED_TARGET_HEADER);
-    return typeof raw === "string" ? pathnameFromPath(raw) : null;
+    if (typeof raw === "string") return pathnameFromPath(raw);
+    const queryValue = getQuery(event)?.[EMBED_TARGET_QUERY_PARAM];
+    const queryTarget = Array.isArray(queryValue) ? queryValue[0] : queryValue;
+    return typeof queryTarget === "string"
+      ? pathnameFromPath(queryTarget)
+      : null;
   } catch {
     return null;
   }
@@ -474,6 +509,17 @@ function isEmbedRuntimeRequest(event: H3Event): boolean {
   );
 }
 
+function isEmbedStaticRuntimeRequest(event: H3Event): boolean {
+  const pathname = requestPathname(event);
+  return (
+    !!pathname &&
+    (pathname.startsWith("/@") ||
+      pathname.startsWith("/app/") ||
+      pathname.startsWith("/node_modules/") ||
+      pathname.startsWith("/packages/"))
+  );
+}
+
 export function normalizeEmbedTargetPath(
   raw: string | undefined | null,
   requestOrigin?: string,
@@ -751,7 +797,14 @@ export async function resolveEmbedSessionFromRequest(
       candidate.source === "cookie" && isRuntimeRequest;
     const isRuntimeQueryRequest =
       candidate.source === "query" && isRuntimeRequest;
-    if (!matchesTarget && !isRuntimeCookieRequest && !isRuntimeQueryRequest) {
+    const capabilityScope = isEmbedCapabilityScope(verified.claims.scope);
+    const allowsUnboundRuntimeRequest =
+      !capabilityScope || isEmbedStaticRuntimeRequest(event);
+    if (
+      !matchesTarget &&
+      (!allowsUnboundRuntimeRequest ||
+        (!isRuntimeCookieRequest && !isRuntimeQueryRequest))
+    ) {
       continue;
     }
     if (candidate.source === "query" && candidate.token) {
@@ -789,10 +842,16 @@ export function requestHasEmbedAuthMarker(event: H3Event): boolean {
     const runtimeRequest = isEmbedRuntimeRequest(event);
     for (const candidate of candidates) {
       const verified = verifyEmbedSessionToken(candidate.token);
+      const allowsUnboundRuntimeRequest =
+        verified.ok &&
+        (!isEmbedCapabilityScope(verified.claims.scope) ||
+          isEmbedStaticRuntimeRequest(event));
       if (
         verified.ok &&
         (requestMatchesEmbedTarget(event, verified.claims.targetPath) ||
-          (candidate.allowRuntime && runtimeRequest))
+          (candidate.allowRuntime &&
+            runtimeRequest &&
+            allowsUnboundRuntimeRequest))
       ) {
         return true;
       }

package/corpus/core/src/server/open-route.ts

@@ -40,7 +40,11 @@ import {
 } from "../shared/mcp-embed-headers.js";
 import { normalizeAppPath } from "../shared/sign-in-journey.js";
 import { getConfiguredAppBasePath } from "./app-base-path.js";
-import { getSession, getConfiguredLoginHtml } from "./auth.js";
+import {
+  getSession,
+  getConfiguredLoginHtml,
+  redirectWithStagedCookies,
+} from "./auth.js";
 import { requestHasEmbedAuthMarker } from "./embed-session.js";
 
 /** Query keys that are route control, not navigation payload. */
@@ -49,6 +53,11 @@ const RESERVED = new Set([
   "view",
   "to",
   "compose",
+  // Mobile/caller-session bridge token (see `promoteQuerySession` in
+  // auth.ts). `getSession()` below reads and promotes it into a cookie; it
+  // must never also land in `navParams`, or it would be persisted into the
+  // `navigate` application-state row that the client polls and reads.
+  "_session",
   EMBED_MODE_QUERY_PARAM,
   EMBED_TOKEN_QUERY_PARAM,
   MCP_APP_CHAT_BRIDGE_QUERY_PARAM,
@@ -138,11 +147,16 @@ function redirect(
   location: string,
   embedRedirect: boolean,
 ): Response {
-  // Native web Response (not h3 v2's reworked sendRedirect) — matches the
-  // redirect pattern used elsewhere in auth.ts.
-  const headers = new Headers({ Location: location });
-  if (embedRedirect) addMcpEmbedHeaders(event, headers);
-  return new Response("", { status: 302, headers });
+  // A bare `new Response("", { status: 302, headers: { Location } })` here
+  // would silently drop the Set-Cookie `getSession()` just staged below (e.g.
+  // `promoteQuerySession` promoting a `_session` query token) — h3 v2 only
+  // merges `event.res.headers`-staged cookies onto a returned Response when
+  // it's 2xx. Route through the same cookie-preserving redirect auth.ts uses.
+  const response = redirectWithStagedCookies(event, location);
+  if (!embedRedirect) return response;
+  const headers = new Headers(response.headers);
+  addMcpEmbedHeaders(event, headers);
+  return new Response("", { status: response.status, headers });
 }
 
 function appendSearchParams(target: string, params: URLSearchParams): string {

package/corpus/core/src/server/prompts/framework-core-compact.ts

@@ -76,7 +76,7 @@ Bring a senior engineer's judgment, arrived at through attention not premature c
 7. **Security** — ${securityRule}
 ${sharedRule8(examples, options)}
 ${SHARED_RULE_9}
-**Native widgets** — For table/chart/graph/report requests, prefer actions labeled \`Native chat widget\`; use \`render-data-widget\` for already-summarized data (≤50 rows) instead of markdown tables. Above that, give the total plus the top rows — never retype a full result set as widget arguments.
+**Native widgets** — For table/chart/graph/report requests, prefer actions labeled \`Native chat widget\`; use \`render-data-widget\` for already-summarized data (≤50 rows) instead of markdown tables. Above that, give the total plus the top rows — never retype a full result set as widget arguments. Deliver files in chat, never just a path.
 10. **Your tool list is not the whole surface** — Most app actions and connected MCP tools load on demand, so search the live registry with \`tool-search\` before concluding a capability doesn't exist.
 11. **Relative dates use runtime context** — The \`<runtime-context>\` block gives the authoritative current date/time. Resolve "today", "yesterday", "last week", and similar phrases to explicit calendar dates before querying data or creating artifacts.
 ${SHARED_RULE_14}

package/corpus/core/src/server/prompts/framework-core.ts

@@ -98,6 +98,7 @@ ${securityRule}
 ${sharedRule8(examples, options)}
 ${SHARED_RULE_9}
 **Native chat widgets** — When an available action says it renders a native widget such as \`data-table\`, \`data-chart\`, or \`data-insights\`, call that action for user requests asking for a table, chart, graph, trend, report, or inline data view. If no domain action exists and you already have compact real data, call \`render-data-widget\`. Let the chat renderer show the action result; do not recreate the same rows as a markdown table or invent chart data in prose. Add only a short human summary or next-step link around the widget. Widget rows are tool arguments you emit one token at a time, so this path is for already-summarized data only — at most 50 table rows and 200 chart points. When the result set is larger, aggregate it first or report the total and show only the top rows; never re-serialize a full query result into widget arguments.
+**Downloadable files** — When the user asks you to create or export a file, deliver it in the same chat turn. For compact tabular results, prefer \`render-data-widget\` so the user gets the native Download CSV action without a second stored copy. For a complete or durable file written through \`workspaceWrite\`, use a normal non-\`scratch/\` path and then call \`show-workspace-file\` with that path so chat renders a direct download card. Never finish by giving filesystem paths or telling the user to navigate elsewhere to find the file.
 10. **Your tool list is not the whole surface** — Most app actions and connected MCP tools load on demand, so search the live registry with \`tool-search\` before concluding a capability doesn't exist.
 11. **Relative dates use runtime context** — The \`<runtime-context>\` block gives the authoritative current date/time. Resolve "today", "yesterday", "last week", and similar phrases to explicit calendar dates before querying data or creating artifacts. When answering factual questions, include the exact date or date range you used.
 ${SHARED_RULE_14}

package/corpus/core/src/server/request-context.ts

@@ -133,6 +133,12 @@ export interface RequestContext {
   userEmail?: string;
   userName?: string;
   orgId?: string;
+  /**
+   * Narrow authorization capability verified from an embed session. This is
+   * deliberately separate from user identity: capability-only sessions must
+   * not satisfy account-backed auth or inherit the ticket owner's privileges.
+   */
+  authCapability?: string;
   timezone?: string;
   /**
    * Set when code reads authenticated request context. Public SSR shell/data
@@ -148,6 +154,18 @@ export interface RequestContext {
    * fallback. Optional — absent on paths that don't populate it.
    */
   requestOrigin?: string;
+  /**
+   * True when the request's real socket peer is loopback, captured by the
+   * action-route handler while the h3 event is still in scope (nothing below
+   * that layer can see the event). Derived from `getRequestIP()` WITHOUT
+   * `x-forwarded-for`, so a remote client cannot set it via headers.
+   *
+   * A local-dev gate only. A tunnel or reverse proxy that reaches the dev
+   * server over loopback also presents as loopback, so this is necessary but
+   * not sufficient on its own — pair it with something that scopes the blast
+   * radius (a resource that is itself local-only, NODE_ENV, etc.).
+   */
+  isLoopbackRequest?: boolean;
   /**
    * True when this request is being processed by an integration-platform
    * webhook (Slack, Telegram, etc.) where the function timeout is the
@@ -388,9 +406,26 @@ export function getRequestOrgId(): string | undefined {
   return processEnv("AGENT_ORG_ID");
 }
 
+/** Return the verified capability for this request, without implying identity. */
+export function getRequestAuthCapability(): string | undefined {
+  const store = als.getStore();
+  if (!store) return undefined;
+  if (store.authCapability) markAuthContextAccess(store);
+  return store.authCapability;
+}
+
+/**
+ * Whether the current request came from a loopback socket peer. Fails closed:
+ * outside a request store (CLI, background job, agent run) there is no peer to
+ * vouch for, so this is `false` rather than inheriting an ambient default.
+ */
+export function getRequestIsLoopback(): boolean {
+  return als.getStore()?.isLoopbackRequest === true;
+}
+
 function markAuthContextAccess(ctx: RequestContext | undefined) {
   if (!ctx) return;
-  if (ctx.userEmail || ctx.userName || ctx.orgId) {
+  if (ctx.userEmail || ctx.userName || ctx.orgId || ctx.authCapability) {
     ctx.authContextAccessed = true;
   }
 }

package/corpus/core/src/shared/embed-auth.ts

@@ -1,5 +1,6 @@
 export const EMBED_START_PATH = "/_agent-native/embed/start";
 export const EMBED_TOKEN_QUERY_PARAM = "__an_embed_token";
+export const EMBED_TARGET_QUERY_PARAM = "__an_embed_target";
 export const EMBED_MODE_QUERY_PARAM = "embedded";
 export const MCP_APP_CHAT_BRIDGE_QUERY_PARAM = "__an_mcp_chat_bridge";
 export const EMBED_SESSION_COOKIE = "an_embed_session";

package/corpus/core/src/shared/html-document.ts

@@ -0,0 +1,115 @@
+type HtmlInjectionTarget = "head" | "body";
+const RAW_TEXT_TAG_NAMES = new Set(["script", "style", "textarea", "title"]);
+
+function tagEndIndex(html: string, start: number): number {
+  let quote: '"' | "'" | null = null;
+
+  for (let index = start; index < html.length; index += 1) {
+    const character = html[index];
+    if (quote) {
+      if (character === quote) quote = null;
+      continue;
+    }
+    if (character === '"' || character === "'") {
+      quote = character;
+      continue;
+    }
+    if (character === ">") return index;
+  }
+
+  return -1;
+}
+
+function tagNameAt(html: string, start: number): string | null {
+  const match = /^[A-Za-z][\w:-]*/.exec(html.slice(start));
+  return match?.[0]?.toLowerCase() ?? null;
+}
+
+function rawTextCloseIndex(html: string, tag: string, start: number): number {
+  const pattern = new RegExp(`<\\/${tag}\\s*>`, "gi");
+  pattern.lastIndex = start;
+  return pattern.exec(html)?.index ?? -1;
+}
+
+function closingTagIndex(
+  html: string,
+  tag: HtmlInjectionTarget | "html",
+  last: boolean,
+): number {
+  let index = -1;
+  let cursor = 0;
+
+  while (cursor < html.length) {
+    const tagStart = html.indexOf("<", cursor);
+    if (tagStart === -1) break;
+
+    if (html.startsWith("<!--", tagStart)) {
+      const commentEnd = html.indexOf("-->", tagStart + 4);
+      cursor = commentEnd === -1 ? html.length : commentEnd + 3;
+      continue;
+    }
+
+    const closing = html[tagStart + 1] === "/";
+    const nameStart = tagStart + (closing ? 2 : 1);
+    const tagName = tagNameAt(html, nameStart);
+    if (!tagName) {
+      cursor = tagStart + 1;
+      continue;
+    }
+
+    const tagEnd = tagEndIndex(html, nameStart + tagName.length);
+    if (tagEnd === -1) break;
+
+    if (
+      closing &&
+      tagName === tag &&
+      !/\S/.test(html.slice(nameStart + tagName.length, tagEnd))
+    ) {
+      index = tagStart;
+      if (!last) return index;
+    }
+
+    if (!closing && RAW_TEXT_TAG_NAMES.has(tagName)) {
+      const rawTextEnd = rawTextCloseIndex(html, tagName, tagEnd + 1);
+      cursor =
+        rawTextEnd === -1 ? html.length : rawTextEnd + tagName.length + 3;
+      continue;
+    }
+
+    cursor = tagEnd + 1;
+  }
+
+  return index;
+}
+
+/**
+ * Inserts markup at a document boundary without using String.replace's
+ * replacement-string semantics. It ignores raw text, attributes, and comments
+ * when locating a real closing tag. Body and html closers use their last
+ * marker so literal close tags cannot capture the injection.
+ */
+export function injectDocumentMarkup(
+  html: string,
+  markup: string,
+  options: { target?: HtmlInjectionTarget } = {},
+): string {
+  if (!markup) return html;
+
+  const target = options.target ?? "body";
+  const targetIndex = closingTagIndex(html, target, target === "body");
+  if (targetIndex !== -1) {
+    return html.slice(0, targetIndex) + markup + html.slice(targetIndex);
+  }
+
+  const bodyIndex = closingTagIndex(html, "body", true);
+  if (bodyIndex !== -1) {
+    return html.slice(0, bodyIndex) + markup + html.slice(bodyIndex);
+  }
+
+  const htmlIndex = closingTagIndex(html, "html", true);
+  if (htmlIndex !== -1) {
+    return html.slice(0, htmlIndex) + markup + html.slice(htmlIndex);
+  }
+
+  return html + markup;
+}

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

@@ -20,6 +20,7 @@ export {
   type SignInJourneyInput,
 } from "./sign-in-journey.js";
 export { truncate } from "./truncate.js";
+export { injectDocumentMarkup } from "./html-document.js";
 export { withBuilderUtmTrackingParams } from "./builder-link-tracking.js";
 export {
   llmConnectionTrackingProperties,

package/corpus/core/src/sharing/access.ts

@@ -16,6 +16,7 @@
 import { and, eq, or, sql, type SQL } from "drizzle-orm";
 
 import {
+  getRequestAuthCapability,
   getRequestUserEmail,
   getRequestOrgId,
 } from "../server/request-context.js";
@@ -54,6 +55,7 @@ export class ForbiddenError extends Error {
 export interface AccessContext {
   userEmail?: string;
   orgId?: string;
+  authCapability?: string;
 }
 
 /** Current request's access context. Pulls from request-context ALS. */
@@ -61,6 +63,7 @@ export function currentAccess(): AccessContext {
   return {
     userEmail: getRequestUserEmail(),
     orgId: getRequestOrgId(),
+    authCapability: getRequestAuthCapability(),
   };
 }
 
@@ -68,7 +71,11 @@ export function resolveRegisteredAccessContext(
   reg: ShareableResourceRegistration | undefined,
   ctx: AccessContext,
 ): AccessContext {
-  return reg?.resolveAccessContext ? reg.resolveAccessContext(ctx) : ctx;
+  if (!reg?.resolveAccessContext) return ctx;
+  const resolved = reg.resolveAccessContext(ctx);
+  return ctx.authCapability
+    ? { ...resolved, authCapability: ctx.authCapability }
+    : resolved;
 }
 
 function normalizeEmailForAccess(email: string | undefined): string | null {

package/corpus/core/src/sharing/registry.ts

@@ -124,7 +124,11 @@ export interface ShareableResourceRegistration {
     | "admin"
     | ((
         resource: any,
-        ctx: { userEmail?: string; orgId?: string },
+        ctx: {
+          userEmail?: string;
+          orgId?: string;
+          authCapability?: string;
+        },
       ) =>
         | "viewer"
         | "editor"
@@ -148,9 +152,14 @@ export interface ShareableResourceRegistration {
    * identity can normalize here so the generic framework sharing actions and
    * access helpers stay in sync with template-owned actions.
    */
-  resolveAccessContext?: (ctx: { userEmail?: string; orgId?: string }) => {
+  resolveAccessContext?: (ctx: {
     userEmail?: string;
     orgId?: string;
+    authCapability?: string;
+  }) => {
+    userEmail?: string;
+    orgId?: string;
+    authCapability?: string;
   };
   /**
    * When true, direct ownership is recognized by owner_email regardless of the

package/corpus/core/src/workspace-files/actions.ts

@@ -0,0 +1,100 @@
+import { z } from "zod";
+
+import { ACTION_CHAT_UI_WORKSPACE_FILE_RENDERER } from "../action-ui.js";
+import { defineAction } from "../action.js";
+import type { ActionEntry } from "../agent/production-agent.js";
+import {
+  getRequestOrgId,
+  getRequestUserEmail,
+} from "../server/request-context.js";
+import { getWorkspaceFileMeta, type WorkspaceFilesScope } from "./store.js";
+
+const workspaceFileResultSchema = z.object({
+  file: z.object({
+    resourceId: z.string().min(1),
+    path: z.string().min(1),
+    name: z.string().min(1),
+    contentType: z.string().min(1),
+    sizeBytes: z.number().int().nonnegative(),
+    updatedAt: z.string().min(1),
+  }),
+});
+
+export type WorkspaceFileActionResult = z.infer<
+  typeof workspaceFileResultSchema
+>;
+
+function currentWorkspaceScope(): WorkspaceFilesScope {
+  const orgId = getRequestOrgId();
+  if (orgId) return { scope: "org", scopeId: orgId };
+
+  const userEmail = getRequestUserEmail();
+  if (userEmail) return { scope: "user", scopeId: userEmail };
+
+  throw new Error(
+    "show-workspace-file requires an authenticated request context.",
+  );
+}
+
+function fileName(path: string): string {
+  return path.split("/").at(-1) || path;
+}
+
+function isTextWorkspaceFile(contentType: string): boolean {
+  const mimeType = contentType.split(";")[0].trim().toLowerCase();
+  return mimeType.startsWith("text/") || mimeType === "application/json";
+}
+
+export const showWorkspaceFileAction = defineAction({
+  description:
+    "Render a workspace file as a downloadable card in chat. Call this after writing a user-requested export or other durable file with workspaceWrite; a file export is not complete until this action succeeds and the download card appears. The path must exactly match an existing file in the current organization or personal workspace.",
+  schema: z.object({
+    path: z
+      .string()
+      .trim()
+      .min(1)
+      .describe(
+        'Exact workspace-relative path returned by workspaceWrite, for example "exports/report.csv".',
+      ),
+  }),
+  outputSchema: workspaceFileResultSchema,
+  outputErrorStrategy: "strict",
+  http: false,
+  readOnly: true,
+  chatUI: {
+    renderer: ACTION_CHAT_UI_WORKSPACE_FILE_RENDERER,
+    title: "Workspace file",
+    description: "A private, downloadable workspace file.",
+  },
+  run: async ({ path }) => {
+    const file = await getWorkspaceFileMeta(currentWorkspaceScope(), path);
+    if (!file) {
+      throw new Error(`Workspace file not found: "${path}"`);
+    }
+    if (!isTextWorkspaceFile(file.contentType)) {
+      throw new Error(
+        `Workspace file "${path}" has unsupported content type "${file.contentType}". show-workspace-file currently supports text files and application/json.`,
+      );
+    }
+
+    return {
+      file: {
+        resourceId: file.id,
+        path: file.path,
+        name: fileName(file.path),
+        contentType: file.contentType,
+        sizeBytes: file.sizeBytes,
+        updatedAt: file.updatedAt,
+      },
+    };
+  },
+});
+
+export function createWorkspaceFileActionEntries(): Record<
+  string,
+  ActionEntry
+> {
+  return {
+    "show-workspace-file": showWorkspaceFileAction,
+  };
+}

package/corpus/core/src/workspace-files/tool.ts

@@ -133,7 +133,9 @@ export function createWorkspaceFilesTool(): Record<string, ActionEntry> {
               return JSON.stringify({
                 ok: true,
                 action: "write",
+                resourceId: meta.id,
                 path: meta.path,
+                contentType: meta.contentType,
                 sizeBytes: meta.sizeBytes,
                 updatedAt: meta.updatedAt,
               });
@@ -153,7 +155,9 @@ export function createWorkspaceFilesTool(): Record<string, ActionEntry> {
               return JSON.stringify({
                 ok: true,
                 action: "append",
+                resourceId: meta.id,
                 path: meta.path,
+                contentType: meta.contentType,
                 sizeBytes: meta.sizeBytes,
                 updatedAt: meta.updatedAt,
               });

package/corpus/templates/analytics/.agents/skills/analysis-workspace/SKILL.md

@@ -65,6 +65,10 @@ Inside `run-code`, use the workspace helper functions:
 - Direct writes cap at 2 MB each. `saveToFile` allows up to 20 MB per pull.
 - Temporary files belong under `scratch/`; durable user-facing files belong in
   normal Resources folders.
+- When the user asked for a file they can keep or download, call
+  `show-workspace-file` with the durable path immediately after the write. The
+  download must appear in chat; do not answer with only a path or navigation
+  instructions.
 
 ## Chunked Batch Analysis (30+ items)
 

package/corpus/templates/analytics/.agents/skills/hubspot/SKILL.md

@@ -2,7 +2,8 @@
 name: hubspot
 description: >-
   Query HubSpot CRM for deals, companies, contacts, tickets, owners, and
-  account/deal context.
+  account/deal context. Use when the user asks for HubSpot data or connection
+  status.
 ---
 
 # HubSpot
@@ -10,6 +11,13 @@ description: >-
 Use HubSpot for CRM facts: deal status, amount, stage, owner, forecast,
 associated account context, contacts, companies, and tickets.
 
+Analytics' HubSpot actions use its native provider credential or granted
+workspace connection. A missing optional HubSpot MCP server does not mean
+HubSpot is disconnected. Never send the user to HubSpot MCP setup to answer an
+Analytics data question. If availability is unclear, call `data-source-status`
+with `key: "hubspot"`; when it reports HubSpot configured, run the native
+HubSpot action directly.
+
 `hubspot-deals` is a legacy-named deal analytics shortcut, not the boundary of
 the HubSpot integration. If the user asks for any HubSpot object, endpoint,
 association, property, filter, batch read/write, or API version that the typed