@agent-native/core 0.129.2 → 0.130.0

package/corpus/templates/analytics/AGENTS.md

@@ -1,9 +1,8 @@
 # Analytics — Agent Guide
 
-Analytics is an agent-native BI workspace. The agent manages data sources,
-queries, dashboards, charts, and warehouse integrations through actions and
-SQL-backed state. Dashboards are the canonical user-facing artifact; legacy
-analyses remain readable only for compatibility.
+Analytics is an agent-native BI workspace for data sources, queries, dashboards,
+charts, and warehouse integrations. Dashboards are the canonical user-facing
+artifact; legacy analyses remain readable only for compatibility.
 
 **This agent is Claude with BigQuery/Gong/HubSpot/Prometheus access.** Reason
 over fetched data here; do not suggest another AI tool.
@@ -17,15 +16,12 @@ ladder.
 ## How To Answer A Data Question
 
 1. **Search existing work first.** Call `search-analytics-query-catalog` before
-   writing any new query. This is grep for analytics: someone has likely already
-   saved this query, and its SQL names the exact source, table, and columns.
-   Adapt the closest match to the requested filters and window, run it once, and
-   stop.
+   writing a query. Adapt the closest saved SQL to the requested filters and
+   window, run it once, and stop.
 2. **One bounded call.** List, filter, count, and cohort questions ("which X,
    excluding Y") are a single SQL statement, or one `run-code` script that
-   filters server-side. Never page through a cohort across separate tool calls
-   and never fan out per item to apply a filter — that is what turns a
-   ten-second answer into a twenty-minute one.
+   filters server-side. Never page through a cohort or fan out per item to apply
+   a filter.
 3. **Escalate only on a miss.** If the catalog returns nothing usable, make at
    most one discovery pass (`list-data-dictionary`, `search-bigquery-schema`,
    `data-source-status`), then query. Don't cross-check or add breakdowns
@@ -34,13 +30,14 @@ ladder.
    chart — never deflect to "check the dashboard." Keep native data widgets to
    already-summarized data (≤50 rows); above that, state the total and show the
    top rows.
-5. **Chunk only for reading.** Group into 5-10 with per-item notes only when 30+
+5. **Deliver exports in chat.** See `analysis-workspace`; never return only a
+   path or tell the user to find a download elsewhere.
+6. **Chunk only for reading.** Group into 5-10 with per-item notes only when 30+
    items each need qualitative reading no query can do (call transcripts, ticket
    threads). Chunking a question a query could answer is the most expensive
    mistake available here. See `adhoc-analysis`.
 
-Use `ask-question` (multiple choice, at most once per turn) only when metric
-definition, date range, or grain is genuinely ambiguous and a wrong guess would
+Use `ask-question` at most once when an ambiguous metric, range, or grain would
 change the numbers.
 
 ## Core Rules
@@ -49,10 +46,8 @@ change the numbers.
   semantics; only present values you actually retrieved, and state uncertainty.
 - Every analytical answer carries audit context: source(s), time window,
   filters, row count/sample size, join method, caveats.
-- Use actions for sources, queries, charts, dashboards, and sharing. Don't
-  bypass access checks with raw SQL for ownable resources. In dev call actions
-  with `pnpm action <name>`; in production call native tools. Use
-  `share-resource` / `set-resource-visibility` for sharing.
+- Use actions for sources, queries, charts, dashboards, and sharing. Don't bypass
+  access checks with raw SQL for ownable resources.
 - Provider actions are shortcuts, not limits — escalate to
   `provider-api-catalog` / `provider-api-docs` / `provider-api-request` when a
   canned action is too narrow. See `provider-api`.
@@ -66,14 +61,12 @@ change the numbers.
 - The `demo` source (Node Exporter) is demo data against a public endpoint.
   Never cite it as real analytics evidence unless the user asks about the demo
   dashboard.
-- Store large payloads (images, PDFs, exports, replay chunks, base64, `data:`
-  URLs) in file/blob storage — never in SQL tables, `application_state`,
-  `settings`, or `resources`. Persist URLs, ids, or handles.
+- Store large payloads in file/blob storage, never SQL or app state. Persist
+  only URLs, ids, or handles.
 - Never hardcode API keys, tokens, webhook URLs, secrets, private Builder data,
   or customer data. Use secrets/OAuth and obvious placeholders in examples.
-- External MCP callers should default to `ask_app` for multi-step work; the
-  curated read-only fallback catalog is bounded and user/org-scoped, and writes
-  stay `ask_app`-only. Backend reads always return real identities.
+- External MCP callers default to `ask_app` for multi-step work; fallback reads
+  are bounded and scoped, and writes stay `ask_app`-only.
 - Dashboard email reports and analytics alert rules are SQL-backed,
   self-describing action surfaces — don't hand-wire routes around them. Reports
   cap at five recipients. See `dashboard-ops`.

package/corpus/templates/analytics/actions/data-source-status.ts

@@ -29,6 +29,15 @@ const DATA_SOURCES_SETUP_LINK = buildDeepLink({
   to: "/data-sources",
 });
 
+function dataSourceSetupLink(provider: string): string {
+  const source = encodeURIComponent(provider);
+  return buildDeepLink({
+    app: APP_ID,
+    view: "data-sources",
+    to: `/data-sources?source=${source}&returnTo=ask`,
+  });
+}
+
 const BUILT_IN_FIRST_PARTY_PROVIDER = {
   provider: "first-party",
   label: "First-party Analytics",
@@ -74,7 +83,7 @@ async function listWorkspaceConnectionsForStatus(): Promise<{
 
 export default defineAction({
   description:
-    "List which analytics data sources are available without revealing secret values. This always includes the built-in first-party Analytics event store, which is queried with `query-agent-native-analytics`; it also reports configured credentials and granted workspace connections. The result includes `hasConnectedExternalDataSources`, `connectedExternalDataSourceCount`, and `dataSourcesSetupLink`; when a requested provider is unavailable, use that link for contextual setup guidance. The `key` arg accepts exact credential names like JIRA_API_TOKEN and provider aliases like jira, pylon, bigquery, github, hubspot, gong, or slack.",
+    "List which analytics data sources are available without revealing secret values. This always includes the built-in first-party Analytics event store, which is queried with `query-agent-native-analytics`; it also reports configured credentials and granted workspace connections. The result includes `hasConnectedExternalDataSources`, `connectedExternalDataSourceCount`, and `dataSourcesSetupLink`; each provider also includes a focused `setupLink`. When a requested provider is unavailable, use its focused link for contextual setup guidance. The `key` arg accepts exact credential names like JIRA_API_TOKEN and provider aliases like jira, pylon, bigquery, github, hubspot, gong, or slack.",
   schema: z.object({
     key: z
       .string()
@@ -198,6 +207,7 @@ export default defineAction({
         return {
           provider: provider.provider,
           label: provider.label,
+          setupLink: dataSourceSetupLink(provider.provider),
           // A failed workspace-connection lookup cannot prove a provider is
           // disconnected — a workspace-held connection lives in exactly the
           // data we could not read. Report null, never false.

package/corpus/templates/analytics/app/i18n-data.ts

@@ -858,6 +858,9 @@ const enUS = {
     githubOAuthUnavailable:
       "OAuth app credentials are not configured on this deployment. Use the personal access token field below.",
     sharedIntegration: "Shared integration",
+    workspaceAdminRequiredTitle: "Organization connection requires an admin",
+    workspaceAdminRequiredDescription:
+      "Ask an organization owner or admin to connect {{name}} for everyone in this organization.",
     sharedReady:
       "Analytics can use this provider through a workspace connection granted from Dispatch.",
     sharedNeedsGrant:
@@ -1325,6 +1328,9 @@ const analyticsSliceTranslations: {
       githubOAuthUnavailable:
         "此部署中未配置 OAuth 应用程序凭据。使用下面的个人访问令牌字段。",
       sharedIntegration: "共享集成",
+      workspaceAdminRequiredTitle: "组织连接需要管理员",
+      workspaceAdminRequiredDescription:
+        "请让组织所有者或管理员为此组织中的所有人连接 {{name}}。",
       sharedReady:
         "Analytics 可以通过 Dispatch 授予的工作空间连接来使用此提供程序。",
       sharedNeedsGrant: "存在工作区连接。打开Dispatch，授予Analytics访问权限。",
@@ -1618,6 +1624,10 @@ const analyticsSliceTranslations: {
       githubOAuthUnavailable:
         "Las credenciales de la aplicación OAuth no están configuradas en esta implementación. Utilice el campo de token de acceso personal a continuación.",
       sharedIntegration: "Integración compartida",
+      workspaceAdminRequiredTitle:
+        "La conexión de la organización requiere un administrador",
+      workspaceAdminRequiredDescription:
+        "Pide a un propietario o administrador de la organización que conecte {{name}} para todos.",
       sharedReady:
         "Analytics puede utilizar este proveedor a través de una conexión de espacio de trabajo otorgada por Dispatch.",
       sharedNeedsGrant:
@@ -1930,6 +1940,10 @@ const analyticsSliceTranslations: {
       githubOAuthUnavailable:
         "Les informations d'identification de l'application OAuth ne sont pas configurées sur ce déploiement. Utilisez le champ du jeton d'accès personnel ci-dessous.",
       sharedIntegration: "Intégration partagée",
+      workspaceAdminRequiredTitle:
+        "La connexion de l’organisation nécessite un administrateur",
+      workspaceAdminRequiredDescription:
+        "Demandez à un propriétaire ou administrateur de l’organisation de connecter {{name}} pour tous.",
       sharedReady:
         "Analytics peut utiliser ce fournisseur via une connexion à l'espace de travail accordée par Dispatch.",
       sharedNeedsGrant:
@@ -2240,6 +2254,10 @@ const analyticsSliceTranslations: {
       githubOAuthUnavailable:
         "Die Anmeldeinformationen für die OAuth-App sind in dieser Bereitstellung nicht konfiguriert. Verwenden Sie das Feld für das persönliche Zugriffstoken unten.",
       sharedIntegration: "Gemeinsame Integration",
+      workspaceAdminRequiredTitle:
+        "Für die Organisationsverbindung ist ein Administrator erforderlich",
+      workspaceAdminRequiredDescription:
+        "Bitte einen Organisationsinhaber oder Administrator, {{name}} für alle zu verbinden.",
       sharedReady:
         "Analytics kann diesen Anbieter über eine von Dispatch gewährte Workspace-Verbindung nutzen.",
       sharedNeedsGrant:
@@ -2548,6 +2566,9 @@ const analyticsSliceTranslations: {
       githubOAuthUnavailable:
         "OAuth アプリの資格情報は、この展開では構成されていません。以下の個人アクセス トークン フィールドを使用してください。",
       sharedIntegration: "共有統合",
+      workspaceAdminRequiredTitle: "組織の接続には管理者が必要です",
+      workspaceAdminRequiredDescription:
+        "組織の所有者または管理者に、組織全体で {{name}} を接続するよう依頼してください。",
       sharedReady:
         "Analytics は、Dispatch から付与されたワークスペース接続を通じてこのプロバイダーを使用できます。",
       sharedNeedsGrant:
@@ -2850,6 +2871,9 @@ const analyticsSliceTranslations: {
       githubOAuthUnavailable:
         "이 배포에서는 OAuth 앱 자격 증명이 구성되지 않습니다. 아래의 개인 액세스 토큰 필드를 사용하세요.",
       sharedIntegration: "공유 통합",
+      workspaceAdminRequiredTitle: "조직 연결에는 관리자가 필요합니다",
+      workspaceAdminRequiredDescription:
+        "조직 소유자 또는 관리자에게 조직의 모든 사용자를 위해 {{name}} 연결을 요청하세요.",
       sharedReady:
         "Analytics는 Dispatch에서 부여된 작업 공간 연결을 통해 이 공급자를 사용할 수 있습니다.",
       sharedNeedsGrant:
@@ -3149,6 +3173,10 @@ const analyticsSliceTranslations: {
       githubOAuthUnavailable:
         "As credenciais do aplicativo OAuth não estão configuradas nesta implantação. Use o campo de token de acesso pessoal abaixo.",
       sharedIntegration: "Integração compartilhada",
+      workspaceAdminRequiredTitle:
+        "A conexão da organização requer um administrador",
+      workspaceAdminRequiredDescription:
+        "Peça a um proprietário ou administrador da organização para conectar {{name}} para todos.",
       sharedReady:
         "Analytics pode usar este provedor por meio de uma conexão de espaço de trabalho concedida pelo Dispatch.",
       sharedNeedsGrant:
@@ -3453,6 +3481,9 @@ const analyticsSliceTranslations: {
       githubOAuthUnavailable:
         "इस परिनियोजन पर OAuth ऐप क्रेडेंशियल कॉन्फ़िगर नहीं किए गए हैं। नीचे व्यक्तिगत एक्सेस टोकन फ़ील्ड का उपयोग करें।",
       sharedIntegration: "साझा एकीकरण",
+      workspaceAdminRequiredTitle: "संगठन कनेक्शन के लिए एडमिन आवश्यक है",
+      workspaceAdminRequiredDescription:
+        "संगठन के मालिक या एडमिन से सभी के लिए {{name}} कनेक्ट करने को कहें।",
       sharedReady:
         "Analytics इस प्रदाता का उपयोग Dispatch से दिए गए कार्यक्षेत्र कनेक्शन के माध्यम से कर सकता है।",
       sharedNeedsGrant:
@@ -3748,6 +3779,9 @@ const analyticsSliceTranslations: {
       githubOAuthUnavailable:
         "لم يتم تكوين بيانات اعتماد تطبيق OAuth في هذا النشر. استخدم حقل رمز الوصول الشخصي أدناه.",
       sharedIntegration: "التكامل المشترك",
+      workspaceAdminRequiredTitle: "يتطلب اتصال المؤسسة مشرفًا",
+      workspaceAdminRequiredDescription:
+        "اطلب من مالك المؤسسة أو أحد المشرفين ربط {{name}} لجميع أعضاء المؤسسة.",
       sharedReady:
         "يمكن لـ Analytics استخدام هذا الموفر من خلال اتصال مساحة العمل الممنوح من Dispatch.",
       sharedNeedsGrant:

package/corpus/templates/analytics/app/lib/data-source-status.ts

@@ -30,6 +30,7 @@ export interface WorkspaceConnectionProviderSummary {
 export interface DataSourceProviderStatus {
   provider: string;
   label: string;
+  setupLink?: string;
   // null when the workspace-connection lookup failed: unreadable, not absent.
   configured: boolean | null;
   configuredKeys: string[];
@@ -75,6 +76,91 @@ const dataSourceWorkspaceProviderIds: Record<string, string> = {
   slack: "slack",
 };
 
+const workspaceOAuthSourceIds = new Set([
+  "notion",
+  "hubspot",
+  "jira",
+  "sentry",
+]);
+
+export function isWorkspaceOAuthSource(source: DataSource): boolean {
+  return workspaceOAuthSourceIds.has(source.id);
+}
+
+export function shouldShowWorkspaceOAuthSetup(
+  source: DataSource,
+  status: SharedConnectionStatus | null,
+  canManageOrg: boolean,
+): boolean {
+  return (
+    canManageOrg &&
+    (status?.kind === "needs_credentials" || status?.kind === "needs_grant") &&
+    isWorkspaceOAuthSource(source)
+  );
+}
+
+export function shouldShowWorkspaceOAuthAdminNotice(
+  source: DataSource,
+  ready: boolean,
+  canManageOrg: boolean,
+  orgLoaded = true,
+  hasOrg = true,
+): boolean {
+  return (
+    orgLoaded &&
+    hasOrg &&
+    !canManageOrg &&
+    !ready &&
+    isWorkspaceOAuthSource(source)
+  );
+}
+
+export function shouldOfferWorkspaceOAuthReconnect(
+  source: DataSource,
+  status: SharedConnectionStatus | null,
+  canManageOrg: boolean,
+  connectionTestFailed: boolean,
+): boolean {
+  return (
+    canManageOrg &&
+    connectionTestFailed &&
+    status?.kind === "ready" &&
+    isWorkspaceOAuthSource(source)
+  );
+}
+
+export type FocusedDataSourceResolution =
+  | { status: "none" }
+  | { status: "found"; source: DataSource }
+  | { status: "unknown"; requestedId: string };
+
+export function focusedDataSourceFromSearchParams(
+  searchParams: URLSearchParams,
+): FocusedDataSourceResolution {
+  const requestedSourceId = searchParams.get("source")?.trim().toLowerCase();
+  if (!requestedSourceId) return { status: "none" };
+
+  // Keep links emitted before PostgreSQL's provider id was aligned with the
+  // UI source id working instead of silently dropping their focus.
+  const sourceId =
+    requestedSourceId === "postgres" ? "postgresql" : requestedSourceId;
+  const source = dataSources.find((candidate) => candidate.id === sourceId);
+  return source
+    ? { status: "found", source }
+    : { status: "unknown", requestedId: requestedSourceId };
+}
+
+export function dataSourceOAuthReturnPath(
+  source: DataSource | undefined,
+  returnToAsk: boolean,
+): string {
+  const params = new URLSearchParams();
+  if (source) params.set("source", source.id);
+  if (returnToAsk) params.set("returnTo", "ask");
+  const query = params.toString();
+  return query ? `/data-sources?${query}` : "/data-sources";
+}
+
 export function getGoogleDriveConnection(
   data: DataSourceStatusResponse | undefined,
 ): WorkspaceConnectionProviderSummary | undefined {

package/corpus/templates/analytics/app/lib/native-mcp-exclusions.ts

@@ -0,0 +1,9 @@
+export const ANALYTICS_NATIVE_MCP_PRESET_EXCLUSIONS = [
+  "atlassian",
+  "github",
+  "hubspot",
+  "notion",
+  "sentry",
+  "slack",
+  "stripe",
+] as const;