@agent-native/core 0.119.2 → 0.119.4

package/corpus/templates/analytics/server/lib/analytics-query-catalog.ts

@@ -0,0 +1,405 @@
+import { getAllSettings, listOrgSettings } from "@agent-native/core/settings";
+
+import { dashboardCatalogEntries } from "./dashboard-catalog";
+import { listDashboards, type DashboardRecord } from "./dashboards-store";
+
+const DATA_DICTIONARY_KEY_PREFIX = "data-dict-";
+const MAX_QUERY_LENGTH = 12_000;
+const STOP_WORDS = new Set([
+  "a",
+  "all",
+  "an",
+  "and",
+  "are",
+  "by",
+  "count",
+  "data",
+  "day",
+  "days",
+  "do",
+  "exact",
+  "find",
+  "for",
+  "from",
+  "get",
+  "give",
+  "how",
+  "i",
+  "in",
+  "last",
+  "look",
+  "many",
+  "me",
+  "metric",
+  "number",
+  "of",
+  "on",
+  "over",
+  "our",
+  "please",
+  "show",
+  "that",
+  "the",
+  "this",
+  "time",
+  "today",
+  "total",
+  "up",
+  "week",
+  "what",
+  "were",
+  "we",
+  "yesterday",
+]);
+
+type DictionaryEntry = Record<string, unknown>;
+type DashboardPanel = Record<string, unknown>;
+
+export type AnalyticsQueryCatalogCandidate =
+  | {
+      kind: "dashboard-panel";
+      origin: "saved-dashboard" | "dashboard-template";
+      score: number;
+      matchedTerms: string[];
+      dashboardId: string;
+      dashboardTitle: string;
+      dashboardDescription?: string;
+      panelId: string;
+      panelTitle: string;
+      panelDescription?: string;
+      source?: string;
+      query: string | Record<string, unknown>;
+      timeScope?: string;
+    }
+  | {
+      kind: "data-dictionary";
+      origin: "data-dictionary";
+      score: number;
+      matchedTerms: string[];
+      id: string;
+      metric: string;
+      definition?: string;
+      source?: string;
+      action?: string;
+      table?: string;
+      columnsUsed?: string;
+      queryTemplate?: string;
+      knownGotchas?: string;
+      approved?: boolean;
+      aiGenerated?: boolean;
+      sourceUrl?: string;
+    };
+
+function text(value: unknown): string {
+  return typeof value === "string" ? value.trim() : "";
+}
+
+function compactQuery(value: unknown): string | Record<string, unknown> | null {
+  if (typeof value === "string") {
+    const trimmed = value.trim();
+    return trimmed ? trimmed.slice(0, MAX_QUERY_LENGTH) : null;
+  }
+  if (value && typeof value === "object" && !Array.isArray(value)) {
+    return value as Record<string, unknown>;
+  }
+  return null;
+}
+
+function searchTerms(search: string): string[] {
+  const normalized = search
+    .toLowerCase()
+    .replace(/[^a-z0-9]+/g, " ")
+    .trim();
+  if (!normalized) return [];
+  const meaningful = normalized
+    .split(/\s+/)
+    .filter((term) => term.length > 1 && !STOP_WORDS.has(term));
+  return meaningful.length ? Array.from(new Set(meaningful)) : [normalized];
+}
+
+function matchScore(
+  search: string,
+  weightedFields: Array<{ value: unknown; weight: number }>,
+): { score: number; matchedTerms: string[] } {
+  const terms = searchTerms(search);
+  if (!terms.length) return { score: 0, matchedTerms: [] };
+
+  const normalizedSearch = search.toLowerCase().trim();
+  const matched = new Set<string>();
+  let score = 0;
+  for (const field of weightedFields) {
+    const value = text(field.value).toLowerCase();
+    if (!value) continue;
+    if (normalizedSearch.length > 2 && value.includes(normalizedSearch)) {
+      score += field.weight * 4;
+    }
+    for (const term of terms) {
+      if (!value.includes(term)) continue;
+      matched.add(term);
+      score += field.weight;
+    }
+  }
+
+  if (matched.size === terms.length) score += 40;
+  return { score, matchedTerms: [...matched] };
+}
+
+function dashboardPanelCandidates(args: {
+  dashboardId: string;
+  dashboardTitle: string;
+  dashboardDescription?: string;
+  config: Record<string, unknown>;
+  origin: "saved-dashboard" | "dashboard-template";
+  search: string;
+}): AnalyticsQueryCatalogCandidate[] {
+  const panels = Array.isArray(args.config.panels)
+    ? (args.config.panels as DashboardPanel[])
+    : [];
+
+  return panels.flatMap((panel) => {
+    const query = compactQuery(panel.sql);
+    if (!query) return [];
+    const panelConfig =
+      panel.config &&
+      typeof panel.config === "object" &&
+      !Array.isArray(panel.config)
+        ? (panel.config as Record<string, unknown>)
+        : {};
+    const panelTitle = text(panel.title) || text(panel.id);
+    const panelDescription = text(panelConfig.description);
+    const { score: rawScore, matchedTerms } = matchScore(args.search, [
+      { value: panelTitle, weight: 24 },
+      { value: panelDescription, weight: 12 },
+      { value: args.dashboardTitle, weight: 10 },
+      { value: args.dashboardDescription, weight: 6 },
+      { value: panel.source, weight: 5 },
+      {
+        value: typeof query === "string" ? query : JSON.stringify(query),
+        weight: 2,
+      },
+    ]);
+    const requestedTerms = new Set(searchTerms(args.search));
+    const titleSpecificityPenalty =
+      searchTerms(panelTitle).filter((term) => !requestedTerms.has(term))
+        .length * 12;
+    const aggregateIntent =
+      /\b(how many|count|number|total)\b/i.test(args.search) &&
+      text(panel.chartType) === "metric"
+        ? 20
+        : 0;
+    const score = rawScore - titleSpecificityPenalty + aggregateIntent;
+    if (score <= 0) return [];
+
+    return [
+      {
+        kind: "dashboard-panel" as const,
+        origin: args.origin,
+        score,
+        matchedTerms,
+        dashboardId: args.dashboardId,
+        dashboardTitle: args.dashboardTitle,
+        ...(args.dashboardDescription
+          ? { dashboardDescription: args.dashboardDescription }
+          : {}),
+        panelId: text(panel.id),
+        panelTitle,
+        ...(panelDescription ? { panelDescription } : {}),
+        ...(text(panel.source) ? { source: text(panel.source) } : {}),
+        query,
+        ...(text(panelConfig.timeScope)
+          ? { timeScope: text(panelConfig.timeScope) }
+          : {}),
+      },
+    ];
+  });
+}
+
+function dictionaryCandidates(
+  entries: DictionaryEntry[],
+  search: string,
+): AnalyticsQueryCatalogCandidate[] {
+  return entries.flatMap((entry) => {
+    const { score, matchedTerms } = matchScore(search, [
+      { value: entry.metric, weight: 28 },
+      { value: entry.commonQuestions, weight: 16 },
+      { value: entry.definition, weight: 12 },
+      { value: entry.table, weight: 8 },
+      { value: entry.columnsUsed, weight: 6 },
+      { value: entry.queryTemplate, weight: 5 },
+      { value: entry.source, weight: 5 },
+      { value: entry.action, weight: 5 },
+      { value: entry.knownGotchas, weight: 2 },
+    ]);
+    if (!score) return [];
+
+    const id = text(entry.id);
+    const metric = text(entry.metric);
+    if (!id || !metric) return [];
+    return [
+      {
+        kind: "data-dictionary" as const,
+        origin: "data-dictionary" as const,
+        score: score + (entry.approved === true ? 12 : 0),
+        matchedTerms,
+        id,
+        metric,
+        ...(text(entry.definition)
+          ? { definition: text(entry.definition) }
+          : {}),
+        ...(text(entry.source) ? { source: text(entry.source) } : {}),
+        ...(text(entry.action) ? { action: text(entry.action) } : {}),
+        ...(text(entry.table) ? { table: text(entry.table) } : {}),
+        ...(text(entry.columnsUsed)
+          ? { columnsUsed: text(entry.columnsUsed) }
+          : {}),
+        ...(text(entry.queryTemplate)
+          ? { queryTemplate: text(entry.queryTemplate) }
+          : {}),
+        ...(text(entry.knownGotchas)
+          ? { knownGotchas: text(entry.knownGotchas) }
+          : {}),
+        ...(typeof entry.approved === "boolean"
+          ? { approved: entry.approved }
+          : {}),
+        ...(typeof entry.aiGenerated === "boolean"
+          ? { aiGenerated: entry.aiGenerated }
+          : {}),
+        ...(text(entry.sourceUrl) ? { sourceUrl: text(entry.sourceUrl) } : {}),
+      },
+    ];
+  });
+}
+
+export function rankAnalyticsQueryCatalog(args: {
+  search: string;
+  dashboards: Array<{
+    id: string;
+    title: string;
+    description?: string;
+    config: Record<string, unknown>;
+    origin: "saved-dashboard" | "dashboard-template";
+  }>;
+  dictionaryEntries: DictionaryEntry[];
+  limit: number;
+}): AnalyticsQueryCatalogCandidate[] {
+  const candidates = [
+    ...args.dashboards.flatMap((dashboard) =>
+      dashboardPanelCandidates({
+        dashboardId: dashboard.id,
+        dashboardTitle: dashboard.title,
+        dashboardDescription: dashboard.description,
+        config: dashboard.config,
+        origin: dashboard.origin,
+        search: args.search,
+      }),
+    ),
+    ...dictionaryCandidates(args.dictionaryEntries, args.search),
+  ];
+
+  return candidates
+    .sort((a, b) => {
+      if (b.score !== a.score) return b.score - a.score;
+      if (a.kind !== b.kind) return a.kind === "data-dictionary" ? -1 : 1;
+      return JSON.stringify(a).localeCompare(JSON.stringify(b));
+    })
+    .slice(0, args.limit);
+}
+
+async function listDictionaryEntries(args: {
+  email: string;
+  orgId: string | null;
+}): Promise<DictionaryEntry[]> {
+  const entries: DictionaryEntry[] = [];
+  const seen = new Set<string>();
+  const collect = (raw: unknown) => {
+    if (!raw || typeof raw !== "object" || Array.isArray(raw)) return;
+    const entry = raw as DictionaryEntry;
+    const id = text(entry.id);
+    if (!id || seen.has(id)) return;
+    seen.add(id);
+    entries.push(entry);
+  };
+
+  if (args.orgId) {
+    const orgEntries = await listOrgSettings(
+      args.orgId,
+      DATA_DICTIONARY_KEY_PREFIX,
+    );
+    for (const value of Object.values(orgEntries)) collect(value);
+  }
+
+  const userPrefix = `u:${args.email}:${DATA_DICTIONARY_KEY_PREFIX}`;
+  const all = await getAllSettings();
+  for (const [key, value] of Object.entries(all)) {
+    if (key.startsWith(userPrefix)) collect(value);
+  }
+  return entries;
+}
+
+function savedDashboardInput(dashboard: DashboardRecord) {
+  const config = dashboard.config as Record<string, unknown>;
+  return {
+    id: dashboard.id,
+    title: text(config.name) || dashboard.title,
+    description: text(config.description) || undefined,
+    config,
+    origin: "saved-dashboard" as const,
+  };
+}
+
+export async function searchAnalyticsQueryCatalog(args: {
+  search: string;
+  email: string;
+  orgId: string | null;
+  limit: number;
+}): Promise<AnalyticsQueryCatalogCandidate[]> {
+  const [savedDashboardsResult, dictionaryEntriesResult] =
+    await Promise.allSettled([
+      listDashboards(
+        { email: args.email, orgId: args.orgId },
+        { kind: "sql", archived: "active", hidden: "visible" },
+      ),
+      listDictionaryEntries({ email: args.email, orgId: args.orgId }),
+    ]);
+  const savedDashboards =
+    savedDashboardsResult.status === "fulfilled"
+      ? savedDashboardsResult.value
+      : [];
+  const dictionaryEntries =
+    dictionaryEntriesResult.status === "fulfilled"
+      ? dictionaryEntriesResult.value
+      : [];
+
+  const savedIds = new Set(savedDashboards.map((dashboard) => dashboard.id));
+  const templateDashboards = dashboardCatalogEntries
+    .filter((entry) => !savedIds.has(entry.defaultDashboardId))
+    .flatMap((entry) => {
+      try {
+        const config = entry.buildConfig() as unknown as Record<
+          string,
+          unknown
+        >;
+        return [
+          {
+            id: entry.defaultDashboardId,
+            title: text(config.name) || entry.name,
+            description: text(config.description) || entry.description,
+            config,
+            origin: "dashboard-template" as const,
+          },
+        ];
+      } catch {
+        return [];
+      }
+    });
+
+  return rankAnalyticsQueryCatalog({
+    search: args.search,
+    dashboards: [
+      ...savedDashboards.map(savedDashboardInput),
+      ...templateDashboards,
+    ],
+    dictionaryEntries,
+    limit: args.limit,
+  });
+}

