@agent-native/core 0.153.4 → 0.153.5

package/corpus/templates/analytics/actions/account-deep-dive.ts

@@ -414,6 +414,7 @@ export default defineAction({
   http: { method: "GET" },
   readOnly: true,
   publicAgent: { expose: true, readOnly: true, requiresAuth: true },
+  grounding: true,
   run: async (args) => {
     const trimmedQuery = args.query.trim();
     const gaps: string[] = [];

package/corpus/templates/analytics/actions/bigquery-query.ts

@@ -17,5 +17,6 @@ export default defineAction({
   http: { method: "POST" },
   readOnly: true,
   toolCallable: true,
+  grounding: true,
   run: bigquery.run,
 });

package/corpus/templates/analytics/actions/bigquery.ts

@@ -75,6 +75,7 @@ export default defineAction({
   }),
   readOnly: true,
   toolCallable: true,
+  grounding: true,
   run: async (args, context?: ActionRunContext) => {
     try {
       return await runQuery(args.sql, { signal: context?.signal });

package/corpus/templates/analytics/actions/content-calendar-schema.ts

@@ -11,6 +11,7 @@ export default defineAction({
   }),
   http: { method: "GET" },
   readOnly: true,
+  grounding: true,
   run: async ({ databaseId }) => {
     return await getContentCalendarSchema(databaseId);
   },

package/corpus/templates/analytics/actions/content-calendar.ts

@@ -18,6 +18,7 @@ export default defineAction({
       ),
   }),
   http: { method: "GET" },
+  grounding: true,
   run: async ({ databaseId }) => {
     const entries = await getContentCalendar(databaseId);
     return { entries, total: Array.isArray(entries) ? entries.length : 0 };

package/corpus/templates/analytics/actions/gcloud.ts

@@ -56,6 +56,7 @@ export default defineAction({
       .describe("Additional Cloud Monitoring filter expression"),
   }),
   http: { method: "GET" },
+  grounding: true,
   run: async (args) => {
     const credentials = await requireActionCredentials(
       ["BIGQUERY_PROJECT_ID", "GOOGLE_APPLICATION_CREDENTIALS_JSON"],

package/corpus/templates/analytics/actions/get-data-program.ts

@@ -22,6 +22,7 @@ export default defineAction({
   }),
   http: { method: "GET" },
   readOnly: true,
+  grounding: true,
   run: async (args) => {
     const ctx = getCredentialContext();
     if (!ctx) throw new Error("No authenticated context for get-data-program.");

package/corpus/templates/analytics/actions/get-error-issue.ts

@@ -29,6 +29,7 @@ export default defineAction({
   http: { method: "GET" },
   readOnly: true,
   publicAgent: { expose: true, readOnly: true, requiresAuth: true },
+  grounding: true,
   run: async (args) => {
     return getErrorIssue(resolveScope(), args.id, {
       eventsLimit: args.eventsLimit,

package/corpus/templates/analytics/actions/get-monitor-stats.ts

@@ -37,6 +37,7 @@ export default defineAction({
       ),
   }),
   http: { method: "GET" },
+  grounding: true,
   run: async ({ monitorIds, timelineDays, responseWindowHours }) => {
     const email = getRequestUserEmail();
     if (!email) throw new Error("no authenticated user");

package/corpus/templates/analytics/actions/get-monitor.ts

@@ -14,6 +14,7 @@ export default defineAction({
     id: z.string().describe("Monitor id."),
   }),
   http: { method: "GET" },
+  grounding: true,
   run: async ({ id }) => {
     const email = getRequestUserEmail();
     if (!email) throw new Error("no authenticated user");

package/corpus/templates/analytics/actions/get-session-replay-events.ts

@@ -40,6 +40,7 @@ export default defineAction({
   }),
   http: { method: "GET" },
   readOnly: true,
+  grounding: true,
   run: async (args) => {
     return getSessionReplayEvents(args.recordingId, resolveScope(), {
       startSeq: args.startSeq,

package/corpus/templates/analytics/actions/get-session-replay-summary.ts

@@ -22,6 +22,7 @@ export default defineAction({
   http: { method: "GET" },
   readOnly: true,
   publicAgent: { expose: true, readOnly: true, requiresAuth: true },
+  grounding: true,
   run: async (args) => {
     return getSessionReplaySummary(args.recordingId, resolveScope());
   },

package/corpus/templates/analytics/actions/get-session-replay-timeline.ts

@@ -32,6 +32,7 @@ export default defineAction({
   http: { method: "GET" },
   readOnly: true,
   publicAgent: { expose: true, readOnly: true, requiresAuth: true },
+  grounding: true,
   run: async (args) => {
     return getSessionReplayTimeline(args.recordingId, resolveScope(), {
       eventLimit: args.eventLimit,

package/corpus/templates/analytics/actions/gong-calls.ts

@@ -583,6 +583,7 @@ export default defineAction({
       ),
   }),
   http: { method: "GET" },
+  grounding: true,
   run: async (args, ctx) => {
     const requestOptions = ctx?.signal ? { signal: ctx.signal } : undefined;
     if (args.users) {

package/corpus/templates/analytics/actions/gong-native-insights.ts

@@ -66,6 +66,7 @@ export default defineAction({
     Boolean(operation && allowCreditRequest),
   publicAgent: { expose: true, readOnly: true, requiresAuth: true },
   http: false,
+  grounding: true,
   run: async ({ operation, allowCreditRequest, arguments: args }) => {
     const tools = gongNativeTools(await listVisibleMcpTools());
     if (!operation) {

package/corpus/templates/analytics/actions/grafana.ts

@@ -36,6 +36,7 @@ export default defineAction({
     to: z.string().optional().describe("Query end time in epoch ms"),
   }),
   readOnly: true,
+  grounding: true,
   run: async (args) => {
     const credentials = await requireActionCredentials(
       ["GRAFANA_URL", "GRAFANA_API_TOKEN"],

package/corpus/templates/analytics/actions/hubspot-deals.ts

@@ -494,6 +494,7 @@ export default defineAction({
   }),
   http: { method: "GET" },
   publicAgent: { expose: true, readOnly: true, requiresAuth: true },
+  grounding: true,
   run: async ({
     properties,
     owner,

package/corpus/templates/analytics/actions/hubspot-metrics.ts

@@ -15,6 +15,7 @@ export default defineAction({
     "Get computed HubSpot sales metrics: win rate, ACV, pipeline value, etc.",
   schema: z.object({}),
   http: { method: "GET" },
+  grounding: true,
   run: async () => {
     const [deals, pipelines] = await Promise.all([
       getAllDeals(),

package/corpus/templates/analytics/actions/hubspot-pipelines.ts

@@ -10,6 +10,7 @@ export default defineAction({
   description: "Get HubSpot deal pipelines and their stages.",
   schema: z.object({}),
   http: { method: "GET" },
+  grounding: true,
   run: async () => {
     const allPipelines = await getDealPipelines();
     const pipelines = getVisiblePipelines(allPipelines);

package/corpus/templates/analytics/actions/hubspot-records.ts

@@ -49,6 +49,7 @@ export default defineAction({
   }),
   http: { method: "GET" },
   publicAgent: { expose: true, readOnly: true, requiresAuth: true },
+  grounding: true,
   run: async ({ objectType, query, properties, limit, after }) => {
     const result = await searchHubSpotObjects({
       objectType,

package/corpus/templates/analytics/actions/jira-search.ts

@@ -25,6 +25,7 @@ export default defineAction({
       .describe("Comma-separated field names to include"),
   }),
   http: false,
+  grounding: true,
   run: async (args) => {
     const credentials = await requireActionCredentials(
       ["JIRA_BASE_URL", "JIRA_USER_EMAIL", "JIRA_API_TOKEN"],

package/corpus/templates/analytics/actions/jira.ts

@@ -66,6 +66,7 @@ export default defineAction({
       .describe("Lookback days for mode=analytics"),
   }),
   http: { method: "GET" },
+  grounding: true,
   run: async (args) => {
     const credentials = await requireActionCredentials(
       ["JIRA_BASE_URL", "JIRA_USER_EMAIL", "JIRA_API_TOKEN"],

package/corpus/templates/analytics/actions/list-error-issues.ts

@@ -47,6 +47,7 @@ export default defineAction({
   http: { method: "GET" },
   readOnly: true,
   publicAgent: { expose: true, readOnly: true, requiresAuth: true },
+  grounding: true,
   run: async (args) => {
     return listErrorIssues(resolveScope(), args);
   },

package/corpus/templates/analytics/actions/list-monitors.ts

@@ -12,6 +12,7 @@ export default defineAction({
     "List the current user's uptime monitors with their latest status, latency, and 24h/7d uptime percentage.",
   schema: z.object({}),
   http: { method: "GET" },
+  grounding: true,
   run: async () => {
     const email = getRequestUserEmail();
     if (!email) throw new Error("no authenticated user");

package/corpus/templates/analytics/actions/list-session-recordings.ts

@@ -59,6 +59,7 @@ export default defineAction({
   http: { method: "GET" },
   readOnly: true,
   publicAgent: { expose: true, readOnly: true, requiresAuth: true },
+  grounding: true,
   run: async (args) => {
     return listSessionRecordings(resolveScope(), args);
   },

package/corpus/templates/analytics/actions/match-error-issues.ts

@@ -45,6 +45,7 @@ export default defineAction({
   }),
   http: { method: "POST" },
   readOnly: true,
+  grounding: true,
   run: async (args) => {
     return matchErrorIssuesBySignatures(resolveScope(), args.signatures);
   },

package/corpus/templates/analytics/actions/prometheus.ts

@@ -52,6 +52,7 @@ export default defineAction({
     metric: z.string().optional().describe("Metric name for mode=metadata"),
   }),
   readOnly: true,
+  grounding: true,
   run: async (args) => {
     const creds = await requireActionCredentials(
       ["PROMETHEUS_URL"],

package/corpus/templates/analytics/actions/pylon-issues.ts

@@ -27,6 +27,7 @@ export default defineAction({
   agentTool: false,
   toolCallable: true,
   http: { method: "POST" },
+  grounding: true,
   run: async ({ account, accounts, query, days, pageSize, maxPages }) => {
     if (accounts) {
       const response = (await executeProviderApiRequest({

package/corpus/templates/analytics/actions/query-agent-native-analytics.ts

@@ -69,6 +69,7 @@ export default defineAction({
   // natural-language question and Analytics forms the query.
   http: false,
   publicAgent: { expose: true, readOnly: true, requiresAuth: true },
+  grounding: true,
   run: async (args) => {
     const result = await queryFirstPartyAnalytics(args.sql, resolveScope(), {
       cache: true,

package/corpus/templates/analytics/actions/query-dashboard-panel.ts

@@ -18,6 +18,7 @@ export default defineAction({
   http: { method: "POST" },
   readOnly: true,
   agentTool: false,
+  grounding: true,
   run: async (args) => {
     const context = getCredentialContext();
     if (!context) {

package/corpus/templates/analytics/actions/query-inbound-forms.ts

@@ -8,6 +8,7 @@ export default defineAction({
     "Query inbound sales/demo form submissions from a configured warehouse form-submissions table.",
   schema: z.object({}),
   http: false,
+  grounding: true,
   run: async () => {
     const sql = `
 SELECT

package/corpus/templates/analytics/actions/run-monitor-check.ts

@@ -14,6 +14,7 @@ export default defineAction({
     id: z.string().describe("Monitor id to check now."),
   }),
   http: { method: "POST" },
+  grounding: true,
   run: async ({ id }) => {
     const email = getRequestUserEmail();
     if (!email) throw new Error("no authenticated user");

package/corpus/templates/analytics/actions/sentry.ts

@@ -44,6 +44,7 @@ export default defineAction({
       .describe("Sentry stats category for mode=stats; defaults to error"),
   }),
   http: { method: "GET" },
+  grounding: true,
   run: async (args) => {
     const credentials = await requireActionCredentials(
       ["SENTRY_SERVER_TOKEN", "SENTRY_AUTH_TOKEN"],

package/corpus/templates/analytics/actions/seo-blog-pages.ts

@@ -10,6 +10,7 @@ export default defineAction({
   description: "Get SEO metrics for all blog pages.",
   schema: z.object({}),
   http: { method: "GET" },
+  grounding: true,
   run: async () => {
     const pages = await getAllBlogPagesSeo();
     return { pages, total: Object.keys(pages).length };

package/corpus/templates/analytics/actions/seo-page-keywords.ts

@@ -15,6 +15,7 @@ export default defineAction({
       .describe("Blog page slug (e.g. micro-frontends)"),
   }),
   http: { method: "GET" },
+  grounding: true,
   run: async (args) => {
     if (!args.slug) return { error: "slug is required" };
     const keywords = await getRankedKeywordsForPage(args.slug, 20);

package/corpus/templates/analytics/actions/seo-top-keywords.ts

@@ -16,6 +16,7 @@ export default defineAction({
       .describe("Max keywords to return (default 500)"),
   }),
   http: { method: "GET" },
+  grounding: true,
   run: async (args) => {
     const limit = Math.min(args.limit ?? 500, 1000);
     const keywords = await getAllTopBlogKeywords(limit);

package/corpus/templates/analytics/actions/slack-messages.ts

@@ -77,6 +77,7 @@ export default defineAction({
       .describe("Per-channel cursors for mode=multi-history"),
   }),
   readOnly: true,
+  grounding: true,
   run: async (args) => {
     const workspace = parseWorkspace(args.workspace);
     const key =

package/corpus/templates/analytics/actions/stripe.ts

@@ -74,6 +74,7 @@ export default defineAction({
       .describe("Months of billing history"),
   }),
   http: { method: "GET" },
+  grounding: true,
   run: async (args) => {
     const credentials = await requireActionCredentials(
       ["STRIPE_SECRET_KEY"],

package/corpus/templates/analytics/actions/test-custom-api-connection.ts

@@ -30,6 +30,7 @@ export default defineAction({
   agentTool: false,
   http: { method: "POST" },
   readOnly: true,
+  grounding: true,
   run: async ({ provider, path, query, itemsPath }) => {
     try {
       const result = (await getAnalyticsProviderApiRuntime().executeRequest({

package/corpus/templates/analytics/server/lib/real-data-actions.ts

@@ -13,45 +13,6 @@ const INJECTED_CONTEXT_BLOCKS = [
   "response-guard",
 ];
 
-export const DATA_QUERY_ACTIONS = new Set([
-  "account-deep-dive",
-  "bigquery",
-  "content-calendar",
-  "content-calendar-schema",
-  // First-party observability reads are grounded data for incident triage,
-  // even though they are not provider queries. Keep the final-response guard
-  // from replacing valid session/error/replay evidence with the generic
-  // "connect a source" fallback.
-  "get-error-issue",
-  "get-session-replay-events",
-  "get-session-replay-summary",
-  "get-session-replay-timeline",
-  "list-error-issues",
-  "list-session-recordings",
-  "match-error-issues",
-  "gcloud",
-  "gong-calls",
-  "gong-native-insights",
-  "grafana",
-  "hubspot-deals",
-  "hubspot-metrics",
-  "hubspot-pipelines",
-  "hubspot-records",
-  "jira",
-  "jira-search",
-  "provider-api-request",
-  "provider-corpus-job",
-  "query-staged-dataset",
-  "query-agent-native-analytics",
-  "query-inbound-forms",
-  "sentry",
-  "seo-blog-pages",
-  "seo-page-keywords",
-  "seo-top-keywords",
-  "slack-messages",
-  "stripe",
-]);
-
 export const CORPUS_SOURCE_ACTIONS = new Set([
   "provider-api-request",
   "provider-corpus-job",
@@ -127,8 +88,39 @@ function isToolName(name: string, expected: string): boolean {
   return normalizeActionToolName(name) === expected;
 }
 
-function isDataQueryActionName(name: string): boolean {
-  return DATA_QUERY_ACTIONS.has(normalizeActionToolName(name));
+let groundingActionNames: ReadonlySet<string> | null = null;
+
+/**
+ * Publish the action names whose definitions declare `grounding: true`.
+ *
+ * The set is pushed in rather than read from `.generated/actions-registry`
+ * because that registry imports every action, and `save-analysis` imports this
+ * module — importing it back here would close an evaluation cycle. The
+ * agent-chat plugin derives the set once at module load; nothing else may.
+ */
+export function registerGroundingActions(names: Iterable<string>): void {
+  const normalized = new Set(
+    [...names].map((name) => normalizeActionToolName(name)),
+  );
+  // An empty set is never a real deployment: it means the installed core build
+  // predates `grounding` and dropped it from every definition. Left unchecked,
+  // the guard would replace every correct grounded answer with "connect data
+  // sources" — the exact silent failure this flag replaced.
+  if (normalized.size === 0) {
+    throw new Error(
+      "no action declares grounding: true; the installed @agent-native/core cannot carry the flag",
+    );
+  }
+  groundingActionNames = normalized;
+}
+
+function isGroundingActionName(name: string): boolean {
+  if (!groundingActionNames) {
+    throw new Error(
+      "grounding actions were never registered: the analytics response guard cannot tell a grounded turn from an ungrounded one",
+    );
+  }
+  return groundingActionNames.has(normalizeActionToolName(name));
 }
 
 function isDashboardConstructionActionName(name: string): boolean {
@@ -214,7 +206,7 @@ function getRunCodeBridgeToolNames(content: string | undefined): string[] {
 
 function hasRunCodeDataQueryAttempt(content: string | undefined): boolean {
   return getRunCodeBridgeToolNames(content).some(
-    (name) => isDataQueryActionName(name) || isMcpDataSourceTool(name),
+    (name) => isGroundingActionName(name) || isMcpDataSourceTool(name),
   );
 }
 
@@ -530,10 +522,9 @@ export function hasIncompleteDataEvidence(
     const name = String(result.name ?? "");
     if (
       name &&
-      !isDataQueryActionName(name) &&
+      !isGroundingActionName(name) &&
       !isMcpDataSourceTool(name) &&
-      !isToolName(name, "run-code") &&
-      !isToolName(name, "provider-api-request")
+      !isToolName(name, "run-code")
     ) {
       return false;
     }
@@ -594,7 +585,7 @@ export function hasDataQueryAttempt(
     if (isToolName(name, "run-code")) {
       return hasRunCodeDataQueryAttempt(result.content);
     }
-    return isDataQueryActionName(name) || isMcpDataSourceTool(name);
+    return isGroundingActionName(name) || isMcpDataSourceTool(name);
   });
 }
 
@@ -605,7 +596,7 @@ function isFailedDataQueryAttempt(result: {
 }): boolean {
   const name = String(result.name ?? "");
   const isDataQuery =
-    isDataQueryActionName(name) ||
+    isGroundingActionName(name) ||
     isMcpDataSourceTool(name) ||
     (isToolName(name, "run-code") &&
       hasRunCodeDataQueryAttempt(result.content));

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

@@ -29,8 +29,28 @@ import {
   looksLikeAnalyticsDataRequest,
   needsCorpusWorkflowForCoverageSensitiveRequest,
   needsSourceRecordBodyWorkflowForCoverageSensitiveRequest,
+  registerGroundingActions,
 } from "../lib/real-data-actions";
 
+// Which actions return real data-source evidence is a fact each action states
+// on itself (`grounding: true`). Reading it off the definitions here is what
+// keeps the response guard from drifting behind a newly shipped source action.
+registerGroundingActions(
+  Object.entries(actionsRegistry)
+    .filter(([, module]) => {
+      // Action modules reach the registry either as the module namespace or as
+      // an already-unwrapped definition, the same two shapes
+      // `loadActionsFromStaticRegistry` normalizes.
+      const candidate = module as
+        | { grounding?: boolean; default?: { grounding?: boolean } }
+        | undefined;
+      return (
+        candidate?.grounding === true || candidate?.default?.grounding === true
+      );
+    })
+    .map(([name]) => name),
+);
+
 const ANALYTICS_BACKGROUND_RUN_SOFT_TIMEOUT_MS = 13 * 60_000;
 // A background job may legitimately spend minutes inside a provider/tool call,
 // which the shared watchdog already excludes. Outside a tool call, however,
@@ -764,17 +784,23 @@ export function realDataFinalGuard(
   }
 
   if (dataQueryAttempted) return null;
+  const failedQueryMessage = failedDataQueryAttemptMessage(context.toolResults);
+  // Whether the built-in source is worth trying is decided by tool evidence,
+  // not by how the draft is worded, so it is asked once for every draft shape.
+  // A source that already failed this turn is not an untried source: steering
+  // the model back into it is how a permanently failing precondition turns
+  // into a retry loop.
+  if (firstPartySourceShouldBeTried && !failedQueryMessage) {
+    return {
+      retryMessage:
+        "The user asked for live analytics, and the built-in first-party Analytics source is available even though no external provider is connected. Call `query-agent-native-analytics` for first-party product, usage, conversion, or observability data and answer from that result. If the request specifically names an external provider, explain what is missing and include the real Connect data sources link.",
+      fallbackMessage:
+        "I couldn't complete a grounded first-party Analytics query yet. Please retry and I'll use the built-in Analytics source before asking you to connect an external provider.",
+      maxRetries: 2,
+      expandToolSurface: true,
+    };
+  }
   if (isSafeNoDataAnalyticsResponse(context.text)) {
-    if (firstPartySourceShouldBeTried) {
-      return {
-        retryMessage:
-          "The built-in first-party Analytics source is available even though no external provider is connected. Use `query-agent-native-analytics` for the user's first-party product, usage, conversion, or observability question before explaining that data is unavailable. Only guide the user to connect a source if the request specifically needs an external provider.",
-        fallbackMessage:
-          "I couldn't complete a grounded first-party Analytics query yet. Please retry and I'll use the built-in Analytics source before asking you to connect an external provider.",
-        maxRetries: 2,
-        expandToolSurface: true,
-      };
-    }
     if (
       needsDataSourceLink &&
       !includesDataSourcesLink(context.text, setupLink)
@@ -787,7 +813,6 @@ export function realDataFinalGuard(
     }
     return null;
   }
-  const failedQueryMessage = failedDataQueryAttemptMessage(context.toolResults);
   if (failedQueryMessage) {
     if (
       needsDataSourceLink &&
@@ -805,11 +830,10 @@ export function realDataFinalGuard(
     };
   }
 
-  if (
-    needsDataSourceLink &&
-    (missingRequestedExternalSource ||
-      (noConnectedExternalSources && externalSourceRequest))
-  ) {
+  // `needsDataSourceLink` already carries "status was checked, the user named an
+  // external source, and it is missing or nothing is connected". Restating those
+  // clauses here is what made the next branch look reachable.
+  if (needsDataSourceLink) {
     return {
       retryMessage: `The requested external source is not connected. Explain what is missing in the context of the user's question and include this exact markdown link: ${setupMarkdown}. Do not use the generic no-grounded-data fallback.`,
       fallbackMessage: `I can help with that once the relevant source is connected. ${setupMarkdown}`,
@@ -819,24 +843,6 @@ export function realDataFinalGuard(
   }
 
   const configuredSources = configuredDataSourceLabels(context.toolResults);
-  if (firstPartySourceShouldBeTried) {
-    return {
-      retryMessage:
-        "The user asked for live analytics, and the built-in first-party Analytics source is available even though no external provider is connected. Call `query-agent-native-analytics` for first-party product, usage, conversion, or observability data and answer from that result. If the request specifically names an external provider, explain what is missing and include the real Connect data sources link.",
-      fallbackMessage:
-        "I couldn't complete a grounded first-party Analytics query yet. Please retry and I'll use the built-in Analytics source before asking you to connect an external provider.",
-      maxRetries: 2,
-      expandToolSurface: true,
-    };
-  }
-  if (noConnectedExternalSources) {
-    return {
-      retryMessage: `The user asked for live analytics, but data-source-status found no connected external providers. The built-in first-party source is still available for first-party Analytics data. If this request needs an external source, respond naturally in the context of the user's question, explain what is missing, and include ${setupMarkdown}. Do not use a generic canned no-data response.`,
-      fallbackMessage: `I can help with that once the relevant source is connected. ${setupMarkdown}`,
-      maxRetries: 2,
-      expandToolSurface: true,
-    };
-  }
   const configuredSourceGuidance = configuredSources.length
     ? ` \`data-source-status\` already confirmed these connected sources: ${configuredSources.join(", ")}. Do not claim that no sources are connected and do not ask the user to reconnect them. Immediately call the relevant query action for one of those sources.`
     : "";

package/dist/action.d.ts

@@ -398,6 +398,15 @@ interface DefineActionWithSchema<TSchema extends StandardSchemaV1, TReturn = any
      *  Only set this manually when you need to override the inference — e.g. a
      *  POST action that only reads data but can't use GET for a protocol reason. */
     readOnly?: boolean;
+    /** Declares that a successful call returns real evidence retrieved from a data
+     *  source at call time — a provider API, a warehouse, a connected repo, or the
+     *  app's own event/observability store. Apps that police fabricated answers
+     *  (see the Analytics final-response guard) read this instead of keeping a
+     *  hand-maintained list of action names, which drifts the moment a new source
+     *  action ships. Orthogonal to `readOnly`: a write that probes a live endpoint
+     *  and returns the outcome is still grounding. Metadata-only reads (schema,
+     *  catalogs, saved config) are not. */
+    grounding?: boolean;
     /** Set false for read-only tools that should stay available in Act mode but
      *  must not run during Plan mode because they perform substantive work
      *  rather than lightweight inspection. Defaults to allowed when read-only. */
@@ -538,6 +547,9 @@ interface DefineActionWithParams<TParams extends Record<string, ParameterSchema>
     /** If true, the framework will NOT emit a screen-refresh change event after a
      *  successful call. Auto-inferred as `true` when `http.method === "GET"`. */
     readOnly?: boolean;
+    /** Declares that a successful call returns real evidence retrieved from a data
+     *  source at call time. See the schema overload above. */
+    grounding?: boolean;
     /** Set false for read-only tools that should stay available in Act mode but
      *  must not run during Plan mode. See the schema overload above. */
     allowInPlanMode?: boolean;
@@ -602,6 +614,7 @@ export interface ActionDefinition<TInput, TReturn> {
     readonly maxBodyBytes?: number;
     readonly agentTool?: boolean;
     readonly readOnly?: boolean;
+    readonly grounding?: boolean;
     readonly allowInPlanMode?: boolean;
     readonly planMode?: ActionPlanModeConfig<TInput>;
     readonly parallelSafe?: boolean;

package/dist/action.js

@@ -164,6 +164,9 @@ export function defineAction(options) {
             : {}),
         ...(typeof agentTool === "boolean" ? { agentTool } : {}),
         ...(typeof readOnly === "boolean" ? { readOnly } : {}),
+        ...(typeof options.grounding === "boolean"
+            ? { grounding: options.grounding }
+            : {}),
         ...(typeof options.allowInPlanMode === "boolean"
             ? { allowInPlanMode: options.allowInPlanMode }
             : {}),