package/corpus/templates/analytics/server/plugins/agent-chat.ts

@@ -46,11 +46,11 @@ const ANALYTICS_DATA_SOURCES_LINK = buildDeepLink({
   to: "/data-sources",
 });
 
-export const SIMPLE_TIME_BOUNDED_METRIC_FAST_PATH_GUIDANCE =
-  "SIMPLE TIME-BOUNDED METRIC FAST PATH — When the data dictionary or a known canonical source identifies the metric, run one bounded aggregate. Once it returns a valid result, answer the explicit question immediately with the source, time window, row count, and only necessary caveats. Do not schema-discover, retry, enrich, cross-check, or add breakdowns after that successful result unless the query failed or the result conflicts with the known metric definition. This does not waive the real-data requirement: never answer from a guess, stale value, or unverified result. ";
+export const BOUNDED_STRUCTURED_LOOKUP_GUIDANCE =
+  "BOUNDED STRUCTURED LOOKUP FAST PATH — Treat existing analytics work like an engineer treats existing code: grep before writing. For an ordinary count, aggregate, grouped metric, trend, or record lookup, first call `search-analytics-query-catalog` once with focused metric/entity terms. It searches accessible dashboard names, chart titles/descriptions/saved queries, shipped dashboard patterns, and data-dictionary definitions together. Prefer the strongest approved dictionary or saved-chart match, preserve its source and business logic, adapt only the requested filters and explicit time window, then run one bounded query against that source. A user-named source wins, but still use a matching saved definition when it supplies the source's proven query shape. If there is no useful match, inspect only the most likely source schema or ask one clarification; do not fan out across providers. Do not separately list every dashboard, call data-source status, browse the whole dictionary, load provider catalogs/corpus tools, or query a second source after a strong match. Once the query succeeds, answer immediately with its source, time window, filters, row count, and only necessary caveats. Do not enrich, cross-check, retry, or add breakdowns unless the user requested them, the first query failed, or its result conflicts with the known definition. The words `all`, `total`, or `exact` in a structured aggregate do not by themselves make it a corpus investigation. Never repeat an identical invalid or failed tool call; correct its arguments once or surface the error. This does not waive the real-data requirement: never answer from a guess, stale value, or unverified result. ";
 
 export const BUILT_IN_FIRST_PARTY_SOURCE_GUIDANCE =
-  "BUILT-IN FIRST-PARTY SOURCE — Analytics always provides one built-in first-party source alongside connected external providers such as BigQuery, HubSpot, Gong, Slack, and the other configured integrations. This does not replace or restrict external sources. For Builder/product signups, page views, app/template usage, conversions, and LLM observability, use `query-agent-native-analytics` over `analytics_events` (or `session_recordings` for replay summaries) when the event lives in first-party Analytics. When the user names an external provider, or the data dictionary identifies one as authoritative, query that provider instead. Do not report the first-party source as disconnected merely because an external provider is not configured. If the first-party query returns no rows, report that grounded result with its scope and time window. ";
+  "BUILT-IN FIRST-PARTY SOURCE — Analytics always provides one built-in first-party source alongside connected external providers such as BigQuery, HubSpot, Gong, Slack, and the other configured integrations. This does not replace or restrict external sources. When `search-analytics-query-catalog` identifies a first-party dashboard/chart definition, preserve its event semantics and use `query-agent-native-analytics` over `analytics_events` or `session_recordings` as appropriate. When the user names an external provider, or the catalog identifies one as authoritative, query that provider instead. Do not report the first-party source as disconnected merely because an external provider is not configured. If the authoritative query returns no rows, report that grounded result with its scope and time window. ";
 
 export const ANALYTICS_OBSERVABILITY_INCIDENT_GUIDANCE =
   "OBSERVABILITY INCIDENT WORKFLOW — For a named user's session or error question, resolve the user's email from context, then use list-session-recordings with userId over a bounded recent window to discover the relevant sessions. Do not require hasErrors=true for this initial lookup: replay/network/stuck-run evidence can exist while the recording's JavaScript errorCount is zero. Use hasErrors=true only when the user specifically asks for recordings with captured JavaScript errors or the recording metadata confirms that filter is appropriate. Use list-error-issues with userId or sessionRecordingId to identify a grouped issue, then get-error-issue for stack, breadcrumbs, occurrences, and linked recordings. For console diagnostics or failed network requests, create-session-replay-agent-link first and use its scoped diagnostics endpoint for detailed error text, stacks, request metadata, and bounded 5xx snippets; enumerate with kind/limit and fromMs/toMs or offset when needed. Use get-session-replay-summary and get-session-replay-timeline for the page-navigation and click sequence, and use get-session-replay-events only for additional bounded replay-event details. If no grouped error exists, correlate first-party observability events such as agent_chat_stuck_detected with query-agent-native-analytics in execution mode. In Plan mode, query-agent-native-analytics is intentionally unavailable: do not claim a live event correlation or root cause from it, and describe the event lookup as a planned next step. Prefer these first-party actions over generic SQL. Report the matching evidence and do not claim a root cause without a corroborating error, event, or replay signal. ";
@@ -75,7 +75,7 @@ export function analyticsSourceGuidanceOpening(): string {
     "<data-source-guidance>\n" +
     "Apply real-data requirements only when presenting analytics results, source records, or derived metrics. Do not call data-source tools for workflow migration, recurring-job setup, UI/code fixes, settings help, conceptual planning, or other non-data tasks unless the user explicitly asks for data. " +
     NON_ANALYTICS_REQUEST_GUIDANCE +
-    SIMPLE_TIME_BOUNDED_METRIC_FAST_PATH_GUIDANCE +
+    BOUNDED_STRUCTURED_LOOKUP_GUIDANCE +
     BUILT_IN_FIRST_PARTY_SOURCE_GUIDANCE +
     ANALYTICS_OBSERVABILITY_INCIDENT_GUIDANCE +
     `DATA-SOURCE SETUP UX — Chat remains available when no external data source is connected. For a live-data request that needs an unavailable external provider, explain what is missing in the context of the user's question and guide them naturally to [Connect data sources](${ANALYTICS_DATA_SOURCES_LINK}). Use that real link from the app; do not emit a generic canned no-data sentence. For general conversation, conceptual questions, and questions the built-in first-party source can answer, continue helping normally. ` +
@@ -85,7 +85,7 @@ export function analyticsSourceGuidanceOpening(): string {
 
 export function analyticsDataDictionaryRoutingContext(): string {
   return `<data-dictionary-routing>
-Data-dictionary definitions are available on demand instead of being embedded in every chat request. Before writing SQL or making a metric-definition claim, call \`list-data-dictionary\` with a focused \`search\` or \`department\` filter. If the user asks what definitions exist and no useful filter is available, call it without filters. Treat approved entries as canonical, verify unreviewed human entries when stakes are high, and treat AI-generated unapproved entries as suggestions only. If no matching definition exists, inspect the configured source schema or ask the user instead of guessing.
+Data-dictionary definitions are available through \`search-analytics-query-catalog\`, which combines focused dictionary lookup with a search over existing dashboard/chart SQL. Use that combined catalog search as the normal preflight for a bounded metric lookup. Call \`list-data-dictionary\` separately only when the user asks to browse definitions or filter them by department. Treat approved entries as canonical, verify unreviewed human entries when stakes are high, and treat AI-generated unapproved entries as suggestions only. After the catalog identifies one source and query shape, query that source once and stop on success. If no matching definition or chart exists, inspect only the most likely source schema or ask the user instead of fanning out across providers.
 </data-dictionary-routing>`;
 }
 
@@ -675,6 +675,7 @@ export default createAgentChatPlugin({
     loadActionsFromStaticRegistry(actionsRegistry),
   ),
   initialToolNames: INITIAL_TOOL_NAMES,
+  corpusTools: "lazy",
   finalResponseGuard: realDataFinalGuard,
   // Enable sandboxed JavaScript execution for analytics data processing.
   // Code runs in an isolated Node.js child process with no access to app
@@ -717,18 +718,12 @@ export default createAgentChatPlugin({
       'DASHBOARD REORDER RULE — For simple chart/section moves, use `mutate-dashboard` code such as `dashboard.panels(["panel-a","panel-b"]).moveToTop();`. For visible placement requests like "second row" or "next to return rates", use row-aware placement such as `dashboard.insertPanel({...}).nextTo("retention-over-time")`, `.atRow(2)`, or `dashboard.panel("panel-a").moveNextTo("panel-b")`; these keep panels in the intended rendered row and expand/rebalance that row when needed. Never count shifting `/panels/<index>` positions for ordinary \'move this chart\' requests. Use `get-sql-dashboard.layout.groups[].rows` as proof of visible row placement, not only flat `panelOrder`. ' +
       "Use configured data sources and actions only. The built-in first-party Analytics source is an additional source and is always available through `query-agent-native-analytics`, even when no external provider credentials are connected. External provider actions remain available and are the authoritative path when the user names a provider or the data lives there. Call `data-source-status` when you need to know which external providers are connected, and treat provider actions as unavailable for analysis only if they return missing credentials, permission, syntax, quota, or network errors. " +
       "The built-in `demo` dashboard source is a demo-environment Prometheus source reserved for the Node Exporter demo. It must never satisfy REAL_DATA_REQUIRED or be cited as user analytics evidence unless the user explicitly asks to inspect the demo dashboard. " +
-      "When the user names a provider or tool such as Jira, Pylon, HubSpot, Gong, Slack, Sentry, GA4, or BigQuery, that named source is authoritative for the turn: use that provider's real tool/API surface, not a warehouse or different-provider substitute, unless the user explicitly asks for the copy/fallback. For bounded lookups where a first-class action fully models the requested source, object, filter, and pagination need, that shortcut is fine. For broad provider searches, cross-source joins, corpus-wide counts, exact cohort coverage, or any answer where absence matters, do not start and stop with shortcuts; use the broad provider API/MCP and corpus/code workflow as the primary path. " +
-      "Provider-specific actions are shortcuts, not limits. If a first-class action cannot express the exact endpoint, object type, filters, request body, pagination mode, API version, or corpus coverage needed, call `provider-api-catalog` and `provider-api-docs` as needed, then call `provider-api-request` against the provider's real HTTP API. Use this raw provider API escape hatch instead of weakening the analysis, broadening filters, sampling default pages, or claiming the integration cannot do something the underlying API can do. " +
-      "When one provider cohort becomes the input to a second provider search, join, or exhaustive corpus scan, stage the upstream cohort with `provider-api-request`/`stageAs` (or a native provider API/MCP bulk primitive) before the downstream search. Avoid starting such workflows with convenience list/search actions that return display-shaped pages or can time out before the corpus path is established. " +
-      'For broad unstructured provider records such as transcripts, messages, tickets, issues, notes, events, documents, or conversation logs, prefer `provider-corpus-job` so the scan has durable checkpoints, stored snippets, coverage counts, and provider quota pause/resume. Use mode="paginated-search" for any provider endpoint that already pages over the target records; use mode="batch-search" when a staged upstream cohort of ids/records must feed a second provider endpoint by `itemBodyPath` or `itemQueryParam`. Continue paused jobs until completed or quota_wait, then read results. Use `run-code` with `providerSearchAll`, `providerFetch`, `appAction`, `workspaceRead`, and Resources-backed workspace files for shorter reductions, joins, classification, and aggregation after the corpus path is established. Convenience actions are bounded shortcuts for common checks, not the ceiling for what the underlying provider API can answer. ' +
-      "When the user asks to search source-record body text, use the raw body endpoint or native provider search for that record type. Parent/container metadata such as call lists, titles, summaries, briefs, channel lists, ticket lists, or issue lists can discover scope but cannot support a complete body-text absence claim. " +
-      "For source-record mention searches, phrase searches, and absence checks across transcripts/messages/tickets/issues, prefer provider-side search, `provider-corpus-job`, staged corpus, `providerSearchAll`, or action-side search arguments that return counts, coverage, and snippets instead of loading raw full records into chat. Use full transcripts/messages only for selected evidence after the search narrows the corpus, and state whether the search covered every matching record or only a bounded sample. " +
-      "For complex provider questions, broad searches, corpus-wide counts, cross-source joins, or any answer where absence matters, prefer a corpus-first workflow: inspect the provider API, fetch every relevant page or an explicitly bounded cohort, stage large responses with `saveToFile`/`stageAs`/`fetchAllPages`, use `provider-corpus-job` for durable long-running searches, and use `run-code` with `providerSearchAll`, `providerFetch`, `appAction`, and Resources-backed workspace files to join, search, classify, and aggregate. Use `scratch/` for temporary staging and durable folder names only for files the user should keep. Do not infer no results from sampled records, default limits, truncated excerpts, or aborted calls. If full coverage is not possible in the turn, say exactly what was inspected and what remains uncovered. " +
-      'For HubSpot deal cohorts, structured `hubspot-deals` filters can enumerate a bounded cohort for direct deal-list answers: `product` for the `products` field, `pipeline` for pipeline label/id, `closedStatus` for won/lost/open/closed, and `closedDateFrom`/`closedDateTo` for close-date windows. The `query` argument is full-text deal search and is not proof that a specific property matched; do not use `query: "Publish"` when the user asked for products field = Publish. If the cohort feeds transcript/message/ticket search, a cross-source join, or exhaustive/absence-sensitive coverage, use `provider-api-request` with HubSpot search and `stageAs` for the cohort first, then continue with the provider API/corpus workflow. Report the returned filter values and cohort count in the methodology. ' +
-      "For named deal, account, renewal, churn-risk, or customer deep dives that need HubSpot and Gong context, `account-deep-dive` can provide a bounded evidence bundle. Use it when the user asks for a targeted entity deep dive, then use the broad provider API/corpus workflow for any requested exhaustive transcript/message/ticket search or absence claim. Do not answer a requested transcript deep dive from call metadata alone. " +
+      "When the user names a provider such as first-party Analytics, BigQuery, HubSpot, Gong, Jira, Pylon, Slack, Sentry, GA4, or another connected source, that source is authoritative for the turn. Use its first-class query action when available; if it is not on the initial tool surface, use tool-search for that provider instead of loading unrelated catalogs. For an ordinary structured lookup, make one bounded query and stop on success. " +
+      "Load provider API, corpus, staging, or code tools only when the user explicitly requests cross-source work, exhaustive unstructured-record coverage, or an absence claim that the first-class action cannot support. For those genuinely broad workflows, fetch every relevant page or an explicitly bounded cohort, preserve coverage counts, and state any uncovered records. " +
+      "For named deal, account, renewal, churn-risk, or customer deep dives that need HubSpot and Gong context, `account-deep-dive` can provide a bounded evidence bundle. Do not answer a requested transcript deep dive from call metadata alone. " +
       "When the user refers to the current analysis, this analysis, this project, or asks to spin off, adapt, modify, or reuse a saved analysis, call `view-screen` first and use the returned analysis details; if an analysis id or @mention is provided, call `get-analysis` before responding. " +
-      "If a provider action fails, stop using that provider for the turn, surface the actual error, and wait for the user to choose whether to fix SQL, use another source, or retry. Do not loop through more queries after a failed provider call. " +
-      "For ordinary ad-hoc, non-coverage-sensitive data questions, answer the explicit question after the first relevant successful query or bounded evidence batch instead of continuing into suggested follow-up investigations. " +
+      "If a query action fails because its arguments are invalid, correct the arguments once. Never repeat the identical failed call. For credential, permission, quota, network, or repeated schema failures, stop using that source for the turn and surface the actual error instead of trying unrelated providers. " +
+      "For ordinary ad-hoc structured data questions, answer the explicit question after the first relevant successful query or bounded evidence batch. The words all, total, or exact do not require cross-source validation when a single structured query fully covers the requested source and filters. " +
       "If the user challenges coverage, asks why more records were not included, or asks for the updated answer, rerun the relevant source query or revise from the corrected cohort and provide the updated deliverable directly. Do not claim an analysis was revised unless the revised answer is included in the response or saved with `save-analysis`. " +
       "Unstructured source records are valid analytics evidence: Pylon tickets, Jira issues, Gong calls/transcripts, Slack messages, and similar text records may be coded for themes, mention counts, sentiment, objections, and qualitative patterns as long as the answer states the inspected sample size and does not imply unsupported statistical certainty. " +
       "For schema questions, prefer data-dictionary entries and configured warehouse schemas over assumptions; use `search-bigquery-schema` for BigQuery metadata before inventing datasets, tables, or columns. " +

package/corpus/templates/content/changelog/2026-07-23-database-toolbar-sort-and-filter-controls-open-reliably.md

@@ -0,0 +1,6 @@
+---
+type: fixed
+date: 2026-07-23
+---
+
+Database toolbar Sort and Filter controls now open reliably with pointer and keyboard activation.

package/corpus/templates/forms/app/lib/public-form-link.ts

@@ -0,0 +1,14 @@
+import { appPath } from "@agent-native/core/client/api-path";
+
+interface PublicFormLink {
+  status: string;
+  slug: string;
+}
+
+export function getPublishedFormUrl(
+  form: PublicFormLink,
+  origin: string,
+): string | undefined {
+  if (form.status !== "published") return undefined;
+  return `${origin}${appPath(`/f/${form.slug}`)}`;
+}

package/corpus/templates/forms/app/pages/FormBuilderPage.tsx

@@ -85,6 +85,7 @@ import {
   type FormBuilderTab,
 } from "@/lib/form-builder-tabs";
 import { normalizeFields } from "@/lib/normalize-fields";
+import { getPublishedFormUrl } from "@/lib/public-form-link";
 import { cn } from "@/lib/utils";
 
 type Translator = ReturnType<typeof useT>;
@@ -175,8 +176,8 @@ export function FormBuilderPage() {
   const { isLocal } = useDbStatus();
   const [showCloudUpgrade, setShowCloudUpgrade] = useState(false);
   const publishedFormUrl =
-    form?.status === "published" && typeof window !== "undefined"
-      ? `${window.location.origin}${appPath(`/f/${form.slug}`)}`
+    form && typeof window !== "undefined"
+      ? getPublishedFormUrl(form, window.location.origin)
       : undefined;
   const [agentPopoverOpen, setAgentPopoverOpen] = useState(false);
   const [agentPrompt, setAgentPrompt] = useState("");
@@ -533,16 +534,11 @@ export function FormBuilderPage() {
   }
 
   function copyShareLink() {
-    if (loadedForm.status !== "published") {
+    if (!publishedFormUrl) {
       toast.info(t("builder.publishBeforeCopyToast"));
       return;
     }
-    if (isLocal) {
-      setShowCloudUpgrade(true);
-      return;
-    }
-    const url = `${window.location.origin}${appPath(`/f/${loadedForm.slug}`)}`;
-    navigator.clipboard.writeText(url);
+    navigator.clipboard.writeText(publishedFormUrl);
     setCopied(true);
     setTimeout(() => setCopied(false), 2000);
     toast.success(t("builder.linkCopiedToast"));
@@ -611,11 +607,7 @@ export function FormBuilderPage() {
                   className="h-10 w-10 active:scale-[0.96] motion-reduce:active:scale-100"
                   asChild
                 >
-                  <a
-                    href={appPath(`/f/${form.slug}`)}
-                    target="_blank"
-                    rel="noopener"
-                  >
+                  <a href={publishedFormUrl} target="_blank" rel="noopener">
                     <IconExternalLink className="h-4 w-4" />
                   </a>
                 </Button>

package/corpus/templates/forms/changelog/2026-07-23-published-form-links-can-be-copied-without-being-asked-to-re.md

@@ -0,0 +1,6 @@
+---
+type: fixed
+date: 2026-07-23
+---
+
+Published form links can be copied without being asked to reconnect the database.

package/corpus/templates/mail/changelog/2026-07-23-scheduled-emails-now-send-only-once-when-multiple-requests-r.md

@@ -0,0 +1,6 @@
+---
+type: fixed
+date: 2026-07-23
+---
+
+Scheduled emails now send only once when multiple requests race.

package/corpus/templates/mail/server/lib/jobs.ts

@@ -722,7 +722,7 @@ export async function sendScheduledJobNowForOwner(
     throw new Error(`Scheduled email is already ${job.status}`);
   }
 
-  await db
+  const claim = await db
     .update(schema.scheduledJobs)
     .set({ status: "processing" } as any)
     .where(
@@ -732,6 +732,9 @@ export async function sendScheduledJobNowForOwner(
         eq(schema.scheduledJobs.status, "pending"),
       ),
     );
+  if (claim.rowsAffected === 0) {
+    throw new Error("Scheduled email is already processing");
+  }
 
   try {
     await sendScheduledEmail(
@@ -769,11 +772,17 @@ export async function markJobDone(id: string): Promise<void> {
     .where(eq(schema.scheduledJobs.id, id));
 }
 
-export async function markJobProcessing(id: string): Promise<void> {
-  await db
+export async function markJobProcessing(id: string): Promise<boolean> {
+  const result = await db
     .update(schema.scheduledJobs)
     .set({ status: "processing" } as any)
-    .where(eq(schema.scheduledJobs.id, id));
+    .where(
+      and(
+        eq(schema.scheduledJobs.id, id),
+        eq(schema.scheduledJobs.status, "pending"),
+      ),
+    );
+  return result.rowsAffected > 0;
 }
 
 export async function getDuePendingJobs(

package/corpus/templates/mail/server/plugins/mail-jobs.ts

@@ -48,7 +48,7 @@ async function processJobs(): Promise<void> {
   const due = await getDuePendingJobs(now);
 
   for (const job of due) {
-    await markJobProcessing(job.id);
+    if (!(await markJobProcessing(job.id))) continue;
 
     try {
       const ownerEmail = job.ownerEmail || job.accountEmail